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