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 17ab44fc 2021-07-31 op is a protocol for 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 17ab44fc 2021-07-31 op Each message consists of a sequence of bytes grouped in one, two, four
 39 17ab44fc 2021-07-31 op and eight-byte 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 17ab44fc 2021-07-31 op Text strings are represented in a similar manner, with a two-byte
 44 17ab44fc 2021-07-31 op count and the sequence of UNICODE codepoints encoded in UTF-8.
 45 17ab44fc 2021-07-31 op Text strings in 9p are not NUL-Terminated.
 46 17ab44fc 2021-07-31 op The NUL-terminator is illegal in all text strings and thus excluded
 47 17ab44fc 2021-07-31 op from paths, user names and so on.
 48 17ab44fc 2021-07-31 op .Pp
 49 17ab44fc 2021-07-31 op Fields are hereafter denoted as
 50 17ab44fc 2021-07-31 op .Bd -literal -offset indent
 51 17ab44fc 2021-07-31 op type[1] tag[2] fid[4]
 52 17ab44fc 2021-07-31 op .Ed
 53 17ab44fc 2021-07-31 op .Pp
 54 17ab44fc 2021-07-31 op to indicate that type is one byte long, tag two and fid four.
 55 17ab44fc 2021-07-31 op Strings are denoted as name[s] and are sent on the wire as
 56 17ab44fc 2021-07-31 op .Bd -literal -offset indent
 57 17ab44fc 2021-07-31 op length[2] string[length]
 58 17ab44fc 2021-07-31 op .Ed
 59 17ab44fc 2021-07-31 op .Pp
 60 17ab44fc 2021-07-31 op A qid, described later, is a 13-byte value that is sent on the wire as
 61 17ab44fc 2021-07-31 op .Bd -literal -offset indent
 62 17ab44fc 2021-07-31 op type[1] version[4] path[8]
 63 17ab44fc 2021-07-31 op .Ed
 64 17ab44fc 2021-07-31 op .Pp
 65 17ab44fc 2021-07-31 op Every message has a header with the following fields:
 66 17ab44fc 2021-07-31 op .Bd -literal -offset indent
 67 17ab44fc 2021-07-31 op len[4] type[1] tag[2]
 68 17ab44fc 2021-07-31 op .Ed
 69 17ab44fc 2021-07-31 op .Pp
 70 17ab44fc 2021-07-31 op where len indicates the overall length of the message, including
 71 17ab44fc 2021-07-31 op itself; type is one byte indicating the type of the message and the
 72 17ab44fc 2021-07-31 op tag is a number choosen by the client to indicate uniquely the
 73 17ab44fc 2021-07-31 op request.
 74 17ab44fc 2021-07-31 op Then follows the optional body of the message whose structure depends
 75 17ab44fc 2021-07-31 op on the the type of the message itself.
 76 17ab44fc 2021-07-31 op .Pp
 77 17ab44fc 2021-07-31 op The message types are as follows:
 78 17ab44fc 2021-07-31 op .Bl -tag -width versionxx
 79 17ab44fc 2021-07-31 op .It Ic version
 80 17ab44fc 2021-07-31 op Negotiate the version and maximum message size.
 81 17ab44fc 2021-07-31 op .Bd -literal
 82 17ab44fc 2021-07-31 op len[4] Tversion tag[2] msize[4] version[s]
 83 17ab44fc 2021-07-31 op len[4] Rversion tag[2] msize[4] version[s]
 84 17ab44fc 2021-07-31 op .Ed
 85 17ab44fc 2021-07-31 op .Pp
 86 17ab44fc 2021-07-31 op The
 87 17ab44fc 2021-07-31 op .Ic version
 88 17ab44fc 2021-07-31 op request must be the first message sent, and the client cannot issue
 89 17ab44fc 2021-07-31 op further requests until it has received the Rversion reply.
 90 17ab44fc 2021-07-31 op .Cm tag
 91 17ab44fc 2021-07-31 op should be
 92 17ab44fc 2021-07-31 op .Dv NOTAG
 93 17ab44fc 2021-07-31 op .Pq \-1
 94 17ab44fc 2021-07-31 op The client suggest a
 95 17ab44fc 2021-07-31 op .Cm msize
 96 17ab44fc 2021-07-31 op .Pq the maximum size for packets
 97 17ab44fc 2021-07-31 op and the version they're using, the server replies with a
 98 17ab44fc 2021-07-31 op .Cm msize
 99 17ab44fc 2021-07-31 op smaller or equal to the one proposed by the client.
100 17ab44fc 2021-07-31 op The version string must always begin with the two character
101 17ab44fc 2021-07-31 op .Dq 9P .
102 17ab44fc 2021-07-31 op If the server don't understand the client required version, should
103 17ab44fc 2021-07-31 op reply with a Rversion using the version string
104 17ab44fc 2021-07-31 op .Dq unknown
105 17ab44fc 2021-07-31 op and not use a Rerror.
106 17ab44fc 2021-07-31 op .It Ic attach
107 17ab44fc 2021-07-31 op Populate the namespace
108 17ab44fc 2021-07-31 op .Bd -literal
109 17ab44fc 2021-07-31 op len[4] Tattach tag[2] fid[4] afid[4] uname[s] aname[s]
110 17ab44fc 2021-07-31 op len[4] Rattach tag[2] qid[13]
111 17ab44fc 2021-07-31 op .Ed
112 17ab44fc 2021-07-31 op .It Ic clunk
113 17ab44fc 2021-07-31 op Close fids.
114 17ab44fc 2021-07-31 op .Bd -literal
115 17ab44fc 2021-07-31 op len[4] Tclunk tag[2] fid[4]
116 17ab44fc 2021-07-31 op len[4] Rclunk tag[2]
117 17ab44fc 2021-07-31 op .Ed
118 17ab44fc 2021-07-31 op .It Ic error
119 17ab44fc 2021-07-31 op Return an error string
120 17ab44fc 2021-07-31 op .Bd -literal
121 17ab44fc 2021-07-31 op len[4] Rerror tag[2] ename[s]
122 17ab44fc 2021-07-31 op .Ed
123 17ab44fc 2021-07-31 op .Pp
124 17ab44fc 2021-07-31 op The Rerror message is used to return an error string describing the
125 17ab44fc 2021-07-31 op failure of a request.
126 17ab44fc 2021-07-31 op .Cm tag
127 17ab44fc 2021-07-31 op indicates the failed request.
128 17ab44fc 2021-07-31 op Note that there isn't a Terror, and it's not possible for a server to
129 17ab44fc 2021-07-31 op reply to a
130 17ab44fc 2021-07-31 op .Ic Tversion
131 17ab44fc 2021-07-31 op using Rerror.
132 17ab44fc 2021-07-31 op .It Ic flush
133 17ab44fc 2021-07-31 op Abort an ongoing operation.
134 17ab44fc 2021-07-31 op .Bd -literal
135 17ab44fc 2021-07-31 op len[4] Tflush tag[2] oldtag[2]
136 17ab44fc 2021-07-31 op len[4] Rflush tag[2]
137 17ab44fc 2021-07-31 op .Ed
138 17ab44fc 2021-07-31 op .El
139 17ab44fc 2021-07-31 op .Sh SEE ALSO
140 17ab44fc 2021-07-31 op .Xr utf8 7 ,
141 17ab44fc 2021-07-31 op .Xr kamid 8