From 058b0118a52061ad57694c01fc8763b22b789c4d Mon Sep 17 00:00:00 2001 From: rsc Date: Mon, 3 Jan 2005 06:40:20 +0000 Subject: Some man pages. --- man/man9/0intro.9p | 630 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 630 insertions(+) create mode 100644 man/man9/0intro.9p (limited to 'man/man9/0intro.9p') diff --git a/man/man9/0intro.9p b/man/man9/0intro.9p new file mode 100644 index 00000000..397486f8 --- /dev/null +++ b/man/man9/0intro.9p @@ -0,0 +1,630 @@ +.TH INTRO 9P +.SH NAME +intro \- introduction to the Plan 9 File Protocol, 9P +.SH SYNOPSIS +.B #include +.SH DESCRIPTION +A Plan 9 +.I server +is an agent that provides one or more hierarchical file systems +\(em file trees \(em +that may be accessed by Plan 9 processes. +A server responds to requests by +.I clients +to navigate the hierarchy, +and to create, remove, read, and write files. +The prototypical server is a separate machine that stores +large numbers of user files on permanent media; +such a machine is called, somewhat confusingly, a +.I file +.IR server . +Another possibility for a server is to synthesize +files on demand, perhaps based on information on data structures +maintained in memory; the +.IR plumber (4) +server is an example of such a server. +.PP +A +.I connection +to a server is a bidirectional communication path from the client to the server. +There may be a single client or +multiple clients sharing the same connection. +.PP +The +.IR "Plan 9 File Protocol" , +9P, is used for messages between +.I clients +and +.IR servers . +A client transmits +.I requests +.RI ( T-messages ) +to a server, which +subsequently returns +.I replies +.RI ( R-messages ) +to the client. +The combined acts of transmitting (receiving) a request of a particular type, +and receiving (transmitting) +its reply is called a +.I transaction +of that type. +.PP +Each message consists of a sequence of bytes. +Two-, four-, and eight-byte fields hold unsigned +integers represented in little-endian order +(least significant byte first). +Data items of larger or variable lengths are represented +by a two-byte field specifying a count, +.IR n , +followed by +.I n +bytes of data. +Text strings are represented this way, +with the text itself stored as a UTF-8 +encoded sequence of Unicode characters (see +.IR utf (7)). +Text strings in 9P messages are not +.SM NUL\c +-terminated: +.I n +counts the bytes of UTF-8 data, which include no final zero byte. +The +.SM NUL +character is illegal in all text strings in 9P, and is therefore +excluded from file names, user names, and so on. +.PP +Each 9P message begins with a four-byte size field +specifying the length in bytes of the complete message including +the four bytes of the size field itself. +The next byte is the message type, one of the constants +in the enumeration in the include file +.BR . +The next two bytes are an identifying +.IR tag , +described below. +The remaining bytes are parameters of different sizes. +In the message descriptions, the number of bytes in a field +is given in brackets after the field name. +The notation +.IR parameter [ n ] +where +.I n +is not a constant represents a variable-length parameter: +.IR n [2] +followed by +.I n +bytes of data forming the +.IR parameter . +The notation +.IR string [ s ] +(using a literal +.I s +character) +is shorthand for +.IR s [2] +followed by +.I s +bytes of UTF-8 text. +(Systems may choose to reduce the set of legal characters +to reduce syntactic problems, +for example to remove slashes from name components, +but the protocol has no such restriction. +Plan 9 names may contain any printable character (that is, any character +outside hexadecimal 00-1F and 80-9F) +except slash.) +Messages are transported in byte form to allow for machine independence; +.IR fcall (3) +describes routines that convert to and from this form into a machine-dependent +C structure. +.SH MESSAGES +.ta \w'\fLTsession 'u +.IP +.ne 2v +.IR size [4] +.B Tversion +.IR tag [2] +.IR msize [4] +.IR version [ s ] +.br +.IR size [4] +.B Rversion +.IR tag [2] +.IR msize [4] +.IR version [ s ] +.IP +.ne 2v +.IR size [4] +.B Tauth +.IR tag [2] +.IR afid [4] +.IR uname [ s ] +.IR aname [ s ] +.br +.br +.IR size [4] +.B Rauth +.IR tag [2] +.IR aqid [13] +.IP +.ne 2v +.IR size [4] +.B Rerror +.IR tag [2] +.IR ename [ s ] +.IP +.ne 2v +.IR size [4] +.B Tflush +.IR tag [2] +.IR oldtag [2] +.br +.IR size [4] +.B Rflush +.IR tag [2] +.IP +.ne 2v +.IR size [4] +.B Tattach +.IR tag [2] +.IR fid [4] +.IR afid [4] +.IR uname [ s ] +.IR aname [ s ] +.br +.IR size [4] +.B Rattach +.IR tag [2] +.IR qid [13] +.IP +.ne 2v +.IR size [4] +.B Twalk +.IR tag [2] +.IR fid [4] +.IR newfid [4] +.IR nwname [2] +.IR nwname *( wname [ s ]) +.br +.IR size [4] +.B Rwalk +.IR tag [2] +.IR nwqid [2] +.IR nwqid *( wqid [13]) +.IP +.ne 2v +.IR size [4] +.B Topen +.IR tag [2] +.IR fid [4] +.IR mode [1] +.br +.IR size [4] +.B Ropen +.IR tag [2] +.IR qid [13] +.IR iounit [4] +.IP +.ne 2v +.IR size [4] +.B Topenfd +.IR tag [2] +.IR fid [4] +.IR mode [1] +.br +.IR size [4] +.B Ropenfd +.IR tag [2] +.IR qid [13] +.IR iounit [4] +.IR unixfd [4] +.IP +.ne 2v +.IR size [4] +.B Tcreate +.IR tag [2] +.IR fid [4] +.IR name [ s ] +.IR perm [4] +.IR mode [1] +.br +.IR size [4] +.B Rcreate +.IR tag [2] +.IR qid [13] +.IR iounit [4] +.IP +.ne 2v +.IR size [4] +.B Tread +.IR tag [2] +.IR fid [4] +.IR offset [8] +.IR count [4] +.br +.IR size [4] +.B Rread +.IR tag [2] +.IR count [4] +.IR data [ count ] +.IP +.ne 2v +.IR size [4] +.B Twrite +.IR tag [2] +.IR fid [4] +.IR offset [8] +.IR count [4] +.IR data [ count ] +.br +.IR size [4] +.B Rwrite +.IR tag [2] +.IR count [4] +.IP +.ne 2v +.IR size [4] +.B Tclunk +.IR tag [2] +.IR fid [4] +.br +.IR size [4] +.B Rclunk +.IR tag [2] +.IP +.ne 2v +.IR size [4] +.B Tremove +.IR tag [2] +.IR fid [4] +.br +.IR size [4] +.B Rremove +.IR tag [2] +.IP +.ne 2v +.IR size [4] +.B Tstat +.IR tag [2] +.IR fid [4] +.br +.IR size [4] +.B Rstat +.IR tag [2] +.IR stat [ n ] +.IP +.ne 2v +.IR size [4] +.B Twstat +.IR tag [2] +.IR fid [4] +.IR stat [ n ] +.br +.IR size [4] +.B Rwstat +.IR tag [2] +.PP +Each T-message has a +.I tag +field, chosen and used by the client to identify the message. +The reply to the message will have the same tag. +Clients must arrange that no two outstanding messages +on the same connection have the same tag. +An exception is the tag +.BR NOTAG , +defined as +.B (ushort)~0 +in +.BR : +the client can use it, when establishing a connection, +to +override tag matching in +.B version +messages. +.PP +The type of an R-message will either be one greater than the type +of the corresponding T-message or +.BR Rerror , +indicating that the request failed. +In the latter case, the +.I ename +field contains a string describing the reason for failure. +.PP +The +.B version +message identifies the version of the protocol and indicates +the maximum message size the system is prepared to handle. +It also initializes the connection and +aborts all outstanding I/O on the connection. +The set of messages between +.B version +requests is called a +.IR session . +.PP +Most T-messages contain a +.IR fid , +a 32-bit unsigned integer that the client uses to identify +a ``current file'' on the server. +Fids are somewhat like file descriptors in a user process, +but they are not restricted to files open for I/O: +directories being examined, files being accessed by +.IR stat (3) +calls, and so on \(em all files being manipulated by the operating +system \(em are identified by fids. +Fids are chosen by the client. +All requests on a connection share the same fid space; +when several clients share a connection, +the agent managing the sharing must arrange +that no two clients choose the same fid. +.PP +The fid supplied in an +.B attach +message +will be taken by the server to refer to the root of the served file tree. +The +.B attach +identifies the user +to the server and may specify a particular file tree served +by the server (for those that supply more than one). +.PP +Permission to attach to the service is proven by providing a special fid, called +.BR afid , +in the +.B attach +message. This +.B afid +is established by exchanging +.B auth +messages and subsequently manipulated using +.B read +and +.B write +messages to exchange authentication information not defined explicitly by 9P. +Once the authentication protocol is complete, the +.B afid +is presented in the +.B attach +to permit the user to access the service. +.PP +A +.B walk +message causes the server to change the current file associated +with a fid to be a file in the directory that is the old current file, or one of +its subdirectories. +.B Walk +returns a new fid that refers to the resulting file. +Usually, a client maintains a fid for the root, +and navigates by +.B walks +from the root fid. +.PP +A client can send multiple T-messages without waiting for the corresponding +R-messages, but all outstanding T-messages must specify different tags. +The server may delay the response to a request +and respond to later ones; +this is sometimes necessary, for example when the client reads +from a file that the server synthesizes from external events +such as keyboard characters. +.PP +Replies (R-messages) to +.BR auth , +.BR attach , +.BR walk , +.BR open , +and +.B create +requests convey a +.I qid +field back to the client. +The qid represents the server's unique identification for the +file being accessed: +two files on the same server hierarchy are the same if and only if their qids +are the same. +(The client may have multiple fids pointing to a single file on a server +and hence having a single qid.) +The thirteen-byte qid fields hold a one-byte type, +specifying whether the file is a directory, append-only file, etc., +and two unsigned integers: +first the four-byte qid +.IR version , +then the eight-byte qid +.IR path . +The path is an integer unique among all files in the hierarchy. +If a file is deleted and recreated with the +same name in the same directory, the old and new path components of the qids +should be different. +The version is a version number for a file; +typically, it is incremented every time the file is modified. +.PP +An existing file can be +.BR opened , +or a new file may be +.B created +in the current (directory) file. +I/O of a given number of bytes +at a given offset +on an open file is done by +.B read +and +.BR write . +.PP +A client should +.B clunk +any fid that is no longer needed. +The +.B remove +transaction deletes files. +.PP +.B Openfd +is an extension used by Unix utilities to allow traditional Unix programs +to have their input or output attached to fids on 9P servers. +See +.IR openfd (9p) +and +.IR 9pclient (3) +for details. +.PP +The +.B stat +transaction retrieves information about the file. +The +.I stat +field in the reply includes the file's +name, +access permissions (read, write and execute for owner, group and public), +access and modification times, and +owner and group identifications +(see +.IR stat (3)). +The owner and group identifications are textual names. +The +.B wstat +transaction allows some of a file's properties +to be changed. +.PP +A request can be aborted with a +flush +request. +When a server receives a +.BR Tflush , +it should not reply to the message with tag +.I oldtag +(unless it has already replied), +and it should immediately send an +.BR Rflush . +The client must wait +until it gets the +.B Rflush +(even if the reply to the original message arrives in the interim), +at which point +.I oldtag +may be reused. +.PP +Because the message size is negotiable and some elements of the +protocol are variable length, it is possible (although unlikely) to have +a situation where a valid message is too large to fit within the negotiated size. +For example, a very long file name may cause a +.B Rstat +of the file or +.B Rread +of its directory entry to be too large to send. +In most such cases, the server should generate an error rather than +modify the data to fit, such as by truncating the file name. +The exception is that a long error string in an +.B Rerror +message should be truncated if necessary, since the string is only +advisory and in some sense arbitrary. +.PP +Most programs do not see the 9P protocol directly; +on Plan 9, calls to library +routines that access files are +translated by the kernel's mount driver +into 9P messages. +.SS Unix +On Unix, 9P services are posted as Unix domain sockets in a +well-known directory (see +.IR getns (3) +and +.IR 9pserve (4)). +Clients connect to these servers using a 9P client library +(see +.IR 9pclient (3)). +.SH DIRECTORIES +Directories are created by +.B create +with +.B DMDIR +set in the permissions argument (see +.IR stat (9P)). +The members of a directory can be found with +.IR read (9P). +All directories must support +.B walks +to the directory +.B .. +(dot-dot) +meaning parent directory, although by convention directories +contain no explicit entry for +.B .. +or +.B . +(dot). +The parent of the root directory of a server's tree is itself. +.SH "ACCESS PERMISSIONS" +This section describes the access permission conventions +implemented by most Plan 9 file servers. These conventions +are not enforced by the protocol and may differ between servers, +especially servers built on top of foreign operating systems. +.PP +Each file server maintains a set of user and group names. +Each user can be a member of any number of groups. +Each group has a +.I group leader +who has special privileges (see +.IR stat (9P) +and +Plan 9's \fIusers\fR(6)). +Every file request has an implicit user id (copied from the original +.BR attach ) +and an implicit set of groups (every group of which the user is a member). +.PP +Each file has an associated +.I owner +and +.I group +id and +three sets of permissions: +those of the owner, those of the group, and those of ``other'' users. +When the owner attempts to do something to a file, the owner, group, +and other permissions are consulted, and if any of them grant +the requested permission, the operation is allowed. +For someone who is not the owner, but is a member of the file's group, +the group and other permissions are consulted. +For everyone else, the other permissions are used. +Each set of permissions says whether reading is allowed, +whether writing is allowed, and whether executing is allowed. +A +.B walk +in a directory is regarded as executing the directory, +not reading it. +Permissions are kept in the low-order bits of the file +.IR mode : +owner read/write/execute permission represented as 1 in bits 8, 7, and 6 +respectively (using 0 to number the low order). +The group permissions are in bits 5, 4, and 3, +and the other permissions are in bits 2, 1, and 0. +.PP +The file +.I mode +contains some additional attributes besides the permissions. +If bit 31 +.RB ( DMDIR ) +is set, the file is a directory; +if bit 30 +.RB ( DMAPPEND ) +is set, the file is append-only (offset is ignored in writes); +if bit 29 +.RB ( DMEXCL ) +is set, the file is exclusive-use (only one client may have it +open at a time); +if bit 27 +.RB ( DMAUTH ) +is set, the file is an authentication file established by +.B auth +messages; +if bit 26 +.RB ( DMTMP ) +is set, the contents of the file (or directory) are not included in nightly archives. +(Bit 28 is skipped for historical reasons.) +These bits are reproduced, from the top bit down, in the type byte of the Qid: +.BR QTDIR , +.BR QTAPPEND , +.BR QTEXCL , +(skipping one bit) +.BR QTAUTH , +and +.BR QTTMP . +The name +.BR QTFILE , +defined to be zero, +identifies the value of the type for a plain file. -- cgit v1.2.3