INTRO(5)                                                 INTRO(5)

     NAME
          intro - introduction to the Inferno File Protocol, Styx

     SYNOPSIS
          #include <lib9.h>
          #include <styx.h>

     DESCRIPTION
          An Inferno server is an agent that provides one or more
          hierarchical file systems - file trees - that may be
          accessed by Inferno processes.  A server responds to
          requests by clients to navigate the hierarchy, and to cre-
          ate, 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 informa-
          tion on data structures inside the kernel; the device
          prog(3) 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 sys-file2chan(2) interface.
          More complex Limbo file service applications can use
          styxlib(2) to handle the protocol messages directly.

          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 bind or mount calls; see sys-bind(2) and intro(2).
          Processes in the group are then clients of the server: sys-
          tem calls operating on files are translated into requests
          and responses transmitted on the connection to the appropri-
          ate service.

          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 transmit-
          ting (receiving) a request of a particular type, and receiv-
          ing (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 enu-
          meration in the C include file <styx.h> (see styx(10.2)).
          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-

     Page 1                       Plan 9            (printed 10/20/21)

     INTRO(5)                                                 INTRO(5)

          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 pro-
          tocol has no such restriction.  Inferno names may contain
          any printable character (that is, any character outside hex-
          adecimal 00-1F and 80-9F) except slash and blank.  Messages
          are transported in byte form to allow for machine indepen-
          dence; styx(10.2) describes C routines that convert to and
          from this form into a machine-dependent C structure.

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

          Each T-message has a 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 NOTAG, value 16rFFFF, meaning
          `no tag': the client can use it, when establishing a connec-
          tion, to override tag matching in messages.

          The type of an R-message will either be one greater than the
          type of the corresponding T-message or Rerror indicating

     Page 2                       Plan 9            (printed 10/20/21)

     INTRO(5)                                                 INTRO(5)

          that the request failed.  In the latter case, the ename
          field 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 necessary.

          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 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 sys-
          stat(2) 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.

          The first fid supplied (in an attach message) will be taken
          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 served by the server (for those that
          supply more than one).  A walk message causes the server to
          change the current file associated with a fid, which must be
          a directory, to be a named file in that directory.  Usually,
          a client maintains a fid for the root, and navigates by
          walks on a fid cloned from the root fid.

          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 on one fid and respond to later
          requests on other fids; this is sometimes necessary, for
          example when the client reads from a file that the server
          synthesizes from external events such as keyboard charac-
          ters.

          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: 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. 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 direc-
          tory, the old and new path components of the qids should be
          different.  Directories always have the CHDIR bit
          (0x80000000) set in their qid path.  The version is a

     Page 3                       Plan 9            (printed 10/20/21)

     INTRO(5)                                                 INTRO(5)

          version number for a file; typically, it is incremented
          every time the file is modified.

          An existing file can be opened, or a new file may be created
          in the current (directory) file.  I/O of a given number of
          bytes (limited to 8192) at a given offset on an open file is
          done by read and write.

          A client should clunk any fid that is no longer needed.  The
          remove transaction deletes files.

          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
          public), access and modification times, and owner and group
          identifications (see sys-stat(2)). The owner and group iden-
          tifications are 28-byte names.  The wstat transaction allows
          some of a file's properties to be changed.

          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.

          Most programs do not see the Styx protocol directly; instead
          calls to library routines that access files are translated
          by the mount driver, mnt(3), into Styx messages.

     DIRECTORIES
          Directories are created by create with CHDIR set in the per-
          missions argument (see stat(5)). The members of a directory
          can be found with read(5). All directories must support
          walks to the directory .. (dot-dot) meaning parent direc-
          tory, although by convention directories contain no explicit
          entry for .. or . (dot).  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.  Each
          group has a group leader who has special privileges (see
          stat(5)). 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

     Page 4                       Plan 9            (printed 10/20/21)

     INTRO(5)                                                 INTRO(5)

          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, the other permissions are used.  Each set of permis-
          sions 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 read-
          ing it.  Permissions are kept in the low-order bits of the
          file mode: owner read/write/execute permission represented
          as 1 in bits 8, 7, and 6 respectively (using 0 to number the
          low order).  The group permissions are in bits 5, 4, and 3,
          and the other permissions are in bits 2, 1, and 0.

          The file mode contains an additional attribute besides the
          permissions: if bit 31 is set, the file is a directory.

     SEE ALSO
          intro(2), styxlib(2), sys-bind(2), sys-stat(2), mnt(3),
          prog(3), read(5), stat(5), styx(10.2)

     Page 5                       Plan 9            (printed 10/20/21)