chiark / gitweb /
Commit as 2.1.0.
[mLib] / buf.3
CommitLineData
9b5ac6ff 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
24buf \- 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
188The
189.B buf
190interface allows relatively convenient reading and writing of structured
191binary data from and to fixed-size memory buffers. It's useful for
192formatting and parsing down network data packets, for example.
193.SS "Buffer basics"
194A buffer has three important pointers associated with it:
195.TP
196.I base
197The base address of the buffer.
198.TP
199.I limit
200Just past the last usable byte in the buffer
201.TP
202.I current
203The position in the buffer at which the next read or write will occur.
204.PP
205A buffer is created using the
206.B buf_init
207function. You must pass it the buffer base address and size, and a
d4efbcd9 208pointer to a
9b5ac6ff 209.B buf
210structure to fill in. It doesn't allocate any memory, so you don't need
211to dispose of the
212.B buf
213structure in any way before forgetting about it.
214.PP
215A collection of macros is provided for finding the positions of the
216various interesting pointers known about a buffer, and the sizes of the
217regions of memory they imply.
218.TP
219.B BBASE
220The buffer's
221.I base
222pointer.
223.TP
224.B BLIM
225The buffer's
226.I limit
227pointer.
228.TP
229.B BCUR
230The buffer's
231.I current
232pointer.
233.TP
234.B BSZ
235The size of the buffer; i.e.,
236.I limit
237\-
238.IR base .
239.TP
240.B BLEN
241The length of data in the buffer (if writing) or the amount of data
d4efbcd9 242read (if reading); i.e.,
9b5ac6ff 243.I current
244\-
245.IR base .
246.TP
247.B BLEFT
248The amount of space left in the buffer (if writing) or the amount of
249data yet to read (if reading); i.e.,
250.I limit
251\-
252.IR current .
253.PP
254The function
255.B buf_flip
256takes a buffer which has been used for writing, and makes it suitable
257for reading. This turns out to be useful when building packets in
d4efbcd9 258multi-layered networking software. Its precise behaviour is to preserve
9b5ac6ff 259.IR base ,
260to set
261.I limit
262to
263.IR current ,
d4efbcd9 264and to set
9b5ac6ff 265.I current
266to
267.IR base .
268.PP
269A buffer can be
270.IR broken ,
271to indicate that it has overflowed or that its contents are otherwise
272invalid. The various buffer access functions described below all fail
273on a broken buffer, and any errors they encounter cause the buffer to
274become broken. Most simple programs which only use the supplied buffer
275access functions can avoid the tedium of error-checking every function
276call and just check the brokenness state at the end of their run.
277.PP
278The function
279.B buf_break
280will break a buffer. The macro
281.B BBAD
282reports true (nonzero) if its buffer argument is broken, or false (zero)
283otherwise; its counterpart
284.B BOK
285reports true if the buffer is OK, and false if it is broken.
286.SS "Low-level buffer access"
287Access to the data in the buffer is usually sequential. The
288.B BENSURE
289macro (or the equivalent
290.B buf_ensure
291function) checks that the buffer is OK and that there is enough space
292remaining in the buffer for
293.I sz
294bytes: if so, it returns zero; otherwise it breaks the buffer and
295returns \-1.
296.PP
297The
298.B BSTEP
299macro advances the buffer's
300.I current
301pointer by
302.I sz
303bytes. It does no bounds checking. Together with
304.BR BENSURE ,
305this provides sequential access to the buffer's contents.
306.PP
307The
308.B buf_get
309function is the basis of most buffer access functions, whether for
310reading or writing. If the buffer is OK, and there are
311.I sz
312or more bytes remaining, it steps the buffer's
313.I current
314pointer by
315.I sz
d4efbcd9 316and returns the
9b5ac6ff 317.I original
318(pre-stepping)
319.I current
320pointer; otherwise it breaks the buffer if necessary, and returns a null
321pointer.
322.PP
323The
324.B buf_put
d4efbcd9 325function writes
9b5ac6ff 326.I sz
327bytes of data starting at
328.I p
329to the buffer. If it succeeded, it returns 0; otherwise it returns \-1.
330.SS "Formatted buffer access"
331The function
332.B buf_getbyte
333returns the next byte from a buffer as a nonnegative integer, or \-1 on
334error. The function
335.B buf_putbyte
336writes its argument to a buffer, and returns 0 on succes; it returns \-1
337if it failed.
338.PP
339Many of the remaining functions deal with integer formatting and buffer
340lengths. The functions support 8-, 16-, 24- and 32-bit integers, in
341big- or little-endian order; on platforms with 64-bit integers, these
342are supported too. The functions' names carry a suffix which is the
343width in bits of the integers they deal with and an optional
344.RB ` l '
345for little- or
346.RB ` b '
347for big-endian byte order. (The variant with no letter uses big-endian
348order. Use of these variants tends to mean `I don't really care, but be
349consistent,' and is not recommended if you have an externally-defined
350spec you're meant to be compatible with.)
351.PP
352The function
353.BI buf_getu suff
354reads an integer. On success, it stores the integer it read at the
355address
356.I w
357given, and returns zero; on failure, it returns \-1. The function
358.BI buf_putu suff
359write an integer. It returns zero on success or \-1 on failure.
360.PP
361Functions which deal with block lengths assume the length is prefixed to
362the data, and don't include themselves. They also have an additional
363.RB ` z '
364variant, which deals with zero-terminated data. No checks are done on
365writing that the data written contains no zero bytes.
366.PP
367The function
368.BI buf_getmem suff
369fetches a block of data. On success, it returns its base address and
370stores its length at the given address; on failure, it returns null.
371The function
372.BI buf_putmem suff
373writes a block of data; it return zero on success or \-1 on failure.
374.PP
375The functon
376.BI buf_getbuf suff
377fetches a block of data and makes a second buffer point to it, i.e.,
378setting its
379.I base
380and
381.I current
382pointers to the start of the block and its
383.I limit
384pointer to just past the end. No copying of bulk data is performed.
385The function
386.BI buf_putbuf suff
387writes the contents of a buffer (i.e., between its
388.I base
389and
390.I current
391pointers). The function
392.BI buf_getdstr suff
393fetches a block of data and append it to a dynamic string (see
394.BR dstr (3)).
395The function
396.BI buf_putdstr suff
397writes the contents of a dynamic string to a buffer. Finally, the
398function
399.BI buf_putstr suff
400writes a standard C null-terminated string to a buffer. All these
401functions return zero on success or \-1 on failure.
402.SH "SEE ALSO"
403.BR dstr (3),
404.BR mLib (3).
405.SH AUTHOR
406Mark Wooding, <mdw@distorted.org.uk>