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