dots

Personal dotfiles
git clone git://git.gormless.xyz/dots.git
Log | Files | Refs

fcall.html (15960B)


      1 <head>
      2 <title>fcall(3) - Plan 9 from User Space</title>
      3 <meta content="text/html; charset=utf-8" http-equiv=Content-Type>
      4 </head>
      5 <body bgcolor=#ffffff>
      6 <table border=0 cellpadding=0 cellspacing=0 width=100%>
      7 <tr height=10><td>
      8 <tr><td width=20><td>
      9 <tr><td width=20><td><b>FCALL(3)</b><td align=right><b>FCALL(3)</b>
     10 <tr><td width=20><td colspan=2>
     11     <br>
     12 <p><font size=+1><b>NAME     </b></font><br>
     13 
     14 <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
     15 
     16     Fcall, convS2M, convD2M, convM2S, convM2D, fcallfmt, dirfmt, dirmodefmt,
     17     read9pmsg, statcheck, sizeS2M, sizeD2M &ndash; interface to Plan 9 File
     18     protocol<br>
     19     
     20 </table>
     21 <p><font size=+1><b>SYNOPSIS     </b></font><br>
     22 
     23 <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
     24 
     25     <tt><font size=+1>#include &lt;u.h&gt;<br>
     26     #include &lt;libc.h&gt;<br>
     27     #include &lt;fcall.h&gt; 
     28     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
     29     </font></tt>
     30     <tt><font size=+1>uint convS2M(Fcall *f, uchar *ap, uint nap) 
     31     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
     32     </font></tt>
     33     <tt><font size=+1>uint convD2M(Dir *d, uchar *ap, uint nap) 
     34     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
     35     </font></tt>
     36     <tt><font size=+1>uint convM2S(uchar *ap, uint nap, Fcall *f) 
     37     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
     38     </font></tt>
     39     <tt><font size=+1>uint convM2D(uchar *ap, uint nap, Dir *d, char *strs) 
     40     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
     41     </font></tt>
     42     <tt><font size=+1>int dirfmt(Fmt*) 
     43     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
     44     </font></tt>
     45     <tt><font size=+1>int fcallfmt(Fmt*) 
     46     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
     47     </font></tt>
     48     <tt><font size=+1>int dirmodefmt(Fmt*) 
     49     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
     50     </font></tt>
     51     <tt><font size=+1>int read9pmsg(int fd, uchar *buf, uint nbuf) 
     52     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
     53     </font></tt>
     54     <tt><font size=+1>int statcheck(uchar *buf, uint nbuf) 
     55     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
     56     </font></tt>
     57     <tt><font size=+1>uint sizeS2M(Fcall *f) 
     58     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
     59     </font></tt>
     60     <tt><font size=+1>uint sizeD2M(Dir *d)<br>
     61     </font></tt>
     62 </table>
     63 <p><font size=+1><b>DESCRIPTION     </b></font><br>
     64 
     65 <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
     66 
     67     These routines convert messages in the machine-independent format
     68     of the Plan 9 file protocol, 9P, to and from a more convenient
     69     form, an <tt><font size=+1>Fcall</font></tt> structure: 
     70     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
     71     
     72     <tt><font size=+1>#define MAXWELEM 16<br>
     73     typedef<br>
     74     struct Fcall<br>
     75     {<br>
     76     
     77     <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
     78 
     79         uchar type;<br>
     80         u32int &nbsp;&nbsp;&nbsp;&nbsp;fid;<br>
     81         ushort &nbsp;&nbsp;&nbsp;&nbsp;tag;<br>
     82         union {<br>
     83          
     84         <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
     85 
     86             struct {<br>
     87               u32int msize; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* Tversion, Rversion */<br>
     88               char &nbsp;&nbsp;&nbsp;*version; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* Tversion, Rversion */<br>
     89              };<br>
     90              struct {<br>
     91               ushort oldtag; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* Tflush */<br>
     92              };<br>
     93              struct {<br>
     94               char &nbsp;&nbsp;&nbsp;*ename; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* Rerror */<br>
     95              };<br>
     96              struct {<br>
     97               Qid &nbsp;&nbsp;&nbsp;&nbsp;qid; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* Rattach, Ropen, Rcreate */<br>
     98               u32int iounit; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* Ropen, Rcreate */<br>
     99              };<br>
    100              struct {<br>
    101               Qid &nbsp;&nbsp;&nbsp;&nbsp;aqid; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* Rauth */<br>
    102              };<br>
    103              struct {<br>
    104               u32int afid; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* Tauth, Tattach */<br>
    105               char &nbsp;&nbsp;&nbsp;*uname; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* Tauth, Tattach */<br>
    106               char &nbsp;&nbsp;&nbsp;*aname; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* Tauth, Tattach */<br>
    107              };<br>
    108              struct {<br>
    109               u32int perm; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* Tcreate */ <br>
    110               char &nbsp;&nbsp;&nbsp;*name; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* Tcreate */<br>
    111               uchar &nbsp;&nbsp;&nbsp;mode; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* Tcreate, Topen */<br>
    112              };<br>
    113              struct {<br>
    114               u32int newfid; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* Twalk */<br>
    115               ushort nwname; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* Twalk */<br>
    116               char &nbsp;&nbsp;&nbsp;*wname[MAXWELEM]; &nbsp;&nbsp;&nbsp;/* Twalk */<br>
    117              };<br>
    118              struct {<br>
    119               ushort nwqid; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* Rwalk */<br>
    120               Qid &nbsp;&nbsp;&nbsp;&nbsp;wqid[MAXWELEM]; &nbsp;&nbsp;&nbsp;&nbsp;/* Rwalk */<br>
    121              };<br>
    122              struct {<br>
    123               vlong &nbsp;&nbsp;&nbsp;offset; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* Tread, Twrite */<br>
    124               u32int count; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* Tread, Twrite, Rread */<br>
    125               char &nbsp;&nbsp;&nbsp;*data; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* Twrite, Rread */<br>
    126              };<br>
    127              struct {<br>
    128               ushort nstat; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* Twstat, Rstat */<br>
    129               uchar &nbsp;&nbsp;&nbsp;*stat; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* Twstat, Rstat */<br>
    130              };<br>
    131             
    132         </table>
    133         };<br>
    134         
    135     </table>
    136     } Fcall;<br>
    137     /* these are implemented as macros */<br>
    138     uchar &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;GBIT8(uchar*)<br>
    139     ushort &nbsp;&nbsp;&nbsp;&nbsp;GBIT16(uchar*)<br>
    140     ulong &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;GBIT32(uchar*)<br>
    141     vlong &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;GBIT64(uchar*)<br>
    142     void &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;PBIT8(uchar*, uchar)<br>
    143     void &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;PBIT16(uchar*, ushort)<br>
    144     void &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;PBIT32(uchar*, ulong)<br>
    145     void &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;PBIT64(uchar*, vlong)<br>
    146     #define &nbsp;&nbsp;&nbsp;BIT8SZ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;1<br>
    147     #define &nbsp;&nbsp;&nbsp;BIT16SZ &nbsp;&nbsp;&nbsp;&nbsp;2<br>
    148     #define &nbsp;&nbsp;&nbsp;BIT32SZ &nbsp;&nbsp;&nbsp;&nbsp;4<br>
    149     #define &nbsp;&nbsp;&nbsp;BIT64SZ &nbsp;&nbsp;&nbsp;&nbsp;8<br>
    150     
    151     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    152     </font></tt>
    153     This structure is defined in <tt><font size=+1>&lt;fcall.h&gt;</font></tt>. See section 5 for a full
    154     description of 9P messages and their encoding. For all message
    155     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>,
    156     <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>&lt;fcall.h&gt;</font></tt>).
    157     <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.
    158     The other
    159     fields are used selectively by the message types given in comments.
    160     
    161     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    162     
    163     <i>ConvM2S</i> takes a 9P message at <i>ap</i> of length <i>nap</i>, and uses it to
    164     fill in <tt><font size=+1>Fcall</font></tt> structure <i>f</i>. If the passed message including any
    165     data for <tt><font size=+1>Twrite</font></tt> and <tt><font size=+1>Rread</font></tt> messages is formatted properly, the
    166     return value is the number of bytes the message occupied in the
    167     buffer <i>ap</i>, which will always be less than or equal to <i>nap</i>; otherwise
    168     it is 0. For <tt><font size=+1>Twrite</font></tt> and
    169     <tt><font size=+1>Tread</font></tt> messages, <tt><font size=+1>data</font></tt> is set to a pointer into the argument message,
    170     not a copy. 
    171     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    172     
    173     <i>ConvS2M</i> does the reverse conversion, turning <i>f</i> into a message
    174     starting at <i>ap</i>. The length of the resulting message is returned.
    175     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
    176     copied into the message. 
    177     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    178     
    179     The constant <tt><font size=+1>IOHDRSZ</font></tt> is a suitable amount of buffer to reserve
    180     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>
    181     will be no more than the buffer size negotiated in the <tt><font size=+1>Tversion/Rversion</font></tt>
    182     exchange, minus <tt><font size=+1>IOHDRSZ</font></tt>. 
    183     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    184     
    185     The routine <i>sizeS2M</i> returns the number of bytes required to store
    186     the machine-independent representation of the <tt><font size=+1>Fcall</font></tt> structure
    187     <i>f</i>, including its initial 32-bit size field. In other words, it
    188     reports the number of bytes produced by a successful call to <i>convS2M</i>.
    189     
    190     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    191     
    192     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>.
    193     <i>ConvM2D</i> converts the machine-independent form starting at <i>ap</i> into
    194     <i>d</i> and returns the length of the machine-independent encoding.
    195     The strings in the returned <tt><font size=+1>Dir</font></tt> structure are stored at successive
    196     locations starting at <tt><font size=+1>strs</font></tt>. Usually <tt><font size=+1>strs</font></tt> will point to storage
    197     immediately after the
    198     <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
    199     pointers in the returned <tt><font size=+1>Dir</font></tt> are all <tt><font size=+1>nil</font></tt>; however, the return
    200     value still includes their length. 
    201     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    202     
    203     <i>ConvD2M</i> does the reverse translation, also returning the length
    204     of the encoding. If the buffer is too short, the return value
    205     will be <tt><font size=+1>BIT16SZ</font></tt> and the correct size will be returned in the first
    206     <tt><font size=+1>BIT16SZ</font></tt> bytes. (If the buffer is less that <tt><font size=+1>BIT16SZ</font></tt>, the return
    207     value is zero; therefore a correct test for complete packing of
    208     the message is that the return value is
    209     greater than <tt><font size=+1>BIT16SZ</font></tt>). The macro <tt><font size=+1>GBIT16</font></tt> can be used to extract
    210     the correct value. The related macros with different sizes retrieve
    211     the corresponding-sized quantities. <tt><font size=+1>PBIT16</font></tt> and its brethren place
    212     values in messages. With the exception of handling short buffers
    213     in <i>convD2M</i>, these macros are not usually needed except by internal
    214     routines. 
    215     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    216     
    217     Analogous to <i>sizeS2M</i>, <i>sizeD2M</i> returns the number of bytes required
    218     to store the machine-independent representation of the <tt><font size=+1>Dir</font></tt> structure
    219     <i>d</i>, including its initial 16-bit size field. 
    220     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    221     
    222     The routine <tt><font size=+1>statcheck</font></tt> checks whether the <i>nbuf</i> bytes of <i>buf</i> contain
    223     a validly formatted machine-independent <tt><font size=+1>Dir</font></tt> entry suitable as
    224     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.
    225     It checks that the sizes of all the elements of the the entry
    226     sum to exactly <i>nbuf</i>, which is a simple but effective test of validity.
    227     <i>Nbuf</i> and <i>buf</i> should
    228     include the second two-byte (16-bit) length field that precedes
    229     the entry when formatted in a 9P message (see <i>stat</i>(9p)); in other
    230     words, <i>nbuf</i> is 2 plus the sum of the sizes of the entry itself.
    231     <i>Statcheck</i> also verifies that the length field has the correct
    232     value (that is, <i>nbuf</i><tt><font size=+1>&#8722;2</font></tt>). It returns <tt><font size=+1>0</font></tt> for a valid entry and <tt><font size=+1>&#8722;1</font></tt>
    233     for an incorrectly formatted entry. 
    234     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    235     
    236     <i>Dirfmt</i>, <i>fcallfmt</i>, and <i>dirmodefmt</i> are formatting routines, suitable
    237     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
    238     into string representations of the directory buffer, <tt><font size=+1>Fcall</font></tt> buffer,
    239     or file mode value. <i>Fcallfmt</i> assumes that <i>dirfmt</i> has been installed
    240     with format letter <tt><font size=+1>D</font></tt> and <i>dirmodefmt</i> with format letter <tt><font size=+1>M</font></tt>. 
    241     <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
    242     
    243     <i>Read9pmsg</i> calls <a href="../man3/read.html"><i>read</i>(3)</a> multiple times, if necessary, to read
    244     an entire 9P message into <tt><font size=+1>buf</font></tt>. The return value is 0 for end of
    245     file, or -1 for error; it does not return partial messages.<br>
    246     
    247 </table>
    248 <p><font size=+1><b>SOURCE     </b></font><br>
    249 
    250 <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
    251 
    252     <tt><font size=+1><a href="/var/usrlocal/plan9/src/lib9">/var/usrlocal/plan9/src/lib9</a><br>
    253     </font></tt>
    254 </table>
    255 <p><font size=+1><b>SEE ALSO    </b></font><br>
    256 
    257 <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
    258 
    259     <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>
    260     
    261 </table>
    262 
    263 <td width=20>
    264 <tr height=20><td>
    265 </table>
    266 <!-- TRAILER -->
    267 <table border=0 cellpadding=0 cellspacing=0 width=100%>
    268 <tr height=15><td width=10><td><td width=10>
    269 <tr><td><td>
    270 <center>
    271 <a href="https://9fans.github.io/plan9port/"><img src="../../dist/glendacircle.png" alt="Space Glenda" border=0></a>
    272 </center>
    273 </table>
    274 <!-- TRAILER -->
    275 </body></html>