2 * Copyright (C) 2004-2008, 2010, 2012, 2014 Internet Systems Consortium, Inc. ("ISC")
3 * Copyright (C) 1998-2002 Internet Software Consortium.
5 * Permission to use, copy, modify, and/or distribute this software for any
6 * purpose with or without fee is hereby granted, provided that the above
7 * copyright notice and this permission notice appear in all copies.
9 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
10 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
11 * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
12 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
13 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
14 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
15 * PERFORMANCE OF THIS SOFTWARE.
18 /* $Id: buffer.h,v 1.55 2010/12/20 23:47:21 tbox Exp $ */
21 #define ISC_BUFFER_H 1
27 /*! \file isc/buffer.h
29 * \brief A buffer is a region of memory, together with a set of related subregions.
30 * Buffers are used for parsing and I/O operations.
32 * The 'used region' and the 'available' region are disjoint, and their
33 * union is the buffer's region. The used region extends from the beginning
34 * of the buffer region to the last used byte. The available region
35 * extends from one byte greater than the last used byte to the end of the
36 * buffer's region. The size of the used region can be changed using various
37 * buffer commands. Initially, the used region is empty.
39 * The used region is further subdivided into two disjoint regions: the
40 * 'consumed region' and the 'remaining region'. The union of these two
41 * regions is the used region. The consumed region extends from the beginning
42 * of the used region to the byte before the 'current' offset (if any). The
43 * 'remaining' region the current pointer to the end of the used
44 * region. The size of the consumed region can be changed using various
45 * buffer commands. Initially, the consumed region is empty.
47 * The 'active region' is an (optional) subregion of the remaining region.
48 * It extends from the current offset to an offset in the remaining region
49 * that is selected with isc_buffer_setactive(). Initially, the active region
50 * is empty. If the current offset advances beyond the chosen offset, the
51 * active region will also be empty.
54 * /------------entire length---------------\
55 * /----- used region -----\/-- available --\
56 * +----------------------------------------+
57 * | consumed | remaining | |
58 * +----------------------------------------+
61 * a == base of buffer.
62 * b == current pointer. Can be anywhere between a and d.
63 * c == active pointer. Meaningful between b and d.
65 * e == length of buffer.
67 * a-e == entire length of buffer.
69 * a-b == consumed region.
70 * b-d == remaining region.
71 * b-c == optional active region.
74 * The following invariants are maintained by all routines:
79 * base is a valid pointer to length bytes of memory
83 * 0 <= current <= used
86 * (although active < current implies empty active region)
90 * Buffers have no synchronization. Clients must ensure exclusive
94 * No anticipated impact.
97 * Memory: 1 pointer + 6 unsigned integers per buffer.
100 * No anticipated impact.
110 #include <isc/lang.h>
111 #include <isc/magic.h>
112 #include <isc/types.h>
115 * To make many functions be inline macros (via \#define) define this.
116 * If it is undefined, a function will be used.
118 /* #define ISC_BUFFER_USEINLINE */
126 #define ISC_BUFFER_MAGIC 0x42756621U /* Buf!. */
127 #define ISC_BUFFER_VALID(b) ISC_MAGIC_VALID(b, ISC_BUFFER_MAGIC)
131 * The following macros MUST be used only on valid buffers. It is the
132 * caller's responsibility to ensure this by using the ISC_BUFFER_VALID
133 * check above, or by calling another isc_buffer_*() function (rather than
139 * Fundamental buffer elements. (A through E in the introductory comment.)
141 #define isc_buffer_base(b) ((void *)(b)->base) /*a*/
142 #define isc_buffer_current(b) \
143 ((void *)((unsigned char *)(b)->base + (b)->current)) /*b*/
144 #define isc_buffer_active(b) \
145 ((void *)((unsigned char *)(b)->base + (b)->active)) /*c*/
146 #define isc_buffer_used(b) \
147 ((void *)((unsigned char *)(b)->base + (b)->used)) /*d*/
148 #define isc_buffer_length(b) ((b)->length) /*e*/
153 * Derived lengths. (Described in the introductory comment.)
155 #define isc_buffer_usedlength(b) ((b)->used) /* d-a */
156 #define isc_buffer_consumedlength(b) ((b)->current) /* b-a */
157 #define isc_buffer_remaininglength(b) ((b)->used - (b)->current) /* d-b */
158 #define isc_buffer_activelength(b) ((b)->active - (b)->current) /* c-b */
159 #define isc_buffer_availablelength(b) ((b)->length - (b)->used) /* e-d */
163 * Note that the buffer structure is public. This is principally so buffer
164 * operations can be implemented using macros. Applications are strongly
165 * discouraged from directly manipulating the structure.
172 /*! The following integers are byte offsets from 'base'. */
175 unsigned int current;
179 ISC_LINK(isc_buffer_t) link;
180 /*! private internal elements */
189 isc_buffer_allocate(isc_mem_t *mctx, isc_buffer_t **dynbuffer,
190 unsigned int length);
192 * \brief Allocate a dynamic linkable buffer which has "length" bytes in the
196 *\li "mctx" is valid.
198 *\li "dynbuffer" is non-NULL, and "*dynbuffer" is NULL.
201 *\li ISC_R_SUCCESS - success
202 *\li ISC_R_NOMEMORY - no memory available
205 *\li Changing the buffer's length field is not permitted.
209 isc_buffer_free(isc_buffer_t **dynbuffer);
211 * \brief Release resources allocated for a dynamic buffer.
214 *\li "dynbuffer" is not NULL.
216 *\li "*dynbuffer" is a valid dynamic buffer.
219 *\li "*dynbuffer" will be NULL on return, and all memory associated with
220 * the dynamic buffer is returned to the memory context used in
221 * isc_buffer_allocate().
225 isc__buffer_init(isc_buffer_t *b, void *base, unsigned int length);
227 * \brief Make 'b' refer to the 'length'-byte region starting at base.
233 *\li 'base' is a pointer to a sequence of 'length' bytes.
238 isc__buffer_initnull(isc_buffer_t *b);
240 *\brief Initialize a buffer 'b' with a null data and zero length/
244 isc_buffer_reinit(isc_buffer_t *b, void *base, unsigned int length);
246 * \brief Make 'b' refer to the 'length'-byte region starting at base.
247 * Any existing data will be copied.
251 *\li 'length' > 0 AND length >= previous length
253 *\li 'base' is a pointer to a sequence of 'length' bytes.
258 isc__buffer_invalidate(isc_buffer_t *b);
260 * \brief Make 'b' an invalid buffer.
263 *\li 'b' is a valid buffer.
266 *\li If assertion checking is enabled, future attempts to use 'b' without
267 * calling isc_buffer_init() on it will cause an assertion failure.
271 isc__buffer_region(isc_buffer_t *b, isc_region_t *r);
273 * \brief Make 'r' refer to the region of 'b'.
277 *\li 'b' is a valid buffer.
279 *\li 'r' points to a region structure.
283 isc__buffer_usedregion(isc_buffer_t *b, isc_region_t *r);
285 * \brief Make 'r' refer to the used region of 'b'.
289 *\li 'b' is a valid buffer.
291 *\li 'r' points to a region structure.
295 isc__buffer_availableregion(isc_buffer_t *b, isc_region_t *r);
297 * \brief Make 'r' refer to the available region of 'b'.
301 *\li 'b' is a valid buffer.
303 *\li 'r' points to a region structure.
307 isc__buffer_add(isc_buffer_t *b, unsigned int n);
309 * \brief Increase the 'used' region of 'b' by 'n' bytes.
313 *\li 'b' is a valid buffer
315 *\li used + n <= length
320 isc__buffer_subtract(isc_buffer_t *b, unsigned int n);
322 * \brief Decrease the 'used' region of 'b' by 'n' bytes.
326 *\li 'b' is a valid buffer
333 isc__buffer_clear(isc_buffer_t *b);
335 * \brief Make the used region empty.
339 *\li 'b' is a valid buffer
348 isc__buffer_consumedregion(isc_buffer_t *b, isc_region_t *r);
350 * \brief Make 'r' refer to the consumed region of 'b'.
354 *\li 'b' is a valid buffer.
356 *\li 'r' points to a region structure.
360 isc__buffer_remainingregion(isc_buffer_t *b, isc_region_t *r);
362 * \brief Make 'r' refer to the remaining region of 'b'.
366 *\li 'b' is a valid buffer.
368 *\li 'r' points to a region structure.
372 isc__buffer_activeregion(isc_buffer_t *b, isc_region_t *r);
374 * \brief Make 'r' refer to the active region of 'b'.
378 *\li 'b' is a valid buffer.
380 *\li 'r' points to a region structure.
384 isc__buffer_setactive(isc_buffer_t *b, unsigned int n);
386 * \brief Sets the end of the active region 'n' bytes after current.
390 *\li 'b' is a valid buffer.
392 *\li current + n <= used
396 isc__buffer_first(isc_buffer_t *b);
398 * \brief Make the consumed region empty.
402 *\li 'b' is a valid buffer
411 isc__buffer_forward(isc_buffer_t *b, unsigned int n);
413 * \brief Increase the 'consumed' region of 'b' by 'n' bytes.
417 *\li 'b' is a valid buffer
419 *\li current + n <= used
424 isc__buffer_back(isc_buffer_t *b, unsigned int n);
426 * \brief Decrease the 'consumed' region of 'b' by 'n' bytes.
430 *\li 'b' is a valid buffer
437 isc_buffer_compact(isc_buffer_t *b);
439 * \brief Compact the used region by moving the remaining region so it occurs
440 * at the start of the buffer. The used region is shrunk by the size of
441 * the consumed region, and the consumed region is then made empty.
445 *\li 'b' is a valid buffer
451 *\li The size of the used region is now equal to the size of the remaining
452 * region (as it was before the call). The contents of the used region
453 * are those of the remaining region (as it was before the call).
457 isc_buffer_getuint8(isc_buffer_t *b);
459 * \brief Read an unsigned 8-bit integer from 'b' and return it.
463 *\li 'b' is a valid buffer.
465 *\li The length of the available region of 'b' is at least 1.
469 *\li The current pointer in 'b' is advanced by 1.
473 *\li A 8-bit unsigned integer.
477 isc__buffer_putuint8(isc_buffer_t *b, isc_uint8_t val);
479 * \brief Store an unsigned 8-bit integer from 'val' into 'b'.
482 *\li 'b' is a valid buffer.
484 *\li The length of the unused region of 'b' is at least 1.
487 *\li The used pointer in 'b' is advanced by 1.
491 isc_buffer_getuint16(isc_buffer_t *b);
493 * \brief Read an unsigned 16-bit integer in network byte order from 'b', convert
494 * it to host byte order, and return it.
498 *\li 'b' is a valid buffer.
500 *\li The length of the available region of 'b' is at least 2.
504 *\li The current pointer in 'b' is advanced by 2.
508 *\li A 16-bit unsigned integer.
512 isc__buffer_putuint16(isc_buffer_t *b, isc_uint16_t val);
514 * \brief Store an unsigned 16-bit integer in host byte order from 'val'
515 * into 'b' in network byte order.
518 *\li 'b' is a valid buffer.
520 *\li The length of the unused region of 'b' is at least 2.
523 *\li The used pointer in 'b' is advanced by 2.
527 isc_buffer_getuint32(isc_buffer_t *b);
529 * \brief Read an unsigned 32-bit integer in network byte order from 'b', convert
530 * it to host byte order, and return it.
534 *\li 'b' is a valid buffer.
536 *\li The length of the available region of 'b' is at least 4.
540 *\li The current pointer in 'b' is advanced by 4.
544 *\li A 32-bit unsigned integer.
548 isc__buffer_putuint32(isc_buffer_t *b, isc_uint32_t val);
550 * \brief Store an unsigned 32-bit integer in host byte order from 'val'
551 * into 'b' in network byte order.
554 *\li 'b' is a valid buffer.
556 *\li The length of the unused region of 'b' is at least 4.
559 *\li The used pointer in 'b' is advanced by 4.
563 isc_buffer_getuint48(isc_buffer_t *b);
565 * \brief Read an unsigned 48-bit integer in network byte order from 'b',
566 * convert it to host byte order, and return it.
570 *\li 'b' is a valid buffer.
572 *\li The length of the available region of 'b' is at least 6.
576 *\li The current pointer in 'b' is advanced by 6.
580 *\li A 48-bit unsigned integer (stored in a 64-bit integer).
584 isc__buffer_putuint48(isc_buffer_t *b, isc_uint64_t val);
586 * \brief Store an unsigned 48-bit integer in host byte order from 'val'
587 * into 'b' in network byte order.
590 *\li 'b' is a valid buffer.
592 *\li The length of the unused region of 'b' is at least 6.
595 *\li The used pointer in 'b' is advanced by 6.
599 isc__buffer_putuint24(isc_buffer_t *b, isc_uint32_t val);
601 * Store an unsigned 24-bit integer in host byte order from 'val'
602 * into 'b' in network byte order.
605 *\li 'b' is a valid buffer.
607 * The length of the unused region of 'b' is at least 3.
610 *\li The used pointer in 'b' is advanced by 3.
614 isc__buffer_putmem(isc_buffer_t *b, const unsigned char *base,
615 unsigned int length);
617 * \brief Copy 'length' bytes of memory at 'base' into 'b'.
620 *\li 'b' is a valid buffer.
622 *\li 'base' points to 'length' bytes of valid memory.
627 isc__buffer_putstr(isc_buffer_t *b, const char *source);
629 * \brief Copy 'source' into 'b', not including terminating NUL.
632 *\li 'b' is a valid buffer.
634 *\li 'source' to be a valid NULL terminated string.
636 *\li strlen(source) <= isc_buffer_available(b)
640 isc_buffer_copyregion(isc_buffer_t *b, const isc_region_t *r);
642 * \brief Copy the contents of 'r' into 'b'.
645 *\li 'b' is a valid buffer.
647 *\li 'r' is a valid region.
652 *\li ISC_R_NOSPACE The available region of 'b' is not
659 * Inline macro versions of the functions. These should never be called
660 * directly by an application, but will be used by the functions within
661 * buffer.c. The callers should always use "isc_buffer_*()" names, never
662 * ones beginning with "isc__"
666 * XXXDCL Something more could be done with initializing buffers that
667 * point to const data. For example, a new function, isc_buffer_initconst,
668 * could be used, and a new boolean flag in the buffer structure could
669 * indicate whether the buffer was initialized with that function.
670 * (isc_bufer_init itself would be reprototyped to *not* have its "base"
671 * parameter be const.) Then if the boolean were true, the isc_buffer_put*
672 * functions could assert a contractual requirement for a non-const buffer.
673 * One drawback is that the isc_buffer_* functions (macros) that return
674 * pointers would still need to return non-const pointers to avoid compiler
675 * warnings, so it would be up to code that uses them to have to deal
676 * with the possibility that the buffer was initialized as const --
677 * a problem that they *already* have to deal with but have absolutely
678 * no ability to. With a new isc_buffer_isconst() function returning
679 * true/false, they could at least assert a contractual requirement for
680 * non-const buffers when needed.
682 #define ISC__BUFFER_INIT(_b, _base, _length) \
684 (_b)->base = _base; \
685 (_b)->length = (_length); \
690 ISC_LINK_INIT(_b, link); \
691 (_b)->magic = ISC_BUFFER_MAGIC; \
694 #define ISC__BUFFER_INITNULL(_b) ISC__BUFFER_INIT(_b, NULL, 0)
696 #define ISC__BUFFER_INVALIDATE(_b) \
706 #define ISC__BUFFER_REGION(_b, _r) \
708 (_r)->base = (_b)->base; \
709 (_r)->length = (_b)->length; \
712 #define ISC__BUFFER_USEDREGION(_b, _r) \
714 (_r)->base = (_b)->base; \
715 (_r)->length = (_b)->used; \
718 #define ISC__BUFFER_AVAILABLEREGION(_b, _r) \
720 (_r)->base = isc_buffer_used(_b); \
721 (_r)->length = isc_buffer_availablelength(_b); \
724 #define ISC__BUFFER_ADD(_b, _n) \
726 (_b)->used += (_n); \
729 #define ISC__BUFFER_SUBTRACT(_b, _n) \
731 (_b)->used -= (_n); \
732 if ((_b)->current > (_b)->used) \
733 (_b)->current = (_b)->used; \
734 if ((_b)->active > (_b)->used) \
735 (_b)->active = (_b)->used; \
738 #define ISC__BUFFER_CLEAR(_b) \
745 #define ISC__BUFFER_CONSUMEDREGION(_b, _r) \
747 (_r)->base = (_b)->base; \
748 (_r)->length = (_b)->current; \
751 #define ISC__BUFFER_REMAININGREGION(_b, _r) \
753 (_r)->base = isc_buffer_current(_b); \
754 (_r)->length = isc_buffer_remaininglength(_b); \
757 #define ISC__BUFFER_ACTIVEREGION(_b, _r) \
759 if ((_b)->current < (_b)->active) { \
760 (_r)->base = isc_buffer_current(_b); \
761 (_r)->length = isc_buffer_activelength(_b); \
768 #define ISC__BUFFER_SETACTIVE(_b, _n) \
770 (_b)->active = (_b)->current + (_n); \
773 #define ISC__BUFFER_FIRST(_b) \
778 #define ISC__BUFFER_FORWARD(_b, _n) \
780 (_b)->current += (_n); \
783 #define ISC__BUFFER_BACK(_b, _n) \
785 (_b)->current -= (_n); \
788 #define ISC__BUFFER_PUTMEM(_b, _base, _length) \
790 memmove(isc_buffer_used(_b), (_base), (_length)); \
791 (_b)->used += (_length); \
794 #define ISC__BUFFER_PUTSTR(_b, _source) \
796 unsigned int _length; \
797 unsigned char *_cp; \
798 _length = strlen(_source); \
799 _cp = isc_buffer_used(_b); \
800 memmove(_cp, (_source), _length); \
801 (_b)->used += (_length); \
804 #define ISC__BUFFER_PUTUINT8(_b, _val) \
806 unsigned char *_cp; \
807 isc_uint8_t _val2 = (_val); \
808 _cp = isc_buffer_used(_b); \
810 _cp[0] = _val2 & 0x00ff; \
813 #define ISC__BUFFER_PUTUINT16(_b, _val) \
815 unsigned char *_cp; \
816 isc_uint16_t _val2 = (_val); \
817 _cp = isc_buffer_used(_b); \
819 _cp[0] = (unsigned char)((_val2 & 0xff00U) >> 8); \
820 _cp[1] = (unsigned char)(_val2 & 0x00ffU); \
823 #define ISC__BUFFER_PUTUINT24(_b, _val) \
825 unsigned char *_cp; \
826 isc_uint32_t _val2 = (_val); \
827 _cp = isc_buffer_used(_b); \
829 _cp[0] = (unsigned char)((_val2 & 0xff0000U) >> 16); \
830 _cp[1] = (unsigned char)((_val2 & 0xff00U) >> 8); \
831 _cp[2] = (unsigned char)(_val2 & 0x00ffU); \
834 #define ISC__BUFFER_PUTUINT32(_b, _val) \
836 unsigned char *_cp; \
837 isc_uint32_t _val2 = (_val); \
838 _cp = isc_buffer_used(_b); \
840 _cp[0] = (unsigned char)((_val2 & 0xff000000) >> 24); \
841 _cp[1] = (unsigned char)((_val2 & 0x00ff0000) >> 16); \
842 _cp[2] = (unsigned char)((_val2 & 0x0000ff00) >> 8); \
843 _cp[3] = (unsigned char)((_val2 & 0x000000ff)); \
846 #if defined(ISC_BUFFER_USEINLINE)
847 #define isc_buffer_init ISC__BUFFER_INIT
848 #define isc_buffer_initnull ISC__BUFFER_INITNULL
849 #define isc_buffer_invalidate ISC__BUFFER_INVALIDATE
850 #define isc_buffer_region ISC__BUFFER_REGION
851 #define isc_buffer_usedregion ISC__BUFFER_USEDREGION
852 #define isc_buffer_availableregion ISC__BUFFER_AVAILABLEREGION
853 #define isc_buffer_add ISC__BUFFER_ADD
854 #define isc_buffer_subtract ISC__BUFFER_SUBTRACT
855 #define isc_buffer_clear ISC__BUFFER_CLEAR
856 #define isc_buffer_consumedregion ISC__BUFFER_CONSUMEDREGION
857 #define isc_buffer_remainingregion ISC__BUFFER_REMAININGREGION
858 #define isc_buffer_activeregion ISC__BUFFER_ACTIVEREGION
859 #define isc_buffer_setactive ISC__BUFFER_SETACTIVE
860 #define isc_buffer_first ISC__BUFFER_FIRST
861 #define isc_buffer_forward ISC__BUFFER_FORWARD
862 #define isc_buffer_back ISC__BUFFER_BACK
863 #define isc_buffer_putmem ISC__BUFFER_PUTMEM
864 #define isc_buffer_putstr ISC__BUFFER_PUTSTR
865 #define isc_buffer_putuint8 ISC__BUFFER_PUTUINT8
866 #define isc_buffer_putuint16 ISC__BUFFER_PUTUINT16
867 #define isc_buffer_putuint24 ISC__BUFFER_PUTUINT24
868 #define isc_buffer_putuint32 ISC__BUFFER_PUTUINT32
870 #define isc_buffer_init isc__buffer_init
871 #define isc_buffer_initnull isc__buffer_initnull
872 #define isc_buffer_invalidate isc__buffer_invalidate
873 #define isc_buffer_region isc__buffer_region
874 #define isc_buffer_usedregion isc__buffer_usedregion
875 #define isc_buffer_availableregion isc__buffer_availableregion
876 #define isc_buffer_add isc__buffer_add
877 #define isc_buffer_subtract isc__buffer_subtract
878 #define isc_buffer_clear isc__buffer_clear
879 #define isc_buffer_consumedregion isc__buffer_consumedregion
880 #define isc_buffer_remainingregion isc__buffer_remainingregion
881 #define isc_buffer_activeregion isc__buffer_activeregion
882 #define isc_buffer_setactive isc__buffer_setactive
883 #define isc_buffer_first isc__buffer_first
884 #define isc_buffer_forward isc__buffer_forward
885 #define isc_buffer_back isc__buffer_back
886 #define isc_buffer_putmem isc__buffer_putmem
887 #define isc_buffer_putstr isc__buffer_putstr
888 #define isc_buffer_putuint8 isc__buffer_putuint8
889 #define isc_buffer_putuint16 isc__buffer_putuint16
890 #define isc_buffer_putuint24 isc__buffer_putuint24
891 #define isc_buffer_putuint32 isc__buffer_putuint32
894 #define isc_buffer_constinit(_b, _d, _l) \
896 union { void *_var; const void *_const; } _deconst; \
897 _deconst._const = (_d); \
898 isc_buffer_init((_b), _deconst._var, (_l)); \
902 * No inline method for this one (yet).
904 #define isc_buffer_putuint48 isc__buffer_putuint48
906 #endif /* ISC_BUFFER_H */