3 intro \- introduction to the Plan 9 File Protocol, 9P
9 is an agent that provides one or more hierarchical file systems
11 that may be accessed by Plan 9 processes.
12 A server responds to requests by
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
21 Another possibility for a server is to synthesize
22 files on demand, perhaps based on information on data structures
23 inside the kernel; the
26 is a part of the Plan 9 kernel that does this.
27 User programs can also act as servers.
31 to a server is a bidirectional communication path from the client to the server.
32 There may be a single client or
33 multiple clients sharing the same connection.
34 A server's file tree is attached to a process
42 Processes in the group are then clients
44 system calls operating on files are translated into requests
45 and responses transmitted on the connection to the appropriate service.
48 .IR "Plan 9 File Protocol" ,
49 9P, is used for messages between
61 The combined acts of transmitting (receiving) a request of a particular type,
62 and receiving (transmitting)
67 Each message consists of a sequence of bytes.
68 Two-, four-, and eight-byte fields hold unsigned
69 integers represented in little-endian order
70 (least significant byte first).
71 Data items of larger or variable lengths are represented
72 by a two-byte field specifying a count,
77 Text strings are represented this way,
78 with the text itself stored as a UTF-8
79 encoded sequence of Unicode characters (see
81 Text strings in 9P messages are not
85 counts the bytes of UTF-8 data, which include no final zero byte.
88 character is illegal in all text strings in 9P, and is therefore
89 excluded from file names, user names, and so on.
91 Each 9P message begins with a four-byte size field
92 specifying the length in bytes of the complete message including
93 the four bytes of the size field itself.
94 The next byte is the message type, one of the constants
95 in the enumeration in the include file
97 The next two bytes are an identifying
100 The remaining bytes are parameters of different sizes.
101 In the message descriptions, the number of bytes in a field
102 is given in brackets after the field name.
107 is not a constant represents a variable-length parameter:
111 bytes of data forming the
123 (Systems may choose to reduce the set of legal characters
124 to reduce syntactic problems,
125 for example to remove slashes from name components,
126 but the protocol has no such restriction.
127 Plan 9 names may contain any printable character (that is, any character
128 outside hexadecimal 00-1F and 80-9F)
130 Messages are transported in byte form to allow for machine independence;
132 describes routines that convert to and from this form into a machine-dependent
135 .ta \w'\fLTsession 'u
201 .IR nwname *( wname [ s ])
207 .IR nwqid *( wqid [13])
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
319 the client can use it, when establishing a connection,
321 override tag matching in
325 The type of an R-message will either be one greater than the type
326 of the corresponding T-message or
328 indicating that the request failed.
329 In the latter case, the
331 field contains a string describing the reason for failure.
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
344 Most T-messages contain a
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
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.
360 The fid supplied in an
363 will be taken by the server to refer to the root of the served file tree.
367 to the server and may specify a particular file tree served
368 by the server (for those that supply more than one).
370 Permission to attach to the service is proven by providing a special fid, called
376 is established by exchanging
378 messages and subsequently manipulated using
382 messages to exchange authentication information not defined explicitly by 9P.
383 Once the authentication protocol is complete, the
387 to permit the user to access the service.
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
395 returns a new fid that refers to the resulting file.
396 Usually, a client maintains a fid for the root,
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.
409 Replies (R-messages) to
418 field back to the client.
419 The qid represents the server's unique identification for the
421 two files on the same server hierarchy are the same if and only if their qids
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
430 then the eight-byte qid
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
436 The version is a version number for a file;
437 typically, it is incremented every time the file is modified.
439 An existing file can be
443 in the current (directory) file.
444 I/O of a given number of bytes
446 on an open file is done by
453 any fid that is no longer needed.
456 transaction deletes files.
460 transaction retrieves information about the file.
463 field in the reply includes the file's
465 access permissions (read, write and execute for owner, group and public),
466 access and modification times, and
467 owner and group identifications
470 The owner and group identifications are textual names.
473 transaction allows some of a file's properties
476 A request can be aborted with a
479 When a server receives a
481 it should not reply to the message with tag
483 (unless it has already replied),
484 and it should immediately send an
489 (even if the reply to the original message arrives in the interim),
494 Because the message size is negotiable and some elements of the
495 protocol are variable length, it is possible (although unlikely) to have
496 a situation where a valid message is too large to fit within the negotiated size.
497 For example, a very long file name may cause a
501 of its directory entry to be too large to send.
502 In most such cases, the server should generate an error rather than
503 modify the data to fit, such as by truncating the file name.
504 The exception is that a long error string in an
506 message should be truncated if necessary, since the string is only
507 advisory and in some sense arbitrary.
509 Most programs do not see the 9P protocol directly; instead calls to library
510 routines that access files are
511 translated by the mount driver,
515 Directories are created by
519 set in the permissions argument (see
521 The members of a directory can be found with
523 All directories must support
528 meaning parent directory, although by convention directories
529 contain no explicit entry for
534 The parent of the root directory of a server's tree is itself.
535 .SH "ACCESS PERMISSIONS"
536 Each file server maintains a set of user and group names.
537 Each user can be a member of any number of groups.
540 who has special privileges (see
544 Every file request has an implicit user id (copied from the original
546 and an implicit set of groups (every group of which the user is a member).
548 Each file has an associated
553 three sets of permissions:
554 those of the owner, those of the group, and those of ``other'' users.
555 When the owner attempts to do something to a file, the owner, group,
556 and other permissions are consulted, and if any of them grant
557 the requested permission, the operation is allowed.
558 For someone who is not the owner, but is a member of the file's group,
559 the group and other permissions are consulted.
560 For everyone else, the other permissions are used.
561 Each set of permissions says whether reading is allowed,
562 whether writing is allowed, and whether executing is allowed.
565 in a directory is regarded as executing the directory,
567 Permissions are kept in the low-order bits of the file
569 owner read/write/execute permission represented as 1 in bits 8, 7, and 6
570 respectively (using 0 to number the low order).
571 The group permissions are in bits 5, 4, and 3,
572 and the other permissions are in bits 2, 1, and 0.
576 contains some additional attributes besides the permissions.
579 is set, the file is a directory;
582 is set, the file is append-only (offset is ignored in writes);
585 is set, the file is exclusive-use (only one client may have it
589 is set, the file is an authentication file established by
594 is set, the contents of the file (or directory) are not included in nightly archives.
595 (Bit 28 is skipped for historical reasons.)
596 These bits are reproduced, from the top bit down, in the type byte of the Qid:
607 identifies the value of the type for a plain file.
projects / plan9front.git / blob