Google Git
Sign in
plan9port / plan9 / 78e51a8c6678b6e3dff3d619aa786669f531f4bc / . / man / man3 / plumb.html
blob: d764969853f8409b4a7fedca827fac8beb450546 [file] [log] [blame]
<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 &ndash; 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 &lt;u.h&gt;<br>
#include &lt;libc.h&gt;<br>
#include &lt;plumb.h&gt;
<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 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;plumbopen(char *port, int omode)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>int &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;plumbsend(int fd, Plumbmsg *m)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>int &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;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 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;plumbfree(Plumbmsg *m)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>Plumbmsg* &nbsp;&nbsp;&nbsp;plumbrecv(int fd)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>char* &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;plumbpack(Plumbmsg *m, int *np)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>Plumbmsg* &nbsp;&nbsp;&nbsp;plumbunpack(char *buf, int n)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>Plumbmsg* &nbsp;&nbsp;&nbsp;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* &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;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* &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;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 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;eplumb(int key, char *port)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>#include &lt;9pclient.h&gt;
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>CFid &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*plumbopenfid(char *port, int omode)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>Plumbmsg* &nbsp;&nbsp;&nbsp;plumbrecvfid(CFid *fid)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>int &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;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 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*src;<br>
char &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*dst;<br>
char &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*wdir;<br>
char &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*type;<br>
Plumbattr *attr;<br>
int &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ndata;<br>
char &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*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 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*name;<br>
char &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*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(&quot;send&quot;, 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(&quot;send&quot;,
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>