1 cfa37a7b 2004-04-10 devnull .TH PLUMB 3
3 cfa37a7b 2004-04-10 devnull eplumb, plumbfree, plumbopen, plumbsend, plumbsendtext, plumblookup, plumbpack, plumbpackattr, plumbaddattr, plumbdelattr, plumbrecv, 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)
54 cfa37a7b 2004-04-10 devnull .SH DESCRIPTION
55 cfa37a7b 2004-04-10 devnull These routines manipulate
56 cfa37a7b 2004-04-10 devnull .IR plumb (6)
57 cfa37a7b 2004-04-10 devnull messages, transmitting them, receiving them, and
58 cfa37a7b 2004-04-10 devnull converting them between text and these data structures:
61 cfa37a7b 2004-04-10 devnull .ta 6n +\w'\fLPlumbattr 'u +\w'ndata; 'u
63 cfa37a7b 2004-04-10 devnull struct Plumbmsg
65 cfa37a7b 2004-04-10 devnull char *src;
66 cfa37a7b 2004-04-10 devnull char *dst;
67 cfa37a7b 2004-04-10 devnull char *wdir;
68 cfa37a7b 2004-04-10 devnull char *type;
69 cfa37a7b 2004-04-10 devnull Plumbattr *attr;
70 cfa37a7b 2004-04-10 devnull int ndata;
71 cfa37a7b 2004-04-10 devnull char *data;
72 cfa37a7b 2004-04-10 devnull } Plumbmsg;
75 cfa37a7b 2004-04-10 devnull struct Plumbattr
77 cfa37a7b 2004-04-10 devnull char *name;
78 cfa37a7b 2004-04-10 devnull char *value;
79 cfa37a7b 2004-04-10 devnull Plumbattr *next;
80 cfa37a7b 2004-04-10 devnull } Plumbattr;
83 cfa37a7b 2004-04-10 devnull .I Plumbopen
84 cfa37a7b 2004-04-10 devnull opens the named plumb
85 cfa37a7b 2004-04-10 devnull .IR port ,
87 bf8a59fa 2004-04-11 devnull .IR open (3)
89 cfa37a7b 2004-04-10 devnull .IR omode .
92 cfa37a7b 2004-04-10 devnull begins with a slash, it is taken as a literal file name;
93 cfa37a7b 2004-04-10 devnull otherwise
94 cfa37a7b 2004-04-10 devnull .I plumbopen
95 cfa37a7b 2004-04-10 devnull searches for the location of the
96 cfa37a7b 2004-04-10 devnull .IR plumber (4)
97 cfa37a7b 2004-04-10 devnull service and opens the port there.
99 cfa37a7b 2004-04-10 devnull For programs using the
100 bf8a59fa 2004-04-11 devnull .IR event (3)
101 cfa37a7b 2004-04-10 devnull interface,
102 cfa37a7b 2004-04-10 devnull .I eplumb
103 cfa37a7b 2004-04-10 devnull registers, using the given
104 cfa37a7b 2004-04-10 devnull .IR key ,
105 cfa37a7b 2004-04-10 devnull receipt of messages from the named
106 cfa37a7b 2004-04-10 devnull .IR port .
108 cfa37a7b 2004-04-10 devnull .I Plumbsend
109 cfa37a7b 2004-04-10 devnull formats and writes message
111 cfa37a7b 2004-04-10 devnull to the file descriptor
112 cfa37a7b 2004-04-10 devnull .IR fd ,
113 cfa37a7b 2004-04-10 devnull which will usually be the result of
114 cfa37a7b 2004-04-10 devnull .B plumbopen("send",
115 cfa37a7b 2004-04-10 devnull .BR OWRITE) .
116 cfa37a7b 2004-04-10 devnull .I Plumbsendtext
117 cfa37a7b 2004-04-10 devnull is a simplified version for text-only messages; it assumes
120 cfa37a7b 2004-04-10 devnull .BR text ,
124 cfa37a7b 2004-04-10 devnull and sets
125 cfa37a7b 2004-04-10 devnull .B ndata
127 cfa37a7b 2004-04-10 devnull .BI strlen( data )\f1.
129 cfa37a7b 2004-04-10 devnull .I Plumbfree
130 cfa37a7b 2004-04-10 devnull frees all the data associated with the message
132 cfa37a7b 2004-04-10 devnull all the components of which must therefore have been allocated with
133 bf8a59fa 2004-04-11 devnull .IR malloc (3).
135 cfa37a7b 2004-04-10 devnull .I Plumbrecv
136 cfa37a7b 2004-04-10 devnull returns the next message available on the file descriptor
137 cfa37a7b 2004-04-10 devnull .IR fd ,
138 cfa37a7b 2004-04-10 devnull or nil for error.
140 cfa37a7b 2004-04-10 devnull .I Plumbpack
141 cfa37a7b 2004-04-10 devnull encodes message
143 cfa37a7b 2004-04-10 devnull as a character string in the format of
144 cfa37a7b 2004-04-10 devnull .IR plumb (6) ,
146 cfa37a7b 2004-04-10 devnull .BI * np
147 cfa37a7b 2004-04-10 devnull to the length in bytes of the string.
148 cfa37a7b 2004-04-10 devnull .I Plumbunpack
149 cfa37a7b 2004-04-10 devnull does the inverse, translating the
151 cfa37a7b 2004-04-10 devnull bytes of
154 cfa37a7b 2004-04-10 devnull .BR Plumbmsg .
156 cfa37a7b 2004-04-10 devnull .I Plumbunpackpartial
157 cfa37a7b 2004-04-10 devnull enables unpacking of messages that arrive in pieces.
158 cfa37a7b 2004-04-10 devnull The first call to
159 cfa37a7b 2004-04-10 devnull .I plumbunpackpartial
160 cfa37a7b 2004-04-10 devnull for a given message must be sufficient to unpack the header;
161 cfa37a7b 2004-04-10 devnull subsequent calls permit unpacking messages with long data sections.
162 cfa37a7b 2004-04-10 devnull For each call,
164 cfa37a7b 2004-04-10 devnull points to the beginning of the complete message received so far, and
166 cfa37a7b 2004-04-10 devnull reports the total number of bytes received for that message.
167 cfa37a7b 2004-04-10 devnull If the message is complete, the return value will be as in
168 cfa37a7b 2004-04-10 devnull .IR plumbunpack .
169 cfa37a7b 2004-04-10 devnull If not, and
170 cfa37a7b 2004-04-10 devnull .I morep
171 cfa37a7b 2004-04-10 devnull is not null, the return value will be
174 cfa37a7b 2004-04-10 devnull .BR * morep
175 cfa37a7b 2004-04-10 devnull will be set to the number of bytes remaining to be read for this message to be complete
176 cfa37a7b 2004-04-10 devnull (recall that the byte count is in the header).
177 cfa37a7b 2004-04-10 devnull Those bytes should be read by the caller, placed at location
178 cfa37a7b 2004-04-10 devnull .IB buf + n \f1,
179 cfa37a7b 2004-04-10 devnull and the message unpacked again.
180 cfa37a7b 2004-04-10 devnull If an error is encountered, the return value will be
183 cfa37a7b 2004-04-10 devnull .BI * morep
184 cfa37a7b 2004-04-10 devnull will be zero.
186 cfa37a7b 2004-04-10 devnull .I Plumbpackattr
187 cfa37a7b 2004-04-10 devnull converts the list
190 cfa37a7b 2004-04-10 devnull .B Plumbattr
191 cfa37a7b 2004-04-10 devnull structures into a null-terminated string.
192 cfa37a7b 2004-04-10 devnull If an attribute value contains white space, quote characters, or equal signs,
193 cfa37a7b 2004-04-10 devnull the value will be quoted appropriately.
194 cfa37a7b 2004-04-10 devnull A newline character will terminate processing.
195 cfa37a7b 2004-04-10 devnull .I Plumbunpackattr
196 cfa37a7b 2004-04-10 devnull converts the null-terminated string
198 cfa37a7b 2004-04-10 devnull back into a list of
199 cfa37a7b 2004-04-10 devnull .I Plumbattr
200 cfa37a7b 2004-04-10 devnull structures.
202 cfa37a7b 2004-04-10 devnull .I Plumblookup
203 cfa37a7b 2004-04-10 devnull searches the
204 cfa37a7b 2004-04-10 devnull .B Plumbattr
207 cfa37a7b 2004-04-10 devnull for an attribute with the given
209 cfa37a7b 2004-04-10 devnull and returns the associated value.
210 cfa37a7b 2004-04-10 devnull The returned string is the original value, not a copy.
211 cfa37a7b 2004-04-10 devnull If the attribute has no value, the returned value will be the empty string;
212 cfa37a7b 2004-04-10 devnull if the attribute does not occur in the list at all, the value will be nil.
214 cfa37a7b 2004-04-10 devnull .I Plumbaddattr
215 cfa37a7b 2004-04-10 devnull appends the
217 cfa37a7b 2004-04-10 devnull .B Plumbattr
218 cfa37a7b 2004-04-10 devnull (which may be a list) to the attribute list
220 cfa37a7b 2004-04-10 devnull and returns the new list.
221 cfa37a7b 2004-04-10 devnull .I Plumbattr
222 cfa37a7b 2004-04-10 devnull searches the list
224 cfa37a7b 2004-04-10 devnull for the first attribute with name
226 cfa37a7b 2004-04-10 devnull and deletes it from the list, returning the resulting list.
227 cfa37a7b 2004-04-10 devnull .I Plumbdelattr
228 cfa37a7b 2004-04-10 devnull is a no-op if no such attribute exists.
229 cfa37a7b 2004-04-10 devnull .SH SOURCE
230 b5fdffee 2004-04-19 devnull .B /usr/local/plan9/src/libplumb
231 cfa37a7b 2004-04-10 devnull .SH SEE ALSO
232 cfa37a7b 2004-04-10 devnull .IR plumb (1),
233 bf8a59fa 2004-04-11 devnull .IR event (3),
234 cfa37a7b 2004-04-10 devnull .IR plumber (4),
235 cfa37a7b 2004-04-10 devnull .IR plumb (6)
236 cfa37a7b 2004-04-10 devnull .SH DIAGNOSTICS
237 cfa37a7b 2004-04-10 devnull When appropriate, including when a
238 cfa37a7b 2004-04-10 devnull .I plumbsend
239 cfa37a7b 2004-04-10 devnull fails, these routine set
240 cfa37a7b 2004-04-10 devnull .IR errstr .
