1 .TH VENTI-PACKET 3
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 .MR memory (3) )
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 \*9/src/libventi
262 .SH SEE ALSO
263 .MR venti (3)
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 .