250 lines
13 KiB
HTML
250 lines
13 KiB
HTML
<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>
|