diff options
Diffstat (limited to 'man/man3/9pclient.html')
| -rw-r--r-- | man/man3/9pclient.html | 250 |
1 files changed, 250 insertions, 0 deletions
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 @@ +<head> +<title>9pclient(3) - Plan 9 from User Space</title> +<meta content="text/html; charset=utf-8" http-equiv=Content-Type> +</head> +<body bgcolor=#ffffff> +<table border=0 cellpadding=0 cellspacing=0 width=100%> +<tr height=10><td> +<tr><td width=20><td> +<tr><td width=20><td><b>9PCLIENT(3)</b><td align=right><b>9PCLIENT(3)</b> +<tr><td width=20><td colspan=2> + <br> +<p><font size=+1><b>NAME </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + 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<br> + +</table> +<p><font size=+1><b>SYNOPSIS </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>#include <u.h> + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>#include <libc.h> + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>#include <fcall.h> + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>#include <9pclient.h> + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>CFsys* fsmount(int fd, char *aname) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>CFsys* nsmount(char *name, char *aname) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>CFid* fsroot(CFsys *fsys) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>void fsunmount(CFsys *fsys) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>CFsys* fsinit(int fd) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int fsversion(CFsys *fsys, int msize, char *version, int nversion) + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>CFid *fsauth(CFsys *fsys, char *uname, char *aname) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>CFid *fsattach(CFsys *fsys, CFid *afid, char *uname, char *aname) + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>void fssetroot(CFsys *fsys, CFid *fid) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>void fsclose(CFid *fid) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>CFid *fscreate(CFsys *fs, char *path, int mode, ulong perm) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>CFid* fsopen(CFsys *fs, char *path, int mode) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>long fspread(CFid *fid, void *buf, long n, vlong offset) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>long fspwrite(CFid *fid, void *buf, long n, vlong offset) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>long fsread(CFid *fid, void *buf, long n) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>long fsreadn(CFid *fid, void *buf, long n) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>long fswrite(CFid *fid, void *buf, long n) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>long fsdirread(CFid *fid, Dir **d) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>long fsdirreadall(CFid *fid, Dir **d) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>Dir* fsdirstat(CFsys *fs, char *path) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>Dir* fsdirfstat(CFid *fid) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int fsdirwstat(CFsys *fs, char *path, Dir *d) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int fsdirfwstat(CFid *fid, Dir *d) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int fsopenfd(CFsys *fs, char *path, int mode)<br> + </font></tt> +</table> +<p><font size=+1><b>DESCRIPTION </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + The <i>9pclient</i> library helps client programs interact with 9P servers. + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + A <tt><font size=+1>CFsys*</font></tt> represents a connection to a 9P server. A <tt><font size=+1>CFid*</font></tt> represents + an active fid on some connection; see <i>intro</i>(9p). + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + A new connection to a 9P server is typically established by <i>fsmount</i> + or <i>nsmount</i>. <i>Fsmount</i> initializes a new 9P conversation on the open + file descriptor <i>fd</i>; <i>nsmount</i> connects to a service named <i>name</i> in + the current name space directory (see <a href="../man4/intro.html"><i>intro</i>(4)</a>). Both attach to + the root of the file system using the attach name <i>aname</i>. + <i>Fsroot</i> returns the <tt><font size=+1>CFid*</font></tt> corresponding to this root. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Fsinit</i>, <i>fsversion</i>, <i>fsauth</i>, <i>fsattach</i>, and <i>fssetroot</i> provide more + detailed control over the file system connection than <i>fsmount</i> + and <i>nsmount</i>. <i>Fsinit</i> allocates a new <tt><font size=+1>CFsys*</font></tt> corresponding to a + 9P conversation on the file descriptor <i>fd</i>. <i>Fsversion</i> executes + a <i>version</i>(9p) transaction to establish maximum message size and + 9P + version. <i>Fsauth</i> executes an <i>auth</i>(9p) transaction, returning the + new auth fid. (<i>Fsread</i> and <i>fswrite</i> can then be used to run the + authentication protocol over the fid.) <i>Fsattach</i> executes an <i>attach</i>(9p) + transaction to connect to the root of a file tree served by the + server. It presents <i>afid</i> (which may be nil) to establish + identity. <i>Fssetroot</i> sets the root fid used by <i>fsopen</i>, <i>fsopenfd</i>, + <i>fsdirstat</i>, and <i>fsdirwstat</i>, which evaluate rooted path names. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + When a fid is no longer needed, it should be clunked by calling + <i>fsclose</i> and then considered freed. Similarly, when the connection + to the server is no longer needed, it should be closed by calling + <i>fsunmount</i>, which will take care of calling <i>fsclose</i> on the current + root fid. Once all fids have been clunked <i>and</i> 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 <a href="../man2/close.html"><i>close</i>(2)</a>). Fids are not reference counted: + when <i>fsclose</i> is called, the clunk transaction and freeing of storage + happen immediately. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Fscreate</i> and <i>fsopen</i> establish new fids using the <i>walk</i>, <i>create</i> + and <i>open</i> transactions (see <i>walk</i>(9p) and <i>open</i>(9p)). The <i>path</i> argument + is evaluated relative to the <tt><font size=+1>CFsys</font></tt> root (see <i>fsroot</i> and <i>fssetroot</i> + 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 (<tt><font size=+1>.</font></tt>) are ignored. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + Once opened, these fids can be read and written using <i>fspread</i> + and <i>fspwrite</i>, which execute <i>read</i> and <i>write</i> transactions (see <i>read</i>(9p)). + The library maintains an offset for each fid, analagous to the + offset maintained by the kernel for each open file descriptor. + <i>Fsread</i> and <i>fswrite</i> read and write from this offset, and + update it after successful calls. Calling <i>fspread</i> or <i>fspwrite</i> + with an <i>offset</i> of –1 is identical to calling <i>fsread</i> or <i>fswrite</i>. + <i>Fsreadn</i> calls <i>fsread</i> repeatedly to obtain exactly <i>n</i> bytes of data, + unless it encounters end-of-file or an error. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + Reading an open a directory returns directory entries encoded + as described in <i>stat</i>(9p). <i>Fsdirread</i> calls <i>fsread</i> and then parses + the encoded entries into an array of <tt><font size=+1>Dir*</font></tt> data structures, storing + a pointer to the array in <tt><font size=+1>*d</font></tt> and returning the number of entries. + <i>Fsdirreadall</i> is similar but reads the entire directory. The + returned pointer should be freed with <i>free</i> (see <a href="../man3/malloc.html"><i>malloc</i>(3)</a>) when + no longer needed. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Fsdirfstat</i> and <i>fsdirfwstat</i> execute <i>stat</i> and <i>wstat</i> (see <i>stat</i>(9p)) + transactions. The <tt><font size=+1>Dir</font></tt> structure returned by <i>fsdirfstat</i> should + be freed with <i>free</i> (see <a href="../man3/malloc.html"><i>malloc</i>(3)</a>) when no longer needed. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Fsdirstat</i> and <i>fsdirwstat</i> are similar to <i>fsdirfstat</i> and <i>fsdirfwstat</i> + but operate on paths relative to the file system root (see <i>fsopen</i> + and <i>fscreate</i> above). + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Fsopenfd</i> 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 <a href="../man2/pipe.html"><i>pipe</i>(2)</a>. 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 <tt><font size=+1>CFsys</font></tt> is unmounted.<br> + +</table> +<p><font size=+1><b>SOURCE </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>/usr/local/plan9/src/lib9pclient<br> + </font></tt> +</table> +<p><font size=+1><b>SEE ALSO </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <a href="../man4/intro.html"><i>intro</i>(4)</a>, <i>intro</i>(9p)<br> + +</table> +<p><font size=+1><b>BUGS </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + The implementation should use a special version string to distinguish + between servers that support <i>openfd</i>(9p) and servers that do not. + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + The interface does not provide access to the <i>walk</i>(9p) transaction, + or to <i>open</i> and <i>create</i> on already-established fids. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + There is no <i>fsseek</i>.<br> + +</table> + +<td width=20> +<tr height=20><td> +</table> +<!-- TRAILER --> +<table border=0 cellpadding=0 cellspacing=0 width=100%> +<tr height=15><td width=10><td><td width=10> +<tr><td><td> +<center> +<a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a> +</center> +</table> +<!-- TRAILER --> +</body></html> |