aboutsummaryrefslogtreecommitdiff
path: root/man/man3/fcall.3
diff options
context:
space:
mode:
Diffstat (limited to 'man/man3/fcall.3')
-rw-r--r--man/man3/fcall.3357
1 files changed, 357 insertions, 0 deletions
diff --git a/man/man3/fcall.3 b/man/man3/fcall.3
new file mode 100644
index 00000000..1219cf20
--- /dev/null
+++ b/man/man3/fcall.3
@@ -0,0 +1,357 @@
+.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
+.IR stat (2).
+.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
+.IR stat (2))
+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 (5));
+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
+.IR fmtinstall (2).
+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
+.IR read (2)
+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 /sys/src/libc/9sys
+.SH SEE ALSO
+.IR intro (2),
+.IR 9p (2),
+.IR stat (2),
+.IR intro (5)