From 3940506bccddeff3235cd8874c540813a3deaf6d Mon Sep 17 00:00:00 2001 From: rsc Date: Thu, 13 Jan 2005 04:56:07 +0000 Subject: forgotten files --- man/man1/9.1 | 19 +++++ man/man3/9p-cmdbuf.3 | 119 +++++++++++++++++++++++++++ man/man3/9p-fid.3 | 204 ++++++++++++++++++++++++++++++++++++++++++++++ man/man3/9p-file.3 | 223 +++++++++++++++++++++++++++++++++++++++++++++++++++ man/man3/9p-intmap.3 | 126 +++++++++++++++++++++++++++++ 5 files changed, 691 insertions(+) create mode 100644 man/man1/9.1 create mode 100644 man/man3/9p-cmdbuf.3 create mode 100644 man/man3/9p-fid.3 create mode 100644 man/man3/9p-file.3 create mode 100644 man/man3/9p-intmap.3 (limited to 'man') diff --git a/man/man1/9.1 b/man/man1/9.1 new file mode 100644 index 00000000..d590f3b3 --- /dev/null +++ b/man/man1/9.1 @@ -0,0 +1,19 @@ +.TH 9 1 +.SH NAME +9 \- run Plan 9 commands +.SH SYNOPSIS +.B . +.B 9 +.PP +.B 9 +.I cmd +[ +.I args +\&... +] +.SH DESCRIPTION +XXX +.SH SOURCE +.B \*9/bin/9 +.SH SEE ALSO +.IR intro (1) diff --git a/man/man3/9p-cmdbuf.3 b/man/man3/9p-cmdbuf.3 new file mode 100644 index 00000000..6aca825b --- /dev/null +++ b/man/man3/9p-cmdbuf.3 @@ -0,0 +1,119 @@ +.TH 9P-CMDBUF 3 +.SH NAME +Cmdbuf, parsecmd, respondcmderror, lookupcmd \- control message parsing +.SH SYNOPSIS +.ft L +.nf +#include +#include +#include +#include +#include <9p.h> +.fi +.PP +.ft L +.nf +.ta \w'\fL1234'u +\w'\fL12345678'u +typedef struct Cmdbuf +{ + char *buf; + char **f; + int nf; +} Cmdbuf; + +typedef struct Cmdtab +{ + int index; + char *cmd; + int narg; +}; + +Cmdbuf *parsecmd(char *p, int n) +Cmdtab *lookupcmd(Cmdbuf *cb, Cmdtab *tab, int ntab) +void respondcmderror(Req *r, Cmdbuf *cb, char *fmt, ...) +.fi +.SH DESCRIPTION +These data structures and functions provide parsing of textual control messages. +.PP +.I Parsecmd +treats the +.I n +bytes at +.I p +(which need not be NUL-terminated) as a UTF string and splits it +using +.I tokenize +(see +.IR getfields (3)). +It returns a +.B Cmdbuf +structure holding pointers to each field in the message. +.PP +.I Lookupcmd +walks through the array +.IR ctab , +which has +.I ntab +entries, +looking for the first +.B Cmdtab +that matches the parsed command. +(If the parsed command is empty, +.I lookupcmd +returns nil immediately.) +A +.B Cmdtab +matches the command if +.I cmd +is equal to +.IB cb -> f [0] +or if +.I cmd +is +.LR * . +Once a matching +.B Cmdtab +has been found, if +.I narg +is not zero, then the parsed command +must have exactly +.I narg +fields (including the command string itself). +If the command has the wrong number of arguments, +.I lookupcmd +returns nil. +Otherwise, it returns a pointer to the +.B Cmdtab +entry. +If +.I lookupcmd +does not find a matching command at all, +it returns nil. +Whenever +.I lookupcmd +returns nil, it sets the system error string. +.PP +.I Respondcmderror +resoponds to request +.I r +with an error of the form +`\fIfmt\fB:\fI cmd\fR,' +where +.I fmt +is the formatted string and +.I cmd +is a reconstruction of the parsed command. +Fmt +is often simply +.B "%r" . +.SH EXAMPLES +This interface is not used in any distributed 9P servers. +It was lifted from the Plan 9 kernel. +Almost any Plan 9 kernel driver +.RB ( /sys/src/9/*/dev*.c +on Plan 9) +is a good example. +.SH SOURCE +.B \*9/src/lib9p/parse.c +.SH SEE ALSO +.IR 9p (3) diff --git a/man/man3/9p-fid.3 b/man/man3/9p-fid.3 new file mode 100644 index 00000000..ddc3e093 --- /dev/null +++ b/man/man3/9p-fid.3 @@ -0,0 +1,204 @@ +.TH 9P-FID 3 +.SH NAME +Fid, Fidpool, allocfidpool, freefidpool, allocfid, closefid, lookupfid, removefid, +Req, Reqpool, allocreqpool, freereqpool, allocreq, closereq, lookupreq, removereq \- 9P fid, request tracking +.SH SYNOPSIS +.ft L +.nf +#include +#include +#include +#include +#include <9p.h> +.fi +.PP +.ft L +.nf +.ta \w'\fL 'u +\w'\fLulong 'u +typedef struct Fid +{ + ulong fid; + char omode; /* -1 if not open */ + char *uid; + Qid qid; + File *file; + void *aux; + \fI...\fP +} Fid; +.fi +.PP +.ft L +.nf +.ta \w'\fL 'u +\w'\fLulong 'u +typedef struct Req +{ + ulong tag; + Fcall ifcall; + Fcall ofcall; + Req *oldreq; + void *aux; + \fI...\fP +} Req; +.fi +.PP +.ft L +.nf +.ta \w'\fLFidpool* 'u +Fidpool* allocfidpool(void (*destroy)(Fid*)) +void freefidpool(Fidpool *p) +Fid* allocfid(Fidpool *p, ulong fid) +Fid* lookupfid(Fidpool *p, ulong fid) +void closefid(Fid *f) +void removefid(Fid *f) +.fi +.PP +.ft L +.nf +.ta \w'\fLReqpool* 'u +Reqpool* allocreqpool(void (*destroy)(Req*)) +void freereqpool(Reqpool *p) +Req* allocreq(Reqpool *p, ulong tag) +Req* lookupreq(Reqpool *p, ulong tag) +void closereq(Req *f) +void removereq(Req *r) +.fi +.SH DESCRIPTION +These routines provide management of +.B Fid +and +.B Req +structures from +.BR Fidpool s +and +.BR Reqpool s. +They are primarily used by the 9P server loop +described in +.IR 9p (3). +.PP +.B Fid +structures are intended to represent +active fids in a 9P connection, as +.B Chan +structures do in the Plan 9 kernel. +The +.B fid +element is the integer fid used in the 9P +connection. +.B Omode +is the mode under which the fid was opened, or +.B -1 +if this fid has not been opened yet. +Note that in addition to the values +.BR OREAD , +.BR OWRITE , +and +.BR ORDWR , +.B omode +can contain the various flags permissible in +an open call. +To ignore the flags, use +.BR omode&OMASK . +.B Omode +should not be changed by the client. +The fid derives from a successful authentication by +.BR uid . +.B Qid +contains the qid returned in the last successful +.B walk +or +.B create +transaction involving the fid. +In a file tree-based server, the +.BR Fid 's +.B file +element points at a +.B File +structure +(see +.IR 9p-file (3)) +corresponding to the fid. +The +.B aux +member is intended for use by the +client to hold information specific to a particular +.BR Fid . +With the exception of +.BR aux , +these elements should be treated +as read-only by the client. +.PP +.I Allocfidpool +creates a new +.BR Fidpool . +.I Freefidpool +destroys such a pool. +.I Allocfid +returns a new +.B Fid +whose fid number is +.IR fid . +There must not already be an extant +.B Fid +with that number in the pool. +Once a +.B Fid +has been allocated, it can be looked up by +fid number using +.IR lookupfid . +.BR Fid s +are reference counted: both +.I allocfid +and +.I lookupfid +increment the reference count on the +.B Fid +structure before +returning. +When a reference to a +.B Fid +is no longer needed, +.I closefid +should be called to note the destruction of the reference. +When the last reference to a +.B Fid +is removed, if +.I destroy +(supplied when creating the fid pool) +is not zero, it is called with the +.B Fid +as a parameter. +It should perform whatever cleanup is necessary +regarding the +.B aux +element. +.I Removefid +is equivalent to +.I closefid +but also removes the +.B Fid +from the pool. +Note that due to lingering references, +the return of +.I removefid +may not mean that +.I destroy +has been called. +.PP +.IR Allocreqpool , +.IR freereqpool , +.IR allocreq , +.IR lookupreq , +.IR closereq , +and +.I removereq +are analogous but +operate on +.BR Reqpool s +and +.B Req +structures. +.SH SOURCE +.B \*9/src/lib9p +.SH SEE ALSO +.IR 9p (3), +.IR 9p-file (3) diff --git a/man/man3/9p-file.3 b/man/man3/9p-file.3 new file mode 100644 index 00000000..80866177 --- /dev/null +++ b/man/man3/9p-file.3 @@ -0,0 +1,223 @@ +.TH 9P-FILE 3 +.SH NAME +Tree, alloctree, freetree, +File, createfile, closefile, removefile, walkfile, +opendirfile, readdirfile, closedirfile, hasperm \- in-memory file hierarchy +.SH SYNOPSIS +.ft L +.nf +#include +#include +#include +#include +#include <9p.h> +.fi +.PP +.ft L +.nf +.ta \w'\fLFile 'u +typedef struct File +{ + Ref; + Dir; + void *aux; + \fI...\fP +} File; +.fi +.PP +.ft L +.nf +.ta \w'\fLTree 'u +typedef struct Tree +{ + File *root; + \fI...\fP +} Tree; +.fi +.PP +.ft L +.nf +.ta \w'\fLReaddir* 'u +4n +4n +Tree* alloctree(char *uid, char *gid, ulong mode, + void (*destroy)(File*)) +void freetree(Tree *tree) +File* createfile(File *dir, char *name, char *uid, + ulong mode, void *aux) +int removefile(File *file) +void closefile(File *file) +File* walkfile(File *dir, char *path) +Readdir* opendirfile(File *dir) +long readdirfile(Readdir *rdir, char *buf, long n) +void closedirfile(Readdir *rdir) +int hasperm(File *file, char *uid, int p) +.fi +.SH DESCRIPTION +.BR File s +and +.BR Tree s +provide an in-memory file hierarchy +intended for use in 9P file servers. +.PP +.I Alloctree +creates a new tree of files, and +.I freetree +destroys it. +The root of the tree +(also the +.B root +element in the structure) +will have mode +.I mode +and be owned by user +.I uid +and group +.IR gid . +.I Destroy +is used when freeing +.B File +structures and is described later. +.PP +.BR File s +(including directories) +other than the root are created using +.IR createfile , +which attempts to create a file named +.I name +in the directory +.IR dir . +If created, the file will have owner +.I uid +and have a group inherited from +the directory. +.I Mode +and the permissions of +.I dir +are used to calculate the permission bits for +the file as described in +.IR open (9p). +It is permissible for +.I name +to be a slash-separated path rather than a single element. +.PP +.I Removefile +removes a file from the file tree. +The file will not be freed until the last +reference to it has been removed. +Directories may only be removed when empty. +.I Removefile +returns zero on success, \-1 on error. +It is correct to consider +.I removefile +to be +.I closefile +with the side effect of removing the file +when possible. +.PP +.I Walkfile +evaluates +.I path +relative to the directory +.IR dir , +returning the resulting file, +or zero if the named file or any intermediate element +does not exist. +.PP +The +.B File +structure's +.B aux +pointer may be used by the client +for +.RB per- File +storage. +.BR File s +are reference-counted: if not zero, +.I destroy +(specified in the call to +.IR alloctree ) +will be called for each file when its +last reference is removed or when the tree is freed. +.I Destroy +should take care of any necessary cleanup related to +.BR aux . +When creating new file references by copying pointers, +call +.I incref +(see +.IR lock (3)) +to update the reference count. +To note the removal of a reference to a file, call +.IR closefile . +.I Createfile +and +.I walkfile +return new references. +.IR Removefile , +.IR closefile , +and +.I walkfile +(but not +.IR createfile ) +consume the passed reference. +.PP +Directories may be read, yielding a directory entry structure +(see +.IR stat (9p)) +for each file in the directory. +In order to allow concurrent reading of directories, +clients must obtain a +.B Readdir +structure by calling +.I opendirfile +on a directory. +Subsequent calls to +.I readdirfile +will each yield an integral number of machine-independent +stat buffers, until end of directory. +When finished, call +.I closedirfile +to free the +.BR Readdir . +.PP +.I Hasperm +does simplistic permission checking; it assumes only +one-user groups named by uid and returns non-zero if +.I uid +has permission +.I p +(a bitwise-or of +.BR AREAD , +.BR AWRITE +and +.BR AEXEC ) +according to +.IB file ->mode \fR. +9P servers written using +.B File +trees will do standard permission checks automatically; +.I hasperm +may be called explicitly to do additional checks. +A 9P server may link against a different +.I hasperm +implementation to provide more complex groups. +.SH EXAMPLE +The following code correctly handles references +when elementwise walking a path and creating a file. +.IP +.EX +f = tree->root; +incref(f); +for(i=0; i +#include +#include +#include +#include <9p.h> +.fi +.PP +.ft L +.nf +.ta \w'\fLIntmap* 'u +Intmap* allocmap(void (*inc)(void*)) +void freemap(Intmap *map, void (*dec)(void*)) +void* lookupkey(Intmap *map, ulong key) +void* insertkey(Intmap *map, ulong key, void *val) +int caninsertkey(Intmap *map, ulong key, void *val) +void* lookupkey(Intmap *map, ulong key) +void* deletekey(Intmap *map, ulong key) +.fi +.SH DESCRIPTION +An +.B Intmap +is an arbitrary mapping from integers to pointers. +.I Allocmap +creates a new map, and +.I freemap +destroys it. +The +.I inc +function is called each time a new pointer is added +to the map; similarly, +.I dec +is called on each pointer left in the map +when it is being freed. +Typically these functions maintain reference counts. +New entries are added to the map by calling +.IR insertkey , +which will return the previous value +associated with the given +.IR key , +or zero if there was no previous value. +.I Caninsertkey +is like +.I insertkey +but only inserts +.I val +if there is no current mapping. +It returns 1 if +.I val +was inserted, 0 otherwise. +.I Lookupkey +returns the pointer associated with +.IR key , +or zero if there is no such pointer. +.I Deletekey +removes the entry for +.I id +from the map, returning the +associated pointer, if any. +.PP +Concurrent access to +.BR Intmap s +is safe, +moderated via a +.B QLock +stored in the +.B Intmap +structure. +.PP +In anticipation of the storage of reference-counted +structures, an increment function +.I inc +may be specified +at map creation time. +.I Lookupkey +calls +.I inc +(if non-zero) +on pointers before returning them. +If the reference count adjustments were +left to the caller (and thus not protected by the lock), +it would be possible to accidentally reclaim a structure +if, for example, it was deleted from the map and its +reference count decremented between the return +of +.I insertkey +and the external increment. +.IR Insertkey +and +.IR caninsertkey +do +.I not +call +.I inc +when inserting +.I val +into the map, nor do +.I insertkey +or +.I deletekey +call +.I inc +when returning old map entries. +The rationale is that calling +an insertion function transfers responsibility for the reference +to the map, and responsibility is given back via the return value of +.I deletekey +or the next +.IR insertkey . +.PP +.BR Intmap s +are used by the 9P library to implement +.BR Fidpool s +and +.BR Reqpool s. +.SH SOURCE +.B \*9/src/lib9p/intmap.c +.SH SEE ALSO +.IR 9p (3), +.IR 9p-fid (3) -- cgit v1.2.3