plumb.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.