NAME

Fcall, convS2M, convD2M, convM2S, convM2D, fcallconv, dirconv − C interface to Inferno File protocol

SYNOPSIS

­#include <styx.h>

int convS2M(Fcall ∗f, char ∗ap)

int convD2M(Dir ∗d, char ∗ap)

int convM2S(char ∗ap, Fcall ∗f, int n)

int convM2D(char ∗ap, Dir ∗d)

int dirconv(va_list ∗arg, Fconv∗)

int fcallconv(va_list ∗arg, Fconv∗)

DESCRIPTION

These routines convert messages in the machine-independent format of the Inferno file protocol, Styx (see section 5 of this manual) to and from a more convenient form, an ­Fcall structure:

typedef
structFcall
{
chartype;
shortfid;
ushorttag;
ushortoldtag; /∗ T-Flush ∗/
Qidqid;/∗ R-Attach, R-Walk, R-Open, R-Create ∗/
charuname[NAMELEN];/∗ T-Attach ∗/
charaname[NAMELEN];/∗ T-Attach ∗/
charename[ERRLEN];/∗ R-Error ∗/
longperm;/∗ T-Create ∗/
shortnewfid; /∗ T-Clone ∗/
charname[NAMELEN];/∗ T-Walk, T-Create ∗/
charmode;/∗ T-Create, T-Open ∗/
longoffset;/∗ T-Read, T-Write ∗/
longcount;/∗ T-Read, T-Write, R-Read ∗/
char∗data;/∗ T-Write, R-Read ∗/
charstat[DIRLEN];/∗ T-Wstat, R-Stat ∗/
} Fcall;

This structure is defined in <styx.h>.  See the other pages in this section of the manual for a full description of Styx messages and their encoding.  For all message types, the ­type field of an ­Fcall holds one of Tnop, Rnop, Tattach, Rattach, etc. (defined in an enumerated type in <styx.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 buffer ­ap of length n, and attempts to unpack a complete Styx message to fill in ­Fcall structure f. To help a caller that is reading and processing Styx messages from an input stream that does not preserve message boundaries, the return value distinguishes three cases:

−If the passed message, including any data for ­Twrite and ­Rread messages, forms a complete, properly formatted Styx message, the return value is the number of bytes consumed.  It can be less than n when further messages or partial messages remain in ap. For ­Twrite and ­Tread messages, f−>data is set to a pointer into the argument message, not a copy. 

−If the message in ­ap is incomplete but valid thus far, the return value is 0; more bytes must be read and added to the buffer to complete the message. 

−If the message is invalid, the return value is -1. 

­ConvS2M does the reverse conversion, turning ­f into a message starting at ap. The length of the resulting message is returned; it returns -1 if the message type is invalid. For ­Twrite and ­Rread messages, f−>count bytes starting at f−>data are copied into the message. 

The constant ­MAXMSG is the length of the longest message, excluding data; ­MAXFDATA (8192) is the maximum ­count in a read or write message.  Thus messages are guaranteed to be shorter than ­MAXMSG+MAXFDATA bytes long. 

Another structure is Dir, used by the routines described in sys-stat(2). ­ConvM2D converts the machine-independent form starting at ­ap into d and returns the length of the encoding.  ­ConvD2M does the reverse translation, also returning the length of the encoding. 

Dirconv and fcallconv are print(10.2) formatting routines. They convert Dir∗ and Fcall∗ values into string representations of the directory buffer or ­Fcall buffer.  ­Fcallconv is installed under format ­F in the Inferno emulator and kernel. 

SOURCE

­/include/styx.h

SEE ALSO

intro(2), styxlib(2), sys-stat(2), intro(5), intro(10), print(10.2)

BUGS

The offset and directory length fields have 8 bytes in the protocol, but these routines assume they fit into a long. 

­ConvS2M should check for counts exceeding MAXFMSG. 

Plan 9  —  June 08, 2000