10564b1175
groff 1.23.0 added .MR to its -man macro package. The NEWS file states
that the inclusion of the macro "was prompted by its introduction to
Plan 9 from User Space's troff in August 2020." From d32deab it seems
that the name for Plan 9 from User Space's implementation was suggested
by groff maintainer G. Brandon Robinson.
Not sure if the intention was to make these definitions compatible, but
it would be nice if they were.
Currently, Plan 9 from User Space's .MR expects its second argument to
be parenthesized. groff's .MR does not. This results in extra
parentheses appearing in manual references when viewing Plan 9 from User
Space's manual pages on a system using groff.
205 lines
3.5 KiB
Groff
205 lines
3.5 KiB
Groff
.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 <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
|
|
.MR 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
|
|
.MR 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
|
|
.MR 9p 3 ,
|
|
.MR 9p-file 3
|