From 78e51a8c6678b6e3dff3d619aa786669f531f4bc Mon Sep 17 00:00:00 2001 From: rsc Date: Fri, 14 Jan 2005 03:45:44 +0000 Subject: checkpoint --- man/man3/9pclient.html | 250 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 250 insertions(+) create mode 100644 man/man3/9pclient.html (limited to 'man/man3/9pclient.html') diff --git a/man/man3/9pclient.html b/man/man3/9pclient.html new file mode 100644 index 00000000..4ae50c21 --- /dev/null +++ b/man/man3/9pclient.html @@ -0,0 +1,250 @@ + +9pclient(3) - Plan 9 from User Space + + + + +
+
+
9PCLIENT(3)9PCLIENT(3) +
+
+

NAME
+ +
+ + CFid, CFsys, fsinit, fsmount, fsroot, fssetroot, fsunmount, nsmount, + fsversion, fsauth, fsattach, fsclose, fscreate, fsdirread, fsdirreadall, + fsdirstat, fsdirfstat, fsdirwstat, fsdirfwstat, fsopen, fsopenfd, + fspread, fspwrite, fsread, fsreadn, fswrite – 9P client library
+ +
+

SYNOPSIS
+ +
+ + #include <u.h> +
+ + #include <libc.h> +
+ + #include <fcall.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) +
+ + 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) +
+ + 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) +
+ + 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)
+ +
+

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, 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. 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. 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. +
+ + Reading an open a directory returns directory entries encoded + as described in stat(9p). 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.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9pclient
+ +
+

SEE ALSO
+ +
+ + intro(4), intro(9p)
+ +
+

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. +
+ + There is no fsseek.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + -- cgit v1.2.3