chiark / gitweb /
76c7dcb666cf58e509723d9ec6b69e5fc7be18a1
[mLib] / man / buf.3
1 .\" -*-nroff-*-
2 .de VS
3 .sp 1
4 .RS
5 .nf
6 .ft B
7 ..
8 .de VE
9 .ft R
10 .fi
11 .RE
12 .sp 1
13 ..
14 .de hP
15 .IP
16 .ft B
17 \h'-\w'\\$1\ 'u'\\$1\ \c
18 .ft P
19 ..
20 .ie t .ds o \(bu
21 .el .ds o o
22 .TH buf 3 "23 September 2005" "Straylight/Edgeware" "mLib utilities library"
23 .SH NAME
24 buf \- reading and writing stuff in buffers
25 .\" @BBASE
26 .\" @BLIM
27 .\" @BCUR
28 .\" @BSZ
29 .\" @BLEN
30 .\" @BLEFT
31 .\" @BSTEP
32 .\" @BBAD
33 .\" @BOK
34 .\" @BENSURE
35 .
36 .\" @buf_init
37 .\" @buf_break
38 .\" @buf_flip
39 .\" @buf_ensure
40 .\" @buf_get
41 .\" @buf_put
42 .
43 .\" @buf_getbyte
44 .\" @buf_putbyte
45 .
46 .\" @buf_getu8
47 .\" @buf_getu16
48 .\" @buf_getu16b
49 .\" @buf_getu16l
50 .\" @buf_getu24
51 .\" @buf_getu24b
52 .\" @buf_getu24l
53 .\" @buf_getu32
54 .\" @buf_getu32b
55 .\" @buf_getu32l
56 .
57 .\" @buf_putu8
58 .\" @buf_putu16
59 .\" @buf_putu16b
60 .\" @buf_putu16l
61 .\" @buf_putu24
62 .\" @buf_putu24b
63 .\" @buf_putu24l
64 .\" @buf_putu32
65 .\" @buf_putu32b
66 .\" @buf_putu32l
67 .
68 .\" @buf_getbuf8
69 .\" @buf_getbuf16
70 .\" @buf_getbuf16b
71 .\" @buf_getbuf16l
72 .\" @buf_getbuf24
73 .\" @buf_getbuf24b
74 .\" @buf_getbuf24l
75 .\" @buf_getbuf32
76 .\" @buf_getbuf32b
77 .\" @buf_getbuf32l
78 .\" @buf_getbufz
79 .
80 .\" @buf_putbuf8
81 .\" @buf_putbuf16
82 .\" @buf_putbuf16b
83 .\" @buf_putbuf16l
84 .\" @buf_putbuf24
85 .\" @buf_putbuf24b
86 .\" @buf_putbuf24l
87 .\" @buf_putbuf32
88 .\" @buf_putbuf32b
89 .\" @buf_putbuf32l
90 .\" @buf_putbufz
91 .
92 .\" @buf_getmem16
93 .\" @buf_getmem16b
94 .\" @buf_getmem16l
95 .\" @buf_getmem24
96 .\" @buf_getmem24b
97 .\" @buf_getmem24l
98 .\" @buf_getmem32
99 .\" @buf_getmem32b
100 .\" @buf_getmem32l
101 .\" @buf_getmem8
102 .\" @buf_getmemz
103 .
104 .\" @buf_putmem8
105 .\" @buf_putmem16
106 .\" @buf_putmem16b
107 .\" @buf_putmem16l
108 .\" @buf_putmem24
109 .\" @buf_putmem24b
110 .\" @buf_putmem24l
111 .\" @buf_putmem32
112 .\" @buf_putmem32b
113 .\" @buf_putmem32l
114 .\" @buf_putmemz
115 .
116 .\" @buf_putstr8
117 .\" @buf_putstr16
118 .\" @buf_putstr16b
119 .\" @buf_putstr16l
120 .\" @buf_putstr24
121 .\" @buf_putstr24b
122 .\" @buf_putstr24l
123 .\" @buf_putstr32
124 .\" @buf_putstr32b
125 .\" @buf_putstr32l
126 .\" @buf_putstrz
127 .
128 .\" @buf_getdstr8
129 .\" @buf_getdstr16
130 .\" @buf_getdstr16b
131 .\" @buf_getdstr16l
132 .\" @buf_getdstr24
133 .\" @buf_getdstr24b
134 .\" @buf_getdstr24l
135 .\" @buf_getdstr32
136 .\" @buf_getdstr32b
137 .\" @buf_getdstr32l
138 .\" @buf_getdstrz
139 .
140 .\" @buf_putdstr8
141 .\" @buf_putdstr16
142 .\" @buf_putdstr16b
143 .\" @buf_putdstr16l
144 .\" @buf_putdstr24
145 .\" @buf_putdstr24b
146 .\" @buf_putdstr24l
147 .\" @buf_putdstr32
148 .\" @buf_putdstr32b
149 .\" @buf_putdstr32l
150 .\" @buf_putdstrz
151 .SH SYNOPSIS
152 .nf
153 .B "#include <mLib/dstr.h>"
154
155 .BI "void buf_init(buf *" b ", void *" p ", size_t " sz );
156 .BI "void buf_flip(buf *" b );
157 .BI "octet *BBASE(buf *" b );
158 .BI "octet *BLIM(buf *" b );
159 .BI "octet *BCUR(buf *" b );
160 .BI "ptrdiff_t BSZ(buf *" b );
161 .BI "ptrdiff_t BLEN(buf *" b );
162 .BI "ptrdiff_t BLEFT(buf *" b );
163
164 .BI "int buf_break(buf *" b );
165 .BI "int BBAD(buf *" b );
166 .BI "int BOK(buf *" b );
167
168 .BI "int buf_ensure(buf *" b ", size_t " sz );
169 .BI "int BENSURE(buf *" b ", size_t " sz );
170 .BI "octet *BSTEP(buf *" b );
171
172 .BI "void *buf_get(buf *" b ", size_t " sz );
173 .BI "void *buf_put(buf *" b ", const void *" p ", size_t " sz );
174
175 .BI "int buf_getbyte(buf *" b );
176 .BI "int buf_putbyte(buf *" b ", int ch" );
177 .BI "int buf_getu" suff "(buf *" b ", uint" suff " *" w );
178 .BI "int buf_putu" suff "(buf *" b ", uint" suff " " w );
179 .BI "void *buf_getmem" suff "(buf *" b ", size_t *" sz );
180 .BI "int buf_putmem" suff "(buf *" b ", const void *" p ", size_t " sz );
181 .BI "int buf_getbuf" suff "(buf *" b ", buf *" bb );
182 .BI "int buf_putbuf" suff "(buf *" b ", buf *" bb );
183 .BI "int buf_getdstr" suff "(buf *" b ", dstr *" d );
184 .BI "int buf_putdstr" suff "(buf *" b ", dstr *" d );
185 .BI "int buf_putstr" suff "(buf *" b ", const char *" p );
186 .fi
187 .SH DESCRIPTION
188 The
189 .B buf
190 interface allows relatively convenient reading and writing of structured
191 binary data from and to fixed-size memory buffers.  It's useful for
192 formatting and parsing down network data packets, for example.
193 .SS "Buffer basics"
194 A buffer has three important pointers associated with it:
195 .TP
196 .I base
197 The base address of the buffer.
198 .TP
199 .I limit
200 Just past the last usable byte in the buffer
201 .TP
202 .I current
203 The position in the buffer at which the next read or write will occur.
204 .PP
205 A buffer is created using the
206 .B buf_init
207 function.  You must pass it the buffer base address and size, and a
208 pointer to a
209 .B buf
210 structure to fill in.  It doesn't allocate any memory, so you don't need
211 to dispose of the
212 .B buf
213 structure in any way before forgetting about it.
214 .PP
215 A collection of macros is provided for finding the positions of the
216 various interesting pointers known about a buffer, and the sizes of the
217 regions of memory they imply.
218 .TP
219 .B BBASE
220 The buffer's
221 .I base
222 pointer.
223 .TP
224 .B BLIM
225 The buffer's
226 .I limit
227 pointer.
228 .TP
229 .B BCUR
230 The buffer's
231 .I current
232 pointer.
233 .TP
234 .B BSZ
235 The size of the buffer; i.e.,
236 .I limit
237 \-
238 .IR base .
239 .TP
240 .B BLEN
241 The length of data in the buffer (if writing) or the amount of data
242 read (if reading); i.e.,
243 .I current
244 \-
245 .IR base .
246 .TP
247 .B BLEFT
248 The amount of space left in the buffer (if writing) or the amount of
249 data yet to read (if reading); i.e.,
250 .I limit
251 \-
252 .IR current .
253 .PP
254 The function
255 .B buf_flip
256 takes a buffer which has been used for writing, and makes it suitable
257 for reading.  This turns out to be useful when building packets in
258 multi-layered networking software.  Its precise behaviour is to preserve
259 .IR base ,
260 to set
261 .I limit
262 to
263 .IR current ,
264 and to set
265 .I current
266 to
267 .IR base .
268 .PP
269 A buffer can be
270 .IR broken ,
271 to indicate that it has overflowed or that its contents are otherwise
272 invalid.  The various buffer access functions described below all fail
273 on a broken buffer, and any errors they encounter cause the buffer to
274 become broken.  Most simple programs which only use the supplied buffer
275 access functions can avoid the tedium of error-checking every function
276 call and just check the brokenness state at the end of their run.
277 .PP
278 The function
279 .B buf_break
280 will break a buffer.  The macro
281 .B BBAD
282 reports true (nonzero) if its buffer argument is broken, or false (zero)
283 otherwise; its counterpart
284 .B BOK
285 reports true if the buffer is OK, and false if it is broken.
286 .SS "Low-level buffer access"
287 Access to the data in the buffer is usually sequential.  The
288 .B BENSURE
289 macro (or the equivalent
290 .B buf_ensure
291 function) checks that the buffer is OK and that there is enough space
292 remaining in the buffer for
293 .I sz
294 bytes: if so, it returns zero; otherwise it breaks the buffer and
295 returns \-1.
296 .PP
297 The
298 .B BSTEP
299 macro advances the buffer's
300 .I current
301 pointer by
302 .I sz
303 bytes.  It does no bounds checking.  Together with
304 .BR BENSURE ,
305 this provides sequential access to the buffer's contents.
306 .PP
307 The
308 .B buf_get
309 function is the basis of most buffer access functions, whether for
310 reading or writing.  If the buffer is OK, and there are
311 .I sz
312 or more bytes remaining, it steps the buffer's
313 .I current
314 pointer by
315 .I sz
316 and returns the
317 .I original
318 (pre-stepping)
319 .I current
320 pointer; otherwise it breaks the buffer if necessary, and returns a null
321 pointer.
322 .PP
323 The
324 .B buf_put
325 function writes
326 .I sz
327 bytes of data starting at
328 .I p
329 to the buffer.  If it succeeded, it returns 0; otherwise it returns \-1.
330 .SS "Formatted buffer access"
331 The function
332 .B buf_getbyte
333 returns the next byte from a buffer as a nonnegative integer, or \-1 on
334 error.  The function
335 .B buf_putbyte
336 writes its argument to a buffer, and returns 0 on succes; it returns \-1
337 if it failed.
338 .PP
339 Many of the remaining functions deal with integer formatting and buffer
340 lengths.  The functions support 8-, 16-, 24- and 32-bit integers, in
341 big- or little-endian order; on platforms with 64-bit integers, these
342 are supported too.  The functions' names carry a suffix which is the
343 width in bits of the integers they deal with and an optional
344 .RB ` l '
345 for little- or
346 .RB ` b '
347 for big-endian byte order.  (The variant with no letter uses big-endian
348 order.  Use of these variants tends to mean `I don't really care, but be
349 consistent,' and is not recommended if you have an externally-defined
350 spec you're meant to be compatible with.)
351 .PP
352 The function
353 .BI buf_getu suff
354 reads an integer.  On success, it stores the integer it read at the
355 address
356 .I w
357 given, and returns zero; on failure, it returns \-1.  The function
358 .BI buf_putu suff
359 write an integer.  It returns zero on success or \-1 on failure.
360 .PP
361 Functions which deal with block lengths assume the length is prefixed to
362 the data, and don't include themselves.  They also have an additional
363 .RB ` z '
364 variant, which deals with zero-terminated data.  No checks are done on
365 writing that the data written contains no zero bytes.
366 .PP
367 The function
368 .BI buf_getmem suff
369 fetches a block of data.  On success, it returns its base address and
370 stores its length at the given address; on failure, it returns null.
371 The function
372 .BI buf_putmem suff
373 writes a block of data; it return zero on success or \-1 on failure.
374 .PP
375 The functon
376 .BI buf_getbuf suff
377 fetches a block of data and makes a second buffer point to it, i.e.,
378 setting its
379 .I base
380 and
381 .I current
382 pointers to the start of the block and its
383 .I limit
384 pointer to just past the end.  No copying of bulk data is performed.
385 The function
386 .BI buf_putbuf suff
387 writes the contents of a buffer (i.e., between its
388 .I base
389 and
390 .I current
391 pointers).  The function
392 .BI buf_getdstr suff
393 fetches a block of data and append it to a dynamic string (see
394 .BR dstr (3)).
395 The function
396 .BI buf_putdstr suff
397 writes the contents of a dynamic string to a buffer.  Finally, the
398 function
399 .BI buf_putstr suff
400 writes a standard C null-terminated string to a buffer.  All these
401 functions return zero on success or \-1 on failure.
402 .SH "SEE ALSO"
403 .BR dstr (3),
404 .BR mLib (3).
405 .SH AUTHOR
406 Mark Wooding, <mdw@distorted.org.uk>