aboutsummaryrefslogtreecommitdiff
path: root/man/man3/9pfid.3
diff options
context:
space:
mode:
Diffstat (limited to 'man/man3/9pfid.3')
-rw-r--r--man/man3/9pfid.3204
1 files changed, 204 insertions, 0 deletions
diff --git a/man/man3/9pfid.3 b/man/man3/9pfid.3
new file mode 100644
index 00000000..ac0f2bfc
--- /dev/null
+++ b/man/man3/9pfid.3
@@ -0,0 +1,204 @@
+.TH 9PFID 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 <u.h>
+#include <libc.h>
+#include <fcall.h>
+#include <thread.h>
+#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 (2).
+.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 9pfile (2))
+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 /sys/src/lib9p
+.SH SEE ALSO
+.IR 9p (2),
+.IR 9pfile (2)