diff options
Diffstat (limited to 'man/man3/plumb.html')
| -rw-r--r-- | man/man3/plumb.html | 257 |
1 files changed, 257 insertions, 0 deletions
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 @@ +<head> +<title>plumb(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>PLUMB(3)</b><td align=right><b>PLUMB(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> + + eplumb, plumbfree, plumbopen, plumbopenfid, plumbsend, plumbsendtofid, + plumbsendtext, plumblookup, plumbpack, plumbpackattr, plumbaddattr, + plumbdelattr, plumbrecv, plumbrecvfid, plumbunpack, plumbunpackpartial, + plumbunpackattr, Plumbmsg – plumb messages<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 <plumb.h> + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <tt><font size=+1>int plumbopen(char *port, int omode) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int plumbsend(int fd, Plumbmsg *m) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int plumbsendtext(int fd, char *src, char *dst, char *wdir, char + *data) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>void plumbfree(Plumbmsg *m) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>Plumbmsg* plumbrecv(int fd) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>char* plumbpack(Plumbmsg *m, int *np) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>Plumbmsg* plumbunpack(char *buf, int n) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>Plumbmsg* plumbunpackpartial(char *buf, int n, int *morep) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>char* plumbpackattr(Plumbattr *a) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>Plumbattr* plumbunpackattr(char *a) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>char* plumblookup(Plumbattr *a, char *name) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>Plumbattr* plumbaddattr(Plumbattr *a, Plumbattr *new) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>Plumbattr* plumbdelattr(Plumbattra *a, char *name) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int eplumb(int key, char *port) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>#include <9pclient.h> + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>CFid *plumbopenfid(char *port, int omode) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>Plumbmsg* plumbrecvfid(CFid *fid) + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int plumbsendtofid(CFid *fid, Plumbmsg *m)<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 manipulate <a href="../man7/plumb.html"><i>plumb</i>(7)</a> messages, transmitting them, + receiving them, and converting them between text and these data + structures:<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>typedef<br> + struct Plumbmsg<br> + {<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + char *src;<br> + char *dst;<br> + char *wdir;<br> + char *type;<br> + Plumbattr *attr;<br> + int ndata;<br> + char *data;<br> + + </table> + } Plumbmsg;<br> + typedef<br> + struct Plumbattr<br> + {<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + char *name;<br> + char *value;<br> + Plumbattr *next;<br> + + </table> + } Plumbattr;<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + + </table> + <i>Plumbopen</i> opens the named plumb <i>port</i>, using <a href="../man3/open.html"><i>open</i>(3)</a> mode <i>omode</i>. + If <i>port</i> begins with a slash, it is taken as a literal file name; + otherwise <i>plumbopen</i> searches for the location of the <a href="../man4/plumber.html"><i>plumber</i>(4)</a> + service and opens the port there. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + For programs using the <a href="../man3/event.html"><i>event</i>(3)</a> interface, <i>eplumb</i> registers, using + the given <i>key</i>, receipt of messages from the named <i>port</i>. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Plumbsend</i> formats and writes message <i>m</i> to the file descriptor + <i>fd</i>, which will usually be the result of <tt><font size=+1>plumbopen("send", OWRITE)</font></tt>. + <i>Plumbsendtext</i> is a simplified version for text-only messages; + it assumes <tt><font size=+1>type</font></tt> is <tt><font size=+1>text</font></tt>, sets <tt><font size=+1>attr</font></tt> to nil, and sets <tt><font size=+1>ndata</font></tt> to <tt><font size=+1>strlen(</font></tt><i>data</i><tt><font size=+1>)</font></tt>. + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Plumbfree</i> frees all the data associated with the message <i>m</i>, all + the components of which must therefore have been allocated with + <a href="../man3/malloc.html"><i>malloc</i>(3)</a>. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Plumbrecv</i> returns the next message available on the file descriptor + <i>fd</i>, or nil for error. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Plumbpack</i> encodes message <i>m</i> as a character string in the format + of <a href="../man7/plumb.html"><i>plumb</i>(7)</a><i>,</i> setting <tt><font size=+1>*</font></tt><i>np</i> to the length in bytes of the string. + <i>Plumbunpack</i> does the inverse, translating the <i>n</i> bytes of <i>buf</i> into + a <tt><font size=+1>Plumbmsg</font></tt>. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Plumbunpackpartial</i> enables unpacking of messages that arrive in + pieces. The first call to <i>plumbunpackpartial</i> for a given message + must be sufficient to unpack the header; subsequent calls permit + unpacking messages with long data sections. For each call, <i>buf</i> + points to the beginning of the complete message received + so far, and <i>n</i> reports the total number of bytes received for that + message. If the message is complete, the return value will be + as in <i>plumbunpack</i>. If not, and <i>morep</i> is not null, the return value + will be <tt><font size=+1>nil</font></tt> and <tt><font size=+1>*</font></tt>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 <i>buf</i><tt><font size=+1>+</font></tt><i>n</i>, and the message unpacked + again. If an error is encountered, the return value will be <tt><font size=+1>nil</font></tt> + and <tt><font size=+1>*</font></tt><i>morep</i> will be zero. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Plumbpackattr</i> converts the list <i>a</i> of <tt><font size=+1>Plumbattr</font></tt> 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. + <i>Plumbunpackattr</i> converts the null-terminated string <i>a</i> back into + a list of <i>Plumbattr</i> structures. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Plumblookup</i> searches the <tt><font size=+1>Plumbattr</font></tt> list <i>a</i> for an attribute with + the given <i>name</i> 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. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Plumbaddattr</i> appends the <i>new</i> <tt><font size=+1>Plumbattr</font></tt> (which may be a list) to + the attribute list <i>a</i> and returns the new list. <i>Plumbattr</i> searches + the list <i>a</i> for the first attribute with name <i>name</i> and deletes + it from the list, returning the resulting list. <i>Plumbdelattr</i> is + a no-op if no such attribute exists. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + The file descriptor returned by <i>plumbopen</i> is created with <i>fsopenfd</i> + (see <a href="../man3/9pclient.html"><i>9pclient</i>(3)</a>), which masks information about read and write + errors. This is acceptable for use in <i>plumbrecv</i> but not for <i>plumbsend</i>, + which depends on seeing details of write errors. <i>Plumbopenfid</i>, + <i>plumbrecvfid</i>, and <i>plumbsendtofid</i> provide an + explicit interface to <i>lib9pclient</i> that preserves the exact error + details.<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/libplumb<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="../man1/plumb.html"><i>plumb</i>(1)</a>, <a href="../man3/event.html"><i>event</i>(3)</a>, <a href="../man4/plumber.html"><i>plumber</i>(4)</a>, <a href="../man7/plumb.html"><i>plumb</i>(7)</a><br> + +</table> +<p><font size=+1><b>DIAGNOSTICS </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + When appropriate, including when a <i>plumbsend</i> fails, these routine + set <i>errstr</i>.<br> + +</table> +<p><font size=+1><b>BUGS </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + To avoid rewriting clients that use <i>plumbsend</i>, the call <tt><font size=+1>plumbopen("send", + OWRITE)</font></tt> returns a useless file descriptor (it is opened to <tt><font size=+1>/dev/null</font></tt>). + <i>Plumbsend</i> looks for this particular file descriptor and uses a + static copy of the <tt><font size=+1>CFid</font></tt> instead.<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> |