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; } 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; 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;
A Styx 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 message 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 appropriate care when manipulating them.
The following functions are provided by Tmsg:
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 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 function 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 represent `no tag value'. The constant VERSION names the current 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 subsequently 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)).
The constant MAXWELEM gives the protocol-defined limit on the length of the arrays Tmsg.names and Rmsg.qids. For specialised applications, the module defines constants Tversion, Rversion, etc. for the message types of the protocol, and the other constants mentioned in Section 5.
STYX(2 ) | Rev: Thu Feb 15 14:43:26 GMT 2007 |