9PCLIENT(3)                                           9PCLIENT(3)

     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)

     9PCLIENT(3)                                           9PCLIENT(3)

          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).

     9PCLIENT(3)                                           9PCLIENT(3)

          A new connection to a 9P server is typically established by
          fsmount or nsmount. Fsmount initializes a new 9P conversa-
          tion 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* correspond-
          ing to this root.

          Fsinit, nsinit, fsversion, fsauth, fsattach, and fssetroot
          provide more detailed control over the file system connec-
          tion 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 mes-
          sage 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 cre-
          ate 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

     9PCLIENT(3)                                           9PCLIENT(3)

          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 trans-
          actions 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 writ-
          ing 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 implementa-
          tion 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

     9PCLIENT(3)                                           9PCLIENT(3)

          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
          /src/lib9pclient

     SEE ALSO
          intro(4), intro(9p), fsaopen and nsaopen in auth(3)

     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) trans-
          action, or to open and create on already-established fids.