diff options
| -rw-r--r-- | include/version.h | 2 | ||||
| -rw-r--r-- | man/5/0intro | 39 | ||||
| -rw-r--r-- | man/5/attach | 2 | ||||
| -rw-r--r-- | man/5/error | 6 | ||||
| -rw-r--r-- | man/5/flush | 27 | ||||
| -rw-r--r-- | man/5/open | 2 | ||||
| -rw-r--r-- | man/5/read | 2 | ||||
| -rw-r--r-- | man/5/stat | 4 | ||||
| -rw-r--r-- | man/5/version | 6 |
9 files changed, 64 insertions, 26 deletions
diff --git a/include/version.h b/include/version.h index 5dbe9821..ac2fdf5e 100644 --- a/include/version.h +++ b/include/version.h @@ -1 +1 @@ -#define VERSION "Fourth Edition (20100115)" +#define VERSION "Fourth Edition (20100202)" diff --git a/man/5/0intro b/man/5/0intro index ccc11e8a..5b2afc06 100644 --- a/man/5/0intro +++ b/man/5/0intro @@ -1,11 +1,25 @@ .TH INTRO 5 .SH NAME -intro \- introduction to the Inferno File Protocol, Styx +intro \- introduction to the Plan 9 File Protocol 9P in Inferno .SH SYNOPSIS .B #include <lib9.h> .br .B #include <styx.h> .SH DESCRIPTION +Inferno uses the Plan 9 protocol 9P to make resources visible as file hierarchies. +There have been two versions of 9P, the most recent being 9P2000. +Inferno originally used its own protocol called +.IR Styx , +which was a simplified version of the first 9P protocol. +When 9P was subsequently revised as 9P2000, Inferno adopted that, but still using the name +.IR Styx . +To reduce confusion and to emphasise that Inferno and Plan 9 use the same protocol, +the name +.I Styx +is being replaced by 9P. +References to `Styx' remain in the programs and documentation, +but will eventually be eliminated. +.PP An Inferno .I server is an agent that provides one or more hierarchical file systems @@ -56,12 +70,11 @@ system calls operating on files are translated into requests and responses transmitted on the connection to the appropriate service. .PP The -.IR "Inferno File Protocol" , -Styx, is used for messages between +.IR "Plan 9 File Protocol" , +9P, is used for messages between .I clients and .IR servers . -The current version of Styx is identical to Plan 9's 9P2000. A client transmits .I requests .RI ( T-messages ) @@ -90,17 +103,17 @@ Text strings are represented this way, with the text itself stored as a UTF-8 encoded sequence of Unicode characters (see .IR utf (6)). -Text strings in Styx messages are not +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 Styx, and is therefore +character is illegal in all text strings in 9P, and is therefore excluded from file names, user names, and so on. .PP -Each Styx message begins with a four-byte size field +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 @@ -397,7 +410,7 @@ messages and subsequently manipulated using .B read and .B write -messages to exchange authentication information not defined explicitly by the protocol. +messages to exchange authentication information not defined explicitly by 9P. Once the authentication protocol is complete, the .B afid is presented in the @@ -524,11 +537,11 @@ The exception is that a long error string in an message should be truncated if necessary, since the string is only advisory and in some sense arbitrary. .PP -Most programs do not see the Styx protocol directly; instead calls to library +Most programs do not see the 9P protocol directly; instead calls to library routines that access files are translated by the mount driver, .IR mnt (3), -into Styx messages. +into 9P messages. .SH DIRECTORIES Directories are created by .B create @@ -613,8 +626,10 @@ These bits are reproduced, from the top bit down, in the type byte of the Qid: .BR QTDIR , .BR QTAPPEND , .BR QTEXCL , -and (skipping one bit) -.BR QTAUTH . +(skipping one bit) +.BR QTAUTH , +and +.BR QTTMP . The name .BR QTFILE , defined to be zero, diff --git a/man/5/attach b/man/5/attach index 09a911f2..4e4860c6 100644 --- a/man/5/attach +++ b/man/5/attach @@ -102,7 +102,7 @@ that may be read and written (using and .B write messages in the usual way) to execute an authentication protocol. -That protocol's definition is not part of Styx itself. +That protocol's definition is not part of 9P itself. .PP Once the protocol is complete, the same .I afid diff --git a/man/5/error b/man/5/error index 9b6984d3..2dfb79bd 100644 --- a/man/5/error +++ b/man/5/error @@ -20,6 +20,6 @@ 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 128 bytes, -defined as the constant -.BR Sys->ERRMAX . +By convention, clients may truncate error messages after +.B Sys->ERRMAX-1 +bytes. diff --git a/man/5/flush b/man/5/flush index 48c2d306..914f81d7 100644 --- a/man/5/flush +++ b/man/5/flush @@ -24,7 +24,7 @@ The semantics of .B flush depends on messages arriving in order. .PP -The server must answer the +The server should answer the .B flush message immediately. If it recognizes @@ -46,6 +46,29 @@ 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. An +.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 @@ -75,4 +98,4 @@ flushing a .BR Tflush , and flushing an invalid tag. .SH SEE ALSO -.IR sys-read (2). +.IR sys-read (2) @@ -202,7 +202,7 @@ and 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 Styx messages; see +into multiple 9P messages; see .IR read (5). .SH ENTRY POINTS .I Open @@ -97,7 +97,7 @@ reply records the number of bytes actually written. It is usually an error if this is not the same as requested. .PP -Because Styx implementations may limit the size of individual +Because 9P implementations may limit the size of individual messages, more than one message may be produced by a single .I read @@ -262,7 +262,7 @@ the machine independent encoding given above .PP Note that since the .B stat -information is sent as a Styx variable-length datum, it is limited to a maximum of +information is sent as a 9P variable-length datum, it is limited to a maximum of 65535 bytes. .SH ENTRY POINTS .B Stat @@ -305,5 +305,5 @@ message is formatted as .IR dev [4]...,'' where .I n -is the value returned by +is the length of the array returned by .BR Styx->packdir . diff --git a/man/5/version b/man/5/version index ea836cb4..9fea7294 100644 --- a/man/5/version +++ b/man/5/version @@ -20,7 +20,7 @@ The 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 Styx connection, +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. @@ -37,8 +37,8 @@ message. 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 Styx message. -This count includes all Styx protocol data, starting from the +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. |