.TH STYX 2.SH NAMEStyx: Rmsg, Tmsg, dir2text, istmsg, packdir, packdirsize, readmsg, qid2text, unpackdir \- interface to 9P (Styx) file protocol.SH SYNOPSIS.EXinclude "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 \fIimplementation-defined\f5;MAXRPC:   con \fIimplementation-defined\f5;.EE.SH DESCRIPTION.B Styxprovides 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 whichis advised before using this module.(The protocol was previously called `Styx' in Inferno, hence the module's name.).B Initmust be called before using any other function in the module..PPA 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.BR Tmsg ,and an R-message by values of type.BR Rmsg .Every message has a.B tagvalue, 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:.B Tmsg.Writeand.B Rmsg.Readcontain an array of byte,.BR 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.B Readerrorthat 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 integertypes in the Limbo representation (in particular, fids, qid paths, counts and offsets), and applicationsshould take appropriate care when manipulating them..PPThe following functions are provided by.BR Tmsg:.TP.BI read( fd\fP,\fP\ msize )Read file descriptor.I fdto obtain exactly one T-message and return (a reference to) the corresponding.BR 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.B Tmsg.Readerrorvalue in which the.B errormember describes the error..I Msizegives the maximum number of bytes in any acceptable T-message,and should be the value negotiated in the exchange of.B versionmessages;any incoming message larger than that will result in a diagnostic as a.B Tmsg.Readerrorvalue.An.I msizeof 0 means `no limit negotiated' and should (only) be used until a message sizehas been negotiated by exchange of.IR version (5)messages..TP.IB t .pack()Return an array of bytes containing the value of.I tin the machine-independent format described in Section 5.It can return nil only if the message.I tis itself nil or has an invalid type..TP.BI unpack( a )The array.I ais assumed to contain zero or more T-messages..B Unpackattempts to unpack the first message, and returns a tuple of the form.RI ( n , v ).If successful,.I nis the number of bytes at the start of.I aused by the message, and.I vis the corresponding.B Tmsgvalue.If.I acontains the prefix of a valid message but more data is required to complete it,.I nis zero (and.I vis nil); the caller will typically read more data, append it to.IR a ,and try again.If the message is invalid,.I nis -1and.I vis nil..TP.IB t .packedsize()Return the number of bytes required for the value of.I twhen packed in its machine-independent format.(Zero is returned if.I tis invalid.).TP.IB t .text()Return a printable string showing the contents of.IR t ,for tracing or debugging..TP.IB t .mtype()Return the 9P message type of the message..PPAn R-message is represented by.BR Rmsg .Its member functions behave exactly as those for.BR Tmsg ,except that they operate on R-messages not T-messages..PPWhen a client reads a directory, the data returned in the reply must be formattedas described in.IR read (5):an array of directory entries, one per file, with each entry formatted ina machine-independent format.An appropriate array value can be produced by.B packdirfrom a.B Sys->Dirstructure, as used by.IR sys-stat (2).The space that packed representation will take can be calculated beforehand by.BR packdirsize .The server will usually fill the buffer for the reply to the readwith as many entries as will fit,checking the space remaining against the result of.B packdirsizeand if the value will fit, storing the result of.BR packdir .Given an array.I acontaining at most one packed directory value (as produced by.BR packdir ),.B unpackdirreturns a tuple.RI ( n,\ d )where.I nis \-1 if.I ais illegally formatted;.I nis zero if.I adoes not contain a complete directory entry value;and otherwise.I nis the number of bytes of.I aused to produce the unpacked.B Dirvalue.I d ..PPThe functions.B dir2textand.B qid2textproduce printable strings showing the contents of the corresponding data structures,for use when tracing or debugging..PPApplications that acts as file servers will read T-messages andreply with R-messages.They can use.B Tmsg.readto read each T-message, build an.B Rmsgreply value.IR r ,and use.IB r .packto produce an array of bytes to be written in reply by.B Sys->write(see.IR sys-read (2))..PPA few specialised programs might need the lower-level function.B readmsgthat underlies.B Tmsg.readand.BR 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.B Tmsg.unpackor.BR Rmsg.unpack ..I Msizeis the negotiated message size, or 0 meaning `no limit'.The predicate.B istmsgreturns true if the contents of array.I flooks like a packed representation of a T-message,judging only by its.I typebyte..PPWhen generating the.B versionmessage (see.IR version (5)),the constant.B NOTAGcan be used in.B Tmsg.tagand.B Rmsg.tagto represent `no tag value'.The constant.B VERSIONnames the current version of the protocol, and can beused as the value of.BR Tmsg.version ..PP.B Compatiblecan be used by a server tocompare its.I msizeand.I version(which is typically.BR VERSION )to those in the.B Tmsg.Versionmessage received from a client, to decide its reply,following the rules in.IR version (5).It returns a tuple.RI ( m ", " v )with values for use in the.B Rmsg.Versionreply..I Mis the lesser of.I msizeand.IB t .msize ,and.I vis the negotiated protocol version, or the value \f5"unknown"\f1if no version could be agreed.The constant.B MAXRPCis a reasonable value for.I msizeon current systems.The resulting value.I mcan subsequently be given to the various read functions as the limit.IR msize .The constant.B IOHDRSZgives the amount to allow for protocol overhead, when limiting data size for.B Tmsg.Writeand.BR Rmsg.Read ..PPThe constant.B NOFIDcan be used as the value of.B afidof the.B attachmessage when authentication is not required (see.IR attach (5))..PPThe constant.B MAXWELEMgives the protocol-defined limit on the length of the arrays.B Tmsg.namesand.BR Rmsg.qids .For specialised applications, the module defines constants.BR Tversion ,.BR Rversion ,etc. for the message types of the protocol, and theother constants mentioned in Section 5..SH SOURCE.B /appl/lib/styx.b.SH SEE ALSO.IR styxservers (2),.IR intro (5)