|  | 
 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
 {
 
 } 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 */
 };
 
 | 
 
 | 
 /* 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     
 SEE ALSO    
 |  |