STYX(2) STYX(2)
NAME
Styx: Rmsg, Tmsg, dir2text, istmesg, packdir, packdirsize,
readmesg, qid2text, unpackdir - interface to 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
Nop =>
Flush =>
oldtag: int;
Clone =>
fid, newfid: int;
Walk =>
fid: int;
name: string;
Open =>
fid, mode: int;
Create =>
fid, perm, mode: int;
name: string;
Read =>
fid, count: int;
offset: big;
Write =>
fid: int;
offset: big;
data: array of byte;
Clunk or
Stat or
Remove =>
fid: int;
Wstat =>
fid: int;
stat: Sys->Dir;
Attach =>
fid: int;
uname, aname: string;
}
read: fn(fd: ref Sys->FD, msglim: int): ref Tmsg;
unpack: fn(a: array of byte): (int, ref Tmsg);
pack: fn(t: self ref Tmsg): array of byte;
packedsize: fn(t: self ref Tmsg): int;
Page 1 Plan 9 (printed 12/30/24)
STYX(2) STYX(2)
text: fn(t: self ref Tmsg): string;
};
Rmsg: adt {
tag: int;
pick {
Nop or
Flush =>
Error =>
ename: string;
Clunk or
Remove or
Clone or
Wstat =>
fid: int;
Walk or
Create or
Open or
Attach =>
fid: int;
qid: Sys->Qid;
Read =>
fid: int;
data: array of byte;
Write =>
fid, count: int;
Stat =>
fid: int;
stat: Sys->Dir;
}
read: fn(fd: ref Sys->FD, msglim: int): ref Rmsg;
unpack: fn(a: array of byte): (int, ref Rmsg);
pack: fn(r: self ref Rmsg): array of byte;
packedsize: fn(r: self ref Rmsg): int;
text: fn(r: self ref Rmsg): string;
};
init: fn();
readmesg: fn(fd: ref Sys->FD, msglim: int): (array of byte, string);
istmesg: fn(a: array of byte): int;
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;
NOTAG: con 16rFFFF;
MAXRPC: con 128 + Sys->ATOMICIO;
DESCRIPTION
Styx provides a Limbo interface to send and receive messages
Page 2 Plan 9 (printed 12/30/24)
STYX(2) STYX(2)
of the Styx file service protocol, described by Section 5
this manual (a thorough reading of which is advised before
using this module). Init must be called before using any
other functions in the module.
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 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.
The following functions are provided by Tmsg:
read(fd, msglim)
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.
Msglim gives the maximum number of bytes in any accept-
able T-message; any incoming message larger than that
will result in a diagnostic as a Tmsg.Readerror value.
A msglim of 0 means `no limit'. The constant MAXRPC is
a reasonable value on current systems.
t.pack()
Return an array of bytes containing the value of t in
the machine-independent format described in Section 5.
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 again nil.
t.packedsize()
Page 3 Plan 9 (printed 12/30/24)
STYX(2) STYX(2)
Return the number of bytes required for the value of t
when packed in its machine-independent format.
t.text()
Return a printable string showing the contents of t,
for tracing or debugging.
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.
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 readmesg 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. The
predicate istmesg 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 nop message (see attach (5)), the con-
stant NOTAG can be used in Tmsg.tag and Rmsg.tag to repre-
sent `no tag value'.
SOURCE
/appl/lib/styx.b
SEE ALSO
styxlib(2), intro(5)
Page 4 Plan 9 (printed 12/30/24)