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 for 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 grouped in one, two, four
39 and eight-byte 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 Text strings are represented in a similar manner, with a two-byte
44 count and the sequence of UNICODE codepoints encoded in UTF-8.
45 Text strings in 9p are not NUL-Terminated.
46 The NUL-terminator is illegal in all text strings and thus excluded
47 from paths, user names and so on.
49 Fields are hereafter denoted as
50 .Bd -literal -offset indent
54 to indicate that type is one byte long, tag two and fid four.
55 Strings are denoted as name[s] and are sent on the wire as
56 .Bd -literal -offset indent
57 length[2] string[length]
60 A qid, described later, is a 13-byte value that is sent on the wire as
61 .Bd -literal -offset indent
62 type[1] version[4] path[8]
65 Every message has a header with the following fields:
66 .Bd -literal -offset indent
70 where len indicates the overall length of the message, including
71 itself; type is one byte indicating the type of the message and the
72 tag is a number choosen by the client to indicate uniquely the
74 Then follows the optional body of the message whose structure depends
75 on the the type of the message itself.
77 The message types are as follows:
78 .Bl -tag -width versionxx
80 Negotiate the version and maximum message size.
82 len[4] Tversion tag[2] msize[4] version[s]
83 len[4] Rversion tag[2] msize[4] version[s]
88 request must be the first message sent, and the client cannot issue
89 further requests until it has received the Rversion reply.
96 .Pq the maximum size for packets
97 and the version they're using, the server replies with a
99 smaller or equal to the one proposed by the client.
100 The version string must always begin with the two character
102 If the server don't understand the client required version, should
103 reply with a Rversion using the version string
105 and not use a Rerror.
107 Populate the namespace
109 len[4] Tattach tag[2] fid[4] afid[4] uname[s] aname[s]
110 len[4] Rattach tag[2] qid[13]
115 len[4] Tclunk tag[2] fid[4]
119 Return an error string
121 len[4] Rerror tag[2] ename[s]
124 The Rerror message is used to return an error string describing the
125 failure of a request.
127 indicates the failed request.
128 Note that there isn't a Terror, and it's not possible for a server to
133 Abort an ongoing operation.
135 len[4] Tflush tag[2] oldtag[2]
