1 /* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */
2 /* include/k5-buf.h - k5buf interface declarations */
3 /*
4 * Copyright 2008 Massachusetts Institute of Technology.
5 * All Rights Reserved.
6 *
7 * Export of this software from the United States of America may
8 * require a specific license from the United States Government.
9 * It is the responsibility of any person or organization contemplating
10 * export to obtain such a license before exporting.
11 *
12 * WITHIN THAT CONSTRAINT, permission to use, copy, modify, and
13 * distribute this software and its documentation for any purpose and
14 * without fee is hereby granted, provided that the above copyright
15 * notice appear in all copies and that both that copyright notice and
16 * this permission notice appear in supporting documentation, and that
17 * the name of M.I.T. not be used in advertising or publicity pertaining
18 * to distribution of the software without specific, written prior
19 * permission. Furthermore if you modify this software you must label
20 * your software as modified software and not distribute it in such a
21 * fashion that it might be confused with the original M.I.T. software.
22 * M.I.T. makes no representations about the suitability of
23 * this software for any purpose. It is provided "as is" without express
24 * or implied warranty.
25 */
26
27 #ifndef K5_BUF_H
28 #define K5_BUF_H
29
30 #include <stdarg.h>
31 #include <string.h>
32
33 /*
34 * The k5buf module is intended to allow multi-step string construction in a
35 * fixed or dynamic buffer without the need to check for a failure at each step
36 * (and without aborting on malloc failure). If an allocation failure occurs
37 * or the fixed buffer runs out of room, the buffer will be set to an error
38 * state which can be detected with k5_buf_status. Data in a buffer is not
39 * automatically terminated with a zero byte; call k5_buf_cstring() to use the
40 * contents as a C string.
41 *
42 * k5buf structures are usually stack-allocated. Do not put k5buf structure
43 * pointers into public APIs. It is okay to reference the data and len fields
44 * of a buffer (they will be NULL/0 if the buffer is in an error state), but do
45 * not change them.
46 */
47
48 /* Buffer type values */
49 enum k5buftype { K5BUF_ERROR, K5BUF_FIXED, K5BUF_DYNAMIC, K5BUF_DYNAMIC_ZAP };
50
51 struct k5buf {
52 enum k5buftype buftype;
53 void *data;
54 size_t space;
55 size_t len;
56 };
57
58 #define EMPTY_K5BUF { K5BUF_ERROR }
59
60 /* Initialize a k5buf using a fixed-sized, existing buffer. SPACE must be
61 * more than zero, or an assertion failure will result. */
62 void k5_buf_init_fixed(struct k5buf *buf, void *data, size_t space);
63
64 /* Initialize a k5buf using an internally allocated dynamic buffer. */
65 void k5_buf_init_dynamic(struct k5buf *buf);
66
67 /* Initialize a k5buf using an internally allocated dynamic buffer, zeroing
68 * memory when reallocating or freeing. */
69 void k5_buf_init_dynamic_zap(struct k5buf *buf);
70
71 /* Add a C string to BUF. */
72 void k5_buf_add(struct k5buf *buf, const char *data);
73
74 /* Add a counted series of bytes to BUF. */
75 void k5_buf_add_len(struct k5buf *buf, const void *data, size_t len);
76
77 /* Add sprintf-style formatted data to BUF. For a fixed-length buffer this
78 * operation will fail if there isn't room for a zero terminator. */
79 void k5_buf_add_fmt(struct k5buf *buf, const char *fmt, ...)
80 #if !defined(__cplusplus) && (__GNUC__ > 2)
81 __attribute__((__format__(__printf__, 2, 3)))
82 #endif
83 ;
84
85 /* Add sprintf-style formatted data to BUF, with a va_list. The value of ap is
86 * undefined after the call. */
87 void k5_buf_add_vfmt(struct k5buf *buf, const char *fmt, va_list ap)
88 #if !defined(__cplusplus) && (__GNUC__ > 2)
89 __attribute__((__format__(__printf__, 2, 0)))
90 #endif
91 ;
92
93 /* Without changing the length of buf, ensure that there is a zero byte after
94 * buf.data and return it. Return NULL on error. */
95 char *k5_buf_cstring(struct k5buf *buf);
96
97 /* Extend the length of buf by len and return a pointer to the reserved space,
98 * to be filled in by the caller. Return NULL on error. */
99 void *k5_buf_get_space(struct k5buf *buf, size_t len);
100
101 /* Truncate BUF. LEN must be between 0 and the existing buffer
102 * length, or an assertion failure will result. */
103 void k5_buf_truncate(struct k5buf *buf, size_t len);
104
105 /* Return ENOMEM if buf is in an error state, 0 otherwise. */
106 int k5_buf_status(struct k5buf *buf);
107
108 /*
109 * Free the storage used in the dynamic buffer BUF. The caller may choose to
110 * take responsibility for freeing the data pointer instead of using this
111 * function. If BUF is a fixed buffer, an assertion failure will result.
112 * Freeing a buffer in the error state, a buffer initialized with EMPTY_K5BUF,
113 * or a zeroed k5buf structure is a no-op.
114 */
115 void k5_buf_free(struct k5buf *buf);
116
117 static inline void
k5_buf_add_byte(struct k5buf * buf,uint8_t val)118 k5_buf_add_byte(struct k5buf *buf, uint8_t val)
119 {
120 k5_buf_add_len(buf, &val, 1);
121 }
122
123 static inline void
k5_buf_add_uint16_be(struct k5buf * buf,uint16_t val)124 k5_buf_add_uint16_be(struct k5buf *buf, uint16_t val)
125 {
126 void *p = k5_buf_get_space(buf, 2);
127
128 if (p != NULL)
129 store_16_be(val, p);
130 }
131
132 static inline void
k5_buf_add_uint16_le(struct k5buf * buf,uint16_t val)133 k5_buf_add_uint16_le(struct k5buf *buf, uint16_t val)
134 {
135 void *p = k5_buf_get_space(buf, 2);
136
137 if (p != NULL)
138 store_16_le(val, p);
139 }
140
141 static inline void
k5_buf_add_uint32_be(struct k5buf * buf,uint32_t val)142 k5_buf_add_uint32_be(struct k5buf *buf, uint32_t val)
143 {
144 void *p = k5_buf_get_space(buf, 4);
145
146 if (p != NULL)
147 store_32_be(val, p);
148 }
149
150 static inline void
k5_buf_add_uint32_le(struct k5buf * buf,uint32_t val)151 k5_buf_add_uint32_le(struct k5buf *buf, uint32_t val)
152 {
153 void *p = k5_buf_get_space(buf, 4);
154
155 if (p != NULL)
156 store_32_le(val, p);
157 }
158
159 static inline void
k5_buf_add_uint64_be(struct k5buf * buf,uint64_t val)160 k5_buf_add_uint64_be(struct k5buf *buf, uint64_t val)
161 {
162 void *p = k5_buf_get_space(buf, 8);
163
164 if (p != NULL)
165 store_64_be(val, p);
166 }
167
168 static inline void
k5_buf_add_uint64_le(struct k5buf * buf,uint64_t val)169 k5_buf_add_uint64_le(struct k5buf *buf, uint64_t val)
170 {
171 void *p = k5_buf_get_space(buf, 8);
172
173 if (p != NULL)
174 store_64_le(val, p);
175 }
176
177 #endif /* K5_BUF_H */
178