|  | 
 NAME     
 |  |  |  | CFid, CFsys, fsinit, fsmount, fsroot, fssetroot, fsunmount, nsinit,
    nsmount, fsversion, fsauth, fsattach, fsclose, fscreate, fsfcreate,
    fsremove, fsfremove, fsaccess, fsdirread, fsdirreadall, fsdirstat,
    fsdirfstat, fsdirwstat, fsdirfwstat, fsopen, fsfopen, nsopen,
    fsopenfd, fspread, fspwrite, fsread, fsreadn, fsseek, fswrite,
    fsprint, fsvprint – 9P client library | 
 SYNOPSIS     
 |  |  |  | #include <u.h> 
    
    
    #include <libc.h> 
    
    
    #include <fcall.h> 
    
    
    #include <thread.h> 
    
    
    #include <9pclient.h> 
    
    
    CFsys* fsmount(int fd, char *aname) 
    
    
    CFsys* nsmount(char *name, char *aname) 
    
    
    CFid*    fsroot(CFsys *fsys) 
    
    
    void    fsunmount(CFsys *fsys) 
    
    
    CFsys* fsinit(int fd) 
    
    
    CFsys* nsinit(char *name) 
    
    
    int     fsversion(CFsys *fsys, int msize, char *version, int nversion)
    
    
    
    CFid*    fsauth(CFsys *fsys, char *uname, char *aname) 
    
    
    CFid*    fsattach(CFsys *fsys, CFid *afid, char *uname, char *aname)
    
    
    
    void    fssetroot(CFsys *fsys, CFid *fid) 
    
    
    void    fsclose(CFid *fid) 
    
    
    CFid*    fscreate(CFsys *fs, char *path, int mode, ulong perm) 
    
    
    int     fsfcreate(CFid *fid, char *path, int mode, ulong perm) 
    
    
    int     fsremove(CFSys *fs, char *path) 
    
    
    int     fsfremove(CFid *fid) 
    
    
    int     fsaccess(CFsys *fs, char *path, int amode) 
    
    
    CFid*    fsopen(CFsys *fs, char *path, int mode) 
    
    
    int     fsfopen(CFid *fid, char *path, int mode) 
    
    
    long    fspread(CFid *fid, void *buf, long n, vlong offset) 
    
    
    long    fspwrite(CFid *fid, void *buf, long n, vlong offset) 
    
    
    long    fsread(CFid *fid, void *buf, long n) 
    
    
    long    fsreadn(CFid *fid, void *buf, long n) 
    
    
    long    fswrite(CFid *fid, void *buf, long n) 
    
    
    int     fsprint(CFid *fid, char *fmt, ...) 
    
    
    int     fsvprint(CFid *fid, char *fmt, ...) 
    
    
    vlong    fsseek(CFid *Fid, vlong n, int type) 
    
    
    Qid     fsqid(CFid *fid) 
    
    
    long    fsdirread(CFid *fid, Dir **d) 
    
    
    long    fsdirreadall(CFid *fid, Dir **d) 
    
    
    Dir*    fsdirstat(CFsys *fs, char *path) 
    
    
    Dir*    fsdirfstat(CFid *fid) 
    
    
    int     fsdirwstat(CFsys *fs, char *path, Dir *d) 
    
    
    int     fsdirfwstat(CFid *fid, Dir *d) 
    
    
    int     fsopenfd(CFsys *fs, char *path, int mode) 
    
    
    CFsys* nsopen(char *name, char *aname, char *path, int mode) 
    
    
    extern int chatty9pclient; 
    
    
    extern int eofkill9pclient; 
 | 
 DESCRIPTION     
 |  |  |  | The 9pclient library helps client programs interact with 9P servers.
    
    
    
    A CFsys* represents a connection to a 9P server. A CFid* represents
    an active fid on some connection; see intro(9p). 
    
    
    A new connection to a 9P server is typically established by fsmount
    or nsmount. Fsmount initializes a new 9P conversation on the open
    file descriptor fd; nsmount connects to a service named name in
    the current name space directory (see intro(4)). Both attach to
    the root of the file system using the attach name aname. Fsroot
    returns the CFid*
    corresponding to this root. 
    
    
    Fsinit, nsinit, fsversion, fsauth, fsattach, and fssetroot provide
    more detailed control over the file system connection than fsmount
    and nsmount. Fsinit allocates a new CFsys* corresponding to a
    9P conversation on the file descriptor fd and then calls fsversion
    to initialize the connection. Nsinit does the same for name space
    services. Fsversion
    executes a version(9p) transaction to establish maximum message
    size and 9P version. Fsauth executes an auth(9p) transaction,
    returning the new auth fid. (Fsread and fswrite can then be used
    to run the authentication protocol over the fid.) Fsattach executes
    an attach(9p) transaction to connect to the root of a file tree
    served by the server. It
    presents afid (which may be nil) to establish identity. Fssetroot
    sets the root fid used by fsopen, fsopenfd, fsdirstat, and fsdirwstat,
    which evaluate rooted path names. 
    
    
    When a fid is no longer needed, it should be clunked by calling
    fsclose and then considered freed. Similarly, when the connection
    to the server is no longer needed, it should be closed by calling
    fsunmount, which will take care of calling fsclose on the current
    root fid. Once all fids have been clunked and the connection has
    been closed (the order is not
    important), the allocated structures will be freed and the file
    descriptor corresponding to the connection will be closed (see
    close(2)). Fids are not reference counted: when fsclose is called,
    the clunk transaction and freeing of storage happen immediately.
    Despite its name, fsclose can be used to clunk fids that are not
    open for I/O. 
    
    
    Fscreate and fsopen establish new fids using the walk, create
    and open transactions (see walk(9p) and open(9p)). The path argument
    is evaluated relative to the CFsys root (see fsroot and fssetroot
    above). The path is parsed as a slash-separated sequence of path
    elements, as on Unix and Plan 9. Elements that are empty or dot
    (.) are ignored. 
    
    
    Alternately, fswalk walks from a fid to a given name to create
    a new fid. The name may be nil, corresponding to a walk with no
    names. Otherwise the name is taken as a slash-separated sequence
    of path elements. Fsfcreate and fsfopen issue create and open
    transactions using the passed fid argument, which should have
    been obtained by calling
    fswalk. 
    
    
    Once opened, fids can be read and written using fspread and fspwrite,
    which execute read and write transactions (see read(9p)). The
    library maintains an offset for each fid, analagous to the offset
    maintained by the kernel for each open file descriptor. Fsread
    and fswrite read and write from this offset, and update it after
    successful calls. Fsseek sets
    the offset; the n and type arguments are used as in seek(3). Calling
    fspread or fspwrite with an offset of –1 is identical to calling
    fsread or fswrite. Fsreadn calls fsread repeatedly to obtain exactly
    n bytes of data, unless it encounters end-of-file or an error.
    
    
    
    Attach, walk, create, and open transactions include in their replies
    an updated qid for the fid being manipulated. Fsqid returns the
    most recent qid returned by one of these transactions for the
    given fid. 
    
    
    Fsaccess behaves like Unix’s access(2). Fsremove removes the named
    path. Fsfremove removes the path corresponding to an open CFid*.
    
    
    
    Reading an open a directory returns directory entries encoded
    as described in stat(9p). 
    
    
    Fsprint and fsvprint are like fprint and vfprint (see print(3))
    but write to CFid*s. 
    
    
    Fsdirread calls fsread and then parses the encoded entries into
    an array of Dir* data structures, storing a pointer to the array
    in *d and returning the number of entries. Fsdirreadall is similar
    but reads the entire directory. The returned pointer should be
    freed with free (see malloc(3)) when no longer needed. 
    
    
    Fsdirfstat and fsdirfwstat execute stat and wstat (see stat(9p))
    transactions. The Dir structure returned by fsdirfstat should
    be freed with free (see malloc(3)) when no longer needed. 
    
    
    Fsdirstat and fsdirwstat are similar to fsdirfstat and fsdirfwstat
    but operate on paths relative to the file system root (see fsopen
    and fscreate above). 
    
    
    Fsopenfd opens a file on the 9P server for reading or writing
    but returns a Unix file descriptor instead of a fid structure.
    The file descriptor is actually one end of a pipe(2). A proxy
    process on the other end is ferrying data between the pipe and
    the 9P fid. Because of the implementation as a pipe, the only
    signal of a read or write error is the closing of the
    pipe. The file descriptor remains valid even after the CFsys is
    unmounted. 
    
    
    Nsopen opens a single file on a name space server: it runs nsmount,
    fsopen, and then fsunmount. 
    
    
    If the chatty9pclient flag is set, the library prints all 9P messages
    to standard error. If the eofkill9pclient flag is set, the library
    calls threadexitsall (see thread(3)) when it detects EOF on a
    9P connection. 
 | 
 SOURCE     
 SEE ALSO    
 BUGS     
 |  |  |  | The implementation should use a special version string to distinguish
    between servers that support openfd(9p) and servers that do not.
    
    
    
    The interface does not provide access to the walk(9p) transaction,
    or to open and create on already-established fids. 
 | 
 |  |