sys/man/2/plumb

   1 .TH PLUMB 2
   2 .SH NAME
   3 eplumb, plumbfree, plumbopen, plumbsend, plumbsendtext, plumblookup, plumbpack, plumbpackattr, plumbaddattr, plumbdelattr, plumbrecv, 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     plumbsend(int fd, Plumbmsg *m)
  18 .PP
  19 .B
  20 int     plumbsendtext(int fd, char *src, char *dst, char *wdir, char *data)
  21 .PP
  22 .B
  23 void    plumbfree(Plumbmsg *m)
  24 .PP
  25 .B
  26 Plumbmsg*       plumbrecv(int fd)
  27 .PP
  28 .B
  29 char*   plumbpack(Plumbmsg *m, int *np)
  30 .PP
  31 .B
  32 Plumbmsg*       plumbunpack(char *buf, int n)
  33 .PP
  34 .B
  35 Plumbmsg*       plumbunpackpartial(char *buf, int n, int *morep)
  36 .PP
  37 .B
  38 char*   plumbpackattr(Plumbattr *a)
  39 .PP
  40 .B
  41 Plumbattr*      plumbunpackattr(char *a)
  42 .PP
  43 .B
  44 char*   plumblookup(Plumbattr *a, char *name)
  45 .PP
  46 .B
  47 Plumbattr*      plumbaddattr(Plumbattr *a, Plumbattr *new)
  48 .PP
  49 .B
  50 Plumbattr*      plumbdelattr(Plumbattra *a, char *name)
  51 .PP
  52 .B
  53 int     eplumb(int key, char *port)
  54 .SH DESCRIPTION
  55 These routines manipulate
  56 .IR plumb (6)
  57 messages, transmitting them, receiving them, and
  58 converting them between text and these data structures:
  59 .IP
  60 .EX
  61 .ta 6n +\w'\fLPlumbattr 'u +\w'ndata;   'u
  62 typedef
  63 struct Plumbmsg
  64 {
  65         char    *src;
  66         char    *dst;
  67         char    *wdir;
  68         char    *type;
  69         Plumbattr       *attr;
  70         int     ndata;
  71         char    *data;
  72 } Plumbmsg;
  73
  74 typedef
  75 struct Plumbattr
  76 {
  77         char    *name;
  78         char    *value;
  79         Plumbattr       *next;
  80 } Plumbattr;
  81 .EE
  82 .PP
  83 .I Plumbopen
  84 opens the named plumb
  85 .IR port ,
  86 using
  87 .IR open (2)
  88 mode
  89 .IR omode .
  90 If
  91 .I port
  92 begins with a slash, it is taken as a literal file name;
  93 otherwise
  94 .I plumbopen
  95 searches for the location of the
  96 .IR plumber (4)
  97 service and opens the port there.
  98 .PP
  99 For programs using the
 100 .IR event (2)
 101 interface,
 102 .I eplumb
 103 registers, using the given
 104 .IR key ,
 105 receipt of messages from the named
 106 .IR port .
 107 .PP
 108 .I Plumbsend
 109 formats and writes message
 110 .I m
 111 to the file descriptor
 112 .IR fd ,
 113 which will usually be the result of
 114 .B plumbopen("send",
 115 .BR OWRITE) .
 116 .I Plumbsendtext
 117 is a simplified version for text-only messages; it assumes
 118 .B type
 119 is
 120 .BR text ,
 121 sets
 122 .B attr
 123 to nil,
 124 and sets
 125 .B ndata
 126 to
 127 .BI strlen( data )\f1.
 128 .PP
 129 .I Plumbfree
 130 frees all the data associated with the message
 131 .IR m ,
 132 all the components of which must therefore have been allocated with
 133 .IR malloc (2).
 134 .PP
 135 .I Plumbrecv
 136 returns the next message available on the file descriptor
 137 .IR fd ,
 138 or nil for error.
 139 .PP
 140 .I Plumbpack
 141 encodes message
 142 .I m
 143 as a character string in the format of
 144 .IR plumb (6) ,
 145 setting
 146 .BI * np
 147 to the length in bytes of the string.
 148 .I Plumbunpack
 149 does the inverse, translating the
 150 .I n
 151 bytes of
 152 .I buf
 153 into a
 154 .BR Plumbmsg .
 155 .PP
 156 .I Plumbunpackpartial
 157 enables unpacking of messages that arrive in pieces.
 158 The first call to
 159 .I plumbunpackpartial
 160 for a given message must be sufficient to unpack the header;
 161 subsequent calls permit unpacking messages with long data sections.
 162 For each call,
 163 .I buf
 164 points to the beginning of the complete message received so far, and
 165 .I n
 166 reports the total number of bytes received for that message.
 167 If the message is complete, the return value will be as in
 168 .IR plumbunpack .
 169 If not, and
 170 .I morep
 171 is not null, the return value will be
 172 .B nil
 173 and
 174 .BR * morep
 175 will be set to the number of bytes remaining to be read for this message to be complete
 176 (recall that the byte count is in the header).
 177 Those bytes should be read by the caller, placed at location
 178 .IB buf + n \f1,
 179 and the message unpacked again.
 180 If an error is encountered, the return value will be
 181 .B nil
 182 and
 183 .BI * morep
 184 will be zero.
 185 .PP
 186 .I Plumbpackattr
 187 converts the list
 188 .I a
 189 of
 190 .B Plumbattr
 191 structures into a null-terminated string.
 192 If an attribute value contains white space, quote characters, or equal signs,
 193 the value will be quoted appropriately.
 194 A newline character will terminate processing.
 195 .I Plumbunpackattr
 196 converts the null-terminated string
 197 .I a
 198 back into a list of
 199 .I Plumbattr
 200 structures.
 201 .PP
 202 .I Plumblookup
 203 searches the
 204 .B Plumbattr
 205 list
 206 .I a
 207 for an attribute with the given
 208 .I name
 209 and returns the associated value.
 210 The returned string is the original value, not a copy.
 211 If the attribute has no value, the returned value will be the empty string;
 212 if the attribute does not occur in the list at all, the value will be nil.
 213 .PP
 214 .I Plumbaddattr
 215 appends the
 216 .I new
 217 .B Plumbattr
 218 (which may be a list) to the attribute list
 219 .IR a
 220 and returns the new list.
 221 .I Plumbdelattr
 222 searches the list
 223 .I a
 224 for the first attribute with name
 225 .I name
 226 and deletes it from the list, returning the resulting list.
 227 .I Plumbdelattr
 228 is a no-op if no such attribute exists.
 229 .SH SOURCE
 230 .B /sys/src/libplumb
 231 .SH SEE ALSO
 232 .IR plumb (1),
 233 .IR event (2),
 234 .IR plumber (4),
 235 .IR plumb (6)
 236 .SH DIAGNOSTICS
 237 When appropriate, including when a
 238 .I plumbsend
 239 fails, these routine set
 240 .IR errstr .