glenda.party
term% ls -F
term% pwd
$home/manuals/9front/2/fcall
term% cat index.txt
FCALL(2)                      System Calls Manual                     FCALL(2)



NAME
       Fcall,  convS2M,  convD2M,  convM2S, convM2D, fcallfmt, dirfmt, dirmod‐
       efmt, 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 de‐
       scription 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  num‐
       ber  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(2).
       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  point‐
       ers  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 ex‐
       tract the correct value.  The related macros with different  sizes  re‐
       trieve  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 rou‐
       tines.

       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 argu‐
       ment, for example, for the wstat (see stat(2)) system call.  It  checks
       that  the  sizes  of all the elements of 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 en‐
       try when formatted in a 9P message (see stat(5)); 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 en‐
       try.

       Dirfmt, fcallfmt, and dirmodefmt are formatting routines, suitable  for
       fmtinstall(2).   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 and dirmodefmt with format letter

       Read9pmsg calls read(2) 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
       /sys/src/libc/9sys

SEE ALSO
       intro(2), 9p(2), stat(2), intro(5)



                                                                      FCALL(2)