4 cfa37a7b 2004-04-10 devnull dirread9p,
5 cfa37a7b 2004-04-10 devnull emalloc9p,
6 cfa37a7b 2004-04-10 devnull erealloc9p,
7 cfa37a7b 2004-04-10 devnull estrdup9p,
9 cfa37a7b 2004-04-10 devnull postmountsrv,
14 cfa37a7b 2004-04-10 devnull threadpostmountsrv,
15 058b0118 2005-01-03 devnull walkandclone \- 9P file service
16 cfa37a7b 2004-04-10 devnull .SH SYNOPSIS
19 cfa37a7b 2004-04-10 devnull #include <u.h>
20 cfa37a7b 2004-04-10 devnull #include <libc.h>
21 cfa37a7b 2004-04-10 devnull #include <fcall.h>
22 cfa37a7b 2004-04-10 devnull #include <thread.h>
23 cfa37a7b 2004-04-10 devnull #include <9p.h>
28 cfa37a7b 2004-04-10 devnull .ta \w'\fL1234'u +\w'\fLTree* 'u
29 cfa37a7b 2004-04-10 devnull typedef struct Srv {
30 cfa37a7b 2004-04-10 devnull Tree* tree;
32 cfa37a7b 2004-04-10 devnull void (*attach)(Req *r);
33 cfa37a7b 2004-04-10 devnull void (*auth)(Req *r);
34 cfa37a7b 2004-04-10 devnull void (*open)(Req *r);
35 cfa37a7b 2004-04-10 devnull void (*create)(Req *r);
36 cfa37a7b 2004-04-10 devnull void (*read)(Req *r);
37 cfa37a7b 2004-04-10 devnull void (*write)(Req *r);
38 cfa37a7b 2004-04-10 devnull void (*remove)(Req *r);
39 cfa37a7b 2004-04-10 devnull void (*flush)(Req *r);
40 cfa37a7b 2004-04-10 devnull void (*stat)(Req *r);
41 cfa37a7b 2004-04-10 devnull void (*wstat)(Req *r);
42 cfa37a7b 2004-04-10 devnull void (*walk)(Req *r);
44 cfa37a7b 2004-04-10 devnull char* (*walk1)(Fid *fid, char *name, Qid *qid);
45 cfa37a7b 2004-04-10 devnull char* (*clone)(Fid *oldfid, Fid *newfid);
47 cfa37a7b 2004-04-10 devnull void (*destroyfid)(Fid *fid);
48 cfa37a7b 2004-04-10 devnull void (*destroyreq)(Req *r);
49 d93fca6a 2005-02-11 devnull void (*start)(Srv *s);
50 cfa37a7b 2004-04-10 devnull void (*end)(Srv *s);
51 cfa37a7b 2004-04-10 devnull void* aux;
53 cfa37a7b 2004-04-10 devnull int infd;
54 cfa37a7b 2004-04-10 devnull int outfd;
55 cfa37a7b 2004-04-10 devnull int srvfd;
56 cfa37a7b 2004-04-10 devnull int nopipe;
62 cfa37a7b 2004-04-10 devnull .ta \w'\fLvoid* 'u
63 cfa37a7b 2004-04-10 devnull int srv(Srv *s)
64 cfa37a7b 2004-04-10 devnull void postmountsrv(Srv *s, char *name, char *mtpt, int flag)
65 cfa37a7b 2004-04-10 devnull void threadpostmountsrv(Srv *s, char *name, char *mtpt, int flag)
66 cfa37a7b 2004-04-10 devnull int postfd(char *srvname, int fd)
67 cfa37a7b 2004-04-10 devnull void respond(Req *r, char *error)
68 cfa37a7b 2004-04-10 devnull ulong readstr(Req *r, char *src)
69 cfa37a7b 2004-04-10 devnull ulong readbuf(Req *r, void *src, ulong nsrc)
70 cfa37a7b 2004-04-10 devnull typedef int Dirgen(int n, Dir *dir, void *aux)
71 cfa37a7b 2004-04-10 devnull void dirread9p(Req *r, Dirgen *gen, void *aux)
72 cfa37a7b 2004-04-10 devnull void walkandclone(Req *r, char *(*walk1)(Fid *old, char *name, void *v),
73 cfa37a7b 2004-04-10 devnull char *(*clone)(Fid *old, Fid *new, void *v), void *v)
78 cfa37a7b 2004-04-10 devnull .ta \w'\fLvoid* 'u
79 cfa37a7b 2004-04-10 devnull void* emalloc9p(ulong n)
80 cfa37a7b 2004-04-10 devnull void* erealloc9p(void *v, ulong n)
81 cfa37a7b 2004-04-10 devnull char* estrdup9p(char *s)
86 cfa37a7b 2004-04-10 devnull extern int chatty9p;
88 cfa37a7b 2004-04-10 devnull .SH DESCRIPTION
89 cfa37a7b 2004-04-10 devnull The function
91 cfa37a7b 2004-04-10 devnull serves a 9P session by reading requests from
92 cfa37a7b 2004-04-10 devnull .BR s->infd ,
93 cfa37a7b 2004-04-10 devnull dispatching them to the function pointers kept in
94 cfa37a7b 2004-04-10 devnull .BR Srv ,
96 cfa37a7b 2004-04-10 devnull writing the responses to
97 cfa37a7b 2004-04-10 devnull .BR s->outfd .
98 cfa37a7b 2004-04-10 devnull (Typically,
99 cfa37a7b 2004-04-10 devnull .I postmountsrv
101 cfa37a7b 2004-04-10 devnull .I threadpostmountsrv
102 cfa37a7b 2004-04-10 devnull initializes the
105 cfa37a7b 2004-04-10 devnull .B outfd
106 cfa37a7b 2004-04-10 devnull structure members. See the description below.)
111 cfa37a7b 2004-04-10 devnull structures are allocated one-to-one with uncompleted
112 cfa37a7b 2004-04-10 devnull requests and active fids, and are described in
113 c8b6342d 2005-01-13 devnull .IR 9p-fid (3).
115 cfa37a7b 2004-04-10 devnull The behavior of
117 cfa37a7b 2004-04-10 devnull depends on whether there is a file tree
119 c8b6342d 2005-01-13 devnull .IR 9p-file (3))
120 cfa37a7b 2004-04-10 devnull associated with the server, that is,
121 cfa37a7b 2004-04-10 devnull whether the
123 cfa37a7b 2004-04-10 devnull element is nonzero.
124 cfa37a7b 2004-04-10 devnull The differences are made explicit in the
125 cfa37a7b 2004-04-10 devnull discussion of the service loop below.
128 cfa37a7b 2004-04-10 devnull element is the client's, to do with as it pleases.
131 cfa37a7b 2004-04-10 devnull does not return until the 9P conversation is finished.
132 cfa37a7b 2004-04-10 devnull Since it is usually run in a separate process so that
133 cfa37a7b 2004-04-10 devnull the caller can exit, the service loop has little chance
134 cfa37a7b 2004-04-10 devnull to return gracefully on out of memory errors.
135 cfa37a7b 2004-04-10 devnull It calls
136 cfa37a7b 2004-04-10 devnull .IR emalloc9p ,
137 cfa37a7b 2004-04-10 devnull .IR erealloc9p ,
139 cfa37a7b 2004-04-10 devnull .I estrdup9p
140 cfa37a7b 2004-04-10 devnull to obtain its memory.
141 cfa37a7b 2004-04-10 devnull The default implementations of these functions
143 cfa37a7b 2004-04-10 devnull .IR malloc ,
144 cfa37a7b 2004-04-10 devnull .IR realloc ,
146 cfa37a7b 2004-04-10 devnull .I strdup
147 cfa37a7b 2004-04-10 devnull but abort the program if they run out of memory.
148 cfa37a7b 2004-04-10 devnull If alternate behavior is desired, clients can link against
149 cfa37a7b 2004-04-10 devnull alternate implementations of these functions.
151 cfa37a7b 2004-04-10 devnull .I Postmountsrv
153 cfa37a7b 2004-04-10 devnull .I threadpostmountsrv
154 cfa37a7b 2004-04-10 devnull are wrappers that create a separate process in which to run
155 cfa37a7b 2004-04-10 devnull .IR srv .
156 cfa37a7b 2004-04-10 devnull They do the following:
159 cfa37a7b 2004-04-10 devnull .IB s -> nopipe
160 cfa37a7b 2004-04-10 devnull is zero (the common case),
161 cfa37a7b 2004-04-10 devnull initialize
162 cfa37a7b 2004-04-10 devnull .IB s -> infd
164 cfa37a7b 2004-04-10 devnull .IB s -> outfd
165 cfa37a7b 2004-04-10 devnull to be one end of a freshly allocated pipe,
167 cfa37a7b 2004-04-10 devnull .IB s -> srvfd
168 cfa37a7b 2004-04-10 devnull initialized as the other end.
172 cfa37a7b 2004-04-10 devnull is non-nil, call
173 cfa37a7b 2004-04-10 devnull .BI postfd( s -> srvfd ,
174 cfa37a7b 2004-04-10 devnull .IB name )
176 cfa37a7b 2004-04-10 devnull .IB s -> srvfd
178 cfa37a7b 2004-04-10 devnull .BI /srv/ name .
180 cfa37a7b 2004-04-10 devnull Fork a child process via
181 058b0118 2005-01-03 devnull .IR rfork (3)
183 cfa37a7b 2004-04-10 devnull .I procrfork
185 bf8a59fa 2004-04-11 devnull .IR thread (3)),
186 cfa37a7b 2004-04-10 devnull using the
187 cfa37a7b 2004-04-10 devnull .BR RFFDG ,
188 cfa37a7b 2004-04-10 devnull .RR RFNOTEG ,
189 cfa37a7b 2004-04-10 devnull .BR RFNAMEG ,
191 cfa37a7b 2004-04-10 devnull .BR RFMEM
193 cfa37a7b 2004-04-10 devnull The child process
195 cfa37a7b 2004-04-10 devnull .IB close( s -> srvfd )
196 cfa37a7b 2004-04-10 devnull and then
197 cfa37a7b 2004-04-10 devnull .IB srv( s ) \fR;
198 cfa37a7b 2004-04-10 devnull it will exit once
200 cfa37a7b 2004-04-10 devnull returns.
204 cfa37a7b 2004-04-10 devnull is non-nil,
206 cfa37a7b 2004-04-10 devnull .BI amount( s -> srvfd,
207 cfa37a7b 2004-04-10 devnull .IB mtpt ,
208 cfa37a7b 2004-04-10 devnull .IB flag ,
209 cfa37a7b 2004-04-10 devnull \fB"")\fR;
210 cfa37a7b 2004-04-10 devnull otherwise, close
211 cfa37a7b 2004-04-10 devnull .IB s -> srvfd \fR.
213 cfa37a7b 2004-04-10 devnull The parent returns to the caller.
215 cfa37a7b 2004-04-10 devnull If any error occurs during
216 cfa37a7b 2004-04-10 devnull this process, the entire process is terminated by calling
217 058b0118 2005-01-03 devnull .IR sysfatal (3).
218 cfa37a7b 2004-04-10 devnull .SS Service functions
219 cfa37a7b 2004-04-10 devnull The functions in a
221 cfa37a7b 2004-04-10 devnull structure named after 9P transactions
222 cfa37a7b 2004-04-10 devnull are called to satisfy requests as they arrive.
223 cfa37a7b 2004-04-10 devnull If a function is provided, it
225 cfa37a7b 2004-04-10 devnull arrange for
226 cfa37a7b 2004-04-10 devnull .I respond
227 cfa37a7b 2004-04-10 devnull to be called when the request is satisfied.
228 cfa37a7b 2004-04-10 devnull The only parameter of each service function
231 cfa37a7b 2004-04-10 devnull parameter (say
232 cfa37a7b 2004-04-10 devnull .IR r ).
233 cfa37a7b 2004-04-10 devnull The incoming request parameters are stored in
234 cfa37a7b 2004-04-10 devnull .IB r -> ifcall \fR;
235 cfa37a7b 2004-04-10 devnull .IB r -> fid
237 cfa37a7b 2004-04-10 devnull .IB r -> newfid
238 cfa37a7b 2004-04-10 devnull are pointers to
240 cfa37a7b 2004-04-10 devnull structures corresponding to the
241 cfa37a7b 2004-04-10 devnull numeric fids in
242 cfa37a7b 2004-04-10 devnull .IB r -> ifcall \fR;
243 cfa37a7b 2004-04-10 devnull similarly,
244 cfa37a7b 2004-04-10 devnull .IB r -> oldreq
247 cfa37a7b 2004-04-10 devnull structure corresponding to
248 cfa37a7b 2004-04-10 devnull .IB r -> ifcall.oldtag \fR.
249 cfa37a7b 2004-04-10 devnull The outgoing response data should be stored in
250 cfa37a7b 2004-04-10 devnull .IB r -> ofcall \fR.
251 cfa37a7b 2004-04-10 devnull The one exception to this rule is that
253 cfa37a7b 2004-04-10 devnull should fill in
254 cfa37a7b 2004-04-10 devnull .IB r -> d
255 cfa37a7b 2004-04-10 devnull rather than
256 cfa37a7b 2004-04-10 devnull .IB r -> ofcall.stat \fR:
257 cfa37a7b 2004-04-10 devnull the library will convert the structure into the machine-independent
258 cfa37a7b 2004-04-10 devnull wire representation.
259 cfa37a7b 2004-04-10 devnull Similarly,
260 cfa37a7b 2004-04-10 devnull .I wstat
261 cfa37a7b 2004-04-10 devnull may consult
262 cfa37a7b 2004-04-10 devnull .IB r -> d
263 cfa37a7b 2004-04-10 devnull rather than decoding
264 cfa37a7b 2004-04-10 devnull .IB r -> ifcall . stat
266 cfa37a7b 2004-04-10 devnull When a request has been handled,
267 cfa37a7b 2004-04-10 devnull .I respond
268 cfa37a7b 2004-04-10 devnull should be called with
270 cfa37a7b 2004-04-10 devnull and an error string.
271 cfa37a7b 2004-04-10 devnull If the request was satisfied successfully, the error
272 cfa37a7b 2004-04-10 devnull string should be a nil pointer.
273 cfa37a7b 2004-04-10 devnull Note that it is permissible for a function to return
274 cfa37a7b 2004-04-10 devnull without itself calling
275 cfa37a7b 2004-04-10 devnull .IR respond ,
276 cfa37a7b 2004-04-10 devnull as long as it has arranged for
277 cfa37a7b 2004-04-10 devnull .I respond
278 cfa37a7b 2004-04-10 devnull to be called at some point in the future
279 cfa37a7b 2004-04-10 devnull by another proc sharing its address space,
280 cfa37a7b 2004-04-10 devnull but see the discussion of
281 cfa37a7b 2004-04-10 devnull .I flush
284 cfa37a7b 2004-04-10 devnull .I respond
285 cfa37a7b 2004-04-10 devnull has been called, the
287 cfa37a7b 2004-04-10 devnull as well as any pointers it once contained must
288 cfa37a7b 2004-04-10 devnull be considered freed and not referenced.
290 cfa37a7b 2004-04-10 devnull If the service loop detects an error in a request
291 cfa37a7b 2004-04-10 devnull (e.g., an attempt to reuse an extant fid, an open of
292 cfa37a7b 2004-04-10 devnull an already open fid, a read from a fid opened for write, etc.)
293 cfa37a7b 2004-04-10 devnull it will reply with an error without consulting
294 cfa37a7b 2004-04-10 devnull the service functions.
296 cfa37a7b 2004-04-10 devnull The service loop provided by
298 cfa37a7b 2004-04-10 devnull (and indirectly by
299 cfa37a7b 2004-04-10 devnull .I postmountsrv
301 cfa37a7b 2004-04-10 devnull .IR threadpostmountsrv )
302 cfa37a7b 2004-04-10 devnull is single-threaded.
303 cfa37a7b 2004-04-10 devnull If it is expected that some requests might
304 cfa37a7b 2004-04-10 devnull block, arranging for alternate processes
305 cfa37a7b 2004-04-10 devnull to handle them is suggested.
307 cfa37a7b 2004-04-10 devnull The constraints on the service functions are as follows.
308 cfa37a7b 2004-04-10 devnull These constraints are checked while the server executes.
309 cfa37a7b 2004-04-10 devnull If a service function fails to do something it ought to have,
311 cfa37a7b 2004-04-10 devnull will call
313 cfa37a7b 2004-04-10 devnull and then abort.
316 cfa37a7b 2004-04-10 devnull If authentication is desired,
319 cfa37a7b 2004-04-10 devnull function should record that
321 cfa37a7b 2004-04-10 devnull is the new authentication fid and
323 cfa37a7b 2004-04-10 devnull .I afid->qid
325 cfa37a7b 2004-04-10 devnull .IR ofcall.qid .
327 cfa37a7b 2004-04-10 devnull may be nil, in which case it will be treated as having
328 cfa37a7b 2004-04-10 devnull responded with the error
329 cfa37a7b 2004-04-10 devnull .RI `` "argv0: authentication not required" ,''
331 cfa37a7b 2004-04-10 devnull .I argv0
332 cfa37a7b 2004-04-10 devnull is the program name variable as set by
333 cfa37a7b 2004-04-10 devnull .I ARGBEGIN
335 bf8a59fa 2004-04-11 devnull .IR arg (3)).
337 cfa37a7b 2004-04-10 devnull .I Attach
339 cfa37a7b 2004-04-10 devnull .I attach
340 cfa37a7b 2004-04-10 devnull function should check the authentication state of
342 cfa37a7b 2004-04-10 devnull if desired,
344 cfa37a7b 2004-04-10 devnull .IB r -> fid -> qid
346 cfa37a7b 2004-04-10 devnull .I ofcall.qid
347 cfa37a7b 2004-04-10 devnull to the qid of the file system root.
348 cfa37a7b 2004-04-10 devnull .I Attach
349 cfa37a7b 2004-04-10 devnull may be nil only if file trees are in use;
350 cfa37a7b 2004-04-10 devnull in this case, the qid will be filled from the root
351 cfa37a7b 2004-04-10 devnull of the tree, and no authentication will be done.
354 cfa37a7b 2004-04-10 devnull If file trees are in use,
356 cfa37a7b 2004-04-10 devnull is handled internally, and
357 cfa37a7b 2004-04-10 devnull .IB srv -> walk
358 cfa37a7b 2004-04-10 devnull is never called.
360 cfa37a7b 2004-04-10 devnull If file trees are not in use,
362 cfa37a7b 2004-04-10 devnull should consult
363 cfa37a7b 2004-04-10 devnull .IB r -> ifcall . wname
365 cfa37a7b 2004-04-10 devnull .IB r -> ifcall . nwname \fR,
366 cfa37a7b 2004-04-10 devnull filling in
367 cfa37a7b 2004-04-10 devnull .IB ofcall . qid
369 cfa37a7b 2004-04-10 devnull .IB ofcall . nqid \fR,
370 cfa37a7b 2004-04-10 devnull and also copying any necessary
372 cfa37a7b 2004-04-10 devnull state from
373 cfa37a7b 2004-04-10 devnull .IB r -> fid
375 cfa37a7b 2004-04-10 devnull .IB r -> newfid
376 cfa37a7b 2004-04-10 devnull when the two are different.
377 cfa37a7b 2004-04-10 devnull As long as
380 cfa37a7b 2004-04-10 devnull .IB ofcall . nqid
381 cfa37a7b 2004-04-10 devnull appropriately, it can
382 cfa37a7b 2004-04-10 devnull .I respond
383 cfa37a7b 2004-04-10 devnull with a nil error string even when 9P
384 cfa37a7b 2004-04-10 devnull demands an error
385 cfa37a7b 2004-04-10 devnull .RI ( e.g. ,
386 cfa37a7b 2004-04-10 devnull in the case of a short walk);
387 cfa37a7b 2004-04-10 devnull the library detects error conditions and handles them appropriately.
389 cfa37a7b 2004-04-10 devnull Because implementing the full walk message is intricate and
390 cfa37a7b 2004-04-10 devnull prone to error, the helper routine
391 cfa37a7b 2004-04-10 devnull .I walkandclone
392 cfa37a7b 2004-04-10 devnull will handle the request given pointers to two functions
393 cfa37a7b 2004-04-10 devnull .I walk1
394 cfa37a7b 2004-04-10 devnull and (optionally)
395 cfa37a7b 2004-04-10 devnull .I clone .
396 cfa37a7b 2004-04-10 devnull .IR Clone ,
397 cfa37a7b 2004-04-10 devnull if non-nil, is called to signal the creation of
398 cfa37a7b 2004-04-10 devnull .I newfid
400 cfa37a7b 2004-04-10 devnull .IR oldfid .
401 cfa37a7b 2004-04-10 devnull Typically a
402 cfa37a7b 2004-04-10 devnull .I clone
403 cfa37a7b 2004-04-10 devnull routine will copy or increment a reference count in
404 cfa37a7b 2004-04-10 devnull .IR oldfid 's
406 cfa37a7b 2004-04-10 devnull element.
407 cfa37a7b 2004-04-10 devnull .I Walk1
408 cfa37a7b 2004-04-10 devnull should walk
411 cfa37a7b 2004-04-10 devnull .IR name ,
412 cfa37a7b 2004-04-10 devnull initializing
413 cfa37a7b 2004-04-10 devnull .IB fid -> qid
414 cfa37a7b 2004-04-10 devnull to the new path's qid.
415 cfa37a7b 2004-04-10 devnull Both should return nil
416 cfa37a7b 2004-04-10 devnull on success or an error message on error.
417 cfa37a7b 2004-04-10 devnull .I Walkandclone
418 cfa37a7b 2004-04-10 devnull will call
419 cfa37a7b 2004-04-10 devnull .I respond
420 cfa37a7b 2004-04-10 devnull after handling the request.
422 cfa37a7b 2004-04-10 devnull .I Walk1\fR, \fPClone
423 cfa37a7b 2004-04-10 devnull If the client provides functions
424 cfa37a7b 2004-04-10 devnull .IB srv -> walk1
425 cfa37a7b 2004-04-10 devnull and (optionally)
426 cfa37a7b 2004-04-10 devnull .IB srv -> clone \fR,
427 cfa37a7b 2004-04-10 devnull the 9P service loop will call
428 cfa37a7b 2004-04-10 devnull .I walkandclone
429 cfa37a7b 2004-04-10 devnull with these functions to handle the request.
430 cfa37a7b 2004-04-10 devnull Unlike the
431 cfa37a7b 2004-04-10 devnull .I walk1
433 cfa37a7b 2004-04-10 devnull .IB srv -> walk1
434 cfa37a7b 2004-04-10 devnull must fill in both
435 cfa37a7b 2004-04-10 devnull .IB fid -> qid
437 cfa37a7b 2004-04-10 devnull .BI * qid
438 cfa37a7b 2004-04-10 devnull with the new qid on a successful walk.
441 cfa37a7b 2004-04-10 devnull If file trees are in use, the file
442 cfa37a7b 2004-04-10 devnull metadata will be consulted on open, create, remove, and wstat
443 cfa37a7b 2004-04-10 devnull to see if the requester has the appropriate permissions.
444 cfa37a7b 2004-04-10 devnull If not, an error will be sent back without consulting a service function.
446 cfa37a7b 2004-04-10 devnull If not using file trees or the user has the appropriate permissions,
448 cfa37a7b 2004-04-10 devnull is called with
449 cfa37a7b 2004-04-10 devnull .IB r -> ofcall . qid
450 cfa37a7b 2004-04-10 devnull already initialized to the one stored in the
452 cfa37a7b 2004-04-10 devnull structure (that is, the one returned in the previous walk).
453 cfa37a7b 2004-04-10 devnull If the qid changes, both should be updated.
455 cfa37a7b 2004-04-10 devnull .I Create
457 cfa37a7b 2004-04-10 devnull .I create
458 cfa37a7b 2004-04-10 devnull function must fill in
460 cfa37a7b 2004-04-10 devnull .IB r -> fid -> qid
462 cfa37a7b 2004-04-10 devnull .IB r -> ofcall . qid
463 cfa37a7b 2004-04-10 devnull on success.
464 cfa37a7b 2004-04-10 devnull When using file trees,
465 cfa37a7b 2004-04-10 devnull .I create
466 cfa37a7b 2004-04-10 devnull should allocate a new
469 cfa37a7b 2004-04-10 devnull .IR createfile ;
470 cfa37a7b 2004-04-10 devnull note that
471 cfa37a7b 2004-04-10 devnull .I createfile
472 cfa37a7b 2004-04-10 devnull may return nil (because, say, the file already exists).
474 cfa37a7b 2004-04-10 devnull .I create
475 cfa37a7b 2004-04-10 devnull function is nil,
477 cfa37a7b 2004-04-10 devnull behaves as though it were a function that always responded
478 cfa37a7b 2004-04-10 devnull with the error ``create prohibited''.
480 cfa37a7b 2004-04-10 devnull .I Remove
481 cfa37a7b 2004-04-10 devnull .I Remove
482 cfa37a7b 2004-04-10 devnull should mark the file as removed, whether
483 cfa37a7b 2004-04-10 devnull by calling
484 cfa37a7b 2004-04-10 devnull .I removefile
485 cfa37a7b 2004-04-10 devnull when using file trees, or by updating an internal data structure.
486 cfa37a7b 2004-04-10 devnull In general it is not a good idea to clean up the
488 cfa37a7b 2004-04-10 devnull information associated with the corresponding
490 cfa37a7b 2004-04-10 devnull at this time, to avoid memory errors if other
491 cfa37a7b 2004-04-10 devnull fids have references to that file.
492 cfa37a7b 2004-04-10 devnull Instead, it is suggested that
493 cfa37a7b 2004-04-10 devnull .I remove
494 cfa37a7b 2004-04-10 devnull simply mark the file as removed (so that further
495 cfa37a7b 2004-04-10 devnull operations on it know to fail) and wait until the
496 cfa37a7b 2004-04-10 devnull file tree's destroy function is called to reclaim the
498 cfa37a7b 2004-04-10 devnull pointer.
499 cfa37a7b 2004-04-10 devnull If not using file trees, it is prudent to take the
500 cfa37a7b 2004-04-10 devnull analogous measures.
502 cfa37a7b 2004-04-10 devnull .I remove
503 cfa37a7b 2004-04-10 devnull is not provided, all remove requests will draw
504 cfa37a7b 2004-04-10 devnull ``remove prohibited'' errors.
509 cfa37a7b 2004-04-10 devnull function must be provided; it fills
510 cfa37a7b 2004-04-10 devnull .IB r -> ofcall . data
511 cfa37a7b 2004-04-10 devnull with at most
512 cfa37a7b 2004-04-10 devnull .IB r -> ifcall . count
513 cfa37a7b 2004-04-10 devnull bytes of data from offset
514 cfa37a7b 2004-04-10 devnull .IB r -> ifcall . offset
515 cfa37a7b 2004-04-10 devnull of the file.
516 cfa37a7b 2004-04-10 devnull It also sets
517 cfa37a7b 2004-04-10 devnull .IB r -> ofcall . count
518 cfa37a7b 2004-04-10 devnull to the number of bytes being returned.
519 cfa37a7b 2004-04-10 devnull If using file trees,
521 cfa37a7b 2004-04-10 devnull will handle reads of directories internally, only
524 cfa37a7b 2004-04-10 devnull for requests on files.
525 cfa37a7b 2004-04-10 devnull .I Readstr
527 cfa37a7b 2004-04-10 devnull .I readbuf
528 cfa37a7b 2004-04-10 devnull are useful for satisfying read requests on a string or buffer.
529 cfa37a7b 2004-04-10 devnull Consulting the request in
530 cfa37a7b 2004-04-10 devnull .IB r -> ifcall \fR,
531 cfa37a7b 2004-04-10 devnull they fill
532 cfa37a7b 2004-04-10 devnull .IB r -> ofcall . data
534 cfa37a7b 2004-04-10 devnull .IB r -> ofcall . count \fR;
535 cfa37a7b 2004-04-10 devnull they do not call
536 cfa37a7b 2004-04-10 devnull .IB respond .
537 cfa37a7b 2004-04-10 devnull Similarly,
538 cfa37a7b 2004-04-10 devnull .I dirread9p
539 cfa37a7b 2004-04-10 devnull can be used to handle directory reads in servers
540 cfa37a7b 2004-04-10 devnull not using file trees.
541 cfa37a7b 2004-04-10 devnull The passed
543 cfa37a7b 2004-04-10 devnull function will be called as necessary to
546 cfa37a7b 2004-04-10 devnull with information for the
547 cfa37a7b 2004-04-10 devnull .IR n th
548 cfa37a7b 2004-04-10 devnull entry in the directory.
549 cfa37a7b 2004-04-10 devnull The string pointers placed in
551 cfa37a7b 2004-04-10 devnull should be fresh copies
552 cfa37a7b 2004-04-10 devnull made with
553 cfa37a7b 2004-04-10 devnull .IR estrdup9p ;
554 cfa37a7b 2004-04-10 devnull they will be freed by
555 cfa37a7b 2004-04-10 devnull .I dirread9p
556 cfa37a7b 2004-04-10 devnull after each successful call to
557 cfa37a7b 2004-04-10 devnull .IR gen .
559 cfa37a7b 2004-04-10 devnull should return zero if it successfully filled
560 cfa37a7b 2004-04-10 devnull .IR dir ,
561 cfa37a7b 2004-04-10 devnull minus one on end of directory.
563 cfa37a7b 2004-04-10 devnull .I Write
565 cfa37a7b 2004-04-10 devnull .I write
566 cfa37a7b 2004-04-10 devnull function is similar but need not be provided.
567 cfa37a7b 2004-04-10 devnull If it is not, all writes will draw
568 cfa37a7b 2004-04-10 devnull ``write prohibited'' errors.
569 cfa37a7b 2004-04-10 devnull Otherwise,
570 cfa37a7b 2004-04-10 devnull .I write
571 cfa37a7b 2004-04-10 devnull should attempt to write the
572 cfa37a7b 2004-04-10 devnull .IB r -> ifcall . count
573 cfa37a7b 2004-04-10 devnull bytes of
574 cfa37a7b 2004-04-10 devnull .IB r -> ifcall . data
575 cfa37a7b 2004-04-10 devnull to offset
576 cfa37a7b 2004-04-10 devnull .IB r -> ifcall . offset
577 cfa37a7b 2004-04-10 devnull of the file, setting
578 cfa37a7b 2004-04-10 devnull .IB r -> ofcall . count
579 cfa37a7b 2004-04-10 devnull to the number of bytes actually written.
580 cfa37a7b 2004-04-10 devnull Most programs consider it an error to
581 cfa37a7b 2004-04-10 devnull write less than the requested amount.
585 cfa37a7b 2004-04-10 devnull should fill
586 cfa37a7b 2004-04-10 devnull .IB r -> d
587 cfa37a7b 2004-04-10 devnull with the stat information for
588 cfa37a7b 2004-04-10 devnull .IB r -> fid \fR.
589 cfa37a7b 2004-04-10 devnull If using file trees,
590 cfa37a7b 2004-04-10 devnull .IB r -> d
591 cfa37a7b 2004-04-10 devnull will have been initialized with the stat info from
592 cfa37a7b 2004-04-10 devnull the tree, and
594 cfa37a7b 2004-04-10 devnull itself may be nil.
596 cfa37a7b 2004-04-10 devnull .I Wstat
598 cfa37a7b 2004-04-10 devnull .I wstat
599 cfa37a7b 2004-04-10 devnull consults
600 cfa37a7b 2004-04-10 devnull .IB r -> d
601 cfa37a7b 2004-04-10 devnull in changing the metadata for
602 cfa37a7b 2004-04-10 devnull .IB r -> fid
603 cfa37a7b 2004-04-10 devnull as described in
604 058b0118 2005-01-03 devnull .IR stat (9p).
605 cfa37a7b 2004-04-10 devnull When using file trees,
607 cfa37a7b 2004-04-10 devnull will take care to check that the request satisfies
608 cfa37a7b 2004-04-10 devnull the permissions outlined in
609 058b0118 2005-01-03 devnull .IR stat (9p).
610 cfa37a7b 2004-04-10 devnull Otherwise
611 cfa37a7b 2004-04-10 devnull .I wstat
612 cfa37a7b 2004-04-10 devnull should take care to enforce permissions
613 cfa37a7b 2004-04-10 devnull where appropriate.
615 cfa37a7b 2004-04-10 devnull .I Flush
616 cfa37a7b 2004-04-10 devnull Single-threaded servers, which always call
617 cfa37a7b 2004-04-10 devnull .I respond
618 cfa37a7b 2004-04-10 devnull before returning from the service functions,
619 cfa37a7b 2004-04-10 devnull need not provide a
620 cfa37a7b 2004-04-10 devnull .I flush
621 cfa37a7b 2004-04-10 devnull implementation:
622 cfa37a7b 2004-04-10 devnull .I flush
623 cfa37a7b 2004-04-10 devnull is only necessary in multithreaded programs,
624 cfa37a7b 2004-04-10 devnull which arrange for
625 cfa37a7b 2004-04-10 devnull .I respond
626 cfa37a7b 2004-04-10 devnull to be called asynchronously.
627 cfa37a7b 2004-04-10 devnull .I Flush
628 cfa37a7b 2004-04-10 devnull should cause the request
629 cfa37a7b 2004-04-10 devnull .IB r -> oldreq
630 cfa37a7b 2004-04-10 devnull to be cancelled or hurried along.
632 cfa37a7b 2004-04-10 devnull .I oldreq
633 cfa37a7b 2004-04-10 devnull is cancelled, this should be signalled by calling
634 cfa37a7b 2004-04-10 devnull .I respond
636 cfa37a7b 2004-04-10 devnull .I oldreq
637 cfa37a7b 2004-04-10 devnull with error string
638 cfa37a7b 2004-04-10 devnull .RB ` interrupted '.
639 cfa37a7b 2004-04-10 devnull .I Flush
640 cfa37a7b 2004-04-10 devnull must respond to
642 cfa37a7b 2004-04-10 devnull with a nil error string.
643 cfa37a7b 2004-04-10 devnull .I Flush
644 cfa37a7b 2004-04-10 devnull may respond to
646 cfa37a7b 2004-04-10 devnull before forcing a response to
647 cfa37a7b 2004-04-10 devnull .IB r -> oldreq \fR.
648 cfa37a7b 2004-04-10 devnull In this case, the library will delay sending
650 cfa37a7b 2004-04-10 devnull .I Rflush
651 cfa37a7b 2004-04-10 devnull message until the response to
652 cfa37a7b 2004-04-10 devnull .IB r -> oldreq
653 cfa37a7b 2004-04-10 devnull has been sent.
656 cfa37a7b 2004-04-10 devnull .IR Destroyfid ,
657 cfa37a7b 2004-04-10 devnull .IR destroyreq ,
658 d93fca6a 2005-02-11 devnull .IR start ,
661 cfa37a7b 2004-04-10 devnull are auxiliary functions, not called in direct response to 9P requests.
663 cfa37a7b 2004-04-10 devnull .I Destroyfid
665 cfa37a7b 2004-04-10 devnull .BR Fid 's
666 cfa37a7b 2004-04-10 devnull reference count drops to zero
667 cfa37a7b 2004-04-10 devnull .RI ( i.e.,
668 cfa37a7b 2004-04-10 devnull it has been clunked and there are no outstanding
669 cfa37a7b 2004-04-10 devnull requests referring to it),
670 cfa37a7b 2004-04-10 devnull .I destroyfid
671 cfa37a7b 2004-04-10 devnull is called to allow the program to dispose
673 cfa37a7b 2004-04-10 devnull .IB fid -> aux
674 cfa37a7b 2004-04-10 devnull pointer.
676 cfa37a7b 2004-04-10 devnull .I Destroyreq
677 cfa37a7b 2004-04-10 devnull Similarly, when a
678 cfa37a7b 2004-04-10 devnull .BR Req 's
679 cfa37a7b 2004-04-10 devnull reference count drops to zero
680 cfa37a7b 2004-04-10 devnull .RI ( i.e. ,
681 cfa37a7b 2004-04-10 devnull it has been handled via
682 cfa37a7b 2004-04-10 devnull .I respond
683 cfa37a7b 2004-04-10 devnull and other outstanding pointers to it have been closed),
684 cfa37a7b 2004-04-10 devnull .I destroyreq
685 cfa37a7b 2004-04-10 devnull is called to allow the program to dispose of the
686 cfa37a7b 2004-04-10 devnull .IB r -> aux
687 cfa37a7b 2004-04-10 devnull pointer.
689 d93fca6a 2005-02-11 devnull .I Start
690 d93fca6a 2005-02-11 devnull Before the 9P service loop begins, the service proc calls
691 d93fca6a 2005-02-11 devnull .I start
692 d93fca6a 2005-02-11 devnull so that the server can run any initialization that must be
693 d93fca6a 2005-02-11 devnull done from inside the service proc.
696 cfa37a7b 2004-04-10 devnull Once the 9P service loop has finished
697 cfa37a7b 2004-04-10 devnull (end of file been reached on the service pipe
698 cfa37a7b 2004-04-10 devnull or a bad message has been read),
700 cfa37a7b 2004-04-10 devnull is called (if provided) to allow any final cleanup.
701 cfa37a7b 2004-04-10 devnull For example, it was used by the Palm Pilot synchronization
702 cfa37a7b 2004-04-10 devnull file system (never finished) to gracefully terminate the serial conversation once
703 cfa37a7b 2004-04-10 devnull the file system had been unmounted.
704 cfa37a7b 2004-04-10 devnull After calling
705 cfa37a7b 2004-04-10 devnull .IR end ,
706 cfa37a7b 2004-04-10 devnull the service loop (which runs in a separate process
707 cfa37a7b 2004-04-10 devnull from its caller) terminates using
708 cfa37a7b 2004-04-10 devnull .I _exits
710 bf8a59fa 2004-04-11 devnull .IR exits (3)).
714 cfa37a7b 2004-04-10 devnull .B chatty9p
715 cfa37a7b 2004-04-10 devnull flag is at least one,
716 cfa37a7b 2004-04-10 devnull a transcript of the 9P session is printed
717 cfa37a7b 2004-04-10 devnull on standard error.
719 cfa37a7b 2004-04-10 devnull .B chatty9p
720 cfa37a7b 2004-04-10 devnull flag is greater than one,
721 cfa37a7b 2004-04-10 devnull additional unspecified debugging output is generated.
722 cfa37a7b 2004-04-10 devnull By convention, servers written using this library
723 cfa37a7b 2004-04-10 devnull accept the
725 cfa37a7b 2004-04-10 devnull option to increment
726 cfa37a7b 2004-04-10 devnull .BR chatty9p .
727 cfa37a7b 2004-04-10 devnull .SH EXAMPLES
728 c8b6342d 2005-01-13 devnull .B \*9/src/lib9p/ramfs.c
729 c8b6342d 2005-01-13 devnull is an example of a simple single-threaded file server.
730 058b0118 2005-01-03 devnull On Plan 9, see
731 058b0118 2005-01-03 devnull .IR archfs ,
732 058b0118 2005-01-03 devnull .IR cdfs ,
733 058b0118 2005-01-03 devnull .IR nntpfs ,
734 058b0118 2005-01-03 devnull .IR webfs ,
736 cfa37a7b 2004-04-10 devnull .I sshnet
737 058b0118 2005-01-03 devnull for more examples.
739 cfa37a7b 2004-04-10 devnull In general, the
741 cfa37a7b 2004-04-10 devnull interface is appropriate for maintaining arbitrary file trees (as in
742 cfa37a7b 2004-04-10 devnull .IR ramfs ).
745 cfa37a7b 2004-04-10 devnull interface is best avoided when the
746 cfa37a7b 2004-04-10 devnull tree structure is easily generated as necessary;
747 cfa37a7b 2004-04-10 devnull this is true when the tree is highly structured (as in
750 cfa37a7b 2004-04-10 devnull .IR nntpfs )
751 cfa37a7b 2004-04-10 devnull or is maintained elsewhere.
752 cfa37a7b 2004-04-10 devnull .SH SOURCE
753 c3674de4 2005-01-11 devnull .B \*9/src/lib9p
754 cfa37a7b 2004-04-10 devnull .SH SEE ALSO
755 c8b6342d 2005-01-13 devnull .IR 9p-fid (3),
756 c8b6342d 2005-01-13 devnull .IR 9p-file (3),
757 058b0118 2005-01-03 devnull .IR intro (9p)
