checkpoint
This commit is contained in:
rsc
parent
2634795b5f
commit
78e51a8c66
314 changed files with 48199 additions and 300 deletions
434
man/man3/9p.html
Normal file
434
man/man3/9p.html
Normal file
|
|
@ -0,0 +1,434 @@
|
|||
<head>
|
||||
<title>9p(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>9P(3)</b><td align=right><b>9P(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>
|
||||
|
||||
Srv, dirread9p, emalloc9p, erealloc9p, estrdup9p, postfd, postmountsrv,
|
||||
readbuf, readstr, respond, srv, threadpostmountsrv, walkandclone
|
||||
– 9P file service<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><br>
|
||||
#include <libc.h><br>
|
||||
#include <fcall.h><br>
|
||||
#include <thread.h><br>
|
||||
#include <9p.h><br>
|
||||
|
||||
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
||||
|
||||
typedef struct Srv {<br>
|
||||
|
||||
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
||||
|
||||
Tree* tree;<br>
|
||||
void (*attach)(Req *r);<br>
|
||||
void (*auth)(Req *r);<br>
|
||||
void (*open)(Req *r);<br>
|
||||
void (*create)(Req *r);<br>
|
||||
void (*read)(Req *r);<br>
|
||||
void (*write)(Req *r);<br>
|
||||
void (*remove)(Req *r);<br>
|
||||
void (*flush)(Req *r);<br>
|
||||
void (*stat)(Req *r);<br>
|
||||
void (*wstat)(Req *r);<br>
|
||||
void (*walk)(Req *r);<br>
|
||||
char* (*walk1)(Fid *fid, char *name, Qid *qid);<br>
|
||||
char* (*clone)(Fid *oldfid, Fid *newfid);<br>
|
||||
void (*destroyfid)(Fid *fid);<br>
|
||||
void (*destroyreq)(Req *r);<br>
|
||||
void (*end)(Srv *s);<br>
|
||||
void* aux;<br>
|
||||
int infd;<br>
|
||||
int outfd;<br>
|
||||
int srvfd;<br>
|
||||
int nopipe;<br>
|
||||
|
||||
</table>
|
||||
} Srv;<br>
|
||||
|
||||
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
||||
|
||||
int srv(Srv *s)<br>
|
||||
void postmountsrv(Srv *s, char *name, char *mtpt, int flag)<br>
|
||||
void threadpostmountsrv(Srv *s, char *name, char *mtpt, int flag)<br>
|
||||
int postfd(char *srvname, int fd)<br>
|
||||
void respond(Req *r, char *error)<br>
|
||||
ulong readstr(Req *r, char *src)<br>
|
||||
ulong readbuf(Req *r, void *src, ulong nsrc)<br>
|
||||
typedef int Dirgen(int n, Dir *dir, void *aux)<br>
|
||||
void dirread9p(Req *r, Dirgen *gen, void *aux)<br>
|
||||
void walkandclone(Req *r, char *(*walk1)(Fid *old, char *name,
|
||||
void *v),<br>
|
||||
|
||||
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
||||
|
||||
|
||||
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
||||
|
||||
char *(*clone)(Fid *old, Fid *new, void *v), void *v)<br>
|
||||
|
||||
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
||||
|
||||
|
||||
</table>
|
||||
|
||||
</table>
|
||||
void* emalloc9p(ulong n)<br>
|
||||
void* erealloc9p(void *v, ulong n)<br>
|
||||
char* estrdup9p(char *s)<br>
|
||||
|
||||
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
||||
|
||||
extern int chatty9p;<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 function <i>srv</i> serves a 9P session by reading requests from
|
||||
<tt><font size=+1>s−>infd</font></tt>, dispatching them to the function pointers kept in <tt><font size=+1>Srv</font></tt>,
|
||||
and writing the responses to <tt><font size=+1>s−>outfd</font></tt>. (Typically, <i>postmountsrv</i>
|
||||
or <i>threadpostmountsrv</i> initializes the <tt><font size=+1>infd</font></tt> and <tt><font size=+1>outfd</font></tt> structure
|
||||
members. See the description below.)
|
||||
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
||||
|
||||
<tt><font size=+1>Req</font></tt> and <tt><font size=+1>Fid</font></tt> structures are allocated one-to-one with uncompleted
|
||||
requests and active fids, and are described in <a href="../man3/9p-fid.html"><i>9p-fid</i>(3)</a>.
|
||||
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
||||
|
||||
The behavior of <i>srv</i> depends on whether there is a file tree (see
|
||||
<a href="../man3/9p-file.html"><i>9p-file</i>(3)</a>) associated with the server, that is, whether the <tt><font size=+1>tree</font></tt>
|
||||
element is nonzero. The differences are made explicit in the discussion
|
||||
of the service loop below. The <tt><font size=+1>aux</font></tt> element is the client’s, to
|
||||
do with as it pleases.
|
||||
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
||||
|
||||
<i>Srv</i> does not return until the 9P conversation is finished. Since
|
||||
it is usually run in a separate process so that the caller can
|
||||
exit, the service loop has little chance to return gracefully
|
||||
on out of memory errors. It calls <i>emalloc9p</i>, <i>erealloc9p</i>, and <i>estrdup9p</i>
|
||||
to obtain its memory. The default implementations of these
|
||||
functions act as <i>malloc</i>, <i>realloc</i>, and <i>strdup</i> but abort the program
|
||||
if they run out of memory. If alternate behavior is desired, clients
|
||||
can link against alternate implementations of these functions.
|
||||
|
||||
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
||||
|
||||
<i>Postmountsrv</i> and <i>threadpostmountsrv</i> are wrappers that create a
|
||||
separate process in which to run <i>srv</i>. They do the following:<br>
|
||||
|
||||
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
||||
|
||||
If <i>s</i><tt><font size=+1>−></font></tt><i>nopipe</i> is zero (the common case), initialize <i>s</i><tt><font size=+1>−></font></tt><i>infd</i> and <i>s</i><tt><font size=+1>−></font></tt><i>outfd</i>
|
||||
to be one end of a freshly allocated pipe, with <i>s</i><tt><font size=+1>−></font></tt><i>srvfd</i> initialized
|
||||
as the other end.<br>
|
||||
If <tt><font size=+1>name</font></tt> is non-nil, call <tt><font size=+1>postfd(</font></tt><i>s</i><tt><font size=+1>−></font></tt><i>srvfd</i><tt><font size=+1>,</font></tt> <i>name</i><tt><font size=+1>)</font></tt> to post <i>s</i><tt><font size=+1>−></font></tt><i>srvfd</i>
|
||||
as <tt><font size=+1>/srv/</font></tt><i>name</i><tt><font size=+1>.<br>
|
||||
</font></tt>Fork a child process via <a href="../man3/rfork.html"><i>rfork</i>(3)</a> or <i>procrfork</i> (see <a href="../man3/thread.html"><i>thread</i>(3)</a>),
|
||||
using the <tt><font size=+1>RFFDG</font></tt>, <tt><font size=+1>RFNAMEG</font></tt>, and <tt><font size=+1>RFMEM</font></tt> flags. The child process calls
|
||||
<i>close(</i><tt><font size=+1>s</font></tt><i>-></i><tt><font size=+1>srvfd</font></tt><i>)</i> and then <i>srv(</i><tt><font size=+1>s</font></tt><i>)</i>; it will exit once <i>srv</i> returns.<br>
|
||||
If <i>mtpt</i> is non-nil, call <tt><font size=+1>amount(</font></tt><i>s</i><tt><font size=+1>−></font></tt><i>srvfd, mtpt</i><tt><font size=+1>,</font></tt> <i>flag</i><tt><font size=+1>, </font></tt>""); otherwise,
|
||||
close <i>s</i><tt><font size=+1>−></font></tt><i>srvfd</i>.<br>
|
||||
The parent returns to the caller.
|
||||
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
||||
|
||||
|
||||
</table>
|
||||
If any error occurs during this process, the entire process is
|
||||
terminated by calling <a href="../man3/sysfatal.html"><i>sysfatal</i>(3)</a>.<br>
|
||||
<p><font size=+1><b>Service functions </b></font><br>
|
||||
The functions in a <tt><font size=+1>Srv</font></tt> structure named after 9P transactions are
|
||||
called to satisfy requests as they arrive. If a function is provided,
|
||||
it <i>must</i> arrange for <i>respond</i> to be called when the request is satisfied.
|
||||
The only parameter of each service function is a <tt><font size=+1>Req*</font></tt> parameter
|
||||
(say <i>r</i>). The incoming request parameters are
|
||||
stored in <i>r</i><tt><font size=+1>−></font></tt><i>ifcall</i>; <i>r</i><tt><font size=+1>−></font></tt><i>fid</i> and <i>r</i><tt><font size=+1>−></font></tt><i>newfid</i> are pointers to <tt><font size=+1>Fid</font></tt> structures
|
||||
corresponding to the numeric fids in <i>r</i><tt><font size=+1>−></font></tt><i>ifcall</i>; similarly, <i>r</i><tt><font size=+1>−></font></tt><i>oldreq</i>
|
||||
is the <tt><font size=+1>Req</font></tt> structure corresponding to <i>r</i><tt><font size=+1>−></font></tt><i>ifcall.oldtag</i>. The outgoing
|
||||
response data should be stored in <i>r</i><tt><font size=+1>−></font></tt><i>ofcall</i>. The one exception
|
||||
to this rule is that <i>stat</i> should fill in
|
||||
<i>r</i><tt><font size=+1>−></font></tt><i>d</i> rather than <i>r</i><tt><font size=+1>−></font></tt><i>ofcall.stat</i>: the library will convert the structure
|
||||
into the machine-independent wire representation. Similarly, <i>wstat</i>
|
||||
may consult <i>r</i><tt><font size=+1>−></font></tt><i>d</i> rather than decoding <i>r</i><tt><font size=+1>−></font></tt><i>ifcall</i><tt><font size=+1>.</font></tt><i>stat</i> itself. When
|
||||
a request has been handled, <i>respond</i> should be called with <i>r</i> and
|
||||
an error string. If the request was satisfied
|
||||
successfully, the error string should be a nil pointer. Note that
|
||||
it is permissible for a function to return without itself calling
|
||||
<i>respond</i>, as long as it has arranged for <i>respond</i> to be called at
|
||||
some point in the future by another proc sharing its address space,
|
||||
but see the discussion of <i>flush</i> below. Once <i>respond</i> has been
|
||||
called, the <tt><font size=+1>Req*</font></tt> as well as any pointers it once contained must
|
||||
be considered freed and not referenced.
|
||||
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
||||
|
||||
If the service loop detects an error in a request (e.g., an attempt
|
||||
to reuse an extant fid, an open of an already open fid, a read
|
||||
from a fid opened for write, etc.) it will reply with an error
|
||||
without consulting the service functions.
|
||||
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
||||
|
||||
The service loop provided by <i>srv</i> (and indirectly by <i>postmountsrv</i>
|
||||
and <i>threadpostmountsrv</i>) is single-threaded. If it is expected
|
||||
that some requests might block, arranging for alternate processes
|
||||
to handle them is suggested.
|
||||
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
||||
|
||||
The constraints on the service functions are as follows. These
|
||||
constraints are checked while the server executes. If a service
|
||||
function fails to do something it ought to have, <i>srv</i> will call
|
||||
<i>endsrv</i> and then abort.<br>
|
||||
<i>Auth</i> If authentication is desired, the <i>auth</i> function should record
|
||||
that <i>afid</i> is the new authentication fid and set <i>afid->qid</i> and <i>ofcall.qid</i>.
|
||||
<i>Auth</i> may be nil, in which case it will be treated as having responded
|
||||
with the error “<i>argv0: authentication not required</i>,” where <i>argv0</i>
|
||||
is the program name variable as set by
|
||||
|
||||
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
||||
|
||||
<i>ARGBEGIN</i> (see <a href="../man3/arg.html"><i>arg</i>(3)</a>).<br>
|
||||
|
||||
</table>
|
||||
<i>Attach</i>The <i>attach</i> function should check the authentication state
|
||||
of <i>afid</i> if desired, and set <i>r</i><tt><font size=+1>−></font></tt><i>fid</i><tt><font size=+1>−></font></tt><i>qid</i> and <i>ofcall.qid</i> to the qid
|
||||
of the file system root. <i>Attach</i> may be nil only if file trees
|
||||
are in use; in this case, the qid will be filled from the root
|
||||
of the tree, and no authentication will be done.
|
||||
<i>Walk</i> If file trees are in use, <i>walk</i> is handled internally, and
|
||||
<i>srv</i><tt><font size=+1>−></font></tt><i>walk</i> is never called.<br>
|
||||
|
||||
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
||||
|
||||
If file trees are not in use, <i>walk</i> should consult <i>r</i><tt><font size=+1>−></font></tt><i>ifcall</i><tt><font size=+1>.</font></tt><i>wname</i>
|
||||
and <i>r</i><tt><font size=+1>−></font></tt><i>ifcall</i><tt><font size=+1>.</font></tt><i>nwname</i>, filling in <i>ofcall</i><tt><font size=+1>.</font></tt><i>qid</i> and <i>ofcall</i><tt><font size=+1>.</font></tt><i>nqid</i>, and
|
||||
also copying any necessary <i>aux</i> state from <i>r</i><tt><font size=+1>−></font></tt><i>fid</i> to <i>r</i><tt><font size=+1>−></font></tt><i>newfid</i> when
|
||||
the two are different. As long as <i>walk</i> sets <i>ofcall</i><tt><font size=+1>.</font></tt><i>nqid</i> appropriately,
|
||||
it can <i>respond</i> with a nil error string
|
||||
even when 9P demands an error (<i>e.g.</i>, in the case of a short walk);
|
||||
the library detects error conditions and handles them appropriately.<br>
|
||||
Because implementing the full walk message is intricate and prone
|
||||
to error, the helper routine <i>walkandclone</i> will handle the request
|
||||
given pointers to two functions <i>walk1</i> and (optionally) <i>clone .
|
||||
Clone</i>, if non-nil, is called to signal the creation of <i>newfid</i>
|
||||
from <i>oldfid</i>. Typically a <i>clone</i> routine will copy or increment
|
||||
a reference count in <i>oldfid</i>’s <i>aux</i> element. <i>Walk1</i> should walk <i>fid</i>
|
||||
to <i>name</i>, initializing <i>fid</i><tt><font size=+1>−></font></tt><i>qid</i> to the new path’s qid. Both should
|
||||
return nil on success or an error message on error. <i>Walkandclone</i>
|
||||
will call <i>respond</i> after handling the request.<br>
|
||||
|
||||
</table>
|
||||
<i>Walk1</i>, <i>Clone<br>
|
||||
</i>
|
||||
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
||||
|
||||
If the client provides functions <i>srv</i><tt><font size=+1>−></font></tt><i>walk1</i> and (optionally) <i>srv</i><tt><font size=+1>−></font></tt><i>clone</i>,
|
||||
the 9P service loop will call <i>walkandclone</i> with these functions
|
||||
to handle the request. Unlike the <i>walk1</i> above, <i>srv</i><tt><font size=+1>−></font></tt><i>walk1</i> must
|
||||
fill in both <i>fid</i><tt><font size=+1>−></font></tt><i>qid</i> and <tt><font size=+1>*</font></tt><i>qid</i> with the new qid on a successful
|
||||
walk.<br>
|
||||
|
||||
</table>
|
||||
<i>Open</i> If file trees are in use, the file metadata will be consulted
|
||||
on open, create, remove, and wstat to see if the requester has
|
||||
the appropriate permissions. If not, an error will be sent back
|
||||
without consulting a service function.
|
||||
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
||||
|
||||
If not using file trees or the user has the appropriate permissions,
|
||||
<i>open</i> is called with <i>r</i><tt><font size=+1>−></font></tt><i>ofcall</i><tt><font size=+1>.</font></tt><i>qid</i> already initialized to the one
|
||||
stored in the <tt><font size=+1>Fid</font></tt> structure (that is, the one returned in the
|
||||
previous walk). If the qid changes, both should be updated.<br>
|
||||
<i>Create</i>The <i>create</i> function must fill in both <i>r</i><tt><font size=+1>−></font></tt><i>fid</i><tt><font size=+1>−></font></tt><i>qid</i> and <i>r</i><tt><font size=+1>−></font></tt><i>ofcall</i><tt><font size=+1>.</font></tt><i>qid</i>
|
||||
on success. When using file trees, <i>create</i> should allocate a new
|
||||
<tt><font size=+1>File</font></tt> with <i>createfile</i>; note that <i>createfile</i> may return nil (because,
|
||||
say, the file already exists). If the <i>create</i> function is nil,
|
||||
<i>srv</i> behaves as though it were a function that always
|
||||
|
||||
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
||||
|
||||
responded with the error “create prohibited”.<br>
|
||||
|
||||
</table>
|
||||
<i>Remove<br>
|
||||
|
||||
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
||||
|
||||
Remove
|
||||
</table>
|
||||
</i>
|
||||
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
||||
|
||||
should mark the file as removed, whether by calling <i>removefile</i>
|
||||
when using file trees, or by updating an internal data structure.
|
||||
In general it is not a good idea to clean up the <i>aux</i> information
|
||||
associated with the corresponding <tt><font size=+1>File</font></tt> at this time, to avoid
|
||||
memory errors if other fids have references to that
|
||||
file. Instead, it is suggested that <i>remove</i> simply mark the file
|
||||
as removed (so that further operations on it know to fail) and
|
||||
wait until the file tree’s destroy function is called to reclaim
|
||||
the <i>aux</i> pointer. If not using file trees, it is prudent to take
|
||||
the analogous measures. If <i>remove</i> is not provided, all remove
|
||||
requests will draw “remove prohibited” errors.<br>
|
||||
|
||||
</table>
|
||||
<i>Read</i> The <i>read</i> function must be provided; it fills <i>r</i><tt><font size=+1>−></font></tt><i>ofcall</i><tt><font size=+1>.</font></tt><i>data</i>
|
||||
with at most <i>r</i><tt><font size=+1>−></font></tt><i>ifcall</i><tt><font size=+1>.</font></tt><i>count</i> bytes of data from offset <i>r</i><tt><font size=+1>−></font></tt><i>ifcall</i><tt><font size=+1>.</font></tt><i>offset</i>
|
||||
of the file. It also sets <i>r</i><tt><font size=+1>−></font></tt><i>ofcall</i><tt><font size=+1>.</font></tt><i>count</i> to the number of bytes
|
||||
being returned. If using file trees, <i>srv</i> will handle reads of
|
||||
directories internally, only calling <i>read</i> for requests on
|
||||
|
||||
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
||||
|
||||
files. <i>Readstr</i> and <i>readbuf</i> are useful for satisfying read requests
|
||||
on a string or buffer. Consulting the request in <i>r</i><tt><font size=+1>−></font></tt><i>ifcall</i>, they
|
||||
fill <i>r</i><tt><font size=+1>−></font></tt><i>ofcall</i><tt><font size=+1>.</font></tt><i>data</i> and set <i>r</i><tt><font size=+1>−></font></tt><i>ofcall</i><tt><font size=+1>.</font></tt><i>count</i>; they do not call <i>respond</i><tt><font size=+1>.</font></tt>
|
||||
Similarly, <i>dirread9p</i> can be used to handle directory reads in
|
||||
servers not using file trees. The passed <i>gen
|
||||
</i>function will be called as necessary to fill <i>dir</i> with information
|
||||
for the <i>n</i>th entry in the directory. The string pointers placed
|
||||
in <i>dir</i> should be fresh copies made with <i>estrdup9p</i>; they will be
|
||||
freed by <i>dirread9p</i> after each successful call to <i>gen</i>. <i>Gen</i> should
|
||||
return zero if it successfully filled <i>dir</i>, minus one on end of
|
||||
directory.<br>
|
||||
|
||||
</table>
|
||||
<i>Write</i>The <i>write</i> function is similar but need not be provided. If
|
||||
it is not, all writes will draw “write prohibited” errors. Otherwise,
|
||||
<i>write</i> should attempt to write the <i>r</i><tt><font size=+1>−></font></tt><i>ifcall</i><tt><font size=+1>.</font></tt><i>count</i> bytes of <i>r</i><tt><font size=+1>−></font></tt><i>ifcall</i><tt><font size=+1>.</font></tt><i>data</i>
|
||||
to offset <i>r</i><tt><font size=+1>−></font></tt><i>ifcall</i><tt><font size=+1>.</font></tt><i>offset</i> of the file, setting <i>r</i><tt><font size=+1>−></font></tt><i>ofcall</i><tt><font size=+1>.</font></tt><i>count</i>
|
||||
to the number of bytes actually written. Most
|
||||
|
||||
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
||||
|
||||
programs consider it an error to write less than the requested
|
||||
amount.<br>
|
||||
|
||||
</table>
|
||||
<i>Stat Stat</i> should fill <i>r</i><tt><font size=+1>−></font></tt><i>d</i> with the stat information for <i>r</i><tt><font size=+1>−></font></tt><i>fid</i>.
|
||||
If using file trees, <i>r</i><tt><font size=+1>−></font></tt><i>d</i> will have been initialized with the stat
|
||||
info from the tree, and <i>stat</i> itself may be nil.<br>
|
||||
<i>Wstat</i>The <i>wstat</i> consults <i>r</i><tt><font size=+1>−></font></tt><i>d</i> in changing the metadata for <i>r</i><tt><font size=+1>−></font></tt><i>fid</i>
|
||||
as described in <i>stat</i>(9p). When using file trees, <i>srv</i> will take
|
||||
care to check that the request satisfies the permissions outlined
|
||||
in <i>stat</i>(9p). Otherwise <i>wstat</i> should take care to enforce permissions
|
||||
where appropriate.<br>
|
||||
<i>Flush</i> Single-threaded servers, which always call <i>respond</i> before
|
||||
returning from the service functions, need not provide a <i>flush</i>
|
||||
implementation: <i>flush</i> is only necessary in multithreaded programs,
|
||||
which arrange for <i>respond</i> to be called asynchronously. <i>Flush</i> should
|
||||
cause the request <i>r</i><tt><font size=+1>−></font></tt><i>oldreq</i> to be cancelled or
|
||||
|
||||
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
||||
|
||||
hurried along. If <i>oldreq</i> is cancelled, this should be signalled
|
||||
by calling <i>respond</i> on <i>oldreq</i> with error string ‘<tt><font size=+1>interrupted</font></tt>’.
|
||||
<i>Flush</i> must respond to <i>r</i> with a nil error string. <i>Flush</i> may respond
|
||||
to <i>r</i> before forcing a response to <i>r</i><tt><font size=+1>−></font></tt><i>oldreq</i>. In this case, the
|
||||
library will delay sending the <i>Rflush</i> message until the
|
||||
response to <i>r</i><tt><font size=+1>−></font></tt><i>oldreq</i> has been sent.
|
||||
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
||||
|
||||
|
||||
</table>
|
||||
<i>Destroyfid</i>, <i>destroyreq</i>, and <i>end</i> are auxiliary functions, not called
|
||||
in direct response to 9P requests.<br>
|
||||
<i>Destroyfid<br>
|
||||
</i>
|
||||
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
||||
|
||||
When a <tt><font size=+1>Fid</font></tt>’s reference count drops to zero (<i>i.e.,</i> it has been
|
||||
clunked and there are no outstanding requests referring to it),
|
||||
<i>destroyfid</i> is called to allow the program to dispose of the <i>fid</i><tt><font size=+1>−></font></tt><i>aux</i>
|
||||
pointer.<br>
|
||||
|
||||
</table>
|
||||
<i>Destroyreq<br>
|
||||
</i>
|
||||
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
||||
|
||||
Similarly, when a <tt><font size=+1>Req</font></tt>’s reference count drops to zero (<i>i.e.</i>, it
|
||||
has been handled via <i>respond</i> and other outstanding pointers to
|
||||
it have been closed), <i>destroyreq</i> is called to allow the program
|
||||
to dispose of the <i>r</i><tt><font size=+1>−></font></tt><i>aux</i> pointer.<br>
|
||||
|
||||
</table>
|
||||
<i>End</i> Once the 9P service loop has finished (end of file been reached
|
||||
on the service pipe or a bad message has been read), <i>end</i> is called
|
||||
(if provided) to allow any final cleanup. For example, it was
|
||||
used by the Palm Pilot synchronization file system (never finished)
|
||||
to gracefully terminate the serial conversation once the
|
||||
|
||||
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
||||
|
||||
file system had been unmounted. After calling <i>end</i>, the service
|
||||
loop (which runs in a separate process from its caller) terminates
|
||||
using <i>_exits</i> (see <a href="../man3/exits.html"><i>exits</i>(3)</a>).
|
||||
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
||||
|
||||
|
||||
</table>
|
||||
If the <tt><font size=+1>chatty9p</font></tt> flag is at least one, a transcript of the 9P session
|
||||
is printed on standard error. If the <tt><font size=+1>chatty9p</font></tt> flag is greater
|
||||
than one, additional unspecified debugging output is generated.
|
||||
By convention, servers written using this library accept the <tt><font size=+1>−D</font></tt>
|
||||
option to increment <tt><font size=+1>chatty9p</font></tt>.
|
||||
|
||||
</table>
|
||||
<p><font size=+1><b>EXAMPLES </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/lib9p/ramfs.c</font></tt> is an example of a simple single-threaded
|
||||
file server. On Plan 9, see <i>archfs</i>, <i>cdfs</i>, <i>nntpfs</i>, <i>webfs</i>, and <i>sshnet</i>
|
||||
for more examples.
|
||||
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
||||
|
||||
In general, the <tt><font size=+1>File</font></tt> interface is appropriate for maintaining
|
||||
arbitrary file trees (as in <i>ramfs</i>). The <tt><font size=+1>File</font></tt> interface is best
|
||||
avoided when the tree structure is easily generated as necessary;
|
||||
this is true when the tree is highly structured (as in <i>cdfs</i> and
|
||||
<i>nntpfs</i>) or is maintained elsewhere.<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/lib9p<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="../man3/9p-fid.html"><i>9p-fid</i>(3)</a>, <a href="../man3/9p-file.html"><i>9p-file</i>(3)</a>, <i>intro</i>(9p)<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>
|
||||
Loading…
Add table
Add a link
Reference in a new issue