10564b1175
groff 1.23.0 added .MR to its -man macro package. The NEWS file states
that the inclusion of the macro "was prompted by its introduction to
Plan 9 from User Space's troff in August 2020." From d32deab it seems
that the name for Plan 9 from User Space's implementation was suggested
by groff maintainer G. Brandon Robinson.
Not sure if the intention was to make these definitions compatible, but
it would be nice if they were.
Currently, Plan 9 from User Space's .MR expects its second argument to
be parenthesized. groff's .MR does not. This results in extra
parentheses appearing in manual references when viewing Plan 9 from User
Space's manual pages on a system using groff.
358 lines
6.9 KiB
Groff
358 lines
6.9 KiB
Groff
.TH FCALL 3
|
|
.SH NAME
|
|
Fcall, convS2M, convD2M, convM2S, convM2D, fcallfmt, dirfmt, dirmodefmt, read9pmsg, statcheck, sizeS2M, sizeD2M \- interface to Plan 9 File protocol
|
|
.SH SYNOPSIS
|
|
.B #include <u.h>
|
|
.br
|
|
.B #include <libc.h>
|
|
.br
|
|
.br
|
|
.B #include <fcall.h>
|
|
.PP
|
|
.B
|
|
uint convS2M(Fcall *f, uchar *ap, uint nap)
|
|
.PP
|
|
.B
|
|
uint convD2M(Dir *d, uchar *ap, uint nap)
|
|
.PP
|
|
.B
|
|
uint convM2S(uchar *ap, uint nap, Fcall *f)
|
|
.PP
|
|
.B
|
|
uint convM2D(uchar *ap, uint nap, Dir *d, char *strs)
|
|
.PP
|
|
.B
|
|
int dirfmt(Fmt*)
|
|
.PP
|
|
.B
|
|
int fcallfmt(Fmt*)
|
|
.PP
|
|
.B
|
|
int dirmodefmt(Fmt*)
|
|
.PP
|
|
.B
|
|
int read9pmsg(int fd, uchar *buf, uint nbuf)
|
|
.PP
|
|
.B
|
|
int statcheck(uchar *buf, uint nbuf)
|
|
.PP
|
|
.B
|
|
uint sizeS2M(Fcall *f)
|
|
.PP
|
|
.B
|
|
uint sizeD2M(Dir *d)
|
|
.SH DESCRIPTION
|
|
These
|
|
routines convert messages in the machine-independent format of
|
|
the Plan 9 file protocol,
|
|
9P, to and from a more convenient form,
|
|
an
|
|
.B Fcall
|
|
structure:
|
|
.PP
|
|
.EX
|
|
.if n .ta 4n +6n +5n +6n +18n +4n
|
|
.if t .ta \w'xxxx'u +\w'short 'u +\w'xxxx'u +\w'ushort 'u +\w'ticket[TICKETLEN]; 'u +\w'/* 'u
|
|
#define MAXWELEM 16
|
|
|
|
typedef
|
|
struct Fcall
|
|
{
|
|
uchar type;
|
|
u32int fid;
|
|
ushort tag;
|
|
union {
|
|
struct {
|
|
u32int msize; /* Tversion, Rversion */
|
|
char *version; /* Tversion, Rversion */
|
|
};
|
|
struct {
|
|
ushort oldtag; /* Tflush */
|
|
};
|
|
struct {
|
|
char *ename; /* Rerror */
|
|
};
|
|
struct {
|
|
Qid qid; /* Rattach, Ropen, Rcreate */
|
|
u32int iounit; /* Ropen, Rcreate */
|
|
};
|
|
struct {
|
|
Qid aqid; /* Rauth */
|
|
};
|
|
struct {
|
|
u32int afid; /* Tauth, Tattach */
|
|
char *uname; /* Tauth, Tattach */
|
|
char *aname; /* Tauth, Tattach */
|
|
};
|
|
struct {
|
|
u32int perm; /* Tcreate */
|
|
char *name; /* Tcreate */
|
|
uchar mode; /* Tcreate, Topen */
|
|
};
|
|
struct {
|
|
u32int newfid; /* Twalk */
|
|
ushort nwname; /* Twalk */
|
|
char *wname[MAXWELEM]; /* Twalk */
|
|
};
|
|
struct {
|
|
ushort nwqid; /* Rwalk */
|
|
Qid wqid[MAXWELEM]; /* Rwalk */
|
|
};
|
|
struct {
|
|
vlong offset; /* Tread, Twrite */
|
|
u32int count; /* Tread, Twrite, Rread */
|
|
char *data; /* Twrite, Rread */
|
|
};
|
|
struct {
|
|
ushort nstat; /* Twstat, Rstat */
|
|
uchar *stat; /* Twstat, Rstat */
|
|
};
|
|
};
|
|
} Fcall;
|
|
.EE
|
|
.EX
|
|
|
|
/* these are implemented as macros */
|
|
|
|
uchar GBIT8(uchar*)
|
|
ushort GBIT16(uchar*)
|
|
ulong GBIT32(uchar*)
|
|
vlong GBIT64(uchar*)
|
|
|
|
void PBIT8(uchar*, uchar)
|
|
void PBIT16(uchar*, ushort)
|
|
void PBIT32(uchar*, ulong)
|
|
void PBIT64(uchar*, vlong)
|
|
|
|
#define BIT8SZ 1
|
|
#define BIT16SZ 2
|
|
#define BIT32SZ 4
|
|
#define BIT64SZ 8
|
|
.EE
|
|
.PP
|
|
This structure is defined in
|
|
.BR <fcall.h> .
|
|
See section 5
|
|
for a full description of 9P messages and their encoding.
|
|
For all message types, the
|
|
.B type
|
|
field of an
|
|
.B Fcall
|
|
holds one of
|
|
.BR Tversion ,
|
|
.BR Rversion ,
|
|
.BR Tattach ,
|
|
.BR Rattach ,
|
|
etc. (defined in an enumerated type in
|
|
.BR <fcall.h> ).
|
|
.B Fid
|
|
is used by most messages, and
|
|
.B tag
|
|
is used by all messages.
|
|
The other fields are used selectively by the message types
|
|
given in comments.
|
|
.PP
|
|
.I ConvM2S
|
|
takes a 9P message at
|
|
.I ap
|
|
of length
|
|
.IR nap ,
|
|
and uses it to fill in
|
|
.B Fcall
|
|
structure
|
|
.IR f .
|
|
If the passed message
|
|
including any data for
|
|
.B Twrite
|
|
and
|
|
.B Rread
|
|
messages
|
|
is formatted properly,
|
|
the return value is the number of bytes the message occupied in the buffer
|
|
.IR ap ,
|
|
which will always be less than or equal to
|
|
.IR nap ;
|
|
otherwise it is 0.
|
|
For
|
|
.B Twrite
|
|
and
|
|
.B Tread
|
|
messages,
|
|
.B data
|
|
is set to a pointer into the argument message,
|
|
not a copy.
|
|
.PP
|
|
.I ConvS2M
|
|
does the reverse conversion, turning
|
|
.I f
|
|
into a message starting at
|
|
.IR ap .
|
|
The length of the resulting message is returned.
|
|
For
|
|
.B Twrite
|
|
and
|
|
.B Rread
|
|
messages,
|
|
.B count
|
|
bytes starting at
|
|
.B data
|
|
are copied into the message.
|
|
.PP
|
|
The constant
|
|
.B IOHDRSZ
|
|
is a suitable amount of buffer to reserve for storing
|
|
the 9P header;
|
|
the data portion of a
|
|
.B Twrite
|
|
or
|
|
.B Rread
|
|
will be no more than the buffer size negotiated in the
|
|
.BR Tversion/Rversion
|
|
exchange, minus
|
|
.BR IOHDRSZ .
|
|
.PP
|
|
The routine
|
|
.I sizeS2M
|
|
returns the number of bytes required to store the machine-independent representation of the
|
|
.B Fcall
|
|
structure
|
|
.IR f ,
|
|
including its initial 32-bit size field.
|
|
In other words, it reports the number of bytes produced
|
|
by a successful call to
|
|
.IR convS2M .
|
|
.PP
|
|
Another structure is
|
|
.BR Dir ,
|
|
used by the routines described in
|
|
.MR stat 3 .
|
|
.I ConvM2D
|
|
converts the machine-independent form starting at
|
|
.I ap
|
|
into
|
|
.IR d
|
|
and returns the length of the machine-independent encoding.
|
|
The strings in the returned
|
|
.B Dir
|
|
structure are stored at successive locations starting at
|
|
.BR strs .
|
|
Usually
|
|
.B strs
|
|
will point to storage immediately after the
|
|
.B Dir
|
|
itself.
|
|
It can also be a
|
|
.B nil
|
|
pointer, in which case the string pointers in the returned
|
|
.B Dir
|
|
are all
|
|
.BR nil ;
|
|
however, the return value still includes their length.
|
|
.PP
|
|
.I ConvD2M
|
|
does the reverse translation,
|
|
also returning the length of the encoding.
|
|
If the buffer is too short, the return value will be
|
|
.B BIT16SZ
|
|
and the correct size will be returned in the first
|
|
.B BIT16SZ
|
|
bytes.
|
|
(If the buffer is less that
|
|
.BR BIT16SZ ,
|
|
the return value is zero; therefore a correct test for
|
|
complete packing of the message is that the return value is
|
|
greater than
|
|
.BR BIT16SZ ).
|
|
The macro
|
|
.B GBIT16
|
|
can be used to extract the correct value.
|
|
The related macros with different sizes retrieve the corresponding-sized quantities.
|
|
.B PBIT16
|
|
and its brethren place values in messages.
|
|
With the exception of handling short buffers in
|
|
.IR convD2M ,
|
|
these macros are not usually needed except by internal routines.
|
|
.PP
|
|
Analogous to
|
|
.IR sizeS2M ,
|
|
.I sizeD2M
|
|
returns the number of bytes required to store the machine-independent representation of the
|
|
.B Dir
|
|
structure
|
|
.IR d ,
|
|
including its initial 16-bit size field.
|
|
.PP
|
|
The routine
|
|
.B statcheck
|
|
checks whether the
|
|
.I nbuf
|
|
bytes of
|
|
.I buf
|
|
contain a validly formatted machine-independent
|
|
.B Dir
|
|
entry suitable as an argument, for example, for the
|
|
.B wstat
|
|
(see
|
|
.MR stat 3 )
|
|
system call.
|
|
It checks that the sizes of all the elements of the the entry sum to exactly
|
|
.IR nbuf ,
|
|
which is a simple but effective test of validity.
|
|
.I Nbuf
|
|
and
|
|
.I buf
|
|
should include the second two-byte (16-bit) length field that precedes the entry when
|
|
formatted in a 9P message (see
|
|
.IR stat (9p));
|
|
in other words,
|
|
.I nbuf
|
|
is 2 plus the sum of the sizes of the entry itself.
|
|
.I Statcheck
|
|
also verifies that the length field has the correct value (that is,
|
|
.IB nbuf -2\f1).
|
|
It returns
|
|
.B 0
|
|
for a valid entry and
|
|
.B -1
|
|
for an incorrectly formatted entry.
|
|
.PP
|
|
.IR Dirfmt ,
|
|
.IR fcallfmt ,
|
|
and
|
|
.I dirmodefmt
|
|
are formatting routines, suitable for
|
|
.MR fmtinstall 3 .
|
|
They convert
|
|
.BR Dir* ,
|
|
.BR Fcall* ,
|
|
and
|
|
.BR long
|
|
values into string representations of the directory buffer,
|
|
.B Fcall
|
|
buffer,
|
|
or file mode value.
|
|
.I Fcallfmt
|
|
assumes that
|
|
.I dirfmt
|
|
has been installed with format letter
|
|
.L D
|
|
and
|
|
.I dirmodefmt
|
|
with format letter
|
|
.LR M .
|
|
.PP
|
|
.I Read9pmsg
|
|
calls
|
|
.MR read 3
|
|
multiple times, if necessary, to read an entire 9P message into
|
|
.BR buf .
|
|
The return value is 0 for end of file, or -1 for error; it does not return
|
|
partial messages.
|
|
.SH SOURCE
|
|
.B \*9/src/lib9
|
|
.SH SEE ALSO
|
|
.MR intro 3 ,
|
|
.MR 9p 3 ,
|
|
.MR stat 3 ,
|
|
.IR intro (9p)
|