208 lines
3.6 KiB
Text
208 lines
3.6 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'\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;
|
||
|
|
\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)
|