9P(3)

💅 9P(3) — Library Functions Manual ✨

okay bestie, so this is 9P(3) from Library Functions Manual, and it's literally the whole vibe of how you build a 9P file service. it's a long one so buckle up 🎀

---

🌸 NAME 🌸

Srv, dirread9p, emalloc9p, erealloc9p, estrdup9p, postfd, readbuf, readstr, respond, srv, threadpostmountsrv, walkandclone — 9P file service, i.e. the entire girlboss toolkit for serving files over 9P 💖

---

✨ SYNOPSIS ✨

#include <u.h>
#include <libc.h>
#include <fcall.h>
#include <thread.h>
#include <9p.h>

typedef struct Srv {
    Tree* tree;

    void  (*attach)(Req *r);
    void  (*auth)(Req *r);
    void  (*open)(Req *r);
    void  (*create)(Req *r);
    void  (*read)(Req *r);
    void  (*write)(Req *r);
    void  (*remove)(Req *r);
    void  (*flush)(Req *r);
    void  (*stat)(Req *r);
    void  (*wstat)(Req *r);
    void  (*walk)(Req *r);

    char* (*walk1)(Fid *fid, char *name, Qid *qid);
    char* (*clone)(Fid *oldfid, Fid *newfid);

    void  (*destroyfid)(Fid *fid);
    void  (*destroyreq)(Req *r);
    void  (*start)(Srv *s);
    void  (*end)(Srv *s);
    void* aux;

    int   infd;
    int   outfd;
    int   srvfd;
    int   nopipe;
} Srv;

int   srv(Srv *s)
void  threadpostmountsrv(Srv *s, char *name, char *mtpt, int flag)
int   postfd(char *srvname, int fd)
void  respond(Req *r, char *error)
ulong readstr(Req *r, char *src)
ulong readbuf(Req *r, void *src, ulong nsrc)
typedef int Dirgen(int n, Dir *dir, void *aux)
void  dirread9p(Req *r, Dirgen *gen, void *aux)
void  walkandclone(Req *r, char *(*walk1)(Fid *old, char *name, void *v),
          char *(*clone)(Fid *old, Fid *new, void *v), void *v)

void* emalloc9p(ulong n)
void* erealloc9p(void *v, ulong n)
char* estrdup9p(char *s)

extern int chatty9p;

---

🦋 DESCRIPTION 🦋

so. the function srv serves a whole 9P session. it reads requests from s->infd, dispatches them to the function pointers you stashed in Srv, and writes the responses out to s->outfd. no cap, that's the whole loop. (threadpostmountsrv is typically the one that sets up the infd and outfd struct members for you — more on that below 👇)

Req and Fid structures get allocated one-to-one with uncompleted requests and active fids respectively, and they're described over in 9p-fid(3).

the behavior of srv depends on whether there's a file tree associated with the server (see 9p-file(3)) — that is, on whether the tree element is nonzero. the differences get spelled out explicitly in the discussion of the service loop below. the aux element belongs to the client, to do with as it pleases 🫶

srv does not return until the 9P conversation is finished. and because it's usually run in a separate process so the caller can just exit, the service loop has basically no chance to return gracefully on out-of-memory errors 😭. so it calls emalloc9p, erealloc9p, and estrdup9p to get its memory. the default implementations of these act as malloc, realloc, and strdup — but they abort the program if they run out of memory. if you want different behavior, clients can link against alternate implementations of these functions. your call, bestie.

threadpostmountsrv is the wrapper that creates a separate process in which to run srv. here's the whole routine, step by step:

• if s->nopipe is zero (the common case), initialize s->infd and s->outfd to be one end of a freshly allocated pipe, with s->srvfd initialized as the other end.
• if name is non-nil, call postfd(s->srvfd, name) to post s->srvfd as /srv/name.
• fork a child process via rfork(3) or procrfork (see thread(3)), using the RFFDG, RFNAMEG, and RFMEM flags. the child process calls close(s->srvfd) and then srv(s); it will exit once srv returns.
• if mtpt is non-nil, call amount(s->srvfd, mtpt, flag, ""); otherwise, close s->srvfd.
• the parent returns to the caller.

⚠️ if any error occurs during this process, the entire process is terminated by calling sysfatal(3). like, whole thing. gone. 💀

---

🌈 Service functions 🌈

the functions in a Srv structure named after 9P transactions get called to satisfy requests as they arrive. if you provide one, it must arrange for respond to be called when the request is satisfied. the only parameter of each service function is a Req* (say r). the incoming request parameters live in r->ifcall; r->fid and r->newfid are pointers to Fid structures corresponding to the numeric fids in r->ifcall; similarly, r->oldreq is the Req structure corresponding to r->ifcall.oldtag. outgoing response data should go in r->ofcall.

the one exception to this rule is that stat should fill in r->d rather than r->ofcall.stat — the library will convert the structure into the machine-independent wire representation for you ✨. similarly, wstat may consult r->d rather than decoding r->ifcall.stat itself.

when a request has been handled, respond should be called with r and an error string. if the request was satisfied successfully, the error string should be a nil pointer. note that it's totally permissible for a function to return without itself calling respond, as long as it has arranged for respond to be called at some point in the future by another proc sharing its address space — but see the discussion of flush below. once respond has been called, the Req* as well as any pointers it once contained must be considered freed and not referenced. like, don't touch it. it's gone. 🙈

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. it handles that itself, main character energy.

the service loop provided by srv (and indirectly by threadpostmountsrv) is single-threaded. so if you expect some requests might block, arranging for alternate processes to handle them is suggested 👑

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, srv will call end and then abort. harsh but fair.

• auth — if authentication is desired, the auth function should record that afid is the new authentication fid and set afid->qid and ofcall.qid. auth may be nil, in which case it will be treated as having responded with the error `argv0: authentication not required`, where argv0 is the program name variable as set by ARGBEGIN (see arg(3)).
• attach — the attach function should check the authentication state of afid if desired, and set r->fid->qid and ofcall.qid to the qid of the file system root. attach 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.
• walk — if file trees are in use, walk is handled internally, and srv->walk is never called.

if file trees are not in use, walk should consult r->ifcall.wname and r->ifcall.nwname, filling in ofcall.qid and ofcall.nqid, and also copy any necessary aux state from r->fid to r->newfid when the two are different. as long as walk sets ofcall.nqid appropriately, it can respond with a nil error string even when 9P demands an error (e.g. in the case of a short walk) — the library detects error conditions and handles them appropriately. it's got you 🫶

and because implementing the full walk message is intricate and prone to error, the helper routine walkandclone will handle the request given pointers to two functions walk1 and (optionally) clone. clone, if non-nil, is called to signal the creation of newfid from oldfid. typically a clone routine will copy or increment a reference count in oldfid's aux element. walk1 should walk fid to name, initializing fid->qid to the new path's qid. both should return nil on success or an error message on error. walkandclone will call respond after handling the request.

• walk1, clone — if the client provides functions srv->walk1 and (optionally) srv->clone, the 9P service loop will call walkandclone with these functions to handle the request. unlike the walk1 above, srv->walk1 must fill in both fid->qid and *qid with the new qid on a successful walk.
• open — 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.

if not using file trees, or the user has the appropriate permissions, open is called with r->ofcall.qid already initialized to the one stored in the Fid structure (that is, the one returned in the previous walk). if the qid changes, both should be updated.

• create — the create function must fill in both r->fid->qid and r->ofcall.qid on success. when using file trees, create should allocate a new File with createfile; note that createfile may return nil (because, say, the file already exists 😬). if the create function is nil, srv behaves as though it were a function that always responded with the error `create prohibited`.
• remove — remove should mark the file as removed, whether by calling removefile when using file trees, or by updating an internal data structure. in general it is not a good idea to clean up the aux information associated with the corresponding File at this time, to avoid memory errors if other fids have references to that file. instead, it's suggested that remove 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 aux pointer. if not using file trees, it's prudent to take the analogous measures. if remove is not provided, all remove requests will draw `remove prohibited` errors.

---

...and there's more, bestie, don't go anywhere 🧚

💖 Read

Okay so read is non-negotiable — it must be provided. It’s the function that fills r->ofcall.data with at most r->ifcall.count bytes of data from offset r->ifcall.offset of the file. It also sets r->ofcall.count to the number of bytes being returned. Slay.

If you’re using file trees, srv handles reads of directories internally and only calls read for requests on files. Cute, right?

Readstr and readbuf are your little helpers for satisfying read requests on a string or buffer. They consult the request in r->ifcall, fill r->ofcall.data, and set r->ofcall.count — but they do not call respond, so don’t expect them to send the reply for you. Similarly, dirread9p can handle directory reads in servers that aren’t using file trees. The gen function you pass gets called as necessary to fill dir with information for the nth entry in the directory. The string pointers placed in dir should be fresh copies made with estrdup9p; dirread9p will free them after each successful call to gen. Gen should return zero if it successfully filled dir, and minus one on end of directory. Periodt.

✨ Write

write is similar but optional — it need not be provided. If it isn’t, all writes will draw write prohibited errors. If you do provide it, write should attempt to write the r->ifcall.count bytes of r->ifcall.data to offset r->ifcall.offset of the file, setting r->ofcall.count to the number of bytes actually written.

Heads up: most programs consider it an error to write less than the requested amount. 💀

🌸 Stat

Stat should fill r->d with the stat information for r->fid. If you’re using file trees, r->d will have been initialized with the stat info from the tree, and stat itself may be nil — yes, truly.

🦋 Wstat

wstat consults r->d when changing the metadata for r->fid, exactly as described in stat(9p). When using file trees, srv will take care to check that the request satisfies the permissions outlined in stat(9p). Otherwise, wstat should take care to enforce permissions where appropriate — no passing the buck, bestie.

💅 Flush

Servers that always call respond before returning from the service functions need not provide a flush implementation: flush is only necessary in programs that arrange for respond to be called asynchronously.

Flush should cause the request r->oldreq to be cancelled or hurried along. If oldreq is cancelled, this should be signalled by calling respond on oldreq with the error string interrupted. Flush must respond to r with a nil error string.

Flush may respond to r before forcing a response to r->oldreq. In this case, the library will delay sending the Rflush message until the response to r->oldreq has been sent. Order matters, okay?

Destroyfid, destroyreq, start, and end are auxiliary functions — not called in direct response to 9P requests. They’re the backstage crew.

🧸 Destroyfid

When a Fid’s reference count drops to zero (i.e., it has been clunked and there are no outstanding requests referring to it), destroyfid is called to allow the program to dispose of the fid->aux pointer.

🎀 Destroyreq

Similarly, when a Req’s reference count drops to zero (i.e., it has been handled via respond and other outstanding pointers to it have been closed), destroyreq is called to allow the program to dispose of the r->aux pointer.

🧚 Start

Before the 9P service loop begins, the service proc calls start so that the server can run any initialization that must be done from inside the service proc.

🌈 End

Once the 9P service loop has finished — end of file reached on the service pipe, or a bad message has been read — end 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 file system had been unmounted. After calling end, the service loop (which runs in a separate process from its caller) terminates using _exits (see exits(3)).

If the chatty9p flag is at least one, a transcript of the 9P session is printed on standard error. If the chatty9p flag is greater than one, additional unspecified debugging output is generated. By convention, servers written using this library accept the -D option to increment chatty9p.

✨ EXAMPLES ✨

/src/lib9p/ramfs.c is an example of a simple single-threaded file server. On Plan 9, see archfs, cdfs, nntpfs, webfs, and sshnet for more examples.

In general, the File interface is appropriate for maintaining arbitrary file trees (as in ramfs). The File interface is best avoided when the tree structure is easily generated as necessary; this is true when the tree is highly structured (as in cdfs and nntpfs) or is maintained elsewhere.

🌈 SOURCE 🌈

/src/lib9p — that’s the source, bestie.

💜 SEE ALSO 💜

9p-fid(3), 9p-file(3), intro(9p)

---

Okay that’s the whole 9P(3) page: source /src/lib9p, version/page 9P(3), and the footer date is whatever the footer says — we’re not out here inventing dates in this group chat. Go forth and clunk those fids 💅✨🦋