Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
9PCLIENT(3)		   Library Functions Manual		   9PCLIENT(3)

NAME
       CFid, CFsys, fsinit, fsmount, fsroot, fssetroot,	fsunmount, nsinit, ns-
       mount, fsversion, fsauth, fsattach, fsclose, fscreate, fsfcreate, fsre-
       move, fsfremove,	fsaccess, fsdirread, fsdirreadall, fsdirstat, fsdirfs-
       tat,  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* cor-
       responding to this root.

       Fsinit, nsinit, fsversion, fsauth, fsattach, and	fssetroot provide more
       detailed	 control  over the file	system connection than fsmount and ns-
       mount.  Fsinit allocates	a new CFsys* corresponding to a	 9P  conversa-
       tion  on	 the file descriptor fd	and then calls fsversion to initialize
       the connection.	Nsinit does the	same for name space services.	Fsver-
       sion  executes  a  version(9p) transaction to establish maximum message
       size and	9P version.  Fsauth executes an	auth(9p) transaction,  return-
       ing  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  or-
       der  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	evalu-
       ated  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.  Oth-
       erwise  the  name  is  taken as a slash-separated sequence of path ele-
       ments.  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	 call-
       ing  fsread  or fswrite.	 Fsreadn calls fsread repeatedly to obtain ex-
       actly 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 re-
       cent 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 de-
       scribed 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 ar-
       ray 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))	trans-
       actions.	 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 re-
       turns a Unix file descriptor instead of a fid structure.	 The file  de-
       scriptor	 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 af-
       ter 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  con-
       nection.

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.

								   9PCLIENT(3)

NAME | SYNOPSIS | DESCRIPTION | SOURCE | SEE ALSO | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=9pclient&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help