1 058b0118 2005-01-03 devnull .TH INTRO 9P
3 058b0118 2005-01-03 devnull intro \- introduction to the Plan 9 File Protocol, 9P
4 058b0118 2005-01-03 devnull .SH SYNOPSIS
5 058b0118 2005-01-03 devnull .B #include <fcall.h>
6 058b0118 2005-01-03 devnull .SH DESCRIPTION
9 058b0118 2005-01-03 devnull is an agent that provides one or more hierarchical file systems
10 058b0118 2005-01-03 devnull \(em file trees \(em
11 058b0118 2005-01-03 devnull that may be accessed by Plan 9 processes.
12 058b0118 2005-01-03 devnull A server responds to requests by
13 058b0118 2005-01-03 devnull .I clients
14 058b0118 2005-01-03 devnull to navigate the hierarchy,
15 058b0118 2005-01-03 devnull and to create, remove, read, and write files.
16 058b0118 2005-01-03 devnull The prototypical server is a separate machine that stores
17 058b0118 2005-01-03 devnull large numbers of user files on permanent media;
18 058b0118 2005-01-03 devnull such a machine is called, somewhat confusingly, a
20 058b0118 2005-01-03 devnull .IR server .
21 058b0118 2005-01-03 devnull Another possibility for a server is to synthesize
22 058b0118 2005-01-03 devnull files on demand, perhaps based on information on data structures
23 058b0118 2005-01-03 devnull maintained in memory; the
24 36cd4c58 2021-01-30 crossd .MR plumber (4)
25 058b0118 2005-01-03 devnull server is an example of such a server.
28 058b0118 2005-01-03 devnull .I connection
29 058b0118 2005-01-03 devnull to a server is a bidirectional communication path from the client to the server.
30 058b0118 2005-01-03 devnull There may be a single client or
31 058b0118 2005-01-03 devnull multiple clients sharing the same connection.
34 058b0118 2005-01-03 devnull .IR "Plan 9 File Protocol" ,
35 058b0118 2005-01-03 devnull 9P, is used for messages between
36 058b0118 2005-01-03 devnull .I clients
38 058b0118 2005-01-03 devnull .IR servers .
39 058b0118 2005-01-03 devnull A client transmits
40 058b0118 2005-01-03 devnull .I requests
41 058b0118 2005-01-03 devnull .RI ( T-messages )
42 058b0118 2005-01-03 devnull to a server, which
43 058b0118 2005-01-03 devnull subsequently returns
44 058b0118 2005-01-03 devnull .I replies
45 058b0118 2005-01-03 devnull .RI ( R-messages )
46 058b0118 2005-01-03 devnull to the client.
47 058b0118 2005-01-03 devnull The combined acts of transmitting (receiving) a request of a particular type,
48 058b0118 2005-01-03 devnull and receiving (transmitting)
49 058b0118 2005-01-03 devnull its reply is called a
50 058b0118 2005-01-03 devnull .I transaction
51 058b0118 2005-01-03 devnull of that type.
53 058b0118 2005-01-03 devnull Each message consists of a sequence of bytes.
54 058b0118 2005-01-03 devnull Two-, four-, and eight-byte fields hold unsigned
55 058b0118 2005-01-03 devnull integers represented in little-endian order
56 058b0118 2005-01-03 devnull (least significant byte first).
57 058b0118 2005-01-03 devnull Data items of larger or variable lengths are represented
58 058b0118 2005-01-03 devnull by a two-byte field specifying a count,
60 058b0118 2005-01-03 devnull followed by
62 058b0118 2005-01-03 devnull bytes of data.
63 058b0118 2005-01-03 devnull Text strings are represented this way,
64 058b0118 2005-01-03 devnull with the text itself stored as a UTF-8
65 058b0118 2005-01-03 devnull encoded sequence of Unicode characters (see
66 36cd4c58 2021-01-30 crossd .MR utf (7) ).
67 058b0118 2005-01-03 devnull Text strings in 9P messages are not
68 058b0118 2005-01-03 devnull .SM NUL\c
69 058b0118 2005-01-03 devnull -terminated:
71 058b0118 2005-01-03 devnull counts the bytes of UTF-8 data, which include no final zero byte.
74 058b0118 2005-01-03 devnull character is illegal in all text strings in 9P, and is therefore
75 058b0118 2005-01-03 devnull excluded from file names, user names, and so on.
77 058b0118 2005-01-03 devnull Each 9P message begins with a four-byte size field
78 058b0118 2005-01-03 devnull specifying the length in bytes of the complete message including
79 058b0118 2005-01-03 devnull the four bytes of the size field itself.
80 058b0118 2005-01-03 devnull The next byte is the message type, one of the constants
81 058b0118 2005-01-03 devnull in the enumeration in the include file
82 058b0118 2005-01-03 devnull .BR <fcall.h> .
83 058b0118 2005-01-03 devnull The next two bytes are an identifying
84 058b0118 2005-01-03 devnull .IR tag ,
85 058b0118 2005-01-03 devnull described below.
86 058b0118 2005-01-03 devnull The remaining bytes are parameters of different sizes.
87 058b0118 2005-01-03 devnull In the message descriptions, the number of bytes in a field
88 058b0118 2005-01-03 devnull is given in brackets after the field name.
89 058b0118 2005-01-03 devnull The notation
90 058b0118 2005-01-03 devnull .IR parameter [ n ]
93 058b0118 2005-01-03 devnull is not a constant represents a variable-length parameter:
94 058b0118 2005-01-03 devnull .IR n [2]
95 058b0118 2005-01-03 devnull followed by
97 058b0118 2005-01-03 devnull bytes of data forming the
98 058b0118 2005-01-03 devnull .IR parameter .
99 058b0118 2005-01-03 devnull The notation
100 058b0118 2005-01-03 devnull .IR string [ s ]
101 058b0118 2005-01-03 devnull (using a literal
103 058b0118 2005-01-03 devnull character)
104 058b0118 2005-01-03 devnull is shorthand for
105 058b0118 2005-01-03 devnull .IR s [2]
106 058b0118 2005-01-03 devnull followed by
108 058b0118 2005-01-03 devnull bytes of UTF-8 text.
109 058b0118 2005-01-03 devnull (Systems may choose to reduce the set of legal characters
110 058b0118 2005-01-03 devnull to reduce syntactic problems,
111 058b0118 2005-01-03 devnull for example to remove slashes from name components,
112 058b0118 2005-01-03 devnull but the protocol has no such restriction.
113 058b0118 2005-01-03 devnull Plan 9 names may contain any printable character (that is, any character
114 058b0118 2005-01-03 devnull outside hexadecimal 00-1F and 80-9F)
115 058b0118 2005-01-03 devnull except slash.)
116 058b0118 2005-01-03 devnull Messages are transported in byte form to allow for machine independence;
117 36cd4c58 2021-01-30 crossd .MR fcall (3)
118 058b0118 2005-01-03 devnull describes routines that convert to and from this form into a machine-dependent
119 058b0118 2005-01-03 devnull C structure.
120 058b0118 2005-01-03 devnull .SH MESSAGES
121 058b0118 2005-01-03 devnull .ta \w'\fLTsession 'u
124 058b0118 2005-01-03 devnull .IR size [4]
125 058b0118 2005-01-03 devnull .B Tversion
126 058b0118 2005-01-03 devnull .IR tag [2]
127 058b0118 2005-01-03 devnull .IR msize [4]
128 058b0118 2005-01-03 devnull .IR version [ s ]
130 058b0118 2005-01-03 devnull .IR size [4]
131 058b0118 2005-01-03 devnull .B Rversion
132 058b0118 2005-01-03 devnull .IR tag [2]
133 058b0118 2005-01-03 devnull .IR msize [4]
134 058b0118 2005-01-03 devnull .IR version [ s ]
137 058b0118 2005-01-03 devnull .IR size [4]
138 058b0118 2005-01-03 devnull .B Tauth
139 058b0118 2005-01-03 devnull .IR tag [2]
140 058b0118 2005-01-03 devnull .IR afid [4]
141 058b0118 2005-01-03 devnull .IR uname [ s ]
142 058b0118 2005-01-03 devnull .IR aname [ s ]
145 058b0118 2005-01-03 devnull .IR size [4]
146 058b0118 2005-01-03 devnull .B Rauth
147 058b0118 2005-01-03 devnull .IR tag [2]
148 058b0118 2005-01-03 devnull .IR aqid [13]
151 058b0118 2005-01-03 devnull .IR size [4]
152 058b0118 2005-01-03 devnull .B Rerror
153 058b0118 2005-01-03 devnull .IR tag [2]
154 058b0118 2005-01-03 devnull .IR ename [ s ]
157 058b0118 2005-01-03 devnull .IR size [4]
158 058b0118 2005-01-03 devnull .B Tflush
159 058b0118 2005-01-03 devnull .IR tag [2]
160 058b0118 2005-01-03 devnull .IR oldtag [2]
162 058b0118 2005-01-03 devnull .IR size [4]
163 058b0118 2005-01-03 devnull .B Rflush
164 058b0118 2005-01-03 devnull .IR tag [2]
167 058b0118 2005-01-03 devnull .IR size [4]
168 058b0118 2005-01-03 devnull .B Tattach
169 058b0118 2005-01-03 devnull .IR tag [2]
170 058b0118 2005-01-03 devnull .IR fid [4]
171 058b0118 2005-01-03 devnull .IR afid [4]
172 058b0118 2005-01-03 devnull .IR uname [ s ]
173 058b0118 2005-01-03 devnull .IR aname [ s ]
175 058b0118 2005-01-03 devnull .IR size [4]
176 058b0118 2005-01-03 devnull .B Rattach
177 058b0118 2005-01-03 devnull .IR tag [2]
178 058b0118 2005-01-03 devnull .IR qid [13]
181 058b0118 2005-01-03 devnull .IR size [4]
182 058b0118 2005-01-03 devnull .B Twalk
183 058b0118 2005-01-03 devnull .IR tag [2]
184 058b0118 2005-01-03 devnull .IR fid [4]
185 058b0118 2005-01-03 devnull .IR newfid [4]
186 058b0118 2005-01-03 devnull .IR nwname [2]
187 058b0118 2005-01-03 devnull .IR nwname *( wname [ s ])
189 058b0118 2005-01-03 devnull .IR size [4]
190 058b0118 2005-01-03 devnull .B Rwalk
191 058b0118 2005-01-03 devnull .IR tag [2]
192 058b0118 2005-01-03 devnull .IR nwqid [2]
193 058b0118 2005-01-03 devnull .IR nwqid *( wqid [13])
196 058b0118 2005-01-03 devnull .IR size [4]
197 058b0118 2005-01-03 devnull .B Topen
198 058b0118 2005-01-03 devnull .IR tag [2]
199 058b0118 2005-01-03 devnull .IR fid [4]
200 058b0118 2005-01-03 devnull .IR mode [1]
202 058b0118 2005-01-03 devnull .IR size [4]
203 058b0118 2005-01-03 devnull .B Ropen
204 058b0118 2005-01-03 devnull .IR tag [2]
205 058b0118 2005-01-03 devnull .IR qid [13]
206 058b0118 2005-01-03 devnull .IR iounit [4]
209 058b0118 2005-01-03 devnull .IR size [4]
210 058b0118 2005-01-03 devnull .B Topenfd
211 058b0118 2005-01-03 devnull .IR tag [2]
212 058b0118 2005-01-03 devnull .IR fid [4]
213 058b0118 2005-01-03 devnull .IR mode [1]
215 058b0118 2005-01-03 devnull .IR size [4]
216 058b0118 2005-01-03 devnull .B Ropenfd
217 058b0118 2005-01-03 devnull .IR tag [2]
218 058b0118 2005-01-03 devnull .IR qid [13]
219 058b0118 2005-01-03 devnull .IR iounit [4]
220 058b0118 2005-01-03 devnull .IR unixfd [4]
223 058b0118 2005-01-03 devnull .IR size [4]
224 058b0118 2005-01-03 devnull .B Tcreate
225 058b0118 2005-01-03 devnull .IR tag [2]
226 058b0118 2005-01-03 devnull .IR fid [4]
227 058b0118 2005-01-03 devnull .IR name [ s ]
228 058b0118 2005-01-03 devnull .IR perm [4]
229 058b0118 2005-01-03 devnull .IR mode [1]
231 058b0118 2005-01-03 devnull .IR size [4]
232 058b0118 2005-01-03 devnull .B Rcreate
233 058b0118 2005-01-03 devnull .IR tag [2]
234 058b0118 2005-01-03 devnull .IR qid [13]
235 058b0118 2005-01-03 devnull .IR iounit [4]
238 058b0118 2005-01-03 devnull .IR size [4]
239 058b0118 2005-01-03 devnull .B Tread
240 058b0118 2005-01-03 devnull .IR tag [2]
241 058b0118 2005-01-03 devnull .IR fid [4]
242 058b0118 2005-01-03 devnull .IR offset [8]
243 058b0118 2005-01-03 devnull .IR count [4]
245 058b0118 2005-01-03 devnull .IR size [4]
246 058b0118 2005-01-03 devnull .B Rread
247 058b0118 2005-01-03 devnull .IR tag [2]
248 058b0118 2005-01-03 devnull .IR count [4]
249 058b0118 2005-01-03 devnull .IR data [ count ]
252 058b0118 2005-01-03 devnull .IR size [4]
253 058b0118 2005-01-03 devnull .B Twrite
254 058b0118 2005-01-03 devnull .IR tag [2]
255 058b0118 2005-01-03 devnull .IR fid [4]
256 058b0118 2005-01-03 devnull .IR offset [8]
257 058b0118 2005-01-03 devnull .IR count [4]
258 058b0118 2005-01-03 devnull .IR data [ count ]
260 058b0118 2005-01-03 devnull .IR size [4]
261 058b0118 2005-01-03 devnull .B Rwrite
262 058b0118 2005-01-03 devnull .IR tag [2]
263 058b0118 2005-01-03 devnull .IR count [4]
266 058b0118 2005-01-03 devnull .IR size [4]
267 058b0118 2005-01-03 devnull .B Tclunk
268 058b0118 2005-01-03 devnull .IR tag [2]
269 058b0118 2005-01-03 devnull .IR fid [4]
271 058b0118 2005-01-03 devnull .IR size [4]
272 058b0118 2005-01-03 devnull .B Rclunk
273 058b0118 2005-01-03 devnull .IR tag [2]
276 058b0118 2005-01-03 devnull .IR size [4]
277 058b0118 2005-01-03 devnull .B Tremove
278 058b0118 2005-01-03 devnull .IR tag [2]
279 058b0118 2005-01-03 devnull .IR fid [4]
281 058b0118 2005-01-03 devnull .IR size [4]
282 058b0118 2005-01-03 devnull .B Rremove
283 058b0118 2005-01-03 devnull .IR tag [2]
286 058b0118 2005-01-03 devnull .IR size [4]
287 058b0118 2005-01-03 devnull .B Tstat
288 058b0118 2005-01-03 devnull .IR tag [2]
289 058b0118 2005-01-03 devnull .IR fid [4]
291 058b0118 2005-01-03 devnull .IR size [4]
292 058b0118 2005-01-03 devnull .B Rstat
293 058b0118 2005-01-03 devnull .IR tag [2]
294 058b0118 2005-01-03 devnull .IR stat [ n ]
297 058b0118 2005-01-03 devnull .IR size [4]
298 058b0118 2005-01-03 devnull .B Twstat
299 058b0118 2005-01-03 devnull .IR tag [2]
300 058b0118 2005-01-03 devnull .IR fid [4]
301 058b0118 2005-01-03 devnull .IR stat [ n ]
303 058b0118 2005-01-03 devnull .IR size [4]
304 058b0118 2005-01-03 devnull .B Rwstat
305 058b0118 2005-01-03 devnull .IR tag [2]
307 058b0118 2005-01-03 devnull Each T-message has a
309 058b0118 2005-01-03 devnull field, chosen and used by the client to identify the message.
310 058b0118 2005-01-03 devnull The reply to the message will have the same tag.
311 058b0118 2005-01-03 devnull Clients must arrange that no two outstanding messages
312 058b0118 2005-01-03 devnull on the same connection have the same tag.
313 058b0118 2005-01-03 devnull An exception is the tag
314 058b0118 2005-01-03 devnull .BR NOTAG ,
315 058b0118 2005-01-03 devnull defined as
316 058b0118 2005-01-03 devnull .B (ushort)~0
318 058b0118 2005-01-03 devnull .BR <fcall.h> :
319 058b0118 2005-01-03 devnull the client can use it, when establishing a connection,
321 058b0118 2005-01-03 devnull override tag matching in
322 058b0118 2005-01-03 devnull .B version
323 058b0118 2005-01-03 devnull messages.
325 058b0118 2005-01-03 devnull The type of an R-message will either be one greater than the type
326 058b0118 2005-01-03 devnull of the corresponding T-message or
327 058b0118 2005-01-03 devnull .BR Rerror ,
328 058b0118 2005-01-03 devnull indicating that the request failed.
329 058b0118 2005-01-03 devnull In the latter case, the
330 058b0118 2005-01-03 devnull .I ename
331 058b0118 2005-01-03 devnull field contains a string describing the reason for failure.
334 058b0118 2005-01-03 devnull .B version
335 058b0118 2005-01-03 devnull message identifies the version of the protocol and indicates
336 058b0118 2005-01-03 devnull the maximum message size the system is prepared to handle.
337 058b0118 2005-01-03 devnull It also initializes the connection and
338 058b0118 2005-01-03 devnull aborts all outstanding I/O on the connection.
339 058b0118 2005-01-03 devnull The set of messages between
340 058b0118 2005-01-03 devnull .B version
341 058b0118 2005-01-03 devnull requests is called a
342 058b0118 2005-01-03 devnull .IR session .
344 058b0118 2005-01-03 devnull Most T-messages contain a
345 058b0118 2005-01-03 devnull .IR fid ,
346 058b0118 2005-01-03 devnull a 32-bit unsigned integer that the client uses to identify
347 058b0118 2005-01-03 devnull a ``current file'' on the server.
348 058b0118 2005-01-03 devnull Fids are somewhat like file descriptors in a user process,
349 058b0118 2005-01-03 devnull but they are not restricted to files open for I/O:
350 058b0118 2005-01-03 devnull directories being examined, files being accessed by
351 36cd4c58 2021-01-30 crossd .MR stat (3)
352 058b0118 2005-01-03 devnull calls, and so on \(em all files being manipulated by the operating
353 058b0118 2005-01-03 devnull system \(em are identified by fids.
354 058b0118 2005-01-03 devnull Fids are chosen by the client.
355 058b0118 2005-01-03 devnull All requests on a connection share the same fid space;
356 058b0118 2005-01-03 devnull when several clients share a connection,
357 058b0118 2005-01-03 devnull the agent managing the sharing must arrange
358 058b0118 2005-01-03 devnull that no two clients choose the same fid.
360 058b0118 2005-01-03 devnull The fid supplied in an
361 058b0118 2005-01-03 devnull .B attach
363 058b0118 2005-01-03 devnull will be taken by the server to refer to the root of the served file tree.
365 058b0118 2005-01-03 devnull .B attach
366 058b0118 2005-01-03 devnull identifies the user
367 058b0118 2005-01-03 devnull to the server and may specify a particular file tree served
368 058b0118 2005-01-03 devnull by the server (for those that supply more than one).
370 058b0118 2005-01-03 devnull Permission to attach to the service is proven by providing a special fid, called
371 058b0118 2005-01-03 devnull .BR afid ,
373 058b0118 2005-01-03 devnull .B attach
374 058b0118 2005-01-03 devnull message. This
376 058b0118 2005-01-03 devnull is established by exchanging
378 058b0118 2005-01-03 devnull messages and subsequently manipulated using
381 058b0118 2005-01-03 devnull .B write
382 058b0118 2005-01-03 devnull messages to exchange authentication information not defined explicitly by 9P.
383 058b0118 2005-01-03 devnull Once the authentication protocol is complete, the
385 058b0118 2005-01-03 devnull is presented in the
386 058b0118 2005-01-03 devnull .B attach
387 058b0118 2005-01-03 devnull to permit the user to access the service.
391 058b0118 2005-01-03 devnull message causes the server to change the current file associated
392 058b0118 2005-01-03 devnull with a fid to be a file in the directory that is the old current file, or one of
393 058b0118 2005-01-03 devnull its subdirectories.
395 058b0118 2005-01-03 devnull returns a new fid that refers to the resulting file.
396 058b0118 2005-01-03 devnull Usually, a client maintains a fid for the root,
397 058b0118 2005-01-03 devnull and navigates by
398 058b0118 2005-01-03 devnull .B walks
399 058b0118 2005-01-03 devnull from the root fid.
401 058b0118 2005-01-03 devnull A client can send multiple T-messages without waiting for the corresponding
402 058b0118 2005-01-03 devnull R-messages, but all outstanding T-messages must specify different tags.
403 058b0118 2005-01-03 devnull The server may delay the response to a request
404 058b0118 2005-01-03 devnull and respond to later ones;
405 058b0118 2005-01-03 devnull this is sometimes necessary, for example when the client reads
406 058b0118 2005-01-03 devnull from a file that the server synthesizes from external events
407 058b0118 2005-01-03 devnull such as keyboard characters.
409 058b0118 2005-01-03 devnull Replies (R-messages) to
410 058b0118 2005-01-03 devnull .BR auth ,
411 058b0118 2005-01-03 devnull .BR attach ,
412 058b0118 2005-01-03 devnull .BR walk ,
413 058b0118 2005-01-03 devnull .BR open ,
415 058b0118 2005-01-03 devnull .B create
416 058b0118 2005-01-03 devnull requests convey a
418 058b0118 2005-01-03 devnull field back to the client.
419 058b0118 2005-01-03 devnull The qid represents the server's unique identification for the
420 058b0118 2005-01-03 devnull file being accessed:
421 058b0118 2005-01-03 devnull two files on the same server hierarchy are the same if and only if their qids
422 058b0118 2005-01-03 devnull are the same.
423 058b0118 2005-01-03 devnull (The client may have multiple fids pointing to a single file on a server
424 058b0118 2005-01-03 devnull and hence having a single qid.)
425 058b0118 2005-01-03 devnull The thirteen-byte qid fields hold a one-byte type,
426 058b0118 2005-01-03 devnull specifying whether the file is a directory, append-only file, etc.,
427 058b0118 2005-01-03 devnull and two unsigned integers:
428 058b0118 2005-01-03 devnull first the four-byte qid
429 058b0118 2005-01-03 devnull .IR version ,
430 058b0118 2005-01-03 devnull then the eight-byte qid
431 058b0118 2005-01-03 devnull .IR path .
432 058b0118 2005-01-03 devnull The path is an integer unique among all files in the hierarchy.
433 058b0118 2005-01-03 devnull If a file is deleted and recreated with the
434 058b0118 2005-01-03 devnull same name in the same directory, the old and new path components of the qids
435 058b0118 2005-01-03 devnull should be different.
436 058b0118 2005-01-03 devnull The version is a version number for a file;
437 058b0118 2005-01-03 devnull typically, it is incremented every time the file is modified.
439 058b0118 2005-01-03 devnull An existing file can be
440 058b0118 2005-01-03 devnull .BR opened ,
441 058b0118 2005-01-03 devnull or a new file may be
442 058b0118 2005-01-03 devnull .B created
443 058b0118 2005-01-03 devnull in the current (directory) file.
444 058b0118 2005-01-03 devnull I/O of a given number of bytes
445 058b0118 2005-01-03 devnull at a given offset
446 058b0118 2005-01-03 devnull on an open file is done by
449 058b0118 2005-01-03 devnull .BR write .
451 058b0118 2005-01-03 devnull A client should
452 058b0118 2005-01-03 devnull .B clunk
453 058b0118 2005-01-03 devnull any fid that is no longer needed.
455 058b0118 2005-01-03 devnull .B remove
456 058b0118 2005-01-03 devnull transaction deletes files.
458 058b0118 2005-01-03 devnull .B Openfd
459 058b0118 2005-01-03 devnull is an extension used by Unix utilities to allow traditional Unix programs
460 058b0118 2005-01-03 devnull to have their input or output attached to fids on 9P servers.
462 058b0118 2005-01-03 devnull .IR openfd (9p)
464 36cd4c58 2021-01-30 crossd .MR 9pclient (3)
465 058b0118 2005-01-03 devnull for details.
469 058b0118 2005-01-03 devnull transaction retrieves information about the file.
472 058b0118 2005-01-03 devnull field in the reply includes the file's
474 058b0118 2005-01-03 devnull access permissions (read, write and execute for owner, group and public),
475 058b0118 2005-01-03 devnull access and modification times, and
476 058b0118 2005-01-03 devnull owner and group identifications
478 36cd4c58 2021-01-30 crossd .MR stat (3) ).
479 058b0118 2005-01-03 devnull The owner and group identifications are textual names.
481 058b0118 2005-01-03 devnull .B wstat
482 058b0118 2005-01-03 devnull transaction allows some of a file's properties
483 058b0118 2005-01-03 devnull to be changed.
485 058b0118 2005-01-03 devnull A request can be aborted with a
487 058b0118 2005-01-03 devnull request.
488 058b0118 2005-01-03 devnull When a server receives a
489 058b0118 2005-01-03 devnull .BR Tflush ,
490 058b0118 2005-01-03 devnull it should not reply to the message with tag
491 058b0118 2005-01-03 devnull .I oldtag
492 058b0118 2005-01-03 devnull (unless it has already replied),
493 058b0118 2005-01-03 devnull and it should immediately send an
494 058b0118 2005-01-03 devnull .BR Rflush .
495 058b0118 2005-01-03 devnull The client must wait
496 058b0118 2005-01-03 devnull until it gets the
497 058b0118 2005-01-03 devnull .B Rflush
498 058b0118 2005-01-03 devnull (even if the reply to the original message arrives in the interim),
499 058b0118 2005-01-03 devnull at which point
500 058b0118 2005-01-03 devnull .I oldtag
501 058b0118 2005-01-03 devnull may be reused.
503 058b0118 2005-01-03 devnull Because the message size is negotiable and some elements of the
504 058b0118 2005-01-03 devnull protocol are variable length, it is possible (although unlikely) to have
505 058b0118 2005-01-03 devnull a situation where a valid message is too large to fit within the negotiated size.
506 058b0118 2005-01-03 devnull For example, a very long file name may cause a
507 058b0118 2005-01-03 devnull .B Rstat
508 058b0118 2005-01-03 devnull of the file or
509 058b0118 2005-01-03 devnull .B Rread
510 058b0118 2005-01-03 devnull of its directory entry to be too large to send.
511 058b0118 2005-01-03 devnull In most such cases, the server should generate an error rather than
512 058b0118 2005-01-03 devnull modify the data to fit, such as by truncating the file name.
513 058b0118 2005-01-03 devnull The exception is that a long error string in an
514 058b0118 2005-01-03 devnull .B Rerror
515 058b0118 2005-01-03 devnull message should be truncated if necessary, since the string is only
516 058b0118 2005-01-03 devnull advisory and in some sense arbitrary.
518 058b0118 2005-01-03 devnull Most programs do not see the 9P protocol directly;
519 058b0118 2005-01-03 devnull on Plan 9, calls to library
520 058b0118 2005-01-03 devnull routines that access files are
521 058b0118 2005-01-03 devnull translated by the kernel's mount driver
522 058b0118 2005-01-03 devnull into 9P messages.
523 058b0118 2005-01-03 devnull .SS Unix
524 058b0118 2005-01-03 devnull On Unix, 9P services are posted as Unix domain sockets in a
525 058b0118 2005-01-03 devnull well-known directory (see
526 36cd4c58 2021-01-30 crossd .MR getns (3)
528 36cd4c58 2021-01-30 crossd .MR 9pserve (4) ).
529 058b0118 2005-01-03 devnull Clients connect to these servers using a 9P client library
531 36cd4c58 2021-01-30 crossd .MR 9pclient (3) ).
532 058b0118 2005-01-03 devnull .SH DIRECTORIES
533 058b0118 2005-01-03 devnull Directories are created by
534 058b0118 2005-01-03 devnull .B create
536 058b0118 2005-01-03 devnull .B DMDIR
537 058b0118 2005-01-03 devnull set in the permissions argument (see
538 058b0118 2005-01-03 devnull .IR stat (9P)).
539 058b0118 2005-01-03 devnull The members of a directory can be found with
540 058b0118 2005-01-03 devnull .IR read (9P).
541 058b0118 2005-01-03 devnull All directories must support
542 058b0118 2005-01-03 devnull .B walks
543 058b0118 2005-01-03 devnull to the directory
545 058b0118 2005-01-03 devnull (dot-dot)
546 058b0118 2005-01-03 devnull meaning parent directory, although by convention directories
547 058b0118 2005-01-03 devnull contain no explicit entry for
552 058b0118 2005-01-03 devnull The parent of the root directory of a server's tree is itself.
553 058b0118 2005-01-03 devnull .SH "ACCESS PERMISSIONS"
554 058b0118 2005-01-03 devnull This section describes the access permission conventions
555 058b0118 2005-01-03 devnull implemented by most Plan 9 file servers. These conventions
556 058b0118 2005-01-03 devnull are not enforced by the protocol and may differ between servers,
557 058b0118 2005-01-03 devnull especially servers built on top of foreign operating systems.
559 058b0118 2005-01-03 devnull Each file server maintains a set of user and group names.
560 058b0118 2005-01-03 devnull Each user can be a member of any number of groups.
561 058b0118 2005-01-03 devnull Each group has a
562 058b0118 2005-01-03 devnull .I group leader
563 058b0118 2005-01-03 devnull who has special privileges (see
564 058b0118 2005-01-03 devnull .IR stat (9P)
566 058b0118 2005-01-03 devnull Plan 9's \fIusers\fR(6)).
567 058b0118 2005-01-03 devnull Every file request has an implicit user id (copied from the original
568 058b0118 2005-01-03 devnull .BR attach )
569 058b0118 2005-01-03 devnull and an implicit set of groups (every group of which the user is a member).
571 058b0118 2005-01-03 devnull Each file has an associated
572 058b0118 2005-01-03 devnull .I owner
574 058b0118 2005-01-03 devnull .I group
576 058b0118 2005-01-03 devnull three sets of permissions:
577 058b0118 2005-01-03 devnull those of the owner, those of the group, and those of ``other'' users.
578 058b0118 2005-01-03 devnull When the owner attempts to do something to a file, the owner, group,
579 058b0118 2005-01-03 devnull and other permissions are consulted, and if any of them grant
580 058b0118 2005-01-03 devnull the requested permission, the operation is allowed.
581 058b0118 2005-01-03 devnull For someone who is not the owner, but is a member of the file's group,
582 058b0118 2005-01-03 devnull the group and other permissions are consulted.
583 058b0118 2005-01-03 devnull For everyone else, the other permissions are used.
584 058b0118 2005-01-03 devnull Each set of permissions says whether reading is allowed,
585 058b0118 2005-01-03 devnull whether writing is allowed, and whether executing is allowed.
588 058b0118 2005-01-03 devnull in a directory is regarded as executing the directory,
589 058b0118 2005-01-03 devnull not reading it.
590 058b0118 2005-01-03 devnull Permissions are kept in the low-order bits of the file
591 058b0118 2005-01-03 devnull .IR mode :
592 058b0118 2005-01-03 devnull owner read/write/execute permission represented as 1 in bits 8, 7, and 6
593 058b0118 2005-01-03 devnull respectively (using 0 to number the low order).
594 058b0118 2005-01-03 devnull The group permissions are in bits 5, 4, and 3,
595 058b0118 2005-01-03 devnull and the other permissions are in bits 2, 1, and 0.
597 058b0118 2005-01-03 devnull The file
599 058b0118 2005-01-03 devnull contains some additional attributes besides the permissions.
600 058b0118 2005-01-03 devnull If bit 31
601 058b0118 2005-01-03 devnull .RB ( DMDIR )
602 058b0118 2005-01-03 devnull is set, the file is a directory;
603 058b0118 2005-01-03 devnull if bit 30
604 058b0118 2005-01-03 devnull .RB ( DMAPPEND )
605 058b0118 2005-01-03 devnull is set, the file is append-only (offset is ignored in writes);
606 058b0118 2005-01-03 devnull if bit 29
607 058b0118 2005-01-03 devnull .RB ( DMEXCL )
608 058b0118 2005-01-03 devnull is set, the file is exclusive-use (only one client may have it
609 058b0118 2005-01-03 devnull open at a time);
610 058b0118 2005-01-03 devnull if bit 27
611 058b0118 2005-01-03 devnull .RB ( DMAUTH )
612 058b0118 2005-01-03 devnull is set, the file is an authentication file established by
614 058b0118 2005-01-03 devnull messages;
615 058b0118 2005-01-03 devnull if bit 26
616 058b0118 2005-01-03 devnull .RB ( DMTMP )
617 058b0118 2005-01-03 devnull is set, the contents of the file (or directory) are not included in nightly archives.
618 058b0118 2005-01-03 devnull (Bit 28 is skipped for historical reasons.)
619 058b0118 2005-01-03 devnull These bits are reproduced, from the top bit down, in the type byte of the Qid:
620 058b0118 2005-01-03 devnull .BR QTDIR ,
621 058b0118 2005-01-03 devnull .BR QTAPPEND ,
622 058b0118 2005-01-03 devnull .BR QTEXCL ,
623 058b0118 2005-01-03 devnull (skipping one bit)
624 058b0118 2005-01-03 devnull .BR QTAUTH ,
626 058b0118 2005-01-03 devnull .BR QTTMP .
627 058b0118 2005-01-03 devnull The name
628 058b0118 2005-01-03 devnull .BR QTFILE ,
629 058b0118 2005-01-03 devnull defined to be zero,
630 058b0118 2005-01-03 devnull identifies the value of the type for a plain file.
