tplumb.3 - plan9port - [fork] Plan 9 from user space
(HTM) git clone git://src.adamsgaard.dk/plan9port
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
tplumb.3 (6105B)
---
1 .TH PLUMB 3
2 .SH NAME
3 eplumb, plumbfree, plumbopen, plumbunmount, plumbopenfid, plumbsend, plumbsendtofid, plumbsendtext, plumblookup, plumbpack, plumbpackattr, plumbaddattr, plumbdelattr, plumbrecv, plumbrecvfid, plumbunpack, plumbunpackpartial, plumbunpackattr, Plumbmsg \- plumb messages
4 .SH SYNOPSIS
5 .B #include <u.h>
6 .br
7 .B #include <libc.h>
8 .br
9 .B #include <plumb.h>
10 .PP
11 .ta \w'\fLPlumbattr* 'u
12 .PP
13 .B
14 int plumbopen(char *port, int omode)
15 .PP
16 .B
17 int plumbunmount(void)
18 .PP
19 .B
20 int plumbsend(int fd, Plumbmsg *m)
21 .PP
22 .B
23 int plumbsendtext(int fd, char *src, char *dst, char *wdir, char *data)
24 .PP
25 .B
26 void plumbfree(Plumbmsg *m)
27 .PP
28 .B
29 Plumbmsg* plumbrecv(int fd)
30 .PP
31 .B
32 char* plumbpack(Plumbmsg *m, int *np)
33 .PP
34 .B
35 Plumbmsg* plumbunpack(char *buf, int n)
36 .PP
37 .B
38 Plumbmsg* plumbunpackpartial(char *buf, int n, int *morep)
39 .PP
40 .B
41 char* plumbpackattr(Plumbattr *a)
42 .PP
43 .B
44 Plumbattr* plumbunpackattr(char *a)
45 .PP
46 .B
47 char* plumblookup(Plumbattr *a, char *name)
48 .PP
49 .B
50 Plumbattr* plumbaddattr(Plumbattr *a, Plumbattr *new)
51 .PP
52 .B
53 Plumbattr* plumbdelattr(Plumbattra *a, char *name)
54 .PP
55 .B
56 int eplumb(int key, char *port)
57 .PP
58 .B
59 #include <9pclient.h>
60 .PP
61 .B
62 CFid *plumbopenfid(char *port, int omode)
63 .PP
64 .B
65 Plumbmsg* plumbrecvfid(CFid *fid)
66 .PP
67 .B
68 int plumbsendtofid(CFid *fid, Plumbmsg *m)
69 .SH DESCRIPTION
70 These routines manipulate
71 .MR plumb (7)
72 messages, transmitting them, receiving them, and
73 converting them between text and these data structures:
74 .IP
75 .EX
76 .ta 6n +\w'\fLPlumbattr 'u +\w'ndata; 'u
77 typedef
78 struct Plumbmsg
79 {
80 char *src;
81 char *dst;
82 char *wdir;
83 char *type;
84 Plumbattr *attr;
85 int ndata;
86 char *data;
87 } Plumbmsg;
88
89 typedef
90 struct Plumbattr
91 {
92 char *name;
93 char *value;
94 Plumbattr *next;
95 } Plumbattr;
96 .EE
97 .PP
98 .I Plumbopen
99 opens the named plumb
100 .IR port ,
101 using
102 .MR open (3)
103 mode
104 .IR omode .
105 If
106 .I port
107 begins with a slash, it is taken as a literal file name;
108 otherwise
109 .I plumbopen
110 searches for the location of the
111 .MR plumber (4)
112 service and opens the port there.
113 .PP
114 For programs using the
115 .MR event (3)
116 interface,
117 .I eplumb
118 registers, using the given
119 .IR key ,
120 receipt of messages from the named
121 .IR port .
122 .PP
123 The library mounts the
124 .MR plumber (4)
125 service on demand (using the
126 .MR 9pclient (3) )
127 library and reuses the mount instance for future
128 calls to
129 .IR plumbopen .
130 .I Plumbunmount
131 causes the library to discard its cached mount.
132 This can be useful if the plumber service itself has been
133 restarted and a client wishes to reconnect.
134 .PP
135 .I Plumbsend
136 formats and writes message
137 .I m
138 to the file descriptor
139 .IR fd ,
140 which will usually be the result of
141 .B plumbopen("send",
142 .BR OWRITE) .
143 .I Plumbsendtext
144 is a simplified version for text-only messages; it assumes
145 .B type
146 is
147 .BR text ,
148 sets
149 .B attr
150 to nil,
151 and sets
152 .B ndata
153 to
154 .BI strlen( data )\f1.
155 .PP
156 .I Plumbfree
157 frees all the data associated with the message
158 .IR m ,
159 all the components of which must therefore have been allocated with
160 .MR malloc (3) .
161 .PP
162 .I Plumbrecv
163 returns the next message available on the file descriptor
164 .IR fd ,
165 or nil for error.
166 .PP
167 .I Plumbpack
168 encodes message
169 .I m
170 as a character string in the format of
171 .IR plumb (7) ,
172 setting
173 .BI * np
174 to the length in bytes of the string.
175 .I Plumbunpack
176 does the inverse, translating the
177 .I n
178 bytes of
179 .I buf
180 into a
181 .BR Plumbmsg .
182 .PP
183 .I Plumbunpackpartial
184 enables unpacking of messages that arrive in pieces.
185 The first call to
186 .I plumbunpackpartial
187 for a given message must be sufficient to unpack the header;
188 subsequent calls permit unpacking messages with long data sections.
189 For each call,
190 .I buf
191 points to the beginning of the complete message received so far, and
192 .I n
193 reports the total number of bytes received for that message.
194 If the message is complete, the return value will be as in
195 .IR plumbunpack .
196 If not, and
197 .I morep
198 is not null, the return value will be
199 .B nil
200 and
201 .BR * morep
202 will be set to the number of bytes remaining to be read for this message to be complete
203 (recall that the byte count is in the header).
204 Those bytes should be read by the caller, placed at location
205 .IB buf + n \f1,
206 and the message unpacked again.
207 If an error is encountered, the return value will be
208 .B nil
209 and
210 .BI * morep
211 will be zero.
212 .PP
213 .I Plumbpackattr
214 converts the list
215 .I a
216 of
217 .B Plumbattr
218 structures into a null-terminated string.
219 If an attribute value contains white space, quote characters, or equal signs,
220 the value will be quoted appropriately.
221 A newline character will terminate processing.
222 .I Plumbunpackattr
223 converts the null-terminated string
224 .I a
225 back into a list of
226 .I Plumbattr
227 structures.
228 .PP
229 .I Plumblookup
230 searches the
231 .B Plumbattr
232 list
233 .I a
234 for an attribute with the given
235 .I name
236 and returns the associated value.
237 The returned string is the original value, not a copy.
238 If the attribute has no value, the returned value will be the empty string;
239 if the attribute does not occur in the list at all, the value will be nil.
240 .PP
241 .I Plumbaddattr
242 appends the
243 .I new
244 .B Plumbattr
245 (which may be a list) to the attribute list
246 .IR a
247 and returns the new list.
248 .I Plumbattr
249 searches the list
250 .I a
251 for the first attribute with name
252 .I name
253 and deletes it from the list, returning the resulting list.
254 .I Plumbdelattr
255 is a no-op if no such attribute exists.
256 .PP
257 The file descriptor returned by
258 .I plumbopen
259 is created with
260 .I fsopenfd
261 (see
262 .MR 9pclient (3) ),
263 which masks information about read and write errors.
264 This is acceptable for use in
265 .I plumbrecv
266 but not for
267 .IR plumbsend ,
268 which depends on seeing details of write errors.
269 .IR Plumbopenfid ,
270 .IR plumbrecvfid ,
271 and
272 .IR plumbsendtofid
273 provide an explicit interface to
274 .I lib9pclient
275 that preserves the exact error details.
276 .SH SOURCE
277 .B \*9/src/libplumb
278 .SH SEE ALSO
279 .MR plumb (1) ,
280 .MR event (3) ,
281 .MR plumber (4) ,
282 .MR plumb (7)
283 .SH DIAGNOSTICS
284 When appropriate, including when a
285 .I plumbsend
286 fails, these routine set
287 .IR errstr .
288 .SH BUGS
289 To avoid rewriting clients that use
290 .IR plumbsend ,
291 the call
292 .B plumbopen("send",
293 .B OWRITE)
294 returns a useless file descriptor
295 (it is opened to
296 .BR /dev/null ).
297 .I Plumbsend
298 looks for this particular file descriptor
299 and uses a static copy of the
300 .B CFid
301 instead.