.TH INTRO 5 .SH NAMEintro \- introduction to the Inferno File Protocol, Styx.SH SYNOPSIS.B #include <lib9.h>.br.B #include <styx.h>.SH DESCRIPTIONAn Inferno.I serveris an agent that provides one or more hierarchical file systems\(em file trees \(emthat may be accessed by Inferno processes.A server responds to requests by.I clientsto navigate the hierarchy,and to create, remove, read, and write files.The prototypical server is a separate machine that storeslarge numbers of user files on permanent media.Another possibility for a server is to synthesizefiles on demand, perhaps based on information on data structuresinside the kernel; the.IR prog (3).I kernel deviceis a part of the Inferno kernel that does this.User programs can also act as servers.One easy way is to serve a set of filesusing the.IR sys-file2chan (2)interface.More complex Limbo file service applications can use.IR styx (2)to handle the protocol messages directly,or use.IR styxservers (2)to provide a higher-level framework for file serving..PPA.I connectionto a server is a bidirectional communication path from the client to the server.There may be a single client ormultiple clients sharing the same connection.A server's file tree is attached to a processgroup's name space by.IR bindand.I mountcalls;see.IR intro (2)and.IR sys-bind (2).Processes in the group are then clientsof the server:system calls operating on files are translated into requestsand responses transmitted on the connection to the appropriate service..PPThe.IR "Inferno File Protocol" ,Styx, is used for messages between.I clientsand.IR servers .The current version of Styx is identical to Plan 9's 9P2000.A client transmits.I requests.RI ( T-messages )to a server, whichsubsequently 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 transactionof that type..PPEach message consists of a sequence of bytes.Two-, four-, and eight-byte fields hold unsignedintegers represented in little-endian order(least significant byte first).Data items of larger or variable lengths are representedby a two-byte field specifying a count,.IR n ,followed by.I nbytes of data.Text strings are represented this way,with the text itself stored as a UTF-8encoded sequence of Unicode characters (see.IR utf (6)).Text strings in Styx messages are not.SM NUL\c-terminated:.I ncounts the bytes of UTF-8 data, which include no final zero byte.The.SM NULcharacter is illegal in all text strings in Styx, and is thereforeexcluded from file names, user names, and so on..PPEach Styx message begins with a four-byte size fieldspecifying the length in bytes of the complete message includingthe four bytes of the size field itself.The next byte is the message type, one of the constantsin the module.IR styx (2),and in the C include file.BR <styx.h>(see.IR styx (10.2)).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 fieldis given in brackets after the field name.The notation.IR parameter [ n ]where.I nis not a constant represents a variable-length parameter:.IR n [2]followed by.I nbytes of data forming the.IR parameter .The notation.IR string [ s ](using a literal.I scharacter)is shorthand for.IR s [2]followed by.I sbytes of UTF-8 text.(Systems may choose to reduce the set of legal charactersto reduce syntactic problems,for example to remove slashes from name components,but the protocol has no such restriction.Inferno names may contain any printable character (that is, any characteroutside hexadecimal 00-1F and 80-9F)except slash.)Messages are transported in byte form to allow for machine independence;.IR styx (10.2)describes routines that convert to and from this form into a machine-dependentC 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 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].PPEach T-message has a.I tagfield, 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 messageson the same connection have the same tag.An exception is the tag.BR NOTAG ,defined as.B 16rFFFFin.IR styx (2)and.IR styx (10.2):the client can use it, when establishing a connection,tooverride tag matching in.B versionmessages..PPThe type of an R-message will either be one greater than the typeof the corresponding T-message or.BR Rerror ,indicating that the request failed.In the latter case, the.I enamefield contains a string describing the reason for failure..PPThe.B versionmessage identifies the version of the protocol and indicatesthe maximum message size the system is prepared to handle.It also initializes the connection andaborts all outstanding I/O on the connection.The set of messages between.B versionrequests is called a.IR session ..PPMost T-messages contain a.IR fid ,a 32-bit unsigned integer that the client uses to identifya ``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 sys-stat (2)calls, and so on \(em all files being manipulated by the operatingsystem \(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 arrangethat no two clients choose the same fid..PPThe fid supplied in an.B attachmessagewill be taken by the server to refer to the root of the served file tree.The.B attachidentifies the userto the server and may specify a particular file tree servedby the server (for those that supply more than one)..PPPermission to attach to the service is proven by providing a special fid, called.BR afid ,in the.B attachmessage. This.B afidis established by exchanging.B authmessages and subsequently manipulated using.B readand.B writemessages to exchange authentication information not defined explicitly by the protocol.Once the authentication protocol is complete, the.B afidis presented in the.B attachto permit the user to access the service..PPA.B walkmessage causes the server to change the current file associatedwith a fid to be a file in the directory that is the old current file, or one ofits subdirectories..B Walkreturns a new fid that refers to the resulting file.Usually, a client maintains a fid for the root,and navigates by.B walksfrom the root fid..PPA client can send multiple T-messages without waiting for the correspondingR-messages, but all outstanding T-messages must specify different tags.The server may delay the response to a requestand respond to later ones;this is sometimes necessary, for example when the client readsfrom a file that the server synthesizes from external eventssuch as keyboard characters..PPReplies (R-messages) to.BR auth ,.BR attach ,.BR walk ,.BR open ,and.B createrequests convey a.I qidfield back to the client.The qid represents the server's unique identification for thefile being accessed:two files on the same server hierarchy are the same if and only if their qidsare the same.(The client may have multiple fids pointing to a single file on a serverand 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 thesame name in the same directory, the old and new path components of the qidsshould be different.The version is a version number for a file;typically, it is incremented every time the file is modified..PPAn existing file can be.BR opened ,or a new file may be.B createdin the current (directory) file.I/O of a given number of bytesat a given offseton an open file is done by.B readand.BR write ..PPA client should.B clunkany fid that is no longer needed.The.B removetransaction deletes files..PPThe.B stattransaction retrieves information about the file.The.I statfield in the reply includes the file'sname,access permissions (read, write and execute for owner, group and public),access and modification times, andowner and group identifications(see.IR stat (2)).The owner and group identifications are textual names.The.B wstattransaction allows some of a file's propertiesto be changed..PPA request can be aborted with aflushrequest.When a server receives a.BR Tflush ,it should not reply to the message with tag.I oldtagLines 1–500 of 632. Load more
.TH INTRO 5 .SH NAME intro \- introduction to the Inferno File Protocol, Styx .SH SYNOPSIS .B #include <lib9.h> .br .B #include <styx.h> .SH DESCRIPTION An Inferno .I server is an agent that provides one or more hierarchical file systems \(em file trees \(em that may be accessed by Inferno 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. Another possibility for a server is to synthesize files on demand, perhaps based on information on data structures inside the kernel; the .IR prog (3) .I kernel device is a part of the Inferno kernel that does this. User programs can also act as servers. One easy way is to serve a set of files using the .IR sys-file2chan (2) interface. More complex Limbo file service applications can use .IR styx (2) to handle the protocol messages directly, or use .IR styxservers (2) to provide a higher-level framework for file serving. .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. A server's file tree is attached to a process group's name space by .IR bind and .I mount calls; see .IR intro (2) and .IR sys-bind (2). Processes in the group are then clients of the server: 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 .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 ) 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 (6)). Text strings in Styx 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 excluded from file names, user names, and so on. .PP Each Styx 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 module .IR styx (2), and in the C include file .BR <styx.h> (see .IR styx (10.2)). 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. Inferno 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 styx (10.2) 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 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 16rFFFF in .IR styx (2) and .IR styx (10.2): 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 sys-stat (2) 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 the protocol. 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 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 (2)). 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