1
0

venti-packet 4.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281
  1. .TH VENTI-PACKET 2
  2. .SH NAME
  3. Packet,
  4. packetalloc,
  5. packetappend,
  6. packetasize,
  7. packetcmp,
  8. packetconcat,
  9. packetconsume,
  10. packetcopy,
  11. packetdup,
  12. packetforeign,
  13. packetfragments,
  14. packetfree,
  15. packetheader,
  16. packetpeek,
  17. packetprefix,
  18. packetsha1,
  19. packetsize,
  20. packetsplit,
  21. packetstats,
  22. packettrailer,
  23. packettrim \- zero-copy network buffers
  24. .SH SYNOPSIS
  25. .ft L
  26. #include <u.h>
  27. .br
  28. #include <libc.h>
  29. .br
  30. #include <venti.h>
  31. .ta +\w'\fLPacket* 'u +\w'\fLxxxx'u
  32. .PP
  33. .B
  34. .PP
  35. .B
  36. Packet* packetalloc(void);
  37. .PP
  38. .B
  39. void packetappend(Packet *p, uchar *buf, int n)
  40. .PP
  41. .B
  42. uint packetasize(Packet *p)
  43. .PP
  44. .B
  45. int packetcmp(Packet *p, Packet *q)
  46. .PP
  47. .B
  48. void packetconcat(Packet *p, Packet *q)
  49. .PP
  50. .B
  51. int packetconsume(Packet *p, uchar *buf, int n)
  52. .PP
  53. .B
  54. int packetcopy(Packet *p, uchar *buf, int offset, int n)
  55. .PP
  56. .B
  57. Packet* packetdup(Packet *p, int offset, int n)
  58. .PP
  59. .B
  60. Packet* packetforeign(uchar *buf, int n,
  61. .br
  62. .B
  63. void (*free)(void *a), void *a)
  64. .PP
  65. .B
  66. int packetfragments(Packet *p, IOchunk *io, int nio,
  67. .br
  68. .B
  69. int offset)
  70. .PP
  71. .B
  72. void packetfree(Packet *p)
  73. .PP
  74. .B
  75. uchar* packetheader(Packet *p, int n)
  76. .PP
  77. .B
  78. uchar* packetpeek(Packet *p, uchar *buf, int offset, int n)
  79. .PP
  80. .B
  81. void packetprefix(Packet *p, uchar *buf, int n)
  82. .PP
  83. .B
  84. void packetsha1(Packet *p, uchar sha1[20])
  85. .PP
  86. .B
  87. uint packetsize(Packet *p)
  88. .PP
  89. .B
  90. Packet* packetsplit(Packet *p, int n)
  91. .PP
  92. .B
  93. void packetstats(void)
  94. .PP
  95. .B
  96. uchar* packettrailer(Packet *p, int n)
  97. .PP
  98. .B
  99. int packettrim(Packet *p, int offset, int n)
  100. .SH DESCRIPTION
  101. A
  102. .B Packet
  103. is a chain of blocks of data.
  104. Each block, called a fragment,
  105. is contiguous in memory, but the entire packet
  106. may not be.
  107. This representation helps avoid unnecessary memory copies.
  108. .PP
  109. .I Packetalloc
  110. allocates an empty packet.
  111. .PP
  112. .I Packetappend
  113. appends the
  114. .I n
  115. bytes at
  116. .I buf
  117. to the end of
  118. .IR p .
  119. .PP
  120. .I Packetasize
  121. returns the number of data bytes allocated to
  122. .IR p .
  123. This may be larger than the number of bytes stored
  124. in
  125. .IR p
  126. because fragments may not be filled completely.
  127. .PP
  128. .I Packetcmp
  129. compares the data sections of two packets as
  130. .I memcmp
  131. (see
  132. .IR memory (2))
  133. would.
  134. .PP
  135. .I Packetconcat
  136. removes all data from
  137. .IR q ,
  138. appending it to
  139. .IR p .
  140. .PP
  141. .I Packetconsume
  142. removes
  143. .I n
  144. bytes from the beginning of
  145. .IR p ,
  146. storing them into
  147. .IR buf .
  148. .PP
  149. .I Packetcopy
  150. copies
  151. .I n
  152. bytes at
  153. .I offset
  154. in
  155. .I p
  156. to
  157. .IR buf .
  158. .PP
  159. .I Packetdup
  160. creates a new packet initialized with
  161. .I n
  162. bytes from
  163. .I offset
  164. in
  165. .IR p .
  166. .PP
  167. .I Packetforeign
  168. allocates a packet containing `foreign' data: the
  169. .I n
  170. bytes pointed to by
  171. .IR buf .
  172. Once the bytes are no longer needed, they are freed by calling
  173. .IB free ( a )\fR.
  174. .PP
  175. .I Packetfragments
  176. initializes up to
  177. .I nio
  178. of the
  179. .I io
  180. structures with pointers to the data in
  181. .IR p ,
  182. starting at
  183. .IR offset .
  184. It returns the total number of bytes represented
  185. by the returned structures.
  186. .I Packetfragments
  187. initializes any unused
  188. .I io
  189. structures with nil pointer and zero length.
  190. .PP
  191. .I Packetfree
  192. frees the packet
  193. .IR p .
  194. .PP
  195. .I Packetheader
  196. returns a pointer to the first
  197. .I n
  198. bytes of
  199. .IR p ,
  200. making them contiguous in memory
  201. if necessary.
  202. .PP
  203. .I Packetpeek
  204. returns a pointer to the
  205. .I n
  206. bytes at
  207. .I offset
  208. in
  209. .IR p .
  210. If the requested bytes are already stored contiguously in memory,
  211. the returned pointer points at the internal data storage for
  212. .IR p .
  213. Otherwise, the bytes are copied into
  214. .IR buf ,
  215. and
  216. .I packetpeek
  217. returns
  218. .IR buf .
  219. .PP
  220. .I Packetprefix
  221. inserts a copy of the
  222. .I n
  223. bytes at
  224. .I buf
  225. at the beginning of
  226. .IR p .
  227. .PP
  228. .I Packetsha1
  229. computes the SHA1 hash of the data contained in
  230. .IR p .
  231. .PP
  232. .I Packetsize
  233. returns the length, in bytes, of the data contained in
  234. .IR p .
  235. .PP
  236. .I Packetsplit
  237. returns a new packet initialized with
  238. .I n
  239. bytes removed from the beginning of
  240. .IR p .
  241. .PP
  242. .I Packetstats
  243. prints run-time statistics to standard output.
  244. .PP
  245. .I Packettrailer
  246. returns a pointer to the last
  247. .I n
  248. bytes of
  249. .IR p ,
  250. making them contiguous in memory
  251. if necessary.
  252. .PP
  253. .I Packettrim
  254. deletes all bytes from the packet
  255. .I p
  256. except the
  257. .I n
  258. bytes at offset
  259. .IR offset .
  260. .SH SOURCE
  261. .B /sys/src/libventi
  262. .SH SEE ALSO
  263. .IR venti (2)
  264. .SH DIAGNOSTICS
  265. These functions return errors only when passed
  266. invalid inputs,
  267. .IR e.g. ,
  268. requests for data at negative offsets or beyond the end of a packet.
  269. .PP
  270. Functions returning pointers return nil on error;
  271. functions returning integers return \-1 on error.
  272. Most functions returning integers return 0 on success.
  273. The exceptions are
  274. .I packetfragments
  275. and
  276. .IR packetcmp ,
  277. whose return values are described above.
  278. .PP
  279. When these functions run out of memory, they
  280. print error messages and call
  281. .IR sysfatal .