GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  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

CONTENTS

Synopsis
Description
Source
See Also
Bugs

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

/usr/local/plan9/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) transaction, or to open and create on already-established fids.

Search for    or go to Top of page |  Section 3 |  Main Index


9PCLIENT (3) -->

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.