The following utilities are used in the Inferno file protocol:

attach nop	messages to initiate activity
clone	duplicate a fid
clunk	forget about a fid
error	return an error
flush	abort a message
open create	prepare a fid for I/O on an existing or new file
read write	transfer data from and to a file
remove	remove a file from a server
stat wstat	inquire or change file attributes
styx call, convs2m, convd2m, convm2s, convm2d, fcallconv, dirconv, dirmodeconv	C interface to Inferno file protocol
walk	descend a directory hierarchy

Synopsis

#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.

Most programs do not see the Styx protocol directly. Most programs make calls to library routines that access files. Their requests are translated by the mount driver, mnt, into Styx messages. Client application programs need not explicitly manage details of fids, tags, etc. described below.

Message Format

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).

Other than the NUL terminator, all characters are legal in file names. 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 and blank. Messages are transported in byte form to allow machine independence. The styx manual page describes C routines that convert to and from this form into a machine-dependent C structure.

Message Types

Tnop     tag [2]
Rnop     tag [2]
Rerror   tag [2] ename [64]
Tflush   tag [2] oldtag [2]
Rflush   tag [2]
Tattach  tag [2] fid [2] uid [28] aname [28]
Rattach  tag [2] fid [2] qid [8]
Tclone   tag [2] fid [2] newfid [2]
Rclone   tag [2] fid [2]
Twalk    tag [2] fid [2] name [28]
Rwalk    tag [2] fid [2] qid [8]
Topen    tag [2] fid [2] mode [1]
Ropen    tag [2] fid [2] qid [8]
Tcreate  tag [2] fid [2] name [28] perm [4] mode [1]
Rcreate  tag [2] fid [2] qid [8]
Tread    tag [2] fid [2] offset [8] count [2]
Rread    tag [2] fid [2] count [2]  pad [1] data [count]
Twrite    tag  [2]  fid [2]  offset [8] count [2] pad [1] data [count]
Rwrite   tag [2] fid [2] count [2]
Tclunk   tag [2] fid [2]
Rclunk   tag [2] fid [2]
Tremove  tag [2] fid [2]
Rremove  tag [2] fid [2]
Tstat    tag [2] fid [2]
Rstat    tag [2] fid [2] stat [116]
Twstat   tag [2] fid [2] stat [116]
Rwstat   tag [2] fid [2]

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.

Fids

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.

The first fid supplied (in an attach message) will be used by the server to refer to the root of the served file tree. The attach identifies the user to the server and may specify a particular file tree provided by the server (for those servers that supply more than one).

A 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. Usually, a client maintains a fid for the root, and navigates by walk's on a fid clone'd from the root fid.

Message Tags

A client can send multiple T-messages without waiting for the corresponding R-messages, as long as all outstanding T-messages have different tags. The server may delay the response to a request on one fid and respond to later requests on other fids. For example, this may be necessary when the client reads from a file that the server synthesizes from external events such as keyboard input.

Qids

The eight-byte qid fields represent two four-byte unsigned integers, first the qid path then the qid version.

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. Directories always have the CHDIR bit (16r80000000) set in their qid path.
version	The version is a version number of the file. Typically, it is incremented every time the file is modified.

File Operations

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

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.

Access Permissions

Every file request has an implicit user id (copied from the original attach) and an implicit set of groups (every group of which the user is a member).

Each file has an associated owner and 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, only the 'other' permissions are used. ---Plan9'ism.

Each set of permissions says whether reading is allowed, whether writing is allowed, and whether executing is allowed. A walk in a directory is regarded as executing the directory, not reading it.

Permissions, and type are stored in the file mode. A set bit indicates that the corresponding permission is granted.

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

See Also