1 17ab44fc 2021-07-31 op .\" Copyright (c) 2021 Omar Polo <op@omarpolo.com>
  2 17ab44fc 2021-07-31 op .\"
  3 17ab44fc 2021-07-31 op .\" Permission to use, copy, modify, and distribute this software for any
  4 17ab44fc 2021-07-31 op .\" purpose with or without fee is hereby granted, provided that the above
  5 17ab44fc 2021-07-31 op .\" copyright notice and this permission notice appear in all copies.
  6 17ab44fc 2021-07-31 op .\"
  7 17ab44fc 2021-07-31 op .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  8 17ab44fc 2021-07-31 op .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  9 17ab44fc 2021-07-31 op .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 10 17ab44fc 2021-07-31 op .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 11 17ab44fc 2021-07-31 op .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 12 17ab44fc 2021-07-31 op .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 13 17ab44fc 2021-07-31 op .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 14 17ab44fc 2021-07-31 op .\"
 15 17ab44fc 2021-07-31 op .Dd $Mdocdate: July 30 2021 $
 16 17ab44fc 2021-07-31 op .Dt 9P 7
 17 17ab44fc 2021-07-31 op .Os
 18 17ab44fc 2021-07-31 op .Sh NAME
 19 17ab44fc 2021-07-31 op .Nm 9P
 20 17ab44fc 2021-07-31 op .Nd Simple Distributed File System
 21 17ab44fc 2021-07-31 op .Sh DESCRIPTION
 22 17ab44fc 2021-07-31 op .Nm
 23 3d1d2398 2021-08-04 op is a protocol that implements a distributed file systems.
 24 17ab44fc 2021-07-31 op It provides primitives to manage
 25 17ab44fc 2021-07-31 op .Pq create, read, write and delete
 26 17ab44fc 2021-07-31 op sets of files remotely.
 27 17ab44fc 2021-07-31 op These files don't necessarily need to be actually stored on a disk,
 28 17ab44fc 2021-07-31 op they may be, for example, synthesise on demand from external sources.
 29 17ab44fc 2021-07-31 op .Pp
 30 17ab44fc 2021-07-31 op A client transmits requests
 31 17ab44fc 2021-07-31 op .Pq T-messages
 32 17ab44fc 2021-07-31 op to a server, which returns replies
 33 17ab44fc 2021-07-31 op .Pq R-messages
 34 17ab44fc 2021-07-31 op to the client.
 35 17ab44fc 2021-07-31 op The combined acts of transmitting a request of a particular type and
 36 17ab44fc 2021-07-31 op receiving a reply is called a transaction of that type.
 37 17ab44fc 2021-07-31 op .Pp
 38 3d1d2398 2021-08-04 op Each message consists of a sequence of bytes mostly grouped in one,
 39 3d1d2398 2021-08-04 op two or four integer fields transmitted in little-endian order
 40 17ab44fc 2021-07-31 op .Pq least significant byte first .
 41 17ab44fc 2021-07-31 op Data items of larger or variable lengths are represented by a two-byte
 42 17ab44fc 2021-07-31 op field specifying the length followed by the actual data.
 43 3d1d2398 2021-08-04 op The only exception to this rule are QIDs, thirteen byte long
 44 3d1d2398 2021-08-04 op objects, that are sent as-is.
 45 3d1d2398 2021-08-04 op .Pp
 46 3d1d2398 2021-08-04 op Text strings are represented with a two-byte count and the sequence of
 47 3d1d2398 2021-08-04 op UNICODE codepoints encoded in UTF-8.
 48 3d1d2398 2021-08-04 op Text strings in 9p are not NUL-terminated.
 49 17ab44fc 2021-07-31 op The NUL-terminator is illegal in all text strings and thus excluded
 50 17ab44fc 2021-07-31 op from paths, user names and so on.
 51 17ab44fc 2021-07-31 op .Pp
 52 17ab44fc 2021-07-31 op Fields are hereafter denoted as
 53 17ab44fc 2021-07-31 op .Bd -literal -offset indent
 54 17ab44fc 2021-07-31 op type[1] tag[2] fid[4]
 55 17ab44fc 2021-07-31 op .Ed
 56 17ab44fc 2021-07-31 op .Pp
 57 17ab44fc 2021-07-31 op to indicate that type is one byte long, tag two and fid four.
 58 17ab44fc 2021-07-31 op Strings are denoted as name[s] and are sent on the wire as
 59 17ab44fc 2021-07-31 op .Bd -literal -offset indent
 60 17ab44fc 2021-07-31 op length[2] string[length]
 61 17ab44fc 2021-07-31 op .Ed
 62 17ab44fc 2021-07-31 op .Pp
 63 17ab44fc 2021-07-31 op A qid, described later, is a 13-byte value that is sent on the wire as
 64 17ab44fc 2021-07-31 op .Bd -literal -offset indent
 65 17ab44fc 2021-07-31 op type[1] version[4] path[8]
 66 17ab44fc 2021-07-31 op .Ed
 67 3d1d2398 2021-08-04 op .Sh MESSAGE STRUCTURE
 68 17ab44fc 2021-07-31 op Every message has a header with the following fields:
 69 17ab44fc 2021-07-31 op .Bd -literal -offset indent
 70 17ab44fc 2021-07-31 op len[4] type[1] tag[2]
 71 17ab44fc 2021-07-31 op .Ed
 72 17ab44fc 2021-07-31 op .Pp
 73 17ab44fc 2021-07-31 op where len indicates the overall length of the message, including
 74 17ab44fc 2021-07-31 op itself; type is one byte indicating the type of the message and the
 75 3d1d2398 2021-08-04 op tag is a number choosen by the client that indicate uniquely the
 76 17ab44fc 2021-07-31 op request.
 77 3d1d2398 2021-08-04 op Then follows an optional body whose structure depends on the type of
 78 3d1d2398 2021-08-04 op the message.
 79 17ab44fc 2021-07-31 op .Pp
 80 17ab44fc 2021-07-31 op The message types are as follows:
 81 17ab44fc 2021-07-31 op .Bl -tag -width versionxx
 82 17ab44fc 2021-07-31 op .It Ic version
 83 17ab44fc 2021-07-31 op Negotiate the version and maximum message size.
 84 17ab44fc 2021-07-31 op .Bd -literal
 85 17ab44fc 2021-07-31 op len[4] Tversion tag[2] msize[4] version[s]
 86 17ab44fc 2021-07-31 op len[4] Rversion tag[2] msize[4] version[s]
 87 17ab44fc 2021-07-31 op .Ed
 88 17ab44fc 2021-07-31 op .Pp
 89 17ab44fc 2021-07-31 op The
 90 17ab44fc 2021-07-31 op .Ic version
 91 17ab44fc 2021-07-31 op request must be the first message sent, and the client cannot issue
 92 17ab44fc 2021-07-31 op further requests until it has received the Rversion reply.
 93 17ab44fc 2021-07-31 op .Cm tag
 94 17ab44fc 2021-07-31 op should be
 95 17ab44fc 2021-07-31 op .Dv NOTAG
 96 3d1d2398 2021-08-04 op .Pq \-1 or 255 .
 97 17ab44fc 2021-07-31 op The client suggest a
 98 17ab44fc 2021-07-31 op .Cm msize
 99 17ab44fc 2021-07-31 op .Pq the maximum size for packets
100 3d1d2398 2021-08-04 op and the protocol version used, the server replies with a
101 17ab44fc 2021-07-31 op .Cm msize
102 17ab44fc 2021-07-31 op smaller or equal to the one proposed by the client.
103 17ab44fc 2021-07-31 op The version string must always begin with the two character
104 17ab44fc 2021-07-31 op .Dq 9P .
105 17ab44fc 2021-07-31 op If the server don't understand the client required version, should
106 17ab44fc 2021-07-31 op reply with a Rversion using the version string
107 17ab44fc 2021-07-31 op .Dq unknown
108 17ab44fc 2021-07-31 op and not use a Rerror.
109 17ab44fc 2021-07-31 op .It Ic attach
110 17ab44fc 2021-07-31 op Populate the namespace
111 17ab44fc 2021-07-31 op .Bd -literal
112 17ab44fc 2021-07-31 op len[4] Tattach tag[2] fid[4] afid[4] uname[s] aname[s]
113 17ab44fc 2021-07-31 op len[4] Rattach tag[2] qid[13]
114 17ab44fc 2021-07-31 op .Ed
115 17ab44fc 2021-07-31 op .It Ic clunk
116 17ab44fc 2021-07-31 op Close fids.
117 17ab44fc 2021-07-31 op .Bd -literal
118 17ab44fc 2021-07-31 op len[4] Tclunk tag[2] fid[4]
119 17ab44fc 2021-07-31 op len[4] Rclunk tag[2]
120 17ab44fc 2021-07-31 op .Ed
121 17ab44fc 2021-07-31 op .It Ic error
122 17ab44fc 2021-07-31 op Return an error string
123 17ab44fc 2021-07-31 op .Bd -literal
124 17ab44fc 2021-07-31 op len[4] Rerror tag[2] ename[s]
125 17ab44fc 2021-07-31 op .Ed
126 17ab44fc 2021-07-31 op .Pp
127 17ab44fc 2021-07-31 op The Rerror message is used to return an error string describing the
128 17ab44fc 2021-07-31 op failure of a request.
129 17ab44fc 2021-07-31 op .Cm tag
130 17ab44fc 2021-07-31 op indicates the failed request.
131 17ab44fc 2021-07-31 op Note that there isn't a Terror, and it's not possible for a server to
132 17ab44fc 2021-07-31 op reply to a
133 17ab44fc 2021-07-31 op .Ic Tversion
134 17ab44fc 2021-07-31 op using Rerror.
135 17ab44fc 2021-07-31 op .It Ic flush
136 17ab44fc 2021-07-31 op Abort an ongoing operation.
137 17ab44fc 2021-07-31 op .Bd -literal
138 17ab44fc 2021-07-31 op len[4] Tflush tag[2] oldtag[2]
139 17ab44fc 2021-07-31 op len[4] Rflush tag[2]
140 17ab44fc 2021-07-31 op .Ed
141 17ab44fc 2021-07-31 op .El
142 17ab44fc 2021-07-31 op .Sh SEE ALSO
143 17ab44fc 2021-07-31 op .Xr utf8 7 ,
144 17ab44fc 2021-07-31 op .Xr kamid 8