1 /***************************************************************************** 2 * $Id: cbuf.h,v 1.2 2008-08-12 18:14:33 chu11 Exp $ 3 ***************************************************************************** 4 * Copyright (C) 2002-2005 The Regents of the University of California. 5 * Produced at Lawrence Livermore National Laboratory (cf, DISCLAIMER). 6 * Written by Chris Dunlap <cdunlap@llnl.gov>. 7 * 8 * This file is from LSD-Tools, the LLNL Software Development Toolbox. 9 * 10 * LSD-Tools is free software; you can redistribute it and/or modify it under 11 * the terms of the GNU General Public License as published by the Free 12 * Software Foundation; either version 2 of the License, or (at your option) 13 * any later version. 14 * 15 * LSD-Tools is distributed in the hope that it will be useful, but WITHOUT 16 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 17 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for 18 * more details. 19 * 20 * You should have received a copy of the GNU General Public License along 21 * with LSD-Tools; if not, write to the Free Software Foundation, Inc., 22 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. 23 *****************************************************************************/ 24 25 26 #ifndef LSD_CBUF_H 27 #define LSD_CBUF_H 28 29 30 /***************************************************************************** 31 * Notes 32 *****************************************************************************/ 33 /* 34 * Cbuf is a circular-buffer capable of dynamically resizing itself. 35 * Unread data in the buffer will be overwritten once the cbuf has 36 * reached its maximum size or is unable to allocate additional memory. 37 * 38 * The CBUF_OPT_OVERWRITE option specifies how unread cbuf data will 39 * be overwritten. If set to CBUF_NO_DROP, unread data will never be 40 * overwritten; writes into the cbuf will return -1 with ENOSPC. If set 41 * to CBUF_WRAP_ONCE, a single write operation will wrap-around the buffer 42 * at most once, and up to cbuf_used() bytes of data may be overwritten. 43 * If set to CBUF_WRAP_MANY, a single write operation will wrap-around the 44 * buffer as many times as needed in order to write all of the data. 45 * 46 * If NDEBUG is not defined, internal debug code will be enabled. This is 47 * intended for development use only and production code should define NDEBUG. 48 * 49 * If WITH_LSD_FATAL_ERROR_FUNC is defined, the linker will expect to 50 * find an external lsd_fatal_error(file,line,mesg) function. By default, 51 * lsd_fatal_error(file,line,mesg) is a macro definition that outputs an 52 * error message to stderr. This macro may be redefined to invoke another 53 * routine instead. 54 * 55 * If WITH_LSD_NOMEM_ERROR_FUNC is defined, the linker will expect to 56 * find an external lsd_nomem_error(file,line,mesg) function. By default, 57 * lsd_nomem_error(file,line,mesg) is a macro definition that returns NULL. 58 * This macro may be redefined to invoke another routine instead. 59 * 60 * If WITH_PTHREADS is defined, these routines will be thread-safe. 61 */ 62 63 64 /***************************************************************************** 65 * Data Types 66 *****************************************************************************/ 67 68 typedef struct cbuf * cbuf_t; /* circular-buffer opaque data type */ 69 70 typedef enum { /* cbuf option names */ 71 CBUF_OPT_OVERWRITE 72 } cbuf_opt_t; 73 74 typedef enum { /* CBUF_OPT_OVERWRITE values: */ 75 CBUF_NO_DROP, /* -never drop data, ENOSPC if full */ 76 CBUF_WRAP_ONCE, /* -drop data, wrapping at most once */ 77 CBUF_WRAP_MANY /* -drop data, wrapping as needed */ 78 } cbuf_overwrite_t; 79 80 81 /***************************************************************************** 82 * Functions 83 *****************************************************************************/ 84 85 cbuf_t cbuf_create (int minsize, int maxsize); 86 /* 87 * Creates and returns a new circular buffer, or lsd_nomem_error() on failure. 88 * The buffer is initially allocated to hold [minsize] bytes of data, 89 * but can attempt to grow up to [maxsize] bytes before overwriting data. 90 * Set minsize = maxsize to prevent cbuf from dynamically resizing itself. 91 * The default overwrite option behavior is CBUF_WRAP_MANY. 92 * Abandoning a cbuf without calling cbuf_destroy() will cause a memory leak. 93 */ 94 95 void cbuf_destroy (cbuf_t cb); 96 /* 97 * Destroys the circular buffer [cb]. 98 */ 99 100 void cbuf_flush (cbuf_t cb); 101 /* 102 * Flushes all data (including replay data) in [cb]. 103 */ 104 105 int cbuf_size (cbuf_t cb); 106 /* 107 * Returns the maximum size of the buffer allocated to [cb] 108 * (ie, the number of bytes it can currently hold). 109 */ 110 111 int cbuf_free (cbuf_t cb); 112 /* 113 * Returns the number of bytes in [cb] available for writing before unread 114 * data is overwritten (assuming the cbuf can resize itself if needed). 115 */ 116 117 int cbuf_used (cbuf_t cb); 118 /* 119 * Returns the number of bytes in [cb] available for reading. 120 */ 121 122 int cbuf_lines_used (cbuf_t cb); 123 /* 124 * Returns the number of lines in [cb] available for reading. 125 */ 126 127 int cbuf_reused (cbuf_t cb); 128 /* 129 * Returns the number of bytes in [cb] available for replaying/rewinding. 130 */ 131 132 int cbuf_lines_reused (cbuf_t cb); 133 /* 134 * Returns the number of lines in [cb] available for replaying/rewinding. 135 */ 136 137 int cbuf_is_empty (cbuf_t cb); 138 /* 139 * Returns non-zero if [cb] is empty; o/w, returns zero. 140 */ 141 142 int cbuf_opt_get (cbuf_t cb, cbuf_opt_t name, int *value); 143 /* 144 * Gets the [name] option for [cb] and sets [value] to the result. 145 * Returns 0 on success, or -1 on error (with errno set). 146 */ 147 148 int cbuf_opt_set (cbuf_t cb, cbuf_opt_t name, int value); 149 /* 150 * Sets the [name] option for [cb] to [value]. 151 * Returns 0 on success, or -1 on error (with errno set). 152 */ 153 154 int cbuf_drop (cbuf_t src, int len); 155 /* 156 * Discards up to [len] bytes of unread data from [src]; 157 * if [len] is -1, all unread data will be dropped. 158 * Dropped data is still available via the replay buffer. 159 * Returns the number of bytes dropped, or -1 on error (with errno set). 160 */ 161 162 int cbuf_peek (cbuf_t src, void *dstbuf, int len); 163 /* 164 * Reads up to [len] bytes of data from the [src] cbuf into [dstbuf], 165 * but does not consume the data read from the cbuf. 166 * The "peek" can be committed to the cbuf via a call to cbuf_drop(), 167 * but the peek+drop combination is not atomic. 168 * Returns the number of bytes read, or -1 on error (with errno set). 169 */ 170 171 int cbuf_read (cbuf_t src, void *dstbuf, int len); 172 /* 173 * Reads up to [len] bytes of data from the [src] cbuf into [dstbuf]. 174 * Returns the number of bytes read, or -1 on error (with errno set). 175 */ 176 177 int cbuf_replay (cbuf_t src, void *dstbuf, int len); 178 /* 179 * Replays up to [len] bytes of previously read data from the [src] cbuf 180 * into [dstbuf]. 181 * Returns the number of bytes replayed, or -1 on error (with errno set). 182 */ 183 184 int cbuf_rewind (cbuf_t src, int len); 185 /* 186 * Rewinds [src] by up to [len] bytes, placing previously read data back in 187 * the unread data buffer; if [len] is -1, all replay data will be rewound. 188 * Returns the number of bytes rewound, or -1 on error (with errno set). 189 */ 190 191 int cbuf_write (cbuf_t dst, void *srcbuf, int len, int *ndropped); 192 /* 193 * Writes up to [len] bytes of data from [srcbuf] into the [dst] cbuf 194 * according to dst's CBUF_OPT_OVERWRITE behavior. 195 * Returns the number of bytes written, or -1 on error (with errno set). 196 * Sets [ndropped] (if not NULL) to the number of bytes overwritten. 197 */ 198 199 int cbuf_drop_line (cbuf_t src, int len, int lines); 200 /* 201 * Discards the specified [lines] of data from [src]. If [lines] is -1, 202 * discards the maximum number of lines comprised of up to [len] characters. 203 * Dropped data is still available via the replay buffer. 204 * Returns the number of bytes dropped, or -1 on error (with errno set). 205 * Returns 0 if the number of lines is not available (ie, all or none). 206 */ 207 208 int cbuf_peek_line (cbuf_t src, char *dstbuf, int len, int lines); 209 /* 210 * Reads the specified [lines] of data from the [src] cbuf into [dstbuf], 211 * but does not consume the data read from the cbuf. If [lines] is -1, 212 * reads the maximum number of lines that [dstbuf] can hold. The buffer 213 * will be NUL-terminated and contain at most ([len] - 1) characters. 214 * The "peek" can be committed to the cbuf via a call to cbuf_drop(), 215 * but the peek+drop combination is not atomic. 216 * Returns strlen of the line(s) on success; truncation occurred if >= [len]. 217 * Returns 0 if the number of lines is not available (ie, all or none). 218 * Returns -1 on error (with errno set). 219 */ 220 221 int cbuf_read_line (cbuf_t src, char *dstbuf, int len, int lines); 222 /* 223 * Reads the specified [lines] of data from the [src] cbuf into [dstbuf]. 224 * If [lines] is -1, reads the maximum number of lines that [dstbuf] 225 * can hold. The buffer will be NUL-terminated and contain at most 226 * ([len] - 1) characters. 227 * Returns strlen of the line(s) on success; truncation occurred if >= [len], 228 * in which case excess line data is discarded. Returns 0 if the number 229 * of lines is not available (ie, all or none), in which case no data is 230 * consumed. Returns -1 on error (with errno set). 231 */ 232 233 int cbuf_replay_line (cbuf_t src, char *dstbuf, int len, int lines); 234 /* 235 * Replays the specified [lines] of data from the [src] cbuf into [dstbuf]. 236 * If [lines] is -1, replays the maximum number of lines that [dstbuf] 237 * can hold. A newline will be appended to [dstbuf] if the last (ie, most 238 * recently read) line does not contain a trailing newline. The buffer 239 * will be NUL-terminated and contain at most ([len] - 1) characters. 240 * Returns strlen of the line(s) on success; truncation occurred if >= [len]. 241 * Returns 0 if the number of lines is not available (ie, all or none). 242 * Returns -1 on error (with errno set). 243 */ 244 245 int cbuf_rewind_line (cbuf_t src, int len, int lines); 246 /* 247 * Rewinds [src] by the specified [lines] of data, placing previously read 248 * data back in the unread data buffer. If [lines] is -1, rewinds the 249 * maximum number of lines comprised of up to [len] characters. 250 * Returns the number of bytes rewound, or -1 on error (with errno set). 251 * Returns 0 if the number of lines is not available (ie, all or none). 252 */ 253 254 int cbuf_write_line (cbuf_t dst, char *srcbuf, int *ndropped); 255 /* 256 * Writes the entire NUL-terminated [srcbuf] string into the [dst] cbuf 257 * according to dst's CBUF_OPT_OVERWRITE behavior. A newline will be 258 * appended to the cbuf if [srcbuf] does not contain a trailing newline. 259 * Returns the number of bytes written, or -1 or error (with errno set). 260 * Sets [ndropped] (if not NULL) to the number of bytes overwritten. 261 */ 262 263 int cbuf_peek_to_fd (cbuf_t src, int dstfd, int len); 264 /* 265 * Reads up to [len] bytes of data from the [src] cbuf into the file 266 * referenced by the [dstfd] file descriptor, but does not consume the 267 * data read from the cbuf. If [len] is -1, it will be set to the number 268 * of [src] bytes available for reading. 269 * The "peek" can be committed to the cbuf via a call to cbuf_drop(), 270 * but the peek+drop combination is not atomic. 271 * Returns the number of bytes read, or -1 on error (with errno set). 272 */ 273 274 int cbuf_read_to_fd (cbuf_t src, int dstfd, int len); 275 /* 276 * Reads up to [len] bytes of data from the [src] cbuf into the file 277 * referenced by the [dstfd] file descriptor. If [len] is -1, it will 278 * be set to the number of [src] bytes available for reading. 279 * Returns the number of bytes read, or -1 on error (with errno set). 280 */ 281 282 int cbuf_replay_to_fd (cbuf_t src, int dstfd, int len); 283 /* 284 * Replays up to [len] bytes of previously read data from the [src] cbuf into 285 * the file referenced by the [dstfd] file descriptor. If [len] is -1, it 286 * will be set to the maximum number of [src] bytes available for replay. 287 * Returns the number of bytes replayed, or -1 on error (with errno set). 288 */ 289 290 int cbuf_write_from_fd (cbuf_t dst, int srcfd, int len, int *ndropped); 291 /* 292 * Writes up to [len] bytes of data from the file referenced by the 293 * [srcfd] file descriptor into the [dst] cbuf according to dst's 294 * CBUF_OPT_OVERWRITE behavior. If [len] is -1, it will be set to 295 * an appropriate chunk size. 296 * Returns the number of bytes written, 0 on EOF, or -1 on error (with errno). 297 * Sets [ndropped] (if not NULL) to the number of bytes overwritten. 298 */ 299 300 int cbuf_copy (cbuf_t src, cbuf_t dst, int len, int *ndropped); 301 /* 302 * Copies up to [len] bytes of data from the [src] cbuf into the [dst] cbuf 303 * according to dst's CBUF_OPT_OVERWRITE behavior. If [len] is -1, 304 * it will be set to the number of [src] bytes available for reading. 305 * Returns the number of bytes copied, or -1 on error (with errno set). 306 * Sets [ndropped] (if not NULL) to the number of [dst] bytes overwritten. 307 */ 308 309 int cbuf_move (cbuf_t src, cbuf_t dst, int len, int *ndropped); 310 /* 311 * Moves up to [len] bytes of data from the [src] cbuf into the [dst] cbuf 312 * according to dst's CBUF_OPT_OVERWRITE behavior. If [len] is -1, 313 * it will be set to the number of [src] bytes available for reading. 314 * Returns the number of bytes moved, or -1 on error (with errno set). 315 * Sets [ndropped] (if not NULL) to the number of [dst] bytes overwritten. 316 */ 317 318 319 #endif /* !LSD_CBUF_H */ 320