1 cfa37a7b 2004-04-10 devnull .TH PLUMB 3
3 058b0118 2005-01-03 devnull eplumb, plumbfree, plumbopen, 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 cfa37a7b 2004-04-10 devnull int plumbsend(int fd, Plumbmsg *m)
20 cfa37a7b 2004-04-10 devnull int plumbsendtext(int fd, char *src, char *dst, char *wdir, char *data)
23 cfa37a7b 2004-04-10 devnull void plumbfree(Plumbmsg *m)
26 cfa37a7b 2004-04-10 devnull Plumbmsg* plumbrecv(int fd)
29 cfa37a7b 2004-04-10 devnull char* plumbpack(Plumbmsg *m, int *np)
32 cfa37a7b 2004-04-10 devnull Plumbmsg* plumbunpack(char *buf, int n)
35 cfa37a7b 2004-04-10 devnull Plumbmsg* plumbunpackpartial(char *buf, int n, int *morep)
38 cfa37a7b 2004-04-10 devnull char* plumbpackattr(Plumbattr *a)
41 cfa37a7b 2004-04-10 devnull Plumbattr* plumbunpackattr(char *a)
44 cfa37a7b 2004-04-10 devnull char* plumblookup(Plumbattr *a, char *name)
47 cfa37a7b 2004-04-10 devnull Plumbattr* plumbaddattr(Plumbattr *a, Plumbattr *new)
50 cfa37a7b 2004-04-10 devnull Plumbattr* plumbdelattr(Plumbattra *a, char *name)
53 cfa37a7b 2004-04-10 devnull int eplumb(int key, char *port)
56 058b0118 2005-01-03 devnull #include <9pclient.h>
59 058b0118 2005-01-03 devnull CFid *plumbopenfid(char *port, int omode)
62 058b0118 2005-01-03 devnull Plumbmsg* plumbrecvfid(CFid *fid)
65 058b0118 2005-01-03 devnull int plumbsendtofid(CFid *fid, Plumbmsg *m)
66 cfa37a7b 2004-04-10 devnull .SH DESCRIPTION
67 cfa37a7b 2004-04-10 devnull These routines manipulate
68 058b0118 2005-01-03 devnull .IR plumb (7)
69 cfa37a7b 2004-04-10 devnull messages, transmitting them, receiving them, and
70 cfa37a7b 2004-04-10 devnull converting them between text and these data structures:
73 cfa37a7b 2004-04-10 devnull .ta 6n +\w'\fLPlumbattr 'u +\w'ndata; 'u
75 cfa37a7b 2004-04-10 devnull struct Plumbmsg
77 cfa37a7b 2004-04-10 devnull char *src;
78 cfa37a7b 2004-04-10 devnull char *dst;
79 cfa37a7b 2004-04-10 devnull char *wdir;
80 cfa37a7b 2004-04-10 devnull char *type;
81 cfa37a7b 2004-04-10 devnull Plumbattr *attr;
82 cfa37a7b 2004-04-10 devnull int ndata;
83 cfa37a7b 2004-04-10 devnull char *data;
84 cfa37a7b 2004-04-10 devnull } Plumbmsg;
87 cfa37a7b 2004-04-10 devnull struct Plumbattr
89 cfa37a7b 2004-04-10 devnull char *name;
90 cfa37a7b 2004-04-10 devnull char *value;
91 cfa37a7b 2004-04-10 devnull Plumbattr *next;
92 cfa37a7b 2004-04-10 devnull } Plumbattr;
95 cfa37a7b 2004-04-10 devnull .I Plumbopen
96 cfa37a7b 2004-04-10 devnull opens the named plumb
97 cfa37a7b 2004-04-10 devnull .IR port ,
99 bf8a59fa 2004-04-11 devnull .IR open (3)
101 cfa37a7b 2004-04-10 devnull .IR omode .
104 cfa37a7b 2004-04-10 devnull begins with a slash, it is taken as a literal file name;
105 cfa37a7b 2004-04-10 devnull otherwise
106 cfa37a7b 2004-04-10 devnull .I plumbopen
107 cfa37a7b 2004-04-10 devnull searches for the location of the
108 cfa37a7b 2004-04-10 devnull .IR plumber (4)
109 cfa37a7b 2004-04-10 devnull service and opens the port there.
111 cfa37a7b 2004-04-10 devnull For programs using the
112 bf8a59fa 2004-04-11 devnull .IR event (3)
113 cfa37a7b 2004-04-10 devnull interface,
114 cfa37a7b 2004-04-10 devnull .I eplumb
115 cfa37a7b 2004-04-10 devnull registers, using the given
116 cfa37a7b 2004-04-10 devnull .IR key ,
117 cfa37a7b 2004-04-10 devnull receipt of messages from the named
118 cfa37a7b 2004-04-10 devnull .IR port .
120 cfa37a7b 2004-04-10 devnull .I Plumbsend
121 cfa37a7b 2004-04-10 devnull formats and writes message
123 cfa37a7b 2004-04-10 devnull to the file descriptor
124 cfa37a7b 2004-04-10 devnull .IR fd ,
125 cfa37a7b 2004-04-10 devnull which will usually be the result of
126 cfa37a7b 2004-04-10 devnull .B plumbopen("send",
127 cfa37a7b 2004-04-10 devnull .BR OWRITE) .
128 cfa37a7b 2004-04-10 devnull .I Plumbsendtext
129 cfa37a7b 2004-04-10 devnull is a simplified version for text-only messages; it assumes
132 cfa37a7b 2004-04-10 devnull .BR text ,
136 cfa37a7b 2004-04-10 devnull and sets
137 cfa37a7b 2004-04-10 devnull .B ndata
139 cfa37a7b 2004-04-10 devnull .BI strlen( data )\f1.
141 cfa37a7b 2004-04-10 devnull .I Plumbfree
142 cfa37a7b 2004-04-10 devnull frees all the data associated with the message
144 cfa37a7b 2004-04-10 devnull all the components of which must therefore have been allocated with
145 bf8a59fa 2004-04-11 devnull .IR malloc (3).
147 cfa37a7b 2004-04-10 devnull .I Plumbrecv
148 cfa37a7b 2004-04-10 devnull returns the next message available on the file descriptor
149 cfa37a7b 2004-04-10 devnull .IR fd ,
150 cfa37a7b 2004-04-10 devnull or nil for error.
152 cfa37a7b 2004-04-10 devnull .I Plumbpack
153 cfa37a7b 2004-04-10 devnull encodes message
155 cfa37a7b 2004-04-10 devnull as a character string in the format of
156 058b0118 2005-01-03 devnull .IR plumb (7) ,
158 cfa37a7b 2004-04-10 devnull .BI * np
159 cfa37a7b 2004-04-10 devnull to the length in bytes of the string.
160 cfa37a7b 2004-04-10 devnull .I Plumbunpack
161 cfa37a7b 2004-04-10 devnull does the inverse, translating the
163 cfa37a7b 2004-04-10 devnull bytes of
166 cfa37a7b 2004-04-10 devnull .BR Plumbmsg .
168 cfa37a7b 2004-04-10 devnull .I Plumbunpackpartial
169 cfa37a7b 2004-04-10 devnull enables unpacking of messages that arrive in pieces.
170 cfa37a7b 2004-04-10 devnull The first call to
171 cfa37a7b 2004-04-10 devnull .I plumbunpackpartial
172 cfa37a7b 2004-04-10 devnull for a given message must be sufficient to unpack the header;
173 cfa37a7b 2004-04-10 devnull subsequent calls permit unpacking messages with long data sections.
174 cfa37a7b 2004-04-10 devnull For each call,
176 cfa37a7b 2004-04-10 devnull points to the beginning of the complete message received so far, and
178 cfa37a7b 2004-04-10 devnull reports the total number of bytes received for that message.
179 cfa37a7b 2004-04-10 devnull If the message is complete, the return value will be as in
180 cfa37a7b 2004-04-10 devnull .IR plumbunpack .
181 cfa37a7b 2004-04-10 devnull If not, and
182 cfa37a7b 2004-04-10 devnull .I morep
183 cfa37a7b 2004-04-10 devnull is not null, the return value will be
186 cfa37a7b 2004-04-10 devnull .BR * morep
187 cfa37a7b 2004-04-10 devnull will be set to the number of bytes remaining to be read for this message to be complete
188 cfa37a7b 2004-04-10 devnull (recall that the byte count is in the header).
189 cfa37a7b 2004-04-10 devnull Those bytes should be read by the caller, placed at location
190 cfa37a7b 2004-04-10 devnull .IB buf + n \f1,
191 cfa37a7b 2004-04-10 devnull and the message unpacked again.
192 cfa37a7b 2004-04-10 devnull If an error is encountered, the return value will be
195 cfa37a7b 2004-04-10 devnull .BI * morep
196 cfa37a7b 2004-04-10 devnull will be zero.
198 cfa37a7b 2004-04-10 devnull .I Plumbpackattr
199 cfa37a7b 2004-04-10 devnull converts the list
202 cfa37a7b 2004-04-10 devnull .B Plumbattr
203 cfa37a7b 2004-04-10 devnull structures into a null-terminated string.
204 cfa37a7b 2004-04-10 devnull If an attribute value contains white space, quote characters, or equal signs,
205 cfa37a7b 2004-04-10 devnull the value will be quoted appropriately.
206 cfa37a7b 2004-04-10 devnull A newline character will terminate processing.
207 cfa37a7b 2004-04-10 devnull .I Plumbunpackattr
208 cfa37a7b 2004-04-10 devnull converts the null-terminated string
210 cfa37a7b 2004-04-10 devnull back into a list of
211 cfa37a7b 2004-04-10 devnull .I Plumbattr
212 cfa37a7b 2004-04-10 devnull structures.
214 cfa37a7b 2004-04-10 devnull .I Plumblookup
215 cfa37a7b 2004-04-10 devnull searches the
216 cfa37a7b 2004-04-10 devnull .B Plumbattr
219 cfa37a7b 2004-04-10 devnull for an attribute with the given
221 cfa37a7b 2004-04-10 devnull and returns the associated value.
222 cfa37a7b 2004-04-10 devnull The returned string is the original value, not a copy.
223 cfa37a7b 2004-04-10 devnull If the attribute has no value, the returned value will be the empty string;
224 cfa37a7b 2004-04-10 devnull if the attribute does not occur in the list at all, the value will be nil.
226 cfa37a7b 2004-04-10 devnull .I Plumbaddattr
227 cfa37a7b 2004-04-10 devnull appends the
229 cfa37a7b 2004-04-10 devnull .B Plumbattr
230 cfa37a7b 2004-04-10 devnull (which may be a list) to the attribute list
232 cfa37a7b 2004-04-10 devnull and returns the new list.
233 cfa37a7b 2004-04-10 devnull .I Plumbattr
234 cfa37a7b 2004-04-10 devnull searches the list
236 cfa37a7b 2004-04-10 devnull for the first attribute with name
238 cfa37a7b 2004-04-10 devnull and deletes it from the list, returning the resulting list.
239 cfa37a7b 2004-04-10 devnull .I Plumbdelattr
240 cfa37a7b 2004-04-10 devnull is a no-op if no such attribute exists.
242 058b0118 2005-01-03 devnull The file descriptor returned by
243 058b0118 2005-01-03 devnull .I plumbopen
244 058b0118 2005-01-03 devnull is created with
245 058b0118 2005-01-03 devnull .I fsopenfd
247 058b0118 2005-01-03 devnull .IR 9pclient (3)),
248 058b0118 2005-01-03 devnull which masks information about read and write errors.
249 058b0118 2005-01-03 devnull This is acceptable for use in
250 058b0118 2005-01-03 devnull .I plumbrecv
251 058b0118 2005-01-03 devnull but not for
252 058b0118 2005-01-03 devnull .IR plumbsend ,
253 058b0118 2005-01-03 devnull which depends on seeing details of write errors.
254 058b0118 2005-01-03 devnull .IR Plumbopenfid ,
255 058b0118 2005-01-03 devnull .IR plumbrecvfid ,
257 058b0118 2005-01-03 devnull .IR plumbsendtofid
258 058b0118 2005-01-03 devnull provide an explicit interface to
259 058b0118 2005-01-03 devnull .I lib9pclient
260 058b0118 2005-01-03 devnull that preserves the exact error details.
261 cfa37a7b 2004-04-10 devnull .SH SOURCE
262 c3674de4 2005-01-11 devnull .B \*9/src/libplumb
263 cfa37a7b 2004-04-10 devnull .SH SEE ALSO
264 cfa37a7b 2004-04-10 devnull .IR plumb (1),
265 bf8a59fa 2004-04-11 devnull .IR event (3),
266 cfa37a7b 2004-04-10 devnull .IR plumber (4),
267 058b0118 2005-01-03 devnull .IR plumb (7)
268 cfa37a7b 2004-04-10 devnull .SH DIAGNOSTICS
269 cfa37a7b 2004-04-10 devnull When appropriate, including when a
270 cfa37a7b 2004-04-10 devnull .I plumbsend
271 cfa37a7b 2004-04-10 devnull fails, these routine set
272 cfa37a7b 2004-04-10 devnull .IR errstr .
273 058b0118 2005-01-03 devnull .SH BUGS
274 058b0118 2005-01-03 devnull To avoid rewriting clients that use
275 058b0118 2005-01-03 devnull .IR plumbsend ,
276 058b0118 2005-01-03 devnull the call
277 058b0118 2005-01-03 devnull .B plumbopen("send",
278 058b0118 2005-01-03 devnull .B OWRITE)
279 058b0118 2005-01-03 devnull returns a useless file descriptor
280 058b0118 2005-01-03 devnull (it is opened to
281 058b0118 2005-01-03 devnull .BR /dev/null ).
282 058b0118 2005-01-03 devnull .I Plumbsend
283 058b0118 2005-01-03 devnull looks for this particular file descriptor
284 058b0118 2005-01-03 devnull and uses a static copy of the
286 058b0118 2005-01-03 devnull instead.
