1 .\" Copyright (c) 2021 Omar Polo <op@omarpolo.com>
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.
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.
15 .Dd $Mdocdate: July 30 2021 $
20 .Nd Simple Distributed File System
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.
30 A client transmits requests
32 to a server, which returns replies
35 The combined acts of transmitting a request of a particular type and
36 receiving a reply is called a transaction of that type.
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.
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.
52 Fields are hereafter denoted as
53 .Bd -literal -offset indent
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]
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]
68 Every message has a header with the following fields:
69 .Bd -literal -offset indent
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
77 Then follows an optional body whose structure depends on the type of
80 The message types are as follows:
81 .Pq the header is omitted for brevity
82 .Bl -tag -width versionxx
84 Negotiate the version and maximum message size.
92 request must be the first message sent, and the client cannot issue
93 further requests until receiving the Rversion reply.
100 .Pq the maximum size for packets
101 and the protocol version used, the server replies with a
103 smaller or equal to the one proposed by the client.
104 The version string must always begin with the two character
106 If the server don't understand the client required version, should
107 reply with a Rversion using the version string
109 and not use a Rerror.
111 Populate the namespace
113 fid[4] afid[4] uname[s] aname[s]
119 message binds the given
121 to the root of the file tree identified by
124 identifies the user and
126 specifies a fid previously established by an auth message, or the
130 .Pq defined as (u32int_t)~0
131 if the authentication is not required.
139 Once a fid has been clunked
143 and the same value can be used for subsequential
149 The actual file on the disk is not removed unless it was opened with the
153 Return an error string.
159 The Rerror message is used to return an error string describing the
160 failure of a request.
163 indicates the failed request.
165 Note that there isn't a
167 request for obvious reason and it's not possible for a server to reply to
175 Abort an ongoing operation.
181 Given the asynchronous nature of the protocol, the server may respond to
182 the pending request before responding to the
184 and is possible for a client to send multiple
186 for the same operation.
187 The client must wait to receive a corresponding
191 for subsequent messages.
195 is received before the
197 reply, the client must assume that the operation was completed with success
198 .Pq fid allocated, files created, ...
199 If no response is received before the
201 then the transaction is considered to have been successfully cancelled.
203 Note that the tag of this request and the corresponding reply is NOT
207 Traverse a file tree.
209 fid[4] newfid[4] nwname[2] nwname*(wname[s])
210 nwqid[2] nwqid*(qid[13])
215 components are walked in order starting from
217 .Pq which must point to a directory
220 is associated to the reached file.
226 to be equal, in this case the fid is
231 As a special case, a walk of zero components duplicates the fid.
233 If the first element cannot be walked for any reason an
238 is returned with a number of qids equal to the file viside by the walk.
239 A client can thus detect a walk when that the replied
241 number is not equal to the
243 field in the request.
244 Only when walk return successfully
248 A maximum of 16 component can be used per walk request.
250 Prepare a fid for I/O.
257 determines the type of I/O:
258 .Bl -tag -width Ds -offset indent -compact
260 Open the file for reading.
261 .It 0x01 Pq Dv OWRITE
262 Open the file for writing.
264 Open the file for both reading and writing.
269 Additionally, the following flags can be or'ed to
271 .Bl -tag -width Ds -offset indent -compact
272 .It 0x10 Pq Dv OTRUNC
273 Truncate the file before opening
274 .It 0x40 Pq Dv ORCLOSE
281 is the optimal blocksize for I/O.
285 fid[4] name[s] perm[4] mode[1]
289 The call attempts to create a file named
291 in the directory identified by
295 and then to open it with
300 It is illegal to use an already opened
302 or to attempt to create the
310 fid[4] offset[8] count[4]
315 must have been prepared for I/O with a previous
320 is zero when reaching end-of-file and may be lesser than what requested.
322 Directories are a stream of stat structures, as described in
324 and for them the read request message must have offset equal to zero or
327 in the previous read on the directory plus the number of bytes returned
328 in the previous read.
329 Thus, is not possible to seek into directories except for rewinding.
333 fid[4] offset[8] count[4] data[count]
338 must have been prepared for I/O with a previous
345 is the amount of data actually written and may differ from the one in
354 The stat structure is made by the following fields:
355 .Bl -tag -width tenletters -compact
357 total byte count of the following data
363 server unique identifier of the file
365 permissions and flags
369 last modification time
371 length of file in bytes
376 if the file is the root directory of the server)
382 name of the user who last modified the file.
387 is always present, even in the
390 While it may be considered redundant, it's kept to simplify the
391 parsing of the stat entries in a directory.
393 Change file attributes
400 must have been prepared for writing with a previous
408 structure is the same described in
413 structure sent reflect what changes the client wishes to make to the
415 To leave some fields as unchanged, use empty string or the maximum
416 allowed value for integral fields.
417 For example, to avoid changing the permission of the fid use
418 0xFFFFFFFF, or (uint32_t)-1.
428 call, even if an error is returned, the
432 .\" .Sh 9P2000.L EXTENSIONS
434 .\" supports also a subset of the
437 .\" The supported messages are
438 .\" .Bl -tag -width readdir
440 .\" Read directory entries
442 .\" fid[4] offset[8] count[4]
443 .\" count[4] data[count]
446 .\" Each directory entry is described by a variable-length record:
447 .\" .Ql qid[13] offset[8] type[1] name[s] .
448 .\" Offset is zero upon the first call.
453 .\" response is not zero then more data is available.
456 .\" is allowed to be zero in the request.
