Subversion Repositories planix.SVN

.TH FCALL 2

.SH NAME

Fcall, convS2M, convD2M, convM2S, convM2D, fcallfmt, dirfmt, dirmodefmt, read9pmsg, statcheck, sizeS2M, sizeD2M \- interface to Plan 9 File protocol

.SH SYNOPSIS

.B #include <u.h>

.br

.B #include <libc.h>

.br

.br

.B #include <fcall.h>

.PP

.B

uint convS2M(Fcall *f, uchar *ap, uint nap)

.PP

.B

uint convD2M(Dir *d, uchar *ap, uint nap)

.PP

.B

uint convM2S(uchar *ap, uint nap, Fcall *f)

.PP

.B

uint convM2D(uchar *ap, uint nap, Dir *d, char *strs)

.PP

.B

int dirfmt(Fmt*)

.PP

.B

int fcallfmt(Fmt*)

.PP

.B

int dirmodefmt(Fmt*)

.PP

.B

int read9pmsg(int fd, uchar *buf, uint nbuf)

.PP

.B

int statcheck(uchar *buf, uint nbuf)

.PP

.B

uint sizeS2M(Fcall *f)

.PP

.B

uint sizeD2M(Dir *d)

.SH DESCRIPTION

These

routines convert messages in the machine-independent format of

the Plan 9 file protocol,

9P, to and from a more convenient form,

an

.B Fcall

structure:

.PP

.EX

.if n .ta 4n +6n +5n +6n +18n +4n

.if t .ta \w'xxxx'u +\w'short 'u +\w'xxxx'u +\w'ushort 'u +\w'ticket[TICKETLEN]; 'u +\w'/* 'u

#define MAXWELEM 16

typedef

struct Fcall

{

	uchar	type;

	u32int	fid;

	ushort	tag;

	union {

		struct {

			u32int	msize;	/* Tversion, Rversion */

			char	*version;	/* Tversion, Rversion */

		};

		struct {

			ushort	oldtag;	/* Tflush */

		};

		struct {

			char	*ename;	/* Rerror */

		};

		struct {

			Qid	qid;	/* Rattach, Ropen, Rcreate */

			u32int	iounit;	/* Ropen, Rcreate */

		};

		struct {

			Qid	aqid;	/* Rauth */

		};

		struct {

			u32int	afid;	/* Tauth, Tattach */

			char	*uname;	/* Tauth, Tattach */

			char	*aname;	/* Tauth, Tattach */

		};

		struct {

			u32int	perm;	/* Tcreate */ 

			char	*name;	/* Tcreate */

			uchar	mode;	/* Tcreate, Topen */

		};

		struct {

			u32int	newfid;	/* Twalk */

			ushort	nwname;	/* Twalk */

			char	*wname[MAXWELEM];	/* Twalk */

		};

		struct {

			ushort	nwqid;	/* Rwalk */

			Qid	wqid[MAXWELEM];	/* Rwalk */

		};

		struct {

			vlong	offset;	/* Tread, Twrite */

			u32int	count;	/* Tread, Twrite, Rread */

			char	*data;	/* Twrite, Rread */

		};

		struct {

			ushort	nstat;	/* Twstat, Rstat */

			uchar	*stat;	/* Twstat, Rstat */

		};

	};

} Fcall;

.EE

.EX

/* these are implemented as macros */

uchar	GBIT8(uchar*)

ushort	GBIT16(uchar*)

ulong	GBIT32(uchar*)

vlong	GBIT64(uchar*)

void	PBIT8(uchar*, uchar)

void	PBIT16(uchar*, ushort)

void	PBIT32(uchar*, ulong)

void	PBIT64(uchar*, vlong)

#define	BIT8SZ	1

#define	BIT16SZ	2

#define	BIT32SZ	4

#define	BIT64SZ	8

.EE

.PP

This structure is defined in

.BR <fcall.h> .

See section 5

for a full description of 9P messages and their encoding.

For all message types, the

.B type

field of an

.B Fcall

holds one of

.BR Tversion ,

.BR Rversion ,

.BR Tattach ,

.BR Rattach ,

etc. (defined in an enumerated type in

.BR <fcall.h> ).

.B Fid

is used by most messages, and

.B tag

is used by all messages.

The other fields are used selectively by the message types

given in comments.

.PP

.I ConvM2S

takes a 9P message at

.I ap

of length

.IR nap ,

and uses it to fill in

.B Fcall

structure

.IR f .

If the passed message

including any data for

.B Twrite

and

.B Rread

messages

is formatted properly,

the return value is the number of bytes the message occupied in the buffer

.IR ap ,

which will always be less than or equal to

.IR nap ;

otherwise it is 0.

For

.B Twrite

and

.B Tread

messages,

.B data

is set to a pointer into the argument message,

not a copy.

.PP

.I ConvS2M

does the reverse conversion, turning

.I f

into a message starting at

.IR ap .

The length of the resulting message is returned.

For

.B Twrite

and

.B Rread

messages,

.B count

bytes starting at

.B data

are copied into the message.

.PP

The constant

.B IOHDRSZ

is a suitable amount of buffer to reserve for storing

the 9P header;

the data portion of a

.B Twrite

or

.B Rread

will be no more than the buffer size negotiated in the

.BR Tversion/Rversion

exchange, minus

.BR IOHDRSZ .

.PP

The routine

.I sizeS2M

returns the number of bytes required to store the machine-independent representation of the

.B Fcall

structure

.IR f ,

including its initial 32-bit size field.

In other words, it reports the number of bytes produced

by a successful call to

.IR convS2M .

.PP

Another structure is

.BR Dir ,

used by the routines described in

.IR stat (2).

.I ConvM2D

converts the machine-independent form starting at

.I ap

into

.IR d

and returns the length of the machine-independent encoding.

The strings in the returned

.B Dir

structure are stored at successive locations starting at

.BR strs .

Usually

.B strs

will point to storage immediately after the

.B Dir

itself.

It can also be a

.B nil

pointer, in which case the string pointers in the returned

.B Dir

are all

.BR nil ;

however, the return value still includes their length.

.PP

.I ConvD2M

does the reverse translation,

also returning the length of the encoding.

If the buffer is too short, the return value will be

.B BIT16SZ

and the correct size will be returned in the first

.B BIT16SZ

bytes.

(If the buffer is less that

.BR BIT16SZ ,

the return value is zero; therefore a correct test for

complete packing of the message is that the return value is

greater than

.BR BIT16SZ ).

The macro

.B GBIT16

can be used to extract the correct value.

The related macros with different sizes retrieve the corresponding-sized quantities.

.B PBIT16

and its brethren place values in messages.

With the exception of handling short buffers in

.IR convD2M ,

these macros are not usually needed except by internal routines.

.PP

Analogous to

.IR sizeS2M ,

.I sizeD2M

returns the number of bytes required to store the machine-independent representation of the

.B Dir

structure

.IR d ,

including its initial 16-bit size field.

.PP

The routine

.B statcheck

checks whether the

.I nbuf

bytes of

.I buf

contain a validly formatted machine-independent

.B Dir

entry suitable as an argument, for example, for the

.B wstat

(see

.IR stat (2))

system call.

It checks that the sizes of all the elements of the the entry sum to exactly

.IR nbuf ,

which is a simple but effective test of validity.

.I Nbuf

and

.I buf

should include the second two-byte (16-bit) length field that precedes the entry when

formatted in a 9P message (see

.IR stat (5));

in other words,

.I nbuf

is 2 plus the sum of the sizes of the entry itself.

.I Statcheck

also verifies that the length field has the correct value (that is,

.IB nbuf -2\f1).

It returns

.B 0

for a valid entry and

.B -1

for an incorrectly formatted entry.

.PP

.IR Dirfmt ,

.IR fcallfmt ,

and

.I dirmodefmt

are formatting routines, suitable for

.IR fmtinstall (2).

They convert

.BR Dir* ,

.BR Fcall* ,

and

.BR long

values into string representations of the directory buffer,

.B Fcall

buffer,

or file mode value.

.I Fcallfmt

assumes that

.I dirfmt

has been installed with format letter

.L D

and

.I dirmodefmt

with format letter

.LR M .

.PP

.I Read9pmsg

calls

.IR read (2)

multiple times, if necessary, to read an entire 9P message into

.BR buf .

The return value is 0 for end of file, or -1 for error; it does not return

partial messages.

.SH SOURCE

.B /sys/src/libc/9sys

.SH SEE ALSO

.IR intro (2),

.IR 9p (2),

.IR stat (2),

.IR intro (5)