The following utilities are used in the Inferno file protocol:
messages to initiate activity|
duplicate a fid|
forget about a fid|
return an error|
abort a message|
prepare a fid for I/O on an existing or new file|
transfer data from and to a file|
remove a file from a server|
inquire or change file attributes|
C interface to Inferno file protocol|
descend a directory hierarchy|
#include <lib9.h> #include <styx.h>
A 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 bin and mount and calls. See bind and Limbo System Modules. Processes in the group are then clients of the servers. Their system calls operating on the server's files are translated into requests and transmitted over the connection to the appropriate server. The server's response completes the request.
The Inferno File Protocol, Styx, is used for messages between clients and servers. A client transmits requests (T-messages) to a server, which subsequently returns replies (R-messages) to the client. The combined acts of transmitting (receiving) a request of a particular type (e.g., read, write, stat) and receiving (transmitting) its reply is called a transaction of that type.
Each message consists of a sequence of bytes. The first byte is the message type, one of the constants in the enumeration in the C include file <styx.h>. (See styx).
The remaining bytes are parameters. Each parameter consists of a fixed number of bytes (except the data fields of write requests or read replies). In the message descriptions below, the number of bytes in a field is given in brackets after the field name. The two-, four-, and eight-byte fields may hold unsigned integers represented in little-endian order (least significant byte first). Fields that contain names are 28-byte strings (including a terminal NUL (zero) byte).
Tnop tag  Rnop tag  Rerror tag  ename  Tflush tag  oldtag  Rflush tag  Tattach tag  fid  uid  aname  Rattach tag  fid  qid  Tclone tag  fid  newfid  Rclone tag  fid  Twalk tag  fid  name  Rwalk tag  fid  qid  Topen tag  fid  mode  Ropen tag  fid  qid  Tcreate tag  fid  name  perm  mode  Rcreate tag  fid  qid  Tread tag  fid  offset  count  Rread tag  fid  count  pad  data [count] Twrite tag  fid  offset  count  pad  data [count] Rwrite tag  fid  count  Tclunk tag  fid  Rclunk tag  fid  Tremove tag  fid  Rremove tag  fid  Tstat tag  fid  Rstat tag  fid  stat  Twstat tag  fid  stat  Rwstat tag  fid The numerical value for the type of an R-message will be one greater than that of the corresponding T-message. See styx. However, when a request fails a Rerror type message is sent instead. The Rerror message has an ename field which contains a string describing the reason for failure.
The nop message request has no obvious effect. Its main purpose is in debugging the connection between a client and a server. It is never required.
Most T-messages contain a fid, a 16-bit unsigned integer that the client uses to identify a current file on the server. Fids are like file descriptors in a user process, but they are not restricted to files open for I/O. They are also used when directories being examined, files are accessed by stat calls, and so on. All files being manipulated by the operating system 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.
Two files on the same server hierarchy are the same if and only if their qids
are the same.
Each T-message has a tag field, that 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 NOTAG, value 16rFFFF, meaning 'no tag'. The client can use the NOTAG message, when establishing a connection, to override tag matching in messages.
Replies (R-messages) to attach, walk, open, and create requests convey a qid field back to the client. The qid represents the server's unique identification for the file being accessed:
The client may have multiple fids pointing to a single file on a server and hence having a single qid.
Two files on the same server hierarchy are the same if and only if their qids are the same.
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. |
Directories always have the CHDIR bit (16r80000000) set in their qid path.
The version is a version number of the file. Typically, it is incremented every time the file is modified.|
An existing file can be open'ed or a new file may be create'd in the current directory. See open.
I/O of a given number of bytes (limit 8192) at a given offset on an open file is done by read and write. See read.
A client should clunk any fid that is no longer needed. See clunk.
The remove transaction deletes files. See remove.
The stat transaction retrieves information about the file. The stat field in the reply includes the file's name, access permissions (read, write and execute for owner, group and others), access and modification times, and owner and group identifications (each 28-byte strings). The wstat transaction allows some of a file's properties to be changed. See stat and stat.
A request can be aborted with a Tflush request. When a server receives a Tflush, it should not reply to the message with tag oldtag (unless it has already replied), and it should immediately send an Rflush. The client should ignore replies with tag oldtag until it gets the Rflush, at which point oldtag may be reused. See flush.
Directories are created by create with CHDIR set in the permissions argument (see stat). The members of a directory can be found with read.
All servers must support requests to walk from the current directory to the directory ".." (dot-dot, meaning parent directory) although, by convention, directories contain no explicit entry for ".." or "." (dot, current directory). The parent of the root directory of a server's tree is itself.
Each file server maintains a set of user and group names. Each user can be a member of any number of groups.
bit 31 |
If bit 31 is set, the file is a directory.|
bits 8, 7, and 6|
Owner read/write/execute permissions.|
bits 5, 4, 3|
Group read/write/execute permissions.|
bits 2, 1, and 0|
Other read/write/execute permissions.|
Header files are located as follows:
<inferno_root> <systarg> / <objtype> /include/lib9.h|
styx, Limbo Modules, bind, stat, prog, read, and stat