FCALL(2)                                                 FCALL(2)

     NAME
          Fcall, convS2M, convD2M, convM2S, convM2D, getS, fcallconv,
          dirconv, dirmodeconv - interface to Plan 9 File protocol

     SYNOPSIS
          #include <u.h>
          #include <libc.h>
          #include <auth.h>
          #include <fcall.h>

          int convS2M(Fcall *f, char *ap)

          int convD2M(Dir *d, char *ap)

          int convM2S(char *ap, Fcall *f, int n)

          int convM2D(char *ap, Dir *d)

          char *getS(int fd, char *ap, Fcall *f, long *lp)

          int dirconv(void *o, Fconv*)

          int fcallconv(void *o, Fconv*)

          int dirmodeconv(void *o, Fconv*)

     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:

          typedef
          struct Fcall {
              char  type;
              short fid;
              short tag;
              union {
                    struct {
                         ushort                  oldtag;/* Tflush */
                         Qid   qid;              /* Rattach, Rwalk,
                                                     Ropen, Rcreate */
                         char  rauth[AUTHENTLEN];    /* Rattach */
                    };
                    struct {
                         char  uname[NAMELEN];   /* Tattach */
                         char  aname[NAMELEN];   /* Tattach */
                         char  ticket[TICKETLEN];    /* Tattach */
                         char  auth[AUTHENTLEN]; /* Tattach */
                    };
                    struct {

     Page 1                       Plan 9             (printed 3/29/24)

     FCALL(2)                                                 FCALL(2)

                         char  ename[ERRLEN];    /* Rerror */
                         char  authid[NAMELEN];  /* Rsession */
                         char  authdom[DOMLEN];  /* Rsession */
                         char  chal[CHALLEN];    /* Tsession/Rsession */
                    };
                    struct {
                         long  perm;             /* Tcreate */
                         short newfid;           /* Tclone, Tclwalk */
                         char  name[NAMELEN];    /* Twalk, Tclwalk,
                                                     Tcreate */
                         char  mode;             /* Tcreate, Topen */
                    };
                    struct {
                         long  offset;           /* Tread, Twrite */
                         long  count;            /* Tread, Twrite, Rread */
                         char  *data;            /* Twrite, Rread */
                    };
                    struct {
                         char  stat[DIRLEN];     /* Twstat, Rstat */
                    };
              };
          } Fcall;

          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 Tnop,
          Rnop, Tsession, Rsession, 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 selec-
          tively by the message types given in comments.

          ConvM2S takes a 9P message at ap of length n, and uses it to
          fill in Fcall structure f. If the passed message including
          any data for Twrite and Rread messages is formatted prop-
          erly, the return value is n; otherwise it is 0.  For Twrite
          and Tread messages, data is set to a pointer into the argu-
          ment message, not a copy.

          ConvS2M does the reverse conversion, turning f into a mes-
          sage starting at ap. The length of the resulting message is
          returned.  For Twrite and Rread messages, count bytes start-
          ing at data are copied into the message.

          The constant MAXMSG is the length of the longest message,
          excluding data; MAXFDATA (8192) is the maximum count in a
          read or write message.  Thus messages are guaranteed to be
          shorter than MAXMSG+MAXFDATA bytes long.

          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 encod-
          ing.  ConvD2M does the reverse translation, also returning

     Page 2                       Plan 9             (printed 3/29/24)

     FCALL(2)                                                 FCALL(2)

          the length of the encoding.

          GetS reads a message from file descriptor fd into ap and
          converts the message using convM2S into the Fcall structure
          f. The lp argument must point to a long holding the size of
          the ap buffer.  It is somewhat resilient to transient read
          errors.  If convM2S succeeds, its return value is stored in
          *lp, and getS returns zero.  Otherwise getS returns a string
          identifying the error.

          Dirconv, fcallconv, and dirmodeconv are formatting routines,
          suitable for fmtinstall (see print(2)). They convert Dir*,
          Fcall*, and long values into string representations of the
          directory buffer, Fcall buffer, or file mode value.
          Fcallconv assumes that dirconv has been installed with for-
          mat letter `D'.

     SOURCE
          /sys/src/libc/9sys

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

     DIAGNOSTICS
          GetS sets errstr.

     BUGS
          The offset and directory length fields have 8 bytes in the
          protocol, but these routines assume they fit into a long.

          ConvS2M should check for counts exceeding MAXFMSG.

     Page 3                       Plan 9             (printed 3/29/24)