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 ++++++++++++++++++++++++++++++++++++++++++++++++++++ man/man9/INDEX | 16 ++ man/man9/attach.9p | 168 ++++++++++++++ man/man9/clunk.9p | 55 +++++ man/man9/error.9p | 28 +++ man/man9/flush.9p | 109 +++++++++ man/man9/open.9p | 249 +++++++++++++++++++++ man/man9/read.9p | 126 +++++++++++ man/man9/remove.9p | 51 +++++ man/man9/stat.9p | 297 +++++++++++++++++++++++++ man/man9/version.9p | 99 +++++++++ man/man9/walk.9p | 189 ++++++++++++++++ 12 files changed, 2017 insertions(+) create mode 100644 man/man9/0intro.9p create mode 100644 man/man9/INDEX create mode 100644 man/man9/attach.9p create mode 100644 man/man9/clunk.9p create mode 100644 man/man9/error.9p create mode 100644 man/man9/flush.9p create mode 100644 man/man9/open.9p create mode 100644 man/man9/read.9p create mode 100644 man/man9/remove.9p create mode 100644 man/man9/stat.9p create mode 100644 man/man9/version.9p create mode 100644 man/man9/walk.9p (limited to 'man/man9') 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. diff --git a/man/man9/INDEX b/man/man9/INDEX new file mode 100644 index 00000000..2e331bf0 --- /dev/null +++ b/man/man9/INDEX @@ -0,0 +1,16 @@ +0intro 0intro.9p +intro 0intro.9p +attach attach.9p +auth attach.9p +clunk clunk.9p +error error.9p +flush flush.9p +create open.9p +open open.9p +read read.9p +write read.9p +remove remove.9p +stat stat.9p +wstat stat.9p +version version.9p +walk walk.9p diff --git a/man/man9/attach.9p b/man/man9/attach.9p new file mode 100644 index 00000000..ddcf7476 --- /dev/null +++ b/man/man9/attach.9p @@ -0,0 +1,168 @@ +.TH ATTACH 9P +.SH NAME +attach, auth \- messages to establish a connection +.SH SYNOPSIS +.ta \w'\fLTauth 'u +.IR size [4] +.B Tauth +.IR tag [2] +.IR afid [4] +.IR uname [ s ] +.IR aname [ s ] +.br +.IR size [4] +.B Rauth +.IR tag [2] +.IR aqid [13] +.PP +.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] +.SH DESCRIPTION +.PP +The +.B attach +message serves as a fresh introduction from a user on +the client machine to the server. +The message identifies the user +.RI ( uname ) +and may select +the file tree to access +.RI ( aname ). +The +.I afid +argument specifies a fid previously established by an +.B auth +message, as described below. +.PP +As a result of the +.B attach +transaction, the client will have a connection to the root +directory of the desired file tree, +represented by +.IR fid . +An error is returned if +.I fid +is already in use. +The server's idea of the root of the file tree is represented by the returned +.IR qid . +.PP +If the client does not wish to authenticate the connection, or knows that +authentication is not required, the +.I afid +field in the +.B attach +message should be set to +.BR NOFID , +defined as +.B (u32int)~0 +in +.BR . +If the client does wish to authenticate, it must acquire and validate an +.I afid +using an +.B auth +message before doing the +.BR attach . +.PP +The +.B auth +message contains +.IR afid , +a new fid to be established for authentication, and the +.I uname +and +.I aname +that will be those of the following +.B attach +message. +If the server does not require authentication, it returns +.B Rerror +to the +.B Tauth +message. +.PP +If the server does require authentication, it returns +.I aqid +defining a file of type +.B QTAUTH +(see +.IR intro (9P)) +that may be read and written (using +.B read +and +.B write +messages in the usual way) to execute an authentication protocol. +That protocol's definition is not part of 9P itself. +.PP +Once the protocol is complete, the same +.I afid +is presented in the +.B attach +message for the user, granting entry. +The same validated +.I afid +may be used for multiple +.B attach +messages with the same +.I uname +and +.IR aname . +.SH ENTRY POINTS +.I Fsmount +and +.I fsauth +(see +.IR 9pclient (3)) +generate +.B attach +and +.B auth +transactions. +.\" An +.\" .B attach +.\" transaction will be generated for kernel devices +.\" (see +.\" .IR intro (3)) +.\" when a system call evaluates a file name +.\" beginning with +.\" .LR # . +.\" .IR Pipe (2) +.\" generates an attach on the kernel device +.\" .IR pipe (3). +.\" The +.\" .I mount +.\" system call +.\" (see +.\" .IR bind (2)) +.\" generates an +.\" .B attach +.\" message to the remote file server. +.\" When the kernel boots, an +.\" .I attach +.\" is made to the root device, +.\" .IR root (3), +.\" and then an +.\" .B attach +.\" is made to the requested file server machine. +.\" .PP +.\" An +.\" .B auth +.\" transaction is generated by the +.\" .IR fauth (2) +.\" system call or by the first +.\" .B mount +.\" system call on an uninitialized connection. +.SH SEE ALSO +.IR 9pclient (3), +.IR version (9P), +Plan 9's \fIauthsrv\fR(6) diff --git a/man/man9/clunk.9p b/man/man9/clunk.9p new file mode 100644 index 00000000..ef3ecdc4 --- /dev/null +++ b/man/man9/clunk.9p @@ -0,0 +1,55 @@ +.TH CLUNK 9P +.SH NAME +clunk \- forget about a fid +.SH SYNOPSIS +.ta \w'\fLTclunk 'u +.IR size [4] +.B Tclunk +.IR tag [2] +.IR fid [4] +.br +.IR size [4] +.B Rclunk +.IR tag [2] +.SH DESCRIPTION +The +.B clunk +request informs the file server +that the current file represented by +.I fid +is no longer needed by the client. +The actual file is not removed on the server unless the fid had been opened with +.BR ORCLOSE . +.PP +Once a fid has been clunked, +the same fid can be reused in a new +.B walk +or +.B attach +request. +.PP +Even if the +.B clunk +returns an error, the +.I fid +is no longer valid. +.SH ENTRY POINTS +.B Clunk +transactions are +generated by +.I fsclose +and +.I fsunmount +(see +.IR 9pclient (3)) +and indirectly by other actions such as failed +.I fsopen +calls. +.\" +.\" A +.\" .B clunk +.\" message is generated by +.\" .I close +.\" and indirectly by other actions such as failed +.\" .I open +.\" calls. diff --git a/man/man9/error.9p b/man/man9/error.9p new file mode 100644 index 00000000..6380f64f --- /dev/null +++ b/man/man9/error.9p @@ -0,0 +1,28 @@ +.TH ERROR 9P +.SH NAME +error \- return an error +.SH SYNOPSIS +.ta \w'\fLRerror 'u +.IR size [4] +.B Rerror +.IR tag [2] +.IR ename [ s ] +.SH DESCRIPTION +The +.B Rerror +message +(there is no +.BR Terror ) +is used to return an error string +describing the +failure of a transaction. +It replaces the corresponding reply message +that would accompany a successful call; its tag is that +of the failing request. +.PP +By convention, clients may truncate error messages after +.B ERRMAX-1 +bytes; +.B ERRMAX +is defined in +.BR . diff --git a/man/man9/flush.9p b/man/man9/flush.9p new file mode 100644 index 00000000..9d3ea267 --- /dev/null +++ b/man/man9/flush.9p @@ -0,0 +1,109 @@ +.TH FLUSH 9P +.SH NAME +flush \- abort a message +.SH SYNOPSIS +.ta \w'\fLTflush 'u +.IR size [4] +.B Tflush +.IR tag [2] +.IR oldtag [2] +.br +.IR size [4] +.B Rflush +.IR tag [2] +.SH DESCRIPTION +When the response to a request is no longer needed, such as when +a user interrupts a process doing a +.IR read (9p), +a +.B Tflush +request is sent to the server to purge the pending response. +The message being flushed is identified by +.IR oldtag . +The semantics of +.B flush +depends on messages arriving in order. +.PP +The server should answer the +.B flush +message immediately. +If it recognizes +.I oldtag +as the tag of a pending transaction, it should abort any pending response +and discard that tag. +In either case, it should respond with an +.B Rflush +echoing the +.I tag +(not +.IR oldtag ) +of the +.B Tflush +message. +A +.B Tflush +can never be responded to by an +.B Rerror +message. +.PP +The server may respond to the pending request before +responding to the +.BR Tflush . +It is possible for a client to send multiple +.B Tflush +messages for a particular pending request. Each +subsequent +.B Tflush +must contain as +.I oldtag +the tag of the pending request (not a previous +.BR Tflush ). +Should multiple +.BR Tflush es +be received for a pending request, they must be answered in +order. A +.B Rflush +for any of the multiple +.BR Tflush es +implies an answer for all previous ones. Therefore, should +a server receive a request and then multiple flushes for that +request, it need respond only to the last flush. +.PP +When the client sends a +.BR Tflush , +it must wait to receive the corresponding +.B Rflush +before reusing +.I oldtag +for subsequent messages. +If a response to the flushed request is received before the +.BR Rflush , +the client must honor the response +as if it had not been flushed, +since the completed request may signify a state change in the server. +For instance, +.B Tcreate +may have created a file and +.B Twalk +may have allocated a fid. +If no response is received before the +.BR Rflush , +the flushed transaction is considered to have been canceled, +and should be treated as though it had never been sent. +.PP +Several exceptional conditions are handled correctly by the above specification: +sending multiple flushes for a single tag, +flushing after a transaction is completed, +flushing a +.BR Tflush , +and flushing an invalid tag. +.SH ENTRY POINTS +The +.IR 9pclient (3) +library does not generate +.B flush +transactions.. +.IR 9pserve (4) +generates +.B flush +transactions to cancel transactions pending when a client hangs up. diff --git a/man/man9/open.9p b/man/man9/open.9p new file mode 100644 index 00000000..b8ed973a --- /dev/null +++ b/man/man9/open.9p @@ -0,0 +1,249 @@ +.TH OPEN 9P +.SH NAME +open, create \- prepare a fid for I/O on an existing or new file +.SH SYNOPSIS +.ta \w'\fLTcreate 'u +.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] +.PP +.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] +.SH DESCRIPTION +The +.B open +request asks the file server to check permissions and +prepare a fid for I/O with subsequent +.B read +and +.B write +messages. +The +.I mode +field determines the type of I/O: +0 +(called +.BR OREAD +in +.BR ), +1 +.RB ( OWRITE ), +2 +.RB ( ORDWR ), +and 3 +.RB ( OEXEC ) +mean +.I +read access, write access, read and write access, +and +.I +execute access, +to be checked against the permissions for the file. +In addition, if +.I mode +has the +.B OTRUNC +.RB ( 0x10 ) +bit set, +the file is to be truncated, which requires write permission +(if +the file is append-only, and permission is granted, the +.B open +succeeds but the file will not be truncated); +if the +.I mode +has the +.B ORCLOSE +.RB ( 0x40 ) +bit set, the file is to be removed when the fid +is clunked, which requires permission to remove the file from its directory. +All other bits in +.I mode +should be zero. +It is illegal to write a directory, truncate it, or attempt to remove it on close. +If the file is marked for exclusive use (see +.IR stat (9P)), +only one client can have the file open at any time. +That is, after such a file has been opened, +further opens will fail until +.I fid +has been clunked. +All these permissions are checked at the time of the +.B open +request; subsequent changes to the permissions of files do not affect +the ability to read, write, or remove an open file. +.PP +The +.B create +request asks the file server to create a new file +with the +.I name +supplied, in the directory +.RI ( dir ) +represented by +.IR fid , +and requires write permission in the directory. +The owner of the file is the implied user id of the request, +the group of the file is the same as +.IR dir , +and the permissions are the value of +.ce +.B "perm & (~0666 | (dir.perm & 0666))" +if a regular file is being created and +.ce +.B "perm & (~0777 | (dir.perm & 0777))" +if a directory is being created. +This means, for example, that if the +.B create +allows read permission to others, but the containing directory +does not, then the created file will not allow others to read the file. +.PP +Finally, the newly created file is opened according to +.IR mode , +and +.I fid +will represent the newly opened file. +.I Mode +is not checked against the permissions in +.IR perm . +The +.I qid +for the new file is returned with the +.B create +reply message. +.PP +Directories are created by setting the +.B DMDIR +bit +.RB ( 0x80000000 ) +in the +.IR perm . +.PP +The names +.B . +and +.B .. +are special; it is illegal to create files with these names. +.PP +It is an error for either of these messages if the fid +is already the product of a successful +.B open +or +.B create +message. +.PP +An attempt to +.B create +a file in a directory where the given +.I name +already exists will be rejected; +in this case, the +.I fscreate +call +(see +.IR 9pclient (3)) +uses +.B open +with truncation. +The algorithm used by the +.IR create +system call +is: +first walk to the directory to contain the file. +If that fails, return an error. +Next +.B walk +to the specified file. +If the +.B walk +succeeds, send a request to +.B open +and truncate the file and return the result, successful or not. +If the +.B walk +fails, send a create message. +If that fails, it may be because the file was created by another +process after the previous walk failed, so (once) try the +.B walk +and +.B open +again. +.\" .PP +.\" For the behavior of +.\" .I create +.\" on a union directory, see +.\" .IR bind (2). +.\" .PP +.\" The +.\" .B iounit +.\" field returned by +.\" .B open +.\" and +.\" .B create +.\" may be zero. +.\" If it is not, it is the maximum number of bytes that are guaranteed to +.\" be read from or written to the file without breaking the I/O transfer +.\" into multiple 9P messages; see +.\" .IR read (9P). +.SH ENTRY POINTS +.I Fsopen +and +.I fscreate +(see +.IR 9pclient (3)) +both generate +.B open +messages; only +.I fscreate +generates a +.B create +message. +The +.B iounit +associated with an open file may be discovered by calling +.IR fsiounit . +.PP +For programs that need atomic file creation, without the race +that exists in the +.B open-create +sequence described above, +.IR fscreate +does the following. +If the +.B OEXCL +.RB ( 0x1000 ) +bit is set in the +.I mode +for a +.I fscreate +call, +the +.B open +message is not sent; the kernel issues only the +.BR create . +Thus, if the file exists, +.I fscreate +will draw an error, but if it doesn't and the +.I fscreate +call succeeds, the process issuing the +.I fscreate +is guaranteed to be the one that created the file. diff --git a/man/man9/read.9p b/man/man9/read.9p new file mode 100644 index 00000000..a68f153e --- /dev/null +++ b/man/man9/read.9p @@ -0,0 +1,126 @@ +.TH READ 9P +.SH NAME +read, write \- transfer data from and to a file +.SH SYNOPSIS +.ta \w'\fLTwrite 'u +.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 ] +.PP +.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] +.SH DESCRIPTION +The +.B read +request +asks for +.I count +bytes of data +from the file identified by +.IR fid , +which must be opened for reading, +starting +.I offset +bytes after the beginning of the file. +The bytes are returned with the +.B read +reply message. +.PP +The +.I count +field in the reply indicates the number of bytes returned. +This may be less than the requested amount. +If the +.I offset +field is greater than or equal to the number of bytes in the file, +a count of zero will be returned. +.PP +For directories, +.B read +returns an integral number of +directory entries exactly as in +.B stat +(see +.IR stat (9P)), +one for each member of the directory. +The +.B read +request message must have +.B offset +equal to zero or the value of +.B offset +in the previous +.B read +on the directory, plus the number of bytes +returned in the previous +.BR read . +In other words, seeking other than to the beginning +is illegal in a directory. +.PP +The +.B write +request asks that +.I count +bytes of data be recorded in the file identified by +.IR fid , +which must be opened for writing, starting +.I offset +bytes after the beginning of the file. +If the file is append-only, +the data will be placed at the end of the file regardless of +.IR offset . +Directories may not be written. +.PP +The +.B write +reply records the number of bytes actually written. +It is usually an error +if this is not the same as requested. +.PP +Because 9P implementations may limit the size of individual +messages, +more than one message may be produced by a single +.I read +or +.I write +call. +The +.I iounit +field returned by +.IR open (9P), +if non-zero, reports the maximum size that is guaranteed +to be transferred atomically. +.SH ENTRY POINTS +.I Fsread +and +.I fswrite +(see +.IR 9pclient (3)) +generate the corresponding messages. +Because they take an offset parameter, the +.I fspread +and +.I fspwrite +calls correspond more directly to the 9P messages. +Although +.I fsseek +affects the offset, it does not generate a message. diff --git a/man/man9/remove.9p b/man/man9/remove.9p new file mode 100644 index 00000000..a9a844a1 --- /dev/null +++ b/man/man9/remove.9p @@ -0,0 +1,51 @@ +.TH REMOVE 9P +.SH NAME +remove \- remove a file from a server +.SH SYNOPSIS +.ta \w'\fLTremove 'u +.IR size [4] +.B Tremove +.IR tag [2] +.IR fid [4] +.br +.IR size [4] +.B Rremove +.IR tag [2] +.SH DESCRIPTION +The +.B remove +request asks the file server both to remove the file represented by +.I fid +and to +.B clunk +the +.IR fid , +even if the remove fails. +This request will fail if the client does not have write permission +in the parent directory. +.PP +It is correct to consider +.B remove +to be a +.B clunk +with the side effect of removing the file if permissions allow. +.PP +If a file has been opened as multiple fids, +possibly on different connections, +and one fid is used to remove the file, +whether the other fids continue to provide access to the file +is implementation-defined. +The Plan 9 file servers +remove the file immediately: attempts to use the other fids +will yield a +``phase error.'' +.IR U9fs +follows the semantics of the underlying Unix file system, +so other fids typically remain usable. +.SH ENTRY POINTS +.I Fsremove +(see +.IR 9pclient (3)) +generates +.B remove +messages. diff --git a/man/man9/stat.9p b/man/man9/stat.9p new file mode 100644 index 00000000..ab68133d --- /dev/null +++ b/man/man9/stat.9p @@ -0,0 +1,297 @@ +.TH STAT 9P +.SH NAME +stat, wstat \- inquire or change file attributes +.SH SYNOPSIS +.ta \w'\fLTwstat 'u +.IR size [4] +.B Tstat +.IR tag [2] +.IR fid [4] +.br +.IR size [4] +.B Rstat +.IR tag [2] +.IR stat [ n ] +.PP +.IR size [4] +.B Twstat +.IR tag [2] +.IR fid [4] +.IR stat [ n ] +.br +.IR size [4] +.B Rwstat +.IR tag [2] +.SH DESCRIPTION +The +.B stat +transaction inquires about the file +identified by +.IR fid . +The reply will contain a +machine-independent +.I directory +.IR entry , +.IR stat , +laid out as follows: +.TP +.I size\f1[2]\fP +total byte count of the following data +.TP +.I type\f1[2]\fP +for kernel use +.TP +.I dev\f1[4]\fP +for kernel use +.TP +.I qid.type\f1[1]\fP +the type of the file (directory, etc.), represented as a bit vector +corresponding to the high 8 bits of the file's mode word. +.TP +.I qid.vers\f1[4]\fP +version number for given path +.TP +.I qid.path\f1[8]\fP +the file server's unique identification for the file +.TP +.I mode\f1[4]\fP +permissions and flags +.TP +.I atime\f1[4]\fP +last access time +.TP +.I mtime\f1[4]\fP +last modification time +.TP +.I length\f1[8]\fP +length of file in bytes +.TP +.I name\f1[ s ]\fP +file name; must be +.B / +if the file is the root directory of the server +.TP +.I uid\f1[ s ]\fP +owner name +.TP +.I gid\f1[ s ]\fP +group name +.TP +.I muid\f1[ s ]\fP +name of the user who last modified the file +.PD +.PP +Integers in this encoding are in little-endian order (least +significant byte first). +The +.I convM2D +and +.I convD2M +routines (see +.IR fcall (3)) +convert between directory entries and a C structure called a +.BR Dir . +.PP +The +.I mode +contains permission bits as described in +.IR intro (9P) +and the following: +.B 0x80000000 +.RB ( DMDIR , +this file is a directory), +.B 0x40000000 +.RB ( DMAPPEND , +append only), +.B 0x20000000 +.RB ( DMEXCL , +exclusive use), +.B 0x04000000 +.RB ( DMTMP , +temporary); +these are echoed in +.BR Qid.type . +Writes to append-only files always place their data at the +end of the file; the +.I offset +in the +.B write +message is ignored, as is the +.B OTRUNC +bit in an open. +Exclusive use files may be open for I/O by only one fid at a time +across all clients of the server. If a second open is attempted, +it draws an error. Servers may implement a timeout on the lock +on an exclusive use file: if the fid holding the file open has +been unused for an extended period (of order at least minutes), +it is reasonable to break the lock and deny the initial fid +further I/O. +Temporary files are not included in nightly archives +(see Plan 9's \fIfossil\fR(4)). +.PP +The two time fields are measured in seconds since the epoch +(Jan 1 00:00 1970 GMT). +The +.I mtime +field reflects the time of the last change of content (except when later changed by +.BR wstat ). +For a plain file, +.I mtime +is the time of the most recent +.BR create , +.B open +with truncation, +or +.BR write ; +for a directory it is the time of the most recent +.BR remove , +.BR create , +or +.B wstat +of a file in the directory. +Similarly, the +.I atime +field records the last +.B read +of the contents; +also it is set whenever +.I mtime +is set. +In addition, for a directory, it is set by +an +.BR attach , +.BR walk , +or +.BR create , +all whether successful or not. +.PP +The +.I muid +field names the user whose actions most recently changed the +.I mtime +of the file. +.PP +The +.I length +records the number of bytes in the file. +Directories and most files representing devices have a conventional +length of 0. +.PP +The +.B stat +request requires no special permissions. +.PP +The +.B wstat +request can change some of the file status information. +The +.I name +can be changed by anyone with write permission in the parent directory; +it is an error to change the name to that of an existing file. +The +.I length +can be changed (affecting the actual length of the file) by anyone with +write permission on the file. +It is an error to attempt to set the length of a directory to a non-zero value, +and servers may decide to reject length changes for other reasons. +The +.I mode +and +.I mtime +can be changed by the owner of the file or the group leader of the file's current +group. +The directory bit cannot be changed by a +.BR wstat ; +the other defined permission and mode bits can. +The +.I gid +can be changed: by the owner if also a member of the new group; or +by the group leader of the file's current group +if also leader of the new group +(see +.IR intro (9P) +for more information about permissions, users, and groups). +None of the other data can be altered by a +.B wstat +and attempts to change them will trigger an error. +In particular, +it is illegal to attempt to change the owner of a file. +(These conditions may be +relaxed when establishing the initial state of a file server; see +Plan 9's \fIfsconfig\fR(8).) +.PP +Either all the changes in +.B wstat +request happen, or none of them does: if the request succeeds, +all changes were made; if it fails, none were. +.PP +A +.B wstat +request can avoid modifying some properties of the file +by providing explicit ``don't touch'' values in the +.B stat +data that is sent: zero-length strings for text values and +the maximum unsigned value of appropriate size +for integral values. +As a special case, if +.I all +the elements of the directory entry in a +.B Twstat +message are ``don't touch'' values, the server may interpret it +as a request to guarantee that the contents of the associated +file are committed to stable storage before the +.B Rwstat +message is returned. +(Consider the message to mean, ``make the state of the file +exactly what it claims to be.'') +.PP +A +.I read +of a directory yields an integral number of directory entries in +the machine independent encoding given above +(see +.IR read (9P)). +.PP +Note that since the +.B stat +information is sent as a 9P variable-length datum, it is limited to a maximum of +65535 bytes. +.SH ENTRY POINTS +.B Stat +messages are generated by +.I fsdirfstat +and +.IR fsdirstat +(see +.IR 9pclient (3)). +.PP +.B Wstat +messages are generated by +.I fsdirfwstat +and +.IR fsdirwstat . +.SH BUGS +To make the contents of a directory, such as returned by +.IR read (9P), +easy to parse, each +directory entry begins with a size field. +For consistency, the entries in +.B Twstat +and +.B Rstat +messages also contain +their size, which means the size appears twice. +For example, the +.B Rstat +message is formatted as +.RI ``(4+1+2+2+ n )[4] +.B Rstat +.IR tag [2] +.IR n [2] +.RI ( n -2)[2] +.IR type [2] +.IR dev [4]...,'' +where +.I n +is the value returned by +.BR convD2M . diff --git a/man/man9/version.9p b/man/man9/version.9p new file mode 100644 index 00000000..c4961217 --- /dev/null +++ b/man/man9/version.9p @@ -0,0 +1,99 @@ +.TH VERSION 9P +.SH NAME +version \- negotiate protocol version +.SH SYNOPSIS +.ta \w'\fLTversion 'u +.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 ] +.SH DESCRIPTION +The +.B version +request negotiates the protocol version and message size +to be used on the connection and initializes the connection for I/O. +.B Tversion +must be the first message sent on the 9P connection, +and the client cannot issue any further requests until it has received the +.B Rversion +reply. +The +.I tag +should be +.B NOTAG +(value +.BR (ushort)~0 ) +for a +.B version +message. +.PP +The client suggests a maximum message size, +.BR msize , +that is the maximum length, in bytes, +it will ever generate or expect to receive in a single 9P message. +This count includes all 9P protocol data, starting from the +.B size +field and extending through the message, +but excludes enveloping transport protocols. +The server responds with its own maximum, +.BR msize , +which must be less than or equal to the client's value. +Thenceforth, both sides of the connection must honor this limit. +.PP +The +.B version +string identifies the level of the protocol. +The string must always begin with the two characters +.RB `` 9P ''. +If the server does not understand the client's version string, +it should respond with an +.B Rversion +message (not +.BR Rerror ) +with the +.B version +string the 7 characters +.RB `` unknown ''. +.PP +The server may respond with the client's version string, +or a version string identifying +an earlier defined protocol version. +Currently, the only defined version is the 6 characters +.RB `` 9P2000 ''. +Version strings are defined such that, if the client string contains +one or more period characters, the initial substring up to but not including +any single period in the version string defines a version of the protocol. +After stripping any such period-separated suffix, the server is allowed to respond +with a string of the form +.BI 9P nnnn\f1, +where +.I nnnn +is less than or equal to the digits sent by the client. +.PP +The client and server will use the protocol version defined by the +server's response for all subsequent communication on the connection. +.PP +A successful +.B version +request initializes the connection. +All outstanding I/O on the connection is aborted; all active fids are freed (`clunked') automatically. +The set of messages between +.B version +requests is called a +.IR session . +.SH ENTRY POINTS +.I Fsversion +(see +.IR 9pclient (3)) +generates +.B version +messages; +it is called automatically by +.IR fsmount . diff --git a/man/man9/walk.9p b/man/man9/walk.9p new file mode 100644 index 00000000..49777f21 --- /dev/null +++ b/man/man9/walk.9p @@ -0,0 +1,189 @@ +.TH WALK 9P +.SH NAME +walk \- descend a directory hierarchy +.SH SYNOPSIS +.ta \w'\fLTwalk 'u +.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 *( qid [13]) +.SH DESCRIPTION +The +.B walk +request carries as arguments an existing +.IR fid +and a proposed +.I newfid +(which must not be in use unless it is the same as +.IR fid ) +that the client wishes to associate with +the result of traversing the directory hierarchy +by `walking' the hierarchy using the successive path name +elements +.BR wname . +The +.I fid +must represent a directory unless zero path name elements are specified. +.PP +The +.I fid +must be valid in the current session and must not have been opened for I/O +by an +.B open +or +.B create +message. +If the full sequence of +.B nwname +elements is walked successfully, +.I newfid +will represent the file that results. +If not, +.I newfid +(and +.BR fid ) +will be unaffected. +However, if +.I newfid +is in use or otherwise illegal, an +.B Rerror +is returned. +.PP +The name +.RB `` .. '' +(dot-dot) represents the parent directory. +The name +.RB `` . '' +(dot), meaning the current directory, is not used in the protocol. +.PP +It is legal for +.B nwname +to be zero, in which case +.I newfid +will represent the same file as +.I fid +and the +.B walk +will usually succeed; this is equivalent to walking to dot. +The rest of this discussion assumes +.B nwname +is greater than zero. +.PP +The +.B nwname +path name elements +.B wname +are walked in order, ``elementwise''. +For the first elementwise walk +to succeed, the file identified by +.I fid +must be a directory, +and the implied user of the request must have permission +to search the directory (see +.IR intro (9P)). +Subsequent elementwise walks have equivalent restrictions +applied to the implicit fid that results from the preceding elementwise walk. +.PP +If the first element cannot be walked for any reason, +.B Rerror +is returned. +Otherwise, the walk will return an +.B Rwalk +message containing +.I nwqid +qids corresponding, in order, to the files that are visited by the +.I nwqid +successful elementwise walks; +.I nwqid +is therefore either +.B nwname +or the index of the first elementwise walk that failed. +The value of +.I nwqid +cannot be zero unless +.B nwname +is zero. +Also, +.I nwqid +will always be less than or equal to +.BR nwname . +Only if it is equal, however, will +.I newfid +be affected, in which case +.I newfid +will represent the file +reached by the final elementwise walk requested in the message. +.PP +A +.B walk +of the name +.RB `` .. '' +in the root directory of a server is equivalent to a walk with no name elements. +.PP +If +.I newfid +is the same as +.IR fid , +the above discussion applies, with the obvious difference +that if the walk changes the state of +.IR newfid , +it also changes the state of +.IR fid ; +and if +.I newfid +is unaffected, then +.I fid +is also unaffected. +.PP +To simplify the implementation of the servers, a maximum of sixteen name elements or qids +may be packed in a single message. +This constant is called +.B MAXWELEM +in +.IR fcall (3). +Despite this restriction, the system imposes no limit on the number of elements in a file name, +only the number that may be transmitted in a single message. +.SH ENTRY POINTS +.I Fswalk +(see +.IR 9pclient (3)) +generates walk messages. +One or more walk messages may be generated by +any call that evaluates file names: +.IR fsopen , +.IR fsopenfd , +.IR fsdirstat , +.IR fsdirwstat . +.\" +.\" A call to +.\" .IR chdir (2) +.\" causes a +.\" .BR walk . +.\" One or more +.\" .B walk +.\" messages may be generated by +.\" any of the following calls, which evaluate file names: +.\" .IR bind , +.\" .IR create , +.\" .IR exec , +.\" .IR mount , +.\" .IR open , +.\" .IR remove , +.\" .IR stat , +.\" .IR unmount , +.\" .IR wstat . +.\" The file name element +.\" .B . +.\" (dot) is interpreted locally and +.\" is not transmitted in +.\" .B walk +.\" messages. -- cgit v1.2.3