[Top] [Prev] [Next]

Inferno Communications Protocol, Styx


The following Styx messages are described in this chapter:
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 a file

read, write - transfer data from and to a file

remove - remove a file from a server

stat, wstat - inquire or change file attributes

walk - descend a directory hierarchy

Inferno uses a single protocol called Styx, to exchange information between computers. It is a lightweight protocol encapsulated by IP. It is connection based and provides a reliable transmission of sequenced messages. Styx has the following attributes:

Styx Communications Protocol

The Styx communications protocol is used for messages between clients and servers across the network.

An Inferno server is a machine that provides access to one or more hierarchical file systems on request from an Inferno process, usually through a network connection. The prototypical server is a separate machine that stores large numbers of user files on permanent media.

A connection to a server is a bidirectional communications link between a server and a client. There may be a single client or multiple clients sharing the same connection. A connection remains established while any of the files in the connection directory are referenced or until a close system call is received from the network.

The primary function of the server is to process file system navigation and file manipulation requests from its clients. A server's file tree is attached to a process group's name space by bind and mount and calls. See bind, mount, unmount - change file name space in Chapter 8 and Limbo System Module in Chapter 8. Processes in the group are then clients of the server. 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.

Most programs do not see the Styx protocol directly, rather they 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 the Styx protocol as described in this section.

Styx protocol

File operations between any two machines are accomplished by sending requests and receiving replies via the Styx protocol in a manner similar to Unix remote procedure calls. The protocol supports remote access to files and allows a remote machine to use these interfaces as gateways.

Styx messages are not manipulated directly by an application designer. Any file operation that invokes Styx results in messages that perform the necessary operations on the remote name space. The exact set of messages differs depending on the call, but in all cases the complexity is concealed from the developer, who simply invokes mount, open, read and similar system commands as necessary.

The protocol contains messages that perform:

Operation

A kernel-resident file server, devmnt, functions as a mount driver that is used by the mount system call to connect the name space of a process to the service provided by a server over a communications channel. After the mount has executed successfully, system calls involving files in that portion of the name space are converted by devmnt into the appropriate Styx messages to the server.

The mount system call issues attach messages to the server to identify and validate the user of the connection. Each distinct use of a connection must mount it separately; devmnt multiplexes the access of the various users and their processes to the service.

File oriented system calls are converted by the kernel into Styx procedure calls. The server devmnt translates these procedure calls into remote procedure calls, which are then transmitted to the server as Styx messages over the communications channel. Each message is implemented by writing the protocol message to the server followed by reading the server channel to get the reply. Errors in the reply message are turned into system call error returns.

A read or write system call on a file served by devmnt may be translated into more than one message since there is a maximum data size for a Styx message. The system call will return when the specified number of bytes have been transferred or a short reply is returned.

Styx messages

A descriptive listing of Styx message pairs by general category is presented in Table 3-1.

Styx message pairs

Tattach

Rattach

Authenticate the caller, establish fid that points to the root directory of the name space of the machine that was called
Tclone

Rclone

Create a copy of an existing fid; when done, two fids are now pointing to the same file in the hierarchy
Twalk

Rwalk

Move fid one step in the file hierarchy
Tclunk

Rclunk

Close a fid (throw it away). The actual file is unaffected.
Tstat

Rstat

Return file attributes
Twstat

Rwstat

Set attributes; usually, an Tstat is first done to get the attributes and then a Twstat is executed with a status buffer altered as needed
Topen

Ropen

Check file permissions and, if allowable, prepare an existing file for reading or writing
Tcreate

Rcreate

Create and open a new file
Tread

Rread

Access contents of file
Twrite

Rwrite

Write to file
Tremove

Rremove

Remove the file that the fid is pointing to and clunk the fid
Tnop Rnop No operation; can be used to synchronize the channel between two services
Tflush Rflush Interrupt a pending operation
Rerror Indicates that an error has occurred; the Contents segment contains the text of the error generated by the server

Styx message structure

The general structure of Styx messages is given in Figure 3-1. Each message consists of a sequence of bytes in defined byte order for machine independence. The first byte, Type, is the message type that is one of the enumerated constants defined in styx.h. Message types are typically arranged in pairs, called transactions. T-messages are requests from client to server (Topen, for example) that are matched by corresponding R-messages that are replies from server to client (Ropen, for example).

General structure of a Styx message

The second field, Tag, is a chosen by the client to identify the message. The client must ensure that no two outstanding messages on the same connection have the same tag. The reply tag will have a value one greater than the request that generated it except in the event of an error reply (Rerror).

The fid field is a file identifier that is part of Styx messages that operate on files. Every file that is manipulated by the operating system is identified by a fid. The Contents field contains one or more 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.

Message Tag

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.

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.

Message Fid

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 (See stat, fstat, fwstat, wstat - get and put file status in Chapter 8), 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.

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 Qid

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:


NOTE:

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

An existing file can be open'd or a new file may be create'd in the current directory. (See open, create - prepare a fid for I/O on a file.)

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, write - transfer data from and to a file.)

A client should clunk any fid that is no longer needed. (See clunk - forget about a fid.)

The remove transaction deletes files. (See remove - remove a file from a server.)

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, fstat, fwstat, wstat - get and put file status in Chapter 8 and stat, wstat - inquire or change file attributes.)

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 - abort a message.)

Directories

Directories are created by create with CHDIR set in the permissions argument (see stat, wstat - inquire or change file attributes). 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.

Access Permissions

Each file server maintains a set of user and group names. Each user can be a member of any number of groups.

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.


NOTE:

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.


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

Header files are located as follows:
<lib9.h>

<inferno_root>/<systarg> / <objtype> /include/lib9.h

<styx.h>

/include/styx.h

See Also
Introduction to Limbo Modules in Chapter 7

bind, mount, unmount - change file name space in Chapter 8

stat, fstat, fwstat, wstat - get and put file status in Chapter 8

read, write - transfer data from and to a file

stat, wstat - inquire or change file attributes



[Top] [Prev] [Next]

infernosupport@lucent.com
Copyright © 1996,Lucent Technologies, Inc. All rights reserved.