diff options
Diffstat (limited to 'man/man3/fcall.html')
| -rw-r--r-- | man/man3/fcall.html | 274 |
1 files changed, 0 insertions, 274 deletions
diff --git a/man/man3/fcall.html b/man/man3/fcall.html deleted file mode 100644 index 926b47dc..00000000 --- a/man/man3/fcall.html +++ /dev/null @@ -1,274 +0,0 @@ -<head> -<title>fcall(3) - Plan 9 from User Space</title> -<meta content="text/html; charset=utf-8" http-equiv=Content-Type> -</head> -<body bgcolor=#ffffff> -<table border=0 cellpadding=0 cellspacing=0 width=100%> -<tr height=10><td> -<tr><td width=20><td> -<tr><td width=20><td><b>FCALL(3)</b><td align=right><b>FCALL(3)</b> -<tr><td width=20><td colspan=2> - <br> -<p><font size=+1><b>NAME </b></font><br> - -<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> - - Fcall, convS2M, convD2M, convM2S, convM2D, fcallfmt, dirfmt, dirmodefmt, - read9pmsg, statcheck, sizeS2M, sizeD2M – interface to Plan 9 File - protocol<br> - -</table> -<p><font size=+1><b>SYNOPSIS </b></font><br> - -<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> - - <tt><font size=+1>#include <u.h><br> - #include <libc.h><br> - #include <fcall.h> - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - </font></tt> - <tt><font size=+1>uint convS2M(Fcall *f, uchar *ap, uint nap) - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - </font></tt> - <tt><font size=+1>uint convD2M(Dir *d, uchar *ap, uint nap) - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - </font></tt> - <tt><font size=+1>uint convM2S(uchar *ap, uint nap, Fcall *f) - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - </font></tt> - <tt><font size=+1>uint convM2D(uchar *ap, uint nap, Dir *d, char *strs) - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - </font></tt> - <tt><font size=+1>int dirfmt(Fmt*) - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - </font></tt> - <tt><font size=+1>int fcallfmt(Fmt*) - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - </font></tt> - <tt><font size=+1>int dirmodefmt(Fmt*) - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - </font></tt> - <tt><font size=+1>int read9pmsg(int fd, uchar *buf, uint nbuf) - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - </font></tt> - <tt><font size=+1>int statcheck(uchar *buf, uint nbuf) - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - </font></tt> - <tt><font size=+1>uint sizeS2M(Fcall *f) - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - </font></tt> - <tt><font size=+1>uint sizeD2M(Dir *d)<br> - </font></tt> -</table> -<p><font size=+1><b>DESCRIPTION </b></font><br> - -<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> - - These routines convert messages in the machine-independent format - of the Plan 9 file protocol, 9P, to and from a more convenient - form, an <tt><font size=+1>Fcall</font></tt> structure: - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - - <tt><font size=+1>#define MAXWELEM 16<br> - typedef<br> - struct Fcall<br> - {<br> - - <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> - - uchar type;<br> - u32int fid;<br> - ushort tag;<br> - union {<br> - - <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> - - struct {<br> - u32int msize; /* Tversion, Rversion */<br> - char *version; /* Tversion, Rversion */<br> - };<br> - struct {<br> - ushort oldtag; /* Tflush */<br> - };<br> - struct {<br> - char *ename; /* Rerror */<br> - };<br> - struct {<br> - Qid qid; /* Rattach, Ropen, Rcreate */<br> - u32int iounit; /* Ropen, Rcreate */<br> - };<br> - struct {<br> - Qid aqid; /* Rauth */<br> - };<br> - struct {<br> - u32int afid; /* Tauth, Tattach */<br> - char *uname; /* Tauth, Tattach */<br> - char *aname; /* Tauth, Tattach */<br> - };<br> - struct {<br> - u32int perm; /* Tcreate */ <br> - char *name; /* Tcreate */<br> - uchar mode; /* Tcreate, Topen */<br> - };<br> - struct {<br> - u32int newfid; /* Twalk */<br> - ushort nwname; /* Twalk */<br> - char *wname[MAXWELEM]; /* Twalk */<br> - };<br> - struct {<br> - ushort nwqid; /* Rwalk */<br> - Qid wqid[MAXWELEM]; /* Rwalk */<br> - };<br> - struct {<br> - vlong offset; /* Tread, Twrite */<br> - u32int count; /* Tread, Twrite, Rread */<br> - char *data; /* Twrite, Rread */<br> - };<br> - struct {<br> - ushort nstat; /* Twstat, Rstat */<br> - uchar *stat; /* Twstat, Rstat */<br> - };<br> - - </table> - };<br> - - </table> - } Fcall;<br> - /* these are implemented as macros */<br> - uchar GBIT8(uchar*)<br> - ushort GBIT16(uchar*)<br> - ulong GBIT32(uchar*)<br> - vlong GBIT64(uchar*)<br> - void PBIT8(uchar*, uchar)<br> - void PBIT16(uchar*, ushort)<br> - void PBIT32(uchar*, ulong)<br> - void PBIT64(uchar*, vlong)<br> - #define BIT8SZ 1<br> - #define BIT16SZ 2<br> - #define BIT32SZ 4<br> - #define BIT64SZ 8<br> - - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - </font></tt> - This structure is defined in <tt><font size=+1><fcall.h></font></tt>. See section 5 for a full - description of 9P messages and their encoding. For all message - types, the <tt><font size=+1>type</font></tt> field of an <tt><font size=+1>Fcall</font></tt> holds one of <tt><font size=+1>Tversion</font></tt>, <tt><font size=+1>Rversion</font></tt>, - <tt><font size=+1>Tattach</font></tt>, <tt><font size=+1>Rattach</font></tt>, etc. (defined in an enumerated type in <tt><font size=+1><fcall.h></font></tt>). - <tt><font size=+1>Fid</font></tt> is used by most messages, and - <tt><font size=+1>tag</font></tt> is used by all messages. The other fields are used selectively - by the message types given in comments. - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - - <i>ConvM2S</i> takes a 9P message at <i>ap</i> of length <i>nap</i>, and uses it to - fill in <tt><font size=+1>Fcall</font></tt> structure <i>f</i>. If the passed message including any - data for <tt><font size=+1>Twrite</font></tt> and <tt><font size=+1>Rread</font></tt> messages is formatted properly, the - return value is the number of bytes the message occupied in the - buffer <i>ap</i>, which will always be less than or equal to <i>nap</i>; - otherwise it is 0. For <tt><font size=+1>Twrite</font></tt> and <tt><font size=+1>Tread</font></tt> messages, <tt><font size=+1>data</font></tt> is set - to a pointer into the argument message, not a copy. - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - - <i>ConvS2M</i> does the reverse conversion, turning <i>f</i> into a message - starting at <i>ap</i>. The length of the resulting message is returned. - For <tt><font size=+1>Twrite</font></tt> and <tt><font size=+1>Rread</font></tt> messages, <tt><font size=+1>count</font></tt> bytes starting at <tt><font size=+1>data</font></tt> are - copied into the message. - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - - The constant <tt><font size=+1>IOHDRSZ</font></tt> is a suitable amount of buffer to reserve - for storing the 9P header; the data portion of a <tt><font size=+1>Twrite</font></tt> or <tt><font size=+1>Rread</font></tt> - will be no more than the buffer size negotiated in the <tt><font size=+1>Tversion/Rversion</font></tt> - exchange, minus <tt><font size=+1>IOHDRSZ</font></tt>. - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - - The routine <i>sizeS2M</i> returns the number of bytes required to store - the machine-independent representation of the <tt><font size=+1>Fcall</font></tt> structure - <i>f</i>, including its initial 32-bit size field. In other words, it - reports the number of bytes produced by a successful call to <i>convS2M</i>. - - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - - Another structure is <tt><font size=+1>Dir</font></tt>, used by the routines described in <a href="../man3/stat.html"><i>stat</i>(3)</a>. - <i>ConvM2D</i> converts the machine-independent form starting at <i>ap</i> into - <i>d</i> and returns the length of the machine-independent encoding. - The strings in the returned <tt><font size=+1>Dir</font></tt> structure are stored at successive - locations starting at <tt><font size=+1>strs</font></tt>. Usually <tt><font size=+1>strs</font></tt> will - point to storage immediately after the <tt><font size=+1>Dir</font></tt> itself. It can also - be a <tt><font size=+1>nil</font></tt> pointer, in which case the string pointers in the returned - <tt><font size=+1>Dir</font></tt> are all <tt><font size=+1>nil</font></tt>; however, the return value still includes their - length. - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - - <i>ConvD2M</i> does the reverse translation, also returning the length - of the encoding. If the buffer is too short, the return value - will be <tt><font size=+1>BIT16SZ</font></tt> and the correct size will be returned in the first - <tt><font size=+1>BIT16SZ</font></tt> bytes. (If the buffer is less that <tt><font size=+1>BIT16SZ</font></tt>, the return - value is zero; therefore a correct test for complete packing of - the - message is that the return value is greater than <tt><font size=+1>BIT16SZ</font></tt>). The - macro <tt><font size=+1>GBIT16</font></tt> can be used to extract the correct value. The related - macros with different sizes retrieve the corresponding-sized quantities. - <tt><font size=+1>PBIT16</font></tt> and its brethren place values in messages. With the exception - of handling short buffers in <i>convD2M</i>, - these macros are not usually needed except by internal routines. - - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - - Analogous to <i>sizeS2M</i>, <i>sizeD2M</i> returns the number of bytes required - to store the machine-independent representation of the <tt><font size=+1>Dir</font></tt> structure - <i>d</i>, including its initial 16-bit size field. - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - - The routine <tt><font size=+1>statcheck</font></tt> checks whether the <i>nbuf</i> bytes of <i>buf</i> contain - a validly formatted machine-independent <tt><font size=+1>Dir</font></tt> entry suitable as - an argument, for example, for the <tt><font size=+1>wstat</font></tt> (see <a href="../man3/stat.html"><i>stat</i>(3)</a>) system call. - It checks that the sizes of all the elements of the the entry - sum to exactly <i>nbuf</i>, which is a simple but effective test - of validity. <i>Nbuf</i> and <i>buf</i> should include the second two-byte (16-bit) - length field that precedes the entry when formatted in a 9P message - (see <i>stat</i>(9p)); in other words, <i>nbuf</i> is 2 plus the sum of the - sizes of the entry itself. <i>Statcheck</i> also verifies that the length - field has the correct value (that is, <i>nbuf</i><tt><font size=+1>−2</font></tt>). It returns <tt><font size=+1>0 - </font></tt>for a valid entry and <tt><font size=+1>−1</font></tt> for an incorrectly formatted entry. - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - - <i>Dirfmt</i>, <i>fcallfmt</i>, and <i>dirmodefmt</i> are formatting routines, suitable - for <a href="../man3/fmtinstall.html"><i>fmtinstall</i>(3)</a>. They convert <tt><font size=+1>Dir*</font></tt>, <tt><font size=+1>Fcall*</font></tt>, and <tt><font size=+1>long</font></tt> values - into string representations of the directory buffer, <tt><font size=+1>Fcall</font></tt> buffer, - or file mode value. <i>Fcallfmt</i> assumes that <i>dirfmt</i> has been installed - with format letter <tt><font size=+1>D</font></tt> and <i>dirmodefmt</i> with format - letter <tt><font size=+1>M</font></tt>. - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - - <i>Read9pmsg</i> calls <a href="../man3/read.html"><i>read</i>(3)</a> multiple times, if necessary, to read - an entire 9P message into <tt><font size=+1>buf</font></tt>. The return value is 0 for end of - file, or -1 for error; it does not return partial messages.<br> - -</table> -<p><font size=+1><b>SOURCE </b></font><br> - -<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> - - <tt><font size=+1>/usr/local/plan9/src/lib9<br> - </font></tt> -</table> -<p><font size=+1><b>SEE ALSO </b></font><br> - -<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> - - <a href="../man3/intro.html"><i>intro</i>(3)</a>, <a href="../man3/9p.html"><i>9p</i>(3)</a>, <a href="../man3/stat.html"><i>stat</i>(3)</a>, <i>intro</i>(9p)<br> - -</table> - -<td width=20> -<tr height=20><td> -</table> -<!-- TRAILER --> -<table border=0 cellpadding=0 cellspacing=0 width=100%> -<tr height=15><td width=10><td><td width=10> -<tr><td><td> -<center> -<a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a> -</center> -</table> -<!-- TRAILER --> -</body></html> |