NAME

Fcall, convS2M, convD2M, convM2S, convM2D, getS, fcallconv, dirconv, dirmodeconv − interface to Plan 9 File protocol

SYNOPSIS

­#include <u.h>
­#include <libc.h>
­#include <auth.h>
­#include <fcall.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)

char ∗getS(int fd, char ∗ap, Fcall ∗f, long ∗lp)

int dirconv(void ∗o, Fconv∗)

int fcallconv(void ∗o, Fconv∗)

int dirmodeconv(void ∗o, Fconv∗)

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:

typedef
struct Fcall {
chartype;
shortfid;
shorttag;
union {
struct {
ushortoldtag; /∗ Tflush ∗/
Qidqid;/∗ Rattach, Rwalk,
Ropen, Rcreate ∗/
charrauth[AUTHENTLEN];/∗ Rattach ∗/
};
struct {
charuname[NAMELEN];/∗ Tattach ∗/
charaname[NAMELEN];/∗ Tattach ∗/
charticket[TICKETLEN];/∗ Tattach ∗/
charauth[AUTHENTLEN];/∗ Tattach ∗/
};
struct {
charename[ERRLEN];/∗ Rerror ∗/
charauthid[NAMELEN];/∗ Rsession ∗/
charauthdom[DOMLEN];/∗ Rsession ∗/
charchal[CHALLEN];/∗ Tsession/Rsession ∗/
};
struct {
longperm;/∗ Tcreate ∗/
shortnewfid;/∗ Tclone, Tclwalk ∗/
charname[NAMELEN];/∗ Twalk, Tclwalk,
Tcreate ∗/
charmode;/∗ Tcreate, Topen ∗/
};
struct {
vlongoffset;/∗ Tread, Twrite ∗/
longcount;/∗ Tread, Twrite, Rread ∗/
char∗data;/∗ Twrite, Rread ∗/
};
struct {
charstat[DIRLEN];/∗ Twstat, Rstat ∗/
};
};
} Fcall;

This structure is defined in <fcall.h>.  See section 5 for a full description of 9P messages and their encoding.  For all message types, the ­type field of an ­Fcall holds one of Tnop, Rnop, Tsession, Rsession, 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 n, 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 n; 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 ­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.  The constant ­MAXRPC is set to this sum. 

Another structure is Dir, used by the routines described in 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. 

­GetS reads a message from file descriptor ­fd into ap and converts the message using ­convM2S into the ­Fcall structure f. The ­lp argument must point to a ­long holding the size of the ­ap buffer.  It is somewhat resilient to transient read errors.  If ­convM2S succeeds, its return value is stored in ∗lp, and ­getS returns zero.  Otherwise ­getS returns a string identifying the error. 

Dirconv, fcallconv, and ­dirmodeconv are formatting routines, suitable for ­fmtinstall (see print(2)). They convert Dir∗, Fcall∗, and long values into string representations of the directory buffer, ­Fcall buffer, or file mode value.  ­Fcallconv assumes that ­dirconv has been installed with format letter D. 

SOURCE

­/sys/src/libc/9sys

SEE ALSO

intro(2), stat(2), intro(5)

DIAGNOSTICS

­GetS sets errstr.

BUGS

­ConvS2M should check for counts exceeding MAXFMSG. 

Plan 9  —  March 27, 2001