1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
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>
|