From 78e51a8c6678b6e3dff3d619aa786669f531f4bc Mon Sep 17 00:00:00 2001 From: rsc Date: Fri, 14 Jan 2005 03:45:44 +0000 Subject: checkpoint --- man/man3/fcall.html | 274 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 274 insertions(+) create mode 100644 man/man3/fcall.html (limited to 'man/man3/fcall.html') diff --git a/man/man3/fcall.html b/man/man3/fcall.html new file mode 100644 index 00000000..926b47dc --- /dev/null +++ b/man/man3/fcall.html @@ -0,0 +1,274 @@ + +fcall(3) - Plan 9 from User Space + + + + +
+
+
FCALL(3)FCALL(3) +
+
+

NAME
+ +
+ + Fcall, convS2M, convD2M, convM2S, convM2D, fcallfmt, dirfmt, dirmodefmt, + read9pmsg, statcheck, sizeS2M, sizeD2M – interface to Plan 9 File + protocol
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <fcall.h> +
+ + uint convS2M(Fcall *f, uchar *ap, uint nap) +
+ + uint convD2M(Dir *d, uchar *ap, uint nap) +
+ + uint convM2S(uchar *ap, uint nap, Fcall *f) +
+ + uint convM2D(uchar *ap, uint nap, Dir *d, char *strs) +
+ + int dirfmt(Fmt*) +
+ + int fcallfmt(Fmt*) +
+ + int dirmodefmt(Fmt*) +
+ + int read9pmsg(int fd, uchar *buf, uint nbuf) +
+ + int statcheck(uchar *buf, uint nbuf) +
+ + uint sizeS2M(Fcall *f) +
+ + uint sizeD2M(Dir *d)
+ +
+

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 Fcall structure: +
+ + #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;
+ /* 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
+ +
+ + This structure is defined in <fcall.h>. See section 5 for a full + description of 9P messages and their encoding. For all message + types, the type field of an Fcall holds one of Tversion, Rversion, + Tattach, Rattach, etc. (defined in an enumerated type in <fcall.h>). + Fid is used by most messages, and + tag is used by all messages. The other fields are used selectively + by the message types given in comments. +
+ + ConvM2S takes a 9P message at ap of length nap, and uses it to + fill in Fcall structure f. If the passed message including any + data for Twrite and Rread messages is formatted properly, the + return value is the number of bytes the message occupied in the + buffer ap, which will always be less than or equal to nap; + otherwise it is 0. For Twrite and Tread messages, data is set + to a pointer into the argument message, not a copy. +
+ + ConvS2M does the reverse conversion, turning f into a message + starting at ap. The length of the resulting message is returned. + For Twrite and Rread messages, count bytes starting at data are + copied into the message. +
+ + The constant IOHDRSZ is a suitable amount of buffer to reserve + for storing the 9P header; the data portion of a Twrite or Rread + will be no more than the buffer size negotiated in the Tversion/Rversion + exchange, minus IOHDRSZ. +
+ + The routine sizeS2M returns the number of bytes required to store + the machine-independent representation of the Fcall structure + f, including its initial 32-bit size field. In other words, it + reports the number of bytes produced by a successful call to convS2M. + +
+ + Another structure is Dir, used by the routines described in stat(3). + ConvM2D converts the machine-independent form starting at ap into + d and returns the length of the machine-independent encoding. + The strings in the returned Dir structure are stored at successive + locations starting at strs. Usually strs will + point to storage immediately after the Dir itself. It can also + be a nil pointer, in which case the string pointers in the returned + Dir are all nil; however, the return value still includes their + length. +
+ + ConvD2M does the reverse translation, also returning the length + of the encoding. If the buffer is too short, the return value + will be BIT16SZ and the correct size will be returned in the first + BIT16SZ bytes. (If the buffer is less that BIT16SZ, the return + value is zero; therefore a correct test for complete packing of + the + message is that the return value is greater than BIT16SZ). The + macro GBIT16 can be used to extract the correct value. The related + macros with different sizes retrieve the corresponding-sized quantities. + PBIT16 and its brethren place values in messages. With the exception + of handling short buffers in convD2M, + these macros are not usually needed except by internal routines. + +
+ + Analogous to sizeS2M, sizeD2M returns the number of bytes required + to store the machine-independent representation of the Dir structure + d, including its initial 16-bit size field. +
+ + The routine statcheck checks whether the nbuf bytes of buf contain + a validly formatted machine-independent Dir entry suitable as + an argument, for example, for the wstat (see stat(3)) system call. + It checks that the sizes of all the elements of the the entry + sum to exactly nbuf, which is a simple but effective test + of validity. Nbuf and buf should include the second two-byte (16-bit) + length field that precedes the entry when formatted in a 9P message + (see stat(9p)); in other words, nbuf is 2 plus the sum of the + sizes of the entry itself. Statcheck also verifies that the length + field has the correct value (that is, nbuf−2). It returns 0 + for a valid entry and −1 for an incorrectly formatted entry. +
+ + Dirfmt, fcallfmt, and dirmodefmt are formatting routines, suitable + for fmtinstall(3). They convert Dir*, Fcall*, and long values + into string representations of the directory buffer, Fcall buffer, + or file mode value. Fcallfmt assumes that dirfmt has been installed + with format letter D and dirmodefmt with format + letter M. +
+ + Read9pmsg calls read(3) multiple times, if necessary, to read + an entire 9P message into buf. The return value is 0 for end of + file, or -1 for error; it does not return partial messages.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9
+ +
+

SEE ALSO
+ +
+ + intro(3), 9p(3), stat(3), intro(9p)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + -- cgit v1.2.3