1 fb1a36c0 2022-01-09 op .\" Copyright (c) 2021 Omar Polo <op@omarpolo.com>
3 fb1a36c0 2022-01-09 op .\" Permission to use, copy, modify, and distribute this software for any
4 fb1a36c0 2022-01-09 op .\" purpose with or without fee is hereby granted, provided that the above
5 fb1a36c0 2022-01-09 op .\" copyright notice and this permission notice appear in all copies.
7 fb1a36c0 2022-01-09 op .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
8 fb1a36c0 2022-01-09 op .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
9 fb1a36c0 2022-01-09 op .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
10 fb1a36c0 2022-01-09 op .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
11 fb1a36c0 2022-01-09 op .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
12 fb1a36c0 2022-01-09 op .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
13 fb1a36c0 2022-01-09 op .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
15 fb1a36c0 2022-01-09 op .Dd $Mdocdate: July 30 2021 $
20 fb1a36c0 2022-01-09 op .Nd Simple Distributed File System
21 fb1a36c0 2022-01-09 op .Sh DESCRIPTION
23 fb1a36c0 2022-01-09 op is a protocol that implements a distributed file systems.
24 fb1a36c0 2022-01-09 op It provides primitives to manage
25 fb1a36c0 2022-01-09 op .Pq create, read, write and delete
26 fb1a36c0 2022-01-09 op sets of files remotely.
27 fb1a36c0 2022-01-09 op These files don't necessarily need to be actually stored on a disk,
28 fb1a36c0 2022-01-09 op they may be, for example, synthesise on demand from external sources.
30 fb1a36c0 2022-01-09 op A client transmits requests
31 fb1a36c0 2022-01-09 op .Pq T-messages
32 fb1a36c0 2022-01-09 op to a server, which returns replies
33 fb1a36c0 2022-01-09 op .Pq R-messages
34 fb1a36c0 2022-01-09 op to the client.
35 fb1a36c0 2022-01-09 op The combined acts of transmitting a request of a particular type and
36 fb1a36c0 2022-01-09 op receiving a reply is called a transaction of that type.
38 fb1a36c0 2022-01-09 op Each message consists of a sequence of bytes mostly grouped in one,
39 fb1a36c0 2022-01-09 op two or four integer fields transmitted in little-endian order
40 fb1a36c0 2022-01-09 op .Pq least significant byte first .
41 fb1a36c0 2022-01-09 op Data items of larger or variable lengths are represented by a two-byte
42 fb1a36c0 2022-01-09 op field specifying the length followed by the actual data.
43 fb1a36c0 2022-01-09 op The only exception to this rule are QIDs, thirteen byte long
44 fb1a36c0 2022-01-09 op objects, that are sent as-is.
46 fb1a36c0 2022-01-09 op Text strings are represented with a two-byte count and the sequence of
47 fb1a36c0 2022-01-09 op UNICODE codepoints encoded in UTF-8.
48 fb1a36c0 2022-01-09 op Text strings in 9p are not NUL-terminated.
49 fb1a36c0 2022-01-09 op The NUL-terminator is illegal in all text strings and thus excluded
50 fb1a36c0 2022-01-09 op from paths, user names and so on.
52 fb1a36c0 2022-01-09 op Fields are hereafter denoted as
53 fb1a36c0 2022-01-09 op .Bd -literal -offset indent
54 fb1a36c0 2022-01-09 op type[1] tag[2] fid[4]
57 fb1a36c0 2022-01-09 op to indicate that type is one byte long, tag two and fid four.
58 fb1a36c0 2022-01-09 op Strings are denoted as name[s] and are sent on the wire as
59 fb1a36c0 2022-01-09 op .Bd -literal -offset indent
60 fb1a36c0 2022-01-09 op length[2] string[length]
63 fb1a36c0 2022-01-09 op A qid, described later, is a 13-byte value that is sent on the wire as
64 fb1a36c0 2022-01-09 op .Bd -literal -offset indent
65 fb1a36c0 2022-01-09 op type[1] version[4] path[8]
67 fb1a36c0 2022-01-09 op .Sh MESSAGE STRUCTURE
68 fb1a36c0 2022-01-09 op Every message has a header with the following fields:
69 fb1a36c0 2022-01-09 op .Bd -literal -offset indent
70 fb1a36c0 2022-01-09 op len[4] type[1] tag[2]
73 fb1a36c0 2022-01-09 op where len indicates the overall length of the message, including
74 fb1a36c0 2022-01-09 op itself; type is one byte indicating the type of the message and the
75 fb1a36c0 2022-01-09 op tag is a number choosen by the client that indicate uniquely the
77 fb1a36c0 2022-01-09 op Then follows an optional body whose structure depends on the type of
80 fb1a36c0 2022-01-09 op The message types are as follows:
81 fb1a36c0 2022-01-09 op .Pq the header is omitted for brevity
82 fb1a36c0 2022-01-09 op .Bl -tag -width versionxx
83 fb1a36c0 2022-01-09 op .It Ic version
84 fb1a36c0 2022-01-09 op Negotiate the version and maximum message size.
86 fb1a36c0 2022-01-09 op msize[4] version[s]
87 fb1a36c0 2022-01-09 op msize[4] version[s]
92 fb1a36c0 2022-01-09 op request must be the first message sent, and the client cannot issue
93 fb1a36c0 2022-01-09 op further requests until receiving the Rversion reply.
97 fb1a36c0 2022-01-09 op .Pq \-1 or 255 .
98 fb1a36c0 2022-01-09 op The client suggest a
100 fb1a36c0 2022-01-09 op .Pq the maximum size for packets
101 fb1a36c0 2022-01-09 op and the protocol version used, the server replies with a
103 fb1a36c0 2022-01-09 op smaller or equal to the one proposed by the client.
104 fb1a36c0 2022-01-09 op The version string must always begin with the two character
106 fb1a36c0 2022-01-09 op If the server don't understand the client required version, should
107 fb1a36c0 2022-01-09 op reply with a Rversion using the version string
109 fb1a36c0 2022-01-09 op and not use a Rerror.
110 fb1a36c0 2022-01-09 op .It Ic attach
111 fb1a36c0 2022-01-09 op Populate the namespace
113 fb1a36c0 2022-01-09 op fid[4] afid[4] uname[s] aname[s]
119 fb1a36c0 2022-01-09 op message binds the given
121 fb1a36c0 2022-01-09 op to the root of the file tree identified by
124 fb1a36c0 2022-01-09 op identifies the user and
126 fb1a36c0 2022-01-09 op specifies a fid previously established by an auth message, or the
130 e13d3f6e 2022-01-22 op .Pq defined as (u32int_t)~0
131 fb1a36c0 2022-01-09 op if the authentication is not required.
136 fb1a36c0 2022-01-09 op .Aq empty response
139 fb1a36c0 2022-01-09 op Once a fid has been clunked
143 fb1a36c0 2022-01-09 op and the same value can be used for subsequential
149 a452e7cd 2022-01-23 op The actual file on the disk is not removed unless it was opened with the
153 fb1a36c0 2022-01-09 op Return an error string.
155 92f79c88 2022-01-22 op .Aq no request
159 fb1a36c0 2022-01-09 op The Rerror message is used to return an error string describing the
160 fb1a36c0 2022-01-09 op failure of a request.
163 fb1a36c0 2022-01-09 op indicates the failed request.
165 fb1a36c0 2022-01-09 op Note that there isn't a
167 fb1a36c0 2022-01-09 op request for obvious reason and it's not possible for a server to reply to
175 fb1a36c0 2022-01-09 op Abort an ongoing operation.
178 fb1a36c0 2022-01-09 op .Aq empty response
181 fb1a36c0 2022-01-09 op Given the asynchronous nature of the protocol, the server may respond to
182 fb1a36c0 2022-01-09 op the pending request before responding to the
184 fb1a36c0 2022-01-09 op and is possible for a client to send multiple
186 fb1a36c0 2022-01-09 op for the same operation.
187 fb1a36c0 2022-01-09 op The client must wait to receive a corresponding
189 fb1a36c0 2022-01-09 op before reusing
191 fb1a36c0 2022-01-09 op for subsequent messages.
193 fb1a36c0 2022-01-09 op If a response for
195 fb1a36c0 2022-01-09 op is received before the
197 fb1a36c0 2022-01-09 op reply, the client must assume that the operation was completed with success
198 fb1a36c0 2022-01-09 op .Pq fid allocated, files created, ...
199 fb1a36c0 2022-01-09 op If no response is received before the
201 fb1a36c0 2022-01-09 op then the transaction is considered to have been successfully cancelled.
203 fb1a36c0 2022-01-09 op Note that the tag of this request and the corresponding reply is NOT
205 fb1a36c0 2022-01-09 op but a new tag value.
207 fb1a36c0 2022-01-09 op Traverse a file tree.
209 fb1a36c0 2022-01-09 op fid[4] newfid[4] nwname[2] nwname*(wname[s])
210 fb1a36c0 2022-01-09 op nwqid[2] nwqid*(qid[13])
215 fb1a36c0 2022-01-09 op components are walked in order starting from
217 fb1a36c0 2022-01-09 op .Pq which must point to a directory
218 fb1a36c0 2022-01-09 op and, if successful,
220 fb1a36c0 2022-01-09 op is associated to the reached file.
222 fb1a36c0 2022-01-09 op It is possible for
226 fb1a36c0 2022-01-09 op to be equal, in this case the fid is
227 fb1a36c0 2022-01-09 op .Dq mutated ,
230 fb1a36c0 2022-01-09 op must be unused.
231 fb1a36c0 2022-01-09 op As a special case, a walk of zero components duplicates the fid.
233 fb1a36c0 2022-01-09 op If the first element cannot be walked for any reason an
238 1add4faa 2022-12-21 op is returned with a number of qids equal to the file visited by the walk.
239 1add4faa 2022-12-21 op A client can thus detect a failed walk when the replied
241 fb1a36c0 2022-01-09 op number is not equal to the
243 fb1a36c0 2022-01-09 op field in the request.
244 fb1a36c0 2022-01-09 op Only when walk return successfully
246 fb1a36c0 2022-01-09 op will be affected.
248 fb1a36c0 2022-01-09 op A maximum of 16 component can be used per walk request.
250 fb1a36c0 2022-01-09 op Prepare a fid for I/O.
252 fb1a36c0 2022-01-09 op fid[4] mode[1]
253 fb1a36c0 2022-01-09 op qid[13] iounit[4]
257 fb1a36c0 2022-01-09 op determines the type of I/O:
258 fb1a36c0 2022-01-09 op .Bl -tag -width Ds -offset indent -compact
259 92f79c88 2022-01-22 op .It 0x00 Pq Dv OREAD
260 92f79c88 2022-01-22 op Open the file for reading.
261 92f79c88 2022-01-22 op .It 0x01 Pq Dv OWRITE
262 92f79c88 2022-01-22 op Open the file for writing.
263 92f79c88 2022-01-22 op .It 0x02 Pq Dv ORDWD
264 92f79c88 2022-01-22 op Open the file for both reading and writing.
265 92f79c88 2022-01-22 op .It 0x03 Pq Dv OEXEC
266 92f79c88 2022-01-22 op Open for exec.
269 92f79c88 2022-01-22 op Additionally, the following flags can be or'ed to
271 92f79c88 2022-01-22 op .Bl -tag -width Ds -offset indent -compact
272 92f79c88 2022-01-22 op .It 0x10 Pq Dv OTRUNC
273 92f79c88 2022-01-22 op Truncate the file before opening
274 92f79c88 2022-01-22 op .It 0x40 Pq Dv ORCLOSE
275 92f79c88 2022-01-22 op Remove the file upon
281 fb1a36c0 2022-01-09 op is the optimal blocksize for I/O.
282 fb1a36c0 2022-01-09 op .It Ic create
283 fb1a36c0 2022-01-09 op Create a file
285 fb1a36c0 2022-01-09 op fid[4] name[s] perm[4] mode[1]
286 fb1a36c0 2022-01-09 op qid[13] iounit[4]
289 fb1a36c0 2022-01-09 op The call attempts to create a file named
291 fb1a36c0 2022-01-09 op in the directory identified by
295 fb1a36c0 2022-01-09 op and then to open it with
297 fb1a36c0 2022-01-09 op into the given
300 fb1a36c0 2022-01-09 op It is illegal to use an already opened
302 fb1a36c0 2022-01-09 op or to attempt to create the
308 3bc95011 2022-01-31 op Read data at offset
310 fb1a36c0 2022-01-09 op fid[4] offset[8] count[4]
311 fb1a36c0 2022-01-09 op count[4] data[count]
315 fb1a36c0 2022-01-09 op must have been prepared for I/O with a previous
320 fb1a36c0 2022-01-09 op is zero when reaching end-of-file and may be lesser than what requested.
322 fb1a36c0 2022-01-09 op Directories are a stream of stat structures, as described in
324 fb1a36c0 2022-01-09 op and for them the read request message must have offset equal to zero or
327 fb1a36c0 2022-01-09 op in the previous read on the directory plus the number of bytes returned
328 fb1a36c0 2022-01-09 op in the previous read.
329 fb1a36c0 2022-01-09 op Thus, is not possible to seek into directories except for rewinding.
331 fb1a36c0 2022-01-09 op Write data at offset
333 fb1a36c0 2022-01-09 op fid[4] offset[8] count[4] data[count]
338 e13d3f6e 2022-01-22 op must have been prepared for I/O with a previous
345 e13d3f6e 2022-01-22 op is the amount of data actually written and may differ from the one in
348 92f79c88 2022-01-22 op Get file status
354 fb1a36c0 2022-01-09 op The stat structure is made by the following fields:
355 ea9dc606 2022-01-22 op .Bl -tag -width tenletters -compact
357 fb1a36c0 2022-01-09 op total byte count of the following data
359 fb1a36c0 2022-01-09 op for kernel use
361 fb1a36c0 2022-01-09 op for kernel use
363 fb1a36c0 2022-01-09 op server unique identifier of the file
365 fb1a36c0 2022-01-09 op permissions and flags
367 fb1a36c0 2022-01-09 op last access time
369 fb1a36c0 2022-01-09 op last modification time
370 fb1a36c0 2022-01-09 op .It length[8]
371 fb1a36c0 2022-01-09 op length of file in bytes
376 fb1a36c0 2022-01-09 op if the file is the root directory of the server)
382 fb1a36c0 2022-01-09 op name of the user who last modified the file.
385 2254cace 2022-01-22 op Note that the
387 e13d3f6e 2022-01-22 op is always present, even in the
390 2254cace 2022-01-22 op While it may be considered redundant, it's kept to simplify the
391 2254cace 2022-01-22 op parsing of the stat entries in a directory.
393 92f79c88 2022-01-22 op Change file attributes
395 cab30d8a 2022-01-22 op fid[4] stat[n]
396 cab30d8a 2022-01-22 op .Aq empty response
400 92f79c88 2022-01-22 op must have been prepared for writing with a previous
408 cab30d8a 2022-01-22 op structure is the same described in
413 cab30d8a 2022-01-22 op structure sent reflect what changes the client wishes to make to the
415 cab30d8a 2022-01-22 op To leave some fields as unchanged, use empty string or the maximum
416 cab30d8a 2022-01-22 op allowed value for integral fields.
417 cab30d8a 2022-01-22 op For example, to avoid changing the permission of the fid use
418 cab30d8a 2022-01-22 op 0xFFFFFFFF, or (uint32_t)-1.
419 fb1a36c0 2022-01-09 op .It Ic remove
420 12a6df20 2022-01-29 op Remove and clunk fid
423 fb1a36c0 2022-01-09 op .Aq empty response
428 12a6df20 2022-01-29 op call, even if an error is returned, the
432 fb1a36c0 2022-01-09 op .\" .Sh 9P2000.L EXTENSIONS
433 fb1a36c0 2022-01-09 op .\" .Xr kamid 8
434 fb1a36c0 2022-01-09 op .\" supports also a subset of the
435 fb1a36c0 2022-01-09 op .\" .Sq 9P2000.L
437 fb1a36c0 2022-01-09 op .\" The supported messages are
438 fb1a36c0 2022-01-09 op .\" .Bl -tag -width readdir
439 fb1a36c0 2022-01-09 op .\" .It Ic readdir
440 fb1a36c0 2022-01-09 op .\" Read directory entries
441 fb1a36c0 2022-01-09 op .\" .Bd -literal
442 fb1a36c0 2022-01-09 op .\" fid[4] offset[8] count[4]
443 fb1a36c0 2022-01-09 op .\" count[4] data[count]
446 fb1a36c0 2022-01-09 op .\" Each directory entry is described by a variable-length record:
447 fb1a36c0 2022-01-09 op .\" .Ql qid[13] offset[8] type[1] name[s] .
448 fb1a36c0 2022-01-09 op .\" Offset is zero upon the first call.
450 fb1a36c0 2022-01-09 op .\" .Ar count
451 fb1a36c0 2022-01-09 op .\" field in the
452 fb1a36c0 2022-01-09 op .\" .Ic Rreaddir
453 fb1a36c0 2022-01-09 op .\" response is not zero then more data is available.
455 fb1a36c0 2022-01-09 op .\" .Ar count
456 fb1a36c0 2022-01-09 op .\" is allowed to be zero in the request.