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 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 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 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 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 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 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 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