From 78e51a8c6678b6e3dff3d619aa786669f531f4bc Mon Sep 17 00:00:00 2001 From: rsc Date: Fri, 14 Jan 2005 03:45:44 +0000 Subject: checkpoint --- man/man3/plumb.html | 257 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 257 insertions(+) create mode 100644 man/man3/plumb.html (limited to 'man/man3/plumb.html') diff --git a/man/man3/plumb.html b/man/man3/plumb.html new file mode 100644 index 00000000..d7649698 --- /dev/null +++ b/man/man3/plumb.html @@ -0,0 +1,257 @@ + +plumb(3) - Plan 9 from User Space + + + + +
+
+
PLUMB(3)PLUMB(3) +
+
+

NAME
+ +
+ + eplumb, plumbfree, plumbopen, plumbopenfid, plumbsend, plumbsendtofid, + plumbsendtext, plumblookup, plumbpack, plumbpackattr, plumbaddattr, + plumbdelattr, plumbrecv, plumbrecvfid, plumbunpack, plumbunpackpartial, + plumbunpackattr, Plumbmsg – plumb messages
+ +
+

SYNOPSIS
+ +
+ + #include <u.h>
+ #include <libc.h>
+ #include <plumb.h> +
+ + +
+ + int          plumbopen(char *port, int omode) +
+ + int          plumbsend(int fd, Plumbmsg *m) +
+ + int          plumbsendtext(int fd, char *src, char *dst, char *wdir, char + *data) +
+ + void         plumbfree(Plumbmsg *m) +
+ + Plumbmsg*    plumbrecv(int fd) +
+ + char*        plumbpack(Plumbmsg *m, int *np) +
+ + Plumbmsg*    plumbunpack(char *buf, int n) +
+ + Plumbmsg*    plumbunpackpartial(char *buf, int n, int *morep) +
+ + char*        plumbpackattr(Plumbattr *a) +
+ + Plumbattr* plumbunpackattr(char *a) +
+ + char*        plumblookup(Plumbattr *a, char *name) +
+ + Plumbattr* plumbaddattr(Plumbattr *a, Plumbattr *new) +
+ + Plumbattr* plumbdelattr(Plumbattra *a, char *name) +
+ + int          eplumb(int key, char *port) +
+ + #include <9pclient.h> +
+ + CFid         *plumbopenfid(char *port, int omode) +
+ + Plumbmsg*    plumbrecvfid(CFid *fid) +
+ + int          plumbsendtofid(CFid *fid, Plumbmsg *m)
+ +
+

DESCRIPTION
+ +
+ + These routines manipulate plumb(7) messages, transmitting them, + receiving them, and converting them between text and these data + structures:
+ +
+ + typedef
+ struct Plumbmsg
+ {
+ +
+ + char        *src;
+ char        *dst;
+ char        *wdir;
+ char        *type;
+ Plumbattr *attr;
+ int         ndata;
+ char        *data;
+ +
+ } Plumbmsg;
+ typedef
+ struct Plumbattr
+ {
+ +
+ + char        *name;
+ char        *value;
+ Plumbattr *next;
+ +
+ } Plumbattr;
+ +
+ + +
+ Plumbopen opens the named plumb port, using open(3) mode omode. + If port begins with a slash, it is taken as a literal file name; + otherwise plumbopen searches for the location of the plumber(4) + service and opens the port there. +
+ + For programs using the event(3) interface, eplumb registers, using + the given key, receipt of messages from the named port. +
+ + Plumbsend formats and writes message m to the file descriptor + fd, which will usually be the result of plumbopen("send", OWRITE). + Plumbsendtext is a simplified version for text-only messages; + it assumes type is text, sets attr to nil, and sets ndata to strlen(data). + +
+ + Plumbfree frees all the data associated with the message m, all + the components of which must therefore have been allocated with + malloc(3). +
+ + Plumbrecv returns the next message available on the file descriptor + fd, or nil for error. +
+ + Plumbpack encodes message m as a character string in the format + of plumb(7), setting *np to the length in bytes of the string. + Plumbunpack does the inverse, translating the n bytes of buf into + a Plumbmsg. +
+ + Plumbunpackpartial enables unpacking of messages that arrive in + pieces. The first call to plumbunpackpartial for a given message + must be sufficient to unpack the header; subsequent calls permit + unpacking messages with long data sections. For each call, buf + points to the beginning of the complete message received + so far, and n reports the total number of bytes received for that + message. If the message is complete, the return value will be + as in plumbunpack. If not, and morep is not null, the return value + will be nil and *morep will be set to the number of bytes remaining + to be read for this message to be complete (recall that + the byte count is in the header). Those bytes should be read by + the caller, placed at location buf+n, and the message unpacked + again. If an error is encountered, the return value will be nil + and *morep will be zero. +
+ + Plumbpackattr converts the list a of Plumbattr structures into + a null-terminated string. If an attribute value contains white + space, quote characters, or equal signs, the value will be quoted + appropriately. A newline character will terminate processing. + Plumbunpackattr converts the null-terminated string a back into + a list of Plumbattr structures. +
+ + Plumblookup searches the Plumbattr list a for an attribute with + the given name and returns the associated value. The returned + string is the original value, not a copy. If the attribute has + no value, the returned value will be the empty string; if the + attribute does not occur in the list at all, the value will be + nil. +
+ + Plumbaddattr appends the new Plumbattr (which may be a list) to + the attribute list a and returns the new list. Plumbattr searches + the list a for the first attribute with name name and deletes + it from the list, returning the resulting list. Plumbdelattr is + a no-op if no such attribute exists. +
+ + The file descriptor returned by plumbopen is created with fsopenfd + (see 9pclient(3)), which masks information about read and write + errors. This is acceptable for use in plumbrecv but not for plumbsend, + which depends on seeing details of write errors. Plumbopenfid, + plumbrecvfid, and plumbsendtofid provide an + explicit interface to lib9pclient that preserves the exact error + details.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libplumb
+ +
+

SEE ALSO
+ +
+ + plumb(1), event(3), plumber(4), plumb(7)
+ +
+

DIAGNOSTICS
+ +
+ + When appropriate, including when a plumbsend fails, these routine + set errstr.
+ +
+

BUGS
+ +
+ + To avoid rewriting clients that use plumbsend, the call plumbopen("send", + OWRITE) returns a useless file descriptor (it is opened to /dev/null). + Plumbsend looks for this particular file descriptor and uses a + static copy of the CFid instead.
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + -- cgit v1.2.3