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 11/17/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 11/17/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 11/17/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 11/17/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 11/17/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 11/17/24)