2321062d2f
This struct member is available for any user of the library, and is not part of our internal API. It should be documented.
219 lines
3.7 KiB
Text
219 lines
3.7 KiB
Text
.TH 9PFID 2
|
|
.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'\fLuvlong 'u
|
|
typedef struct Qid
|
|
{
|
|
uvlong path;
|
|
ulong vers;
|
|
uchar type;
|
|
} Qid;
|
|
.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;
|
|
Fid *fid;
|
|
Fid *afid;
|
|
Fid *newfid;
|
|
Srv *srv;
|
|
\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)
|
|
Fid* removefid(Fidpool *p, ulong fid);
|
|
void closefid(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)
|
|
Req* removereq(Reqpool *p, ulong tag);
|
|
void closereq(Req *f)
|
|
.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 lookupfid
|
|
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)
|