The following Styx messages are described in this chapter:
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.
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 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). 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. 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.
Two files on the same server hierarchy are the same if and only if
their qids are the same.
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:
The client may have multiple fids pointing to a single file on a server and hence having a single qid.
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.
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.
Access Permissions
Each file server maintains a set of user and group names. Each user can be a member of any number of groups.
NOTE:
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.
Header Files
Header files are located as follows:
<lib9.h>
|
<inferno_root>/<systarg> / <objtype> /include/lib9.h
|
<styx.h>
|
/include/styx.h
|