1
0

plumb 4.7 KB

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