Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
FCALL(3)		   Library Functions Manual		      FCALL(3)

NAME
       Fcall,  convS2M,	 convD2M,  convM2S, convM2D, fcallfmt, dirfmt, dirmod-
       efmt, read9pmsg,	statcheck, sizeS2M, sizeD2M - interface	to Plan	9 File
       protocol

SYNOPSIS
       #include	<u.h>
       #include	<libc.h>
       #include	<fcall.h>

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

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

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

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

       int dirfmt(Fmt*)

       int fcallfmt(Fmt*)

       int dirmodefmt(Fmt*)

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

       int statcheck(uchar *buf, uint nbuf)

       uint sizeS2M(Fcall *f)

       uint sizeD2M(Dir	*d)

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
       Fcall structure:

       #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;

       /* 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

       This  structure	is defined in <fcall.h>.  See section 5	for a full de-
       scription of 9P messages	and their encoding.  For  all  message	types,
       the  type  field	 of an Fcall holds one of Tversion, Rversion, Tattach,
       Rattach,	etc. (defined in an enumerated type  in	 <fcall.h>).   Fid  is
       used  by	 most  messages,  and  tag is used by all messages.  The other
       fields are used selectively by the message types	given in comments.

       ConvM2S takes a 9P message at ap	of length nap, and uses	it to fill  in
       Fcall structure f.  If the passed message including any data for	Twrite
       and Rread messages is formatted properly, the return value is the  num-
       ber  of	bytes the message occupied in the buffer ap, which will	always
       be less than or equal to	nap; otherwise it is 0.	 For Twrite and	 Tread
       messages,  data	is  set	 to a pointer into the argument	message, not a
       copy.

       ConvS2M does the	reverse	conversion, turning f into a message  starting
       at  ap.	 The  length of	the resulting message is returned.  For	Twrite
       and Rread messages, count bytes starting	at data	are  copied  into  the
       message.

       The  constant  IOHDRSZ  is  a  suitable amount of buffer	to reserve for
       storing the 9P header; the data portion of a Twrite or Rread will be no
       more than the buffer size negotiated in the Tversion/Rversion exchange,
       minus IOHDRSZ.

       The routine sizeS2M returns the number of bytes required	to  store  the
       machine-independent  representation of the Fcall	structure f, including
       its initial 32-bit size field.  In other	words, it reports  the	number
       of bytes	produced by a successful call to convS2M.

       Another	structure  is  Dir,  used by the routines described in ConvM2D
       converts	the machine-independent	form starting at ap into d and returns
       the length of the machine-independent encoding.	The strings in the re-
       turned Dir structure are	stored at  successive  locations  starting  at
       strs.  Usually strs will	point to storage immediately after the Dir it-
       self.  It can also be a nil pointer, in which case the string  pointers
       in  the	returned  Dir are all nil; however, the	return value still in-
       cludes their length.

       ConvD2M does the	reverse	translation, also returning the	length of  the
       encoding.  If the buffer	is too short, the return value will be BIT16SZ
       and the correct size will be returned in	the first BIT16SZ bytes.   (If
       the  buffer is less that	BIT16SZ, the return value is zero; therefore a
       correct test for	complete packing of the	message	 is  that  the	return
       value  is  greater  than	BIT16SZ).  The macro GBIT16 can	be used	to ex-
       tract the correct value.	 The related macros with different  sizes  re-
       trieve  the  corresponding-sized	 quantities.   PBIT16 and its brethren
       place values in messages.  With the exception of	handling short buffers
       in convD2M, these macros	are not	usually	needed except by internal rou-
       tines.

       Analogous to sizeS2M, sizeD2M returns the number	of bytes  required  to
       store  the  machine-independent	representation of the Dir structure d,
       including its initial 16-bit size field.

       The routine statcheck checks whether the	nbuf bytes of  buf  contain  a
       validly	formatted  machine-independent	Dir entry suitable as an argu-
       ment, for example, for the wstat	(see system call.  It checks that  the
       sizes  of  all the elements of the the entry sum	to exactly nbuf, which
       is a simple but effective test of validity.  Nbuf and  buf  should  in-
       clude the second	two-byte (16-bit) length field that precedes the entry
       when formatted in a 9P message (see stat(9p)); in other words, nbuf  is
       2  plus the sum of the sizes of the entry itself.  Statcheck also veri-
       fies that the length field has the correct value	(that is, nbuf-2).  It
       returns 0 for a valid entry and -1 for an incorrectly formatted entry.

       Dirfmt,	fcallfmt, and dirmodefmt are formatting	routines, suitable for
       They convert Dir*, Fcall*, and long values into string  representations
       of  the	directory  buffer, Fcall buffer, or file mode value.  Fcallfmt
       assumes that dirfmt has been installed with format letter  and  dirmod-
       efmt with format	letter

       Read9pmsg calls multiple	times, if necessary, to	read an	entire 9P mes-
       sage into buf.  The return value	is 0 for end of	file, or -1 for	error;
       it does not return partial messages.

SOURCE
       /src/lib9

SEE ALSO
       intro(9p)

								      FCALL(3)

NAME | SYNOPSIS | DESCRIPTION | SOURCE | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=fcall&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help