1 cfa37a7b 2004-04-10 devnull .TH PLUMB 3
3 1dc6e083 2006-06-25 devnull eplumb, plumbfree, plumbopen, plumbunmount, plumbopenfid, plumbsend, plumbsendtofid, plumbsendtext, plumblookup, plumbpack, plumbpackattr, plumbaddattr, plumbdelattr, plumbrecv, plumbrecvfid, plumbunpack, plumbunpackpartial, plumbunpackattr, Plumbmsg \- plumb messages
4 cfa37a7b 2004-04-10 devnull .SH SYNOPSIS
5 cfa37a7b 2004-04-10 devnull .B #include <u.h>
7 cfa37a7b 2004-04-10 devnull .B #include <libc.h>
9 cfa37a7b 2004-04-10 devnull .B #include <plumb.h>
11 cfa37a7b 2004-04-10 devnull .ta \w'\fLPlumbattr* 'u
14 cfa37a7b 2004-04-10 devnull int plumbopen(char *port, int omode)
17 1dc6e083 2006-06-25 devnull int plumbunmount(void)
20 cfa37a7b 2004-04-10 devnull int plumbsend(int fd, Plumbmsg *m)
23 cfa37a7b 2004-04-10 devnull int plumbsendtext(int fd, char *src, char *dst, char *wdir, char *data)
26 cfa37a7b 2004-04-10 devnull void plumbfree(Plumbmsg *m)
29 cfa37a7b 2004-04-10 devnull Plumbmsg* plumbrecv(int fd)
32 cfa37a7b 2004-04-10 devnull char* plumbpack(Plumbmsg *m, int *np)
35 cfa37a7b 2004-04-10 devnull Plumbmsg* plumbunpack(char *buf, int n)
38 cfa37a7b 2004-04-10 devnull Plumbmsg* plumbunpackpartial(char *buf, int n, int *morep)
41 cfa37a7b 2004-04-10 devnull char* plumbpackattr(Plumbattr *a)
44 cfa37a7b 2004-04-10 devnull Plumbattr* plumbunpackattr(char *a)
47 cfa37a7b 2004-04-10 devnull char* plumblookup(Plumbattr *a, char *name)
50 cfa37a7b 2004-04-10 devnull Plumbattr* plumbaddattr(Plumbattr *a, Plumbattr *new)
53 cfa37a7b 2004-04-10 devnull Plumbattr* plumbdelattr(Plumbattra *a, char *name)
56 cfa37a7b 2004-04-10 devnull int eplumb(int key, char *port)
59 058b0118 2005-01-03 devnull #include <9pclient.h>
62 058b0118 2005-01-03 devnull CFid *plumbopenfid(char *port, int omode)
65 058b0118 2005-01-03 devnull Plumbmsg* plumbrecvfid(CFid *fid)
68 058b0118 2005-01-03 devnull int plumbsendtofid(CFid *fid, Plumbmsg *m)
69 cfa37a7b 2004-04-10 devnull .SH DESCRIPTION
70 cfa37a7b 2004-04-10 devnull These routines manipulate
71 d32deab1 2020-08-16 rsc .MR plumb (7)
72 cfa37a7b 2004-04-10 devnull messages, transmitting them, receiving them, and
73 cfa37a7b 2004-04-10 devnull converting them between text and these data structures:
76 cfa37a7b 2004-04-10 devnull .ta 6n +\w'\fLPlumbattr 'u +\w'ndata; 'u
78 cfa37a7b 2004-04-10 devnull struct Plumbmsg
80 cfa37a7b 2004-04-10 devnull char *src;
81 cfa37a7b 2004-04-10 devnull char *dst;
82 cfa37a7b 2004-04-10 devnull char *wdir;
83 cfa37a7b 2004-04-10 devnull char *type;
84 cfa37a7b 2004-04-10 devnull Plumbattr *attr;
85 cfa37a7b 2004-04-10 devnull int ndata;
86 cfa37a7b 2004-04-10 devnull char *data;
87 cfa37a7b 2004-04-10 devnull } Plumbmsg;
90 cfa37a7b 2004-04-10 devnull struct Plumbattr
92 cfa37a7b 2004-04-10 devnull char *name;
93 cfa37a7b 2004-04-10 devnull char *value;
94 cfa37a7b 2004-04-10 devnull Plumbattr *next;
95 cfa37a7b 2004-04-10 devnull } Plumbattr;
98 cfa37a7b 2004-04-10 devnull .I Plumbopen
99 cfa37a7b 2004-04-10 devnull opens the named plumb
100 cfa37a7b 2004-04-10 devnull .IR port ,
102 d32deab1 2020-08-16 rsc .MR open (3)
104 cfa37a7b 2004-04-10 devnull .IR omode .
107 cfa37a7b 2004-04-10 devnull begins with a slash, it is taken as a literal file name;
108 cfa37a7b 2004-04-10 devnull otherwise
109 cfa37a7b 2004-04-10 devnull .I plumbopen
110 cfa37a7b 2004-04-10 devnull searches for the location of the
111 d32deab1 2020-08-16 rsc .MR plumber (4)
112 cfa37a7b 2004-04-10 devnull service and opens the port there.
114 cfa37a7b 2004-04-10 devnull For programs using the
115 d32deab1 2020-08-16 rsc .MR event (3)
116 cfa37a7b 2004-04-10 devnull interface,
117 cfa37a7b 2004-04-10 devnull .I eplumb
118 cfa37a7b 2004-04-10 devnull registers, using the given
119 cfa37a7b 2004-04-10 devnull .IR key ,
120 cfa37a7b 2004-04-10 devnull receipt of messages from the named
121 cfa37a7b 2004-04-10 devnull .IR port .
123 1dc6e083 2006-06-25 devnull The library mounts the
124 d32deab1 2020-08-16 rsc .MR plumber (4)
125 1dc6e083 2006-06-25 devnull service on demand (using the
126 d32deab1 2020-08-16 rsc .MR 9pclient (3) )
127 1dc6e083 2006-06-25 devnull library and reuses the mount instance for future
128 1dc6e083 2006-06-25 devnull calls to
129 1dc6e083 2006-06-25 devnull .IR plumbopen .
130 1dc6e083 2006-06-25 devnull .I Plumbunmount
131 1dc6e083 2006-06-25 devnull causes the library to discard its cached mount.
132 1dc6e083 2006-06-25 devnull This can be useful if the plumber service itself has been
133 1dc6e083 2006-06-25 devnull restarted and a client wishes to reconnect.
135 cfa37a7b 2004-04-10 devnull .I Plumbsend
136 cfa37a7b 2004-04-10 devnull formats and writes message
138 cfa37a7b 2004-04-10 devnull to the file descriptor
139 cfa37a7b 2004-04-10 devnull .IR fd ,
140 cfa37a7b 2004-04-10 devnull which will usually be the result of
141 cfa37a7b 2004-04-10 devnull .B plumbopen("send",
142 cfa37a7b 2004-04-10 devnull .BR OWRITE) .
143 cfa37a7b 2004-04-10 devnull .I Plumbsendtext
144 cfa37a7b 2004-04-10 devnull is a simplified version for text-only messages; it assumes
147 cfa37a7b 2004-04-10 devnull .BR text ,
151 cfa37a7b 2004-04-10 devnull and sets
152 cfa37a7b 2004-04-10 devnull .B ndata
154 cfa37a7b 2004-04-10 devnull .BI strlen( data )\f1.
156 cfa37a7b 2004-04-10 devnull .I Plumbfree
157 cfa37a7b 2004-04-10 devnull frees all the data associated with the message
159 cfa37a7b 2004-04-10 devnull all the components of which must therefore have been allocated with
160 d32deab1 2020-08-16 rsc .MR malloc (3) .
162 cfa37a7b 2004-04-10 devnull .I Plumbrecv
163 cfa37a7b 2004-04-10 devnull returns the next message available on the file descriptor
164 cfa37a7b 2004-04-10 devnull .IR fd ,
165 cfa37a7b 2004-04-10 devnull or nil for error.
167 cfa37a7b 2004-04-10 devnull .I Plumbpack
168 cfa37a7b 2004-04-10 devnull encodes message
170 cfa37a7b 2004-04-10 devnull as a character string in the format of
171 058b0118 2005-01-03 devnull .IR plumb (7) ,
173 cfa37a7b 2004-04-10 devnull .BI * np
174 cfa37a7b 2004-04-10 devnull to the length in bytes of the string.
175 cfa37a7b 2004-04-10 devnull .I Plumbunpack
176 cfa37a7b 2004-04-10 devnull does the inverse, translating the
178 cfa37a7b 2004-04-10 devnull bytes of
181 cfa37a7b 2004-04-10 devnull .BR Plumbmsg .
183 cfa37a7b 2004-04-10 devnull .I Plumbunpackpartial
184 cfa37a7b 2004-04-10 devnull enables unpacking of messages that arrive in pieces.
185 cfa37a7b 2004-04-10 devnull The first call to
186 cfa37a7b 2004-04-10 devnull .I plumbunpackpartial
187 cfa37a7b 2004-04-10 devnull for a given message must be sufficient to unpack the header;
188 cfa37a7b 2004-04-10 devnull subsequent calls permit unpacking messages with long data sections.
189 cfa37a7b 2004-04-10 devnull For each call,
191 cfa37a7b 2004-04-10 devnull points to the beginning of the complete message received so far, and
193 cfa37a7b 2004-04-10 devnull reports the total number of bytes received for that message.
194 cfa37a7b 2004-04-10 devnull If the message is complete, the return value will be as in
195 cfa37a7b 2004-04-10 devnull .IR plumbunpack .
196 cfa37a7b 2004-04-10 devnull If not, and
197 cfa37a7b 2004-04-10 devnull .I morep
198 cfa37a7b 2004-04-10 devnull is not null, the return value will be
201 cfa37a7b 2004-04-10 devnull .BR * morep
202 cfa37a7b 2004-04-10 devnull will be set to the number of bytes remaining to be read for this message to be complete
203 cfa37a7b 2004-04-10 devnull (recall that the byte count is in the header).
204 cfa37a7b 2004-04-10 devnull Those bytes should be read by the caller, placed at location
205 cfa37a7b 2004-04-10 devnull .IB buf + n \f1,
206 cfa37a7b 2004-04-10 devnull and the message unpacked again.
207 cfa37a7b 2004-04-10 devnull If an error is encountered, the return value will be
210 cfa37a7b 2004-04-10 devnull .BI * morep
211 cfa37a7b 2004-04-10 devnull will be zero.
213 cfa37a7b 2004-04-10 devnull .I Plumbpackattr
214 cfa37a7b 2004-04-10 devnull converts the list
217 cfa37a7b 2004-04-10 devnull .B Plumbattr
218 cfa37a7b 2004-04-10 devnull structures into a null-terminated string.
219 cfa37a7b 2004-04-10 devnull If an attribute value contains white space, quote characters, or equal signs,
220 cfa37a7b 2004-04-10 devnull the value will be quoted appropriately.
221 cfa37a7b 2004-04-10 devnull A newline character will terminate processing.
222 cfa37a7b 2004-04-10 devnull .I Plumbunpackattr
223 cfa37a7b 2004-04-10 devnull converts the null-terminated string
225 cfa37a7b 2004-04-10 devnull back into a list of
226 cfa37a7b 2004-04-10 devnull .I Plumbattr
227 cfa37a7b 2004-04-10 devnull structures.
229 cfa37a7b 2004-04-10 devnull .I Plumblookup
230 cfa37a7b 2004-04-10 devnull searches the
231 cfa37a7b 2004-04-10 devnull .B Plumbattr
234 cfa37a7b 2004-04-10 devnull for an attribute with the given
236 cfa37a7b 2004-04-10 devnull and returns the associated value.
237 cfa37a7b 2004-04-10 devnull The returned string is the original value, not a copy.
238 cfa37a7b 2004-04-10 devnull If the attribute has no value, the returned value will be the empty string;
239 cfa37a7b 2004-04-10 devnull if the attribute does not occur in the list at all, the value will be nil.
241 cfa37a7b 2004-04-10 devnull .I Plumbaddattr
242 cfa37a7b 2004-04-10 devnull appends the
244 cfa37a7b 2004-04-10 devnull .B Plumbattr
245 cfa37a7b 2004-04-10 devnull (which may be a list) to the attribute list
247 cfa37a7b 2004-04-10 devnull and returns the new list.
248 cfa37a7b 2004-04-10 devnull .I Plumbattr
249 cfa37a7b 2004-04-10 devnull searches the list
251 cfa37a7b 2004-04-10 devnull for the first attribute with name
253 cfa37a7b 2004-04-10 devnull and deletes it from the list, returning the resulting list.
254 cfa37a7b 2004-04-10 devnull .I Plumbdelattr
255 cfa37a7b 2004-04-10 devnull is a no-op if no such attribute exists.
257 058b0118 2005-01-03 devnull The file descriptor returned by
258 058b0118 2005-01-03 devnull .I plumbopen
259 058b0118 2005-01-03 devnull is created with
260 058b0118 2005-01-03 devnull .I fsopenfd
262 d32deab1 2020-08-16 rsc .MR 9pclient (3) ),
263 058b0118 2005-01-03 devnull which masks information about read and write errors.
264 058b0118 2005-01-03 devnull This is acceptable for use in
265 058b0118 2005-01-03 devnull .I plumbrecv
266 058b0118 2005-01-03 devnull but not for
267 058b0118 2005-01-03 devnull .IR plumbsend ,
268 058b0118 2005-01-03 devnull which depends on seeing details of write errors.
269 058b0118 2005-01-03 devnull .IR Plumbopenfid ,
270 058b0118 2005-01-03 devnull .IR plumbrecvfid ,
272 058b0118 2005-01-03 devnull .IR plumbsendtofid
273 058b0118 2005-01-03 devnull provide an explicit interface to
274 058b0118 2005-01-03 devnull .I lib9pclient
275 058b0118 2005-01-03 devnull that preserves the exact error details.
276 cfa37a7b 2004-04-10 devnull .SH SOURCE
277 c3674de4 2005-01-11 devnull .B \*9/src/libplumb
278 cfa37a7b 2004-04-10 devnull .SH SEE ALSO
279 d32deab1 2020-08-16 rsc .MR plumb (1) ,
280 d32deab1 2020-08-16 rsc .MR event (3) ,
281 d32deab1 2020-08-16 rsc .MR plumber (4) ,
282 d32deab1 2020-08-16 rsc .MR plumb (7)
283 cfa37a7b 2004-04-10 devnull .SH DIAGNOSTICS
284 cfa37a7b 2004-04-10 devnull When appropriate, including when a
285 cfa37a7b 2004-04-10 devnull .I plumbsend
286 cfa37a7b 2004-04-10 devnull fails, these routine set
287 cfa37a7b 2004-04-10 devnull .IR errstr .
288 058b0118 2005-01-03 devnull .SH BUGS
289 058b0118 2005-01-03 devnull To avoid rewriting clients that use
290 058b0118 2005-01-03 devnull .IR plumbsend ,
291 058b0118 2005-01-03 devnull the call
292 058b0118 2005-01-03 devnull .B plumbopen("send",
293 058b0118 2005-01-03 devnull .B OWRITE)
294 058b0118 2005-01-03 devnull returns a useless file descriptor
295 058b0118 2005-01-03 devnull (it is opened to
296 058b0118 2005-01-03 devnull .BR /dev/null ).
297 058b0118 2005-01-03 devnull .I Plumbsend
298 058b0118 2005-01-03 devnull looks for this particular file descriptor
299 058b0118 2005-01-03 devnull and uses a static copy of the
301 058b0118 2005-01-03 devnull instead.
