Subversion Repositories planix.SVN

.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)