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 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 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
       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 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 re-
       cent qid	returned by one	of these transactions for the given fid.

       Fsaccess	behaves	like Unix's Fsremove removes the named	path.	Fsfre-
       move 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	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
       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 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 A proxy process on the other	end is
       ferrying	data between the pipe and the 9P fid.  Because of  the	imple-
       mentation  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 when it detects EOF on	a 9P connection.

SOURCE
       /src/lib9pclient

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

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.1-RELEASE+and+Ports>

home | help