257 lines
13 KiB
HTML
257 lines
13 KiB
HTML
<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>
|