STYX(2)                                                   STYX(2)

     NAME
          Styx: Rmsg, Tmsg, dir2text, istmsg, packdir, packdirsize,
          readmsg, qid2text, unpackdir - interface to 9P (Styx) file
          protocol

     SYNOPSIS
          include "styx.m";
          styx := load Styx Styx->PATH;

          Tmsg: adt {
              tag: int;
              pick {
              Readerror =>
                  error: string;      # tag is unused in this case
              Version =>
                  msize: int;
                  version: string;
              Auth =>
                  afid: int;
                  uname, aname: string;
              Attach =>
                  fid, afid: int;
                  uname, aname: string;
              Flush =>
                  oldtag: int;
              Walk =>
                  fid, newfid: int;
                  names: array of string;
              Open =>
                  fid, mode: int;
              Create =>
                  fid: int;
                  name: string;
                  perm, mode: int;
              Read =>
                  fid: int;
                  offset: big;
                  count: int;
              Write =>
                  fid: int;
                  offset: big;
                  data: array of byte;
              Clunk or
              Stat or
              Remove =>
                  fid: int;
              Wstat =>
                  fid: int;
                  stat: Sys->Dir;
              }

     Page 1                       Plan 9             (printed 3/29/24)

     STYX(2)                                                   STYX(2)

              read:   fn(fd: ref Sys->FD, msize: int): ref Tmsg;
              unpack: fn(a: array of byte): (int, ref Tmsg);
              pack:   fn(nil: self ref Tmsg): array of byte;
              packedsize: fn(nil: self ref Tmsg): int;
              text:   fn(nil: self ref Tmsg): string;
              mtype:  fn(nil: self ref Tmsg): int;
          };

          Rmsg: adt {
              tag: int;
              pick {
              Readerror =>
                  error: string;      # tag is unused in this case
              Version =>
                  msize: int;
                  version: string;
              Auth =>
                  aqid: Sys->Qid;
              Attach =>
                  qid: Sys->Qid;
              Flush =>
              Error =>
                  ename: string;
              Clunk or
              Remove or
              Wstat =>
              Walk =>
                  qids: array of Sys->Qid;
              Create or
              Open =>
                  qid: Sys->Qid;
                  iounit: int;
              Read =>
                  data: array of byte;
              Write =>
                  count: int;
              Stat =>
                  stat: Sys->Dir;
              }

              read:   fn(fd: ref Sys->FD, msize: int): ref Rmsg;
              unpack: fn(a: array of byte): (int, ref Rmsg);
              pack:   fn(nil: self ref Rmsg): array of byte;
              packedsize: fn(nil: self ref Rmsg): int;
              text:   fn(nil: self ref Rmsg): string;
              mtype:  fn(nil: self ref Rmsg): int;
          };

          init:        fn();

          readmsg:     fn(fd: ref Sys->FD, msize: int): (array of byte, string);
          istmsg:      fn(f: array of byte): int;

     Page 2                       Plan 9             (printed 3/29/24)

     STYX(2)                                                   STYX(2)

          compatible:  fn(t: ref Tmsg.Version, msize: int, version: string): (int, string);

          packdirsize: fn(d: Sys->Dir): int;
          packdir:     fn(d: Sys->Dir): array of byte;
          unpackdir:   fn(f: array of byte): (int, Sys->Dir);
          dir2text:    fn(d: Sys->Dir): string;
          qid2text:    fn(q: Sys->Qid): string;

          VERSION:  con "9P2000";
          MAXWELEM: con 16;
          NOTAG:    con 16rFFFF;
          NOFID:    con ~0;
          IOHDRSZ:  con implementation-defined;
          MAXRPC:   con implementation-defined;

     DESCRIPTION
          Styx provides a Limbo interface to send and receive messages
          of the 9P file service protocol, described by Section 5 of
          this manual, a thorough reading of which is advised before
          using this module.  (The protocol was previously called
          `Styx' in Inferno, hence the module's name.)  Init must be
          called before using any other function in the module.

          A 9P client transmits requests to a server as `T-messages'
          and receives replies in matching `R-messages'.  A T-message
          is here represented by values of the type Tmsg, and an R-
          message by values of type Rmsg.  Every message has a tag
          value, and the alternatives of the pick adt represent the
          possible operation types of a T-message, generally with
          parameter names and types corresponding to those described
          in section 5.  The exceptions are: Tmsg.Write and Rmsg.Read
          contain an array of byte, data, to hold the data for the
          corresponding message, and the `count' parameter of the mes-
          sage is simply the length of that array; and there is an
          alternative labelled Readerror that does not appear in the
          protocol but is used to represent input errors as described
          below.  Also note that values that are `unsigned' integers
          in the protocol are typically given signed integer types in
          the Limbo representation (in particular, fids, qid paths,
          counts and offsets), and applications should take appropri-
          ate care when manipulating them.

          The following functions are provided by Tmsg:

          read(fd, msize)
               Read file descriptor fd to obtain exactly one T-message
               and return (a reference to) the corresponding Tmsg.  A
               nil value is returned on end of file.  Otherwise, if
               the read fails or the data read does not form a valid
               T-message, the value returned will be a Tmsg.Readerror
               value in which the error member describes the error.
               Msize gives the maximum number of bytes in any

     Page 3                       Plan 9             (printed 3/29/24)

     STYX(2)                                                   STYX(2)

               acceptable T-message, and should be the value negoti-
               ated in the exchange of version messages; any incoming
               message larger than that will result in a diagnostic as
               a Tmsg.Readerror value.  An msize of 0 means `no limit
               negotiated' and should (only) be used until a message
               size has been negotiated by exchange of version(5) mes-
               sages.

          t.pack()
               Return an array of bytes containing the value of t in
               the machine-independent format described in Section 5.
               It can return nil only if the message t is itself nil
               or has an invalid type.

          unpack(a)
               The array a is assumed to contain zero or more T-
               messages.  Unpack attempts to unpack the first message,
               and returns a tuple of the form (n,v).  If successful,
               n is the number of bytes at the start of a used by the
               message, and v is the corresponding Tmsg value.  If a
               contains the prefix of a valid message but more data is
               required to complete it, n is zero (and v is nil); the
               caller will typically read more data, append it to a,
               and try again.  If the message is invalid, n is -1 and
               v is nil.

          t.packedsize()
               Return the number of bytes required for the value of t
               when packed in its machine-independent format.  (Zero
               is returned if t is invalid.)

          t.text()
               Return a printable string showing the contents of t,
               for tracing or debugging.

          t.mtype()
               Return the 9P message type of the message.

          An R-message is represented by Rmsg.  Its member functions
          behave exactly as those for Tmsg, except that they operate
          on R-messages not T-messages.

          When a client reads a directory, the data returned in the
          reply must be formatted as described in read(5): an array of
          directory entries, one per file, with each entry formatted
          in a machine-independent format.  An appropriate array value
          can be produced by packdir from a Sys->Dir structure, as
          used by sys-stat(2). The space that packed representation
          will take can be calculated beforehand by packdirsize.  The
          server will usually fill the buffer for the reply to the
          read with as many entries as will fit, checking the space
          remaining against the result of packdirsize and if the value

     Page 4                       Plan 9             (printed 3/29/24)

     STYX(2)                                                   STYX(2)

          will fit, storing the result of packdir.  Given an array a
          containing at most one packed directory value (as produced
          by packdir), unpackdir returns a tuple (n, d) where n is -1
          if a is illegally formatted; n is zero if a does not contain
          a complete directory entry value; and otherwise n is the
          number of bytes of a used to produce the unpacked Dir value
          d .

          The functions dir2text and qid2text produce printable
          strings showing the contents of the corresponding data
          structures, for use when tracing or debugging.

          Applications that acts as file servers will read T-messages
          and reply with R-messages.  They can use Tmsg.read to read
          each T-message, build an Rmsg reply value r, and use r.pack
          to produce an array of bytes to be written in reply by
          Sys->write (see sys-read(2)).

          A few specialised programs might need the lower-level func-
          tion readmsg that underlies Tmsg.read and Rmsg.read.  It
          reads a single message, which can be either a T-message or
          R-message, and returns it as an array of bytes, which can
          then be unpacked using Tmsg.unpack or Rmsg.unpack.  Msize is
          the negotiated message size, or 0 meaning `no limit'.  The
          predicate istmsg returns true if the contents of array f
          looks like a packed representation of a T-message, judging
          only by its type byte.

          When generating the version message (see version(5)), the
          constant NOTAG can be used in Tmsg.tag and Rmsg.tag to rep-
          resent `no tag value'.  The constant VERSION names the cur-
          rent version of the protocol, and can be used as the value
          of Tmsg.version.

          Compatible can be used by a server to compare its msize and
          version (which is typically VERSION) to those in the
          Tmsg.Version message received from a client, to decide its
          reply, following the rules in version(5). It returns a tuple
          (m, v) with values for use in the Rmsg.Version reply.  M is
          the lesser of msize and t.msize, and v is the negotiated
          protocol version, or the value "unknown" if no version could
          be agreed.  The constant MAXRPC is a reasonable value for
          msize on current systems.  The resulting value m can subse-
          quently be given to the various read functions as the limit
          msize. The constant IOHDRSZ gives the amount to allow for
          protocol overhead, when limiting data size for Tmsg.Write
          and Rmsg.Read.

          The constant NOFID can be used as the value of afid of the
          attach message when authentication is not required (see
          attach(5)).

     Page 5                       Plan 9             (printed 3/29/24)

     STYX(2)                                                   STYX(2)

          The constant MAXWELEM gives the protocol-defined limit on
          the length of the arrays Tmsg.names and Rmsg.qids.  For spe-
          cialised applications, the module defines constants
          Tversion, Rversion, etc. for the message types of the proto-
          col, and the other constants mentioned in Section 5.

     SOURCE
          /appl/lib/styx.b

     SEE ALSO
          styxservers(2), intro(5)

     Page 6                       Plan 9             (printed 3/29/24)