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