|
NAME
| |
CFid, CFsys, fsinit, fsmount, fsroot, fssetroot, fsunmount, nsinit,
nsmount, fsversion, fsauth, fsattach, fsclose, fscreate, fsremove,
fsfremove, fsaccess, fsdirread, fsdirreadall, fsdirstat, fsdirfstat,
fsdirwstat, fsdirfwstat, fsopen, 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 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)
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)
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)
|
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.
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.
Once opened, these 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.
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.
|
SOURCE
| |
/usr/local/plan9/src/lib9pclient
|
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.
|
|
|