1 17ab44fc 2021-07-31 op .\" Copyright (c) 2021 Omar Polo <op@omarpolo.com>
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.
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.
15 17ab44fc 2021-07-31 op .Dd $Mdocdate: July 30 2021 $
20 17ab44fc 2021-07-31 op .Nd Simple Distributed File System
21 17ab44fc 2021-07-31 op .Sh DESCRIPTION
23 3d1d2398 2021-08-04 op is a protocol that implements a 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.
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.
38 3d1d2398 2021-08-04 op Each message consists of a sequence of bytes mostly grouped in one,
39 3d1d2398 2021-08-04 op two or four 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 3d1d2398 2021-08-04 op The only exception to this rule are QIDs, thirteen byte long
44 3d1d2398 2021-08-04 op objects, that are sent as-is.
46 3d1d2398 2021-08-04 op Text strings are represented with a two-byte count and the sequence of
47 3d1d2398 2021-08-04 op UNICODE codepoints encoded in UTF-8.
48 3d1d2398 2021-08-04 op Text strings in 9p are not NUL-terminated.
49 17ab44fc 2021-07-31 op The NUL-terminator is illegal in all text strings and thus excluded
50 17ab44fc 2021-07-31 op from paths, user names and so on.
52 17ab44fc 2021-07-31 op Fields are hereafter denoted as
53 17ab44fc 2021-07-31 op .Bd -literal -offset indent
54 17ab44fc 2021-07-31 op type[1] tag[2] fid[4]
57 17ab44fc 2021-07-31 op to indicate that type is one byte long, tag two and fid four.
58 17ab44fc 2021-07-31 op Strings are denoted as name[s] and are sent on the wire as
59 17ab44fc 2021-07-31 op .Bd -literal -offset indent
60 17ab44fc 2021-07-31 op length[2] string[length]
63 17ab44fc 2021-07-31 op A qid, described later, is a 13-byte value that is sent on the wire as
64 17ab44fc 2021-07-31 op .Bd -literal -offset indent
65 17ab44fc 2021-07-31 op type[1] version[4] path[8]
67 3d1d2398 2021-08-04 op .Sh MESSAGE STRUCTURE
68 17ab44fc 2021-07-31 op Every message has a header with the following fields:
69 17ab44fc 2021-07-31 op .Bd -literal -offset indent
70 17ab44fc 2021-07-31 op len[4] type[1] tag[2]
73 17ab44fc 2021-07-31 op where len indicates the overall length of the message, including
74 17ab44fc 2021-07-31 op itself; type is one byte indicating the type of the message and the
75 3d1d2398 2021-08-04 op tag is a number choosen by the client that indicate uniquely the
77 3d1d2398 2021-08-04 op Then follows an optional body whose structure depends on the type of
80 17ab44fc 2021-07-31 op The message types are as follows:
81 d3d4880e 2021-12-02 op .Pq the header is omitted for brevity
82 17ab44fc 2021-07-31 op .Bl -tag -width versionxx
83 17ab44fc 2021-07-31 op .It Ic version
84 17ab44fc 2021-07-31 op Negotiate the version and maximum message size.
86 3756a3df 2021-08-08 op msize[4] version[s]
87 3756a3df 2021-08-08 op msize[4] version[s]
92 17ab44fc 2021-07-31 op request must be the first message sent, and the client cannot issue
93 d3d4880e 2021-12-02 op further requests until receiving the Rversion reply.
97 3d1d2398 2021-08-04 op .Pq \-1 or 255 .
98 17ab44fc 2021-07-31 op The client suggest a
100 17ab44fc 2021-07-31 op .Pq the maximum size for packets
101 3d1d2398 2021-08-04 op and the protocol version used, the server replies with a
103 17ab44fc 2021-07-31 op smaller or equal to the one proposed by the client.
104 17ab44fc 2021-07-31 op The version string must always begin with the two character
106 17ab44fc 2021-07-31 op If the server don't understand the client required version, should
107 17ab44fc 2021-07-31 op reply with a Rversion using the version string
109 17ab44fc 2021-07-31 op and not use a Rerror.
110 17ab44fc 2021-07-31 op .It Ic attach
111 17ab44fc 2021-07-31 op Populate the namespace
113 3756a3df 2021-08-08 op fid[4] afid[4] uname[s] aname[s]
119 30d22cc7 2021-12-14 op message binds the given
121 30d22cc7 2021-12-14 op to the root of the file tree identified by
124 30d22cc7 2021-12-14 op identifies the user and
126 30d22cc7 2021-12-14 op specifies a fid previously established by an auth message, or the
130 30d22cc7 2021-12-14 op .Pq defined as (u32int)~0
131 30d22cc7 2021-12-14 op if the authentication is not required.
136 3756a3df 2021-08-08 op .Aq empty response
139 30d22cc7 2021-12-14 op Once a fid has been clunked
143 30d22cc7 2021-12-14 op and the same value can be used for subsequential
149 30d22cc7 2021-12-14 op The actual file on the disk is not remove unless it was opened with the
153 30d22cc7 2021-12-14 op Return an error string.
158 17ab44fc 2021-07-31 op The Rerror message is used to return an error string describing the
159 17ab44fc 2021-07-31 op failure of a request.
162 17ab44fc 2021-07-31 op indicates the failed request.
164 3756a3df 2021-08-08 op Note that there isn't a
166 30d22cc7 2021-12-14 op request for obvious reason and it's not possible for a server to reply to
174 17ab44fc 2021-07-31 op Abort an ongoing operation.
177 3756a3df 2021-08-08 op .Aq empty response
180 30d22cc7 2021-12-14 op Given the asynchronous nature of the protocol, the server may respond to
181 30d22cc7 2021-12-14 op the pending request before responding to the
183 30d22cc7 2021-12-14 op and is possible for a client to send multiple
185 30d22cc7 2021-12-14 op for the same operation.
186 30d22cc7 2021-12-14 op The client must wait to receive a corresponding
188 30d22cc7 2021-12-14 op before reusing
190 30d22cc7 2021-12-14 op for subsequent messages.
192 30d22cc7 2021-12-14 op If a response for
194 30d22cc7 2021-12-14 op is received before the
196 30d22cc7 2021-12-14 op reply, the client must assume that the operation was completed with success
197 30d22cc7 2021-12-14 op .Pq fid allocated, files created, ...
198 30d22cc7 2021-12-14 op If no response is received before the
200 30d22cc7 2021-12-14 op then the transaction is considered to have been successfully cancelled.
202 30d22cc7 2021-12-14 op Note that the tag of this request and the corresponding reply is NOT
204 30d22cc7 2021-12-14 op but a new tag value.
206 5ab50685 2021-08-08 op Traverse a file tree.
208 3756a3df 2021-08-08 op fid[4] newfid[4] nwname[2] nwname*(wname[s])
209 3756a3df 2021-08-08 op nwqid[2] nwqid*(qid[13])
214 30d22cc7 2021-12-14 op components are walked in order starting from
216 30d22cc7 2021-12-14 op .Pq which must point to a directory
217 30d22cc7 2021-12-14 op and, if successful,
219 30d22cc7 2021-12-14 op is associated to the reached file.
221 30d22cc7 2021-12-14 op It is possible for
225 30d22cc7 2021-12-14 op to be equal, in this case the fid is
226 30d22cc7 2021-12-14 op .Dq mutated ,
229 30d22cc7 2021-12-14 op must be unused.
230 30d22cc7 2021-12-14 op As a special case, a walk of zero components duplicates the fid.
232 30d22cc7 2021-12-14 op If the first element cannot be walked for any reason an
237 30d22cc7 2021-12-14 op is returned with a number of qids equal to the file viside by the walk.
238 30d22cc7 2021-12-14 op A client can thus detect a walk when that the replied
240 30d22cc7 2021-12-14 op number is not equal to the
242 30d22cc7 2021-12-14 op field in the request.
243 30d22cc7 2021-12-14 op Only when walk return successfully
245 30d22cc7 2021-12-14 op will be affected.
247 30d22cc7 2021-12-14 op A maximum of 16 component can be used per walk request.
249 30d22cc7 2021-12-14 op Prepare a fid for I/O.
251 021481ca 2021-12-13 op fid[4] mode[1]
252 021481ca 2021-12-13 op qid[13] iounit[4]
256 30d22cc7 2021-12-14 op determines the type of I/O:
257 30d22cc7 2021-12-14 op .Bl -tag -width Ds -offset indent -compact
258 30d22cc7 2021-12-14 op .It 0 Dt OREAD
259 30d22cc7 2021-12-14 op .It 1 Dt OWRITE
260 30d22cc7 2021-12-14 op .It 2 Dt ORDWD
261 30d22cc7 2021-12-14 op .It 3 Dt OEXEC
266 30d22cc7 2021-12-14 op is the optimal blocksize for I/O.
