1 /* $NetBSD: buffer.h,v 1.1.1.4 2021/04/07 02:43:14 christos Exp $ */ 2 /* 3 * Copyright (c) 2007-2012 Niels Provos and Nick Mathewson 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions 7 * are met: 8 * 1. Redistributions of source code must retain the above copyright 9 * notice, this list of conditions and the following disclaimer. 10 * 2. Redistributions in binary form must reproduce the above copyright 11 * notice, this list of conditions and the following disclaimer in the 12 * documentation and/or other materials provided with the distribution. 13 * 3. The name of the author may not be used to endorse or promote products 14 * derived from this software without specific prior written permission. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 17 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 18 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 19 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 20 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 21 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 22 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 23 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 24 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 25 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26 */ 27 #ifndef EVENT2_BUFFER_H_INCLUDED_ 28 #define EVENT2_BUFFER_H_INCLUDED_ 29 30 /** @file event2/buffer.h 31 32 Functions for buffering data for network sending or receiving. 33 34 An evbuffer can be used for preparing data before sending it to 35 the network or conversely for reading data from the network. 36 Evbuffers try to avoid memory copies as much as possible. As a 37 result, evbuffers can be used to pass data around without actually 38 incurring the overhead of copying the data. 39 40 A new evbuffer can be allocated with evbuffer_new(), and can be 41 freed with evbuffer_free(). Most users will be using evbuffers via 42 the bufferevent interface. To access a bufferevent's evbuffers, use 43 bufferevent_get_input() and bufferevent_get_output(). 44 45 There are several guidelines for using evbuffers. 46 47 - if you already know how much data you are going to add as a result 48 of calling evbuffer_add() multiple times, it makes sense to use 49 evbuffer_expand() first to make sure that enough memory is allocated 50 before hand. 51 52 - evbuffer_add_buffer() adds the contents of one buffer to the other 53 without incurring any unnecessary memory copies. 54 55 - evbuffer_add() and evbuffer_add_buffer() do not mix very well: 56 if you use them, you will wind up with fragmented memory in your 57 buffer. 58 59 - For high-performance code, you may want to avoid copying data into and out 60 of buffers. You can skip the copy step by using 61 evbuffer_reserve_space()/evbuffer_commit_space() when writing into a 62 buffer, and evbuffer_peek() when reading. 63 64 In Libevent 2.0 and later, evbuffers are represented using a linked 65 list of memory chunks, with pointers to the first and last chunk in 66 the chain. 67 68 As the contents of an evbuffer can be stored in multiple different 69 memory blocks, it cannot be accessed directly. Instead, evbuffer_pullup() 70 can be used to force a specified number of bytes to be contiguous. This 71 will cause memory reallocation and memory copies if the data is split 72 across multiple blocks. It is more efficient, however, to use 73 evbuffer_peek() if you don't require that the memory to be contiguous. 74 */ 75 76 #include <event2/visibility.h> 77 78 #ifdef __cplusplus 79 extern "C" { 80 #endif 81 82 #include <event2/event-config.h> 83 #include <stdarg.h> 84 #ifdef EVENT__HAVE_SYS_TYPES_H 85 #include <sys/types.h> 86 #endif 87 #ifdef EVENT__HAVE_SYS_UIO_H 88 #include <sys/uio.h> 89 #endif 90 #include <event2/util.h> 91 92 /** 93 An evbuffer is an opaque data type for efficiently buffering data to be 94 sent or received on the network. 95 96 @see event2/event.h for more information 97 */ 98 struct evbuffer 99 #ifdef EVENT_IN_DOXYGEN_ 100 {} 101 #endif 102 ; 103 104 /** 105 Pointer to a position within an evbuffer. 106 107 Used when repeatedly searching through a buffer. Calling any function 108 that modifies or re-packs the buffer contents may invalidate all 109 evbuffer_ptrs for that buffer. Do not modify or contruct these values 110 except with evbuffer_ptr_set. 111 112 An evbuffer_ptr can represent any position from the start of a buffer up 113 to a position immediately after the end of a buffer. 114 115 @see evbuffer_ptr_set() 116 */ 117 struct evbuffer_ptr { 118 ev_ssize_t pos; 119 120 /* Do not alter or rely on the values of fields: they are for internal 121 * use */ 122 struct { 123 void *chain; 124 size_t pos_in_chain; 125 } internal_; 126 }; 127 128 /** Describes a single extent of memory inside an evbuffer. Used for 129 direct-access functions. 130 131 @see evbuffer_reserve_space, evbuffer_commit_space, evbuffer_peek 132 */ 133 #ifdef EVENT__HAVE_SYS_UIO_H 134 #define evbuffer_iovec iovec 135 /* Internal use -- defined only if we are using the native struct iovec */ 136 #define EVBUFFER_IOVEC_IS_NATIVE_ 137 #else 138 struct evbuffer_iovec { 139 /** The start of the extent of memory. */ 140 void *iov_base; 141 /** The length of the extent of memory. */ 142 size_t iov_len; 143 }; 144 #endif 145 146 /** 147 Allocate storage for a new evbuffer. 148 149 @return a pointer to a newly allocated evbuffer struct, or NULL if an error 150 occurred 151 */ 152 EVENT2_EXPORT_SYMBOL 153 struct evbuffer *evbuffer_new(void); 154 /** 155 Deallocate storage for an evbuffer. 156 157 @param buf pointer to the evbuffer to be freed 158 */ 159 EVENT2_EXPORT_SYMBOL 160 void evbuffer_free(struct evbuffer *buf); 161 162 /** 163 Enable locking on an evbuffer so that it can safely be used by multiple 164 threads at the same time. 165 166 NOTE: when locking is enabled, the lock will be held when callbacks are 167 invoked. This could result in deadlock if you aren't careful. Plan 168 accordingly! 169 170 @param buf An evbuffer to make lockable. 171 @param lock A lock object, or NULL if we should allocate our own. 172 @return 0 on success, -1 on failure. 173 */ 174 EVENT2_EXPORT_SYMBOL 175 int evbuffer_enable_locking(struct evbuffer *buf, void *lock); 176 177 /** 178 Acquire the lock on an evbuffer. Has no effect if locking was not enabled 179 with evbuffer_enable_locking. 180 */ 181 EVENT2_EXPORT_SYMBOL 182 void evbuffer_lock(struct evbuffer *buf); 183 184 /** 185 Release the lock on an evbuffer. Has no effect if locking was not enabled 186 with evbuffer_enable_locking. 187 */ 188 EVENT2_EXPORT_SYMBOL 189 void evbuffer_unlock(struct evbuffer *buf); 190 191 192 /** If this flag is set, then we will not use evbuffer_peek(), 193 * evbuffer_remove(), evbuffer_remove_buffer(), and so on to read bytes 194 * from this buffer: we'll only take bytes out of this buffer by 195 * writing them to the network (as with evbuffer_write_atmost), by 196 * removing them without observing them (as with evbuffer_drain), 197 * or by copying them all out at once (as with evbuffer_add_buffer). 198 * 199 * Using this option allows the implementation to use sendfile-based 200 * operations for evbuffer_add_file(); see that function for more 201 * information. 202 * 203 * This flag is on by default for bufferevents that can take advantage 204 * of it; you should never actually need to set it on a bufferevent's 205 * output buffer. 206 */ 207 #define EVBUFFER_FLAG_DRAINS_TO_FD 1 208 209 /** Change the flags that are set for an evbuffer by adding more. 210 * 211 * @param buffer the evbuffer that the callback is watching. 212 * @param cb the callback whose status we want to change. 213 * @param flags One or more EVBUFFER_FLAG_* options 214 * @return 0 on success, -1 on failure. 215 */ 216 EVENT2_EXPORT_SYMBOL 217 int evbuffer_set_flags(struct evbuffer *buf, ev_uint64_t flags); 218 /** Change the flags that are set for an evbuffer by removing some. 219 * 220 * @param buffer the evbuffer that the callback is watching. 221 * @param cb the callback whose status we want to change. 222 * @param flags One or more EVBUFFER_FLAG_* options 223 * @return 0 on success, -1 on failure. 224 */ 225 EVENT2_EXPORT_SYMBOL 226 int evbuffer_clear_flags(struct evbuffer *buf, ev_uint64_t flags); 227 228 /** 229 Returns the total number of bytes stored in the evbuffer 230 231 @param buf pointer to the evbuffer 232 @return the number of bytes stored in the evbuffer 233 */ 234 EVENT2_EXPORT_SYMBOL 235 size_t evbuffer_get_length(const struct evbuffer *buf); 236 237 /** 238 Returns the number of contiguous available bytes in the first buffer chain. 239 240 This is useful when processing data that might be split into multiple 241 chains, or that might all be in the first chain. Calls to 242 evbuffer_pullup() that cause reallocation and copying of data can thus be 243 avoided. 244 245 @param buf pointer to the evbuffer 246 @return 0 if no data is available, otherwise the number of available bytes 247 in the first buffer chain. 248 */ 249 EVENT2_EXPORT_SYMBOL 250 size_t evbuffer_get_contiguous_space(const struct evbuffer *buf); 251 252 /** 253 Expands the available space in an evbuffer. 254 255 Expands the available space in the evbuffer to at least datlen, so that 256 appending datlen additional bytes will not require any new allocations. 257 258 @param buf the evbuffer to be expanded 259 @param datlen the new minimum length requirement 260 @return 0 if successful, or -1 if an error occurred 261 */ 262 EVENT2_EXPORT_SYMBOL 263 int evbuffer_expand(struct evbuffer *buf, size_t datlen); 264 265 /** 266 Reserves space in the last chain or chains of an evbuffer. 267 268 Makes space available in the last chain or chains of an evbuffer that can 269 be arbitrarily written to by a user. The space does not become 270 available for reading until it has been committed with 271 evbuffer_commit_space(). 272 273 The space is made available as one or more extents, represented by 274 an initial pointer and a length. You can force the memory to be 275 available as only one extent. Allowing more extents, however, makes the 276 function more efficient. 277 278 Multiple subsequent calls to this function will make the same space 279 available until evbuffer_commit_space() has been called. 280 281 It is an error to do anything that moves around the buffer's internal 282 memory structures before committing the space. 283 284 NOTE: The code currently does not ever use more than two extents. 285 This may change in future versions. 286 287 @param buf the evbuffer in which to reserve space. 288 @param size how much space to make available, at minimum. The 289 total length of the extents may be greater than the requested 290 length. 291 @param vec an array of one or more evbuffer_iovec structures to 292 hold pointers to the reserved extents of memory. 293 @param n_vec The length of the vec array. Must be at least 1; 294 2 is more efficient. 295 @return the number of provided extents, or -1 on error. 296 @see evbuffer_commit_space() 297 */ 298 EVENT2_EXPORT_SYMBOL 299 int 300 evbuffer_reserve_space(struct evbuffer *buf, ev_ssize_t size, 301 struct evbuffer_iovec *vec, int n_vec); 302 303 /** 304 Commits previously reserved space. 305 306 Commits some of the space previously reserved with 307 evbuffer_reserve_space(). It then becomes available for reading. 308 309 This function may return an error if the pointer in the extents do 310 not match those returned from evbuffer_reserve_space, or if data 311 has been added to the buffer since the space was reserved. 312 313 If you want to commit less data than you got reserved space for, 314 modify the iov_len pointer of the appropriate extent to a smaller 315 value. Note that you may have received more space than you 316 requested if it was available! 317 318 @param buf the evbuffer in which to reserve space. 319 @param vec one or two extents returned by evbuffer_reserve_space. 320 @param n_vecs the number of extents. 321 @return 0 on success, -1 on error 322 @see evbuffer_reserve_space() 323 */ 324 EVENT2_EXPORT_SYMBOL 325 int evbuffer_commit_space(struct evbuffer *buf, 326 struct evbuffer_iovec *vec, int n_vecs); 327 328 /** 329 Append data to the end of an evbuffer. 330 331 @param buf the evbuffer to be appended to 332 @param data pointer to the beginning of the data buffer 333 @param datlen the number of bytes to be copied from the data buffer 334 @return 0 on success, -1 on failure. 335 */ 336 EVENT2_EXPORT_SYMBOL 337 int evbuffer_add(struct evbuffer *buf, const void *data, size_t datlen); 338 339 340 /** 341 Read data from an evbuffer and drain the bytes read. 342 343 If more bytes are requested than are available in the evbuffer, we 344 only extract as many bytes as were available. 345 346 @param buf the evbuffer to be read from 347 @param data the destination buffer to store the result 348 @param datlen the maximum size of the destination buffer 349 @return the number of bytes read, or -1 if we can't drain the buffer. 350 */ 351 EVENT2_EXPORT_SYMBOL 352 int evbuffer_remove(struct evbuffer *buf, void *data, size_t datlen); 353 354 /** 355 Read data from an evbuffer, and leave the buffer unchanged. 356 357 If more bytes are requested than are available in the evbuffer, we 358 only extract as many bytes as were available. 359 360 @param buf the evbuffer to be read from 361 @param data_out the destination buffer to store the result 362 @param datlen the maximum size of the destination buffer 363 @return the number of bytes read, or -1 if we can't drain the buffer. 364 */ 365 EVENT2_EXPORT_SYMBOL 366 ev_ssize_t evbuffer_copyout(struct evbuffer *buf, void *data_out, size_t datlen); 367 368 /** 369 Read data from the middle of an evbuffer, and leave the buffer unchanged. 370 371 If more bytes are requested than are available in the evbuffer, we 372 only extract as many bytes as were available. 373 374 @param buf the evbuffer to be read from 375 @param pos the position to start reading from 376 @param data_out the destination buffer to store the result 377 @param datlen the maximum size of the destination buffer 378 @return the number of bytes read, or -1 if we can't drain the buffer. 379 */ 380 EVENT2_EXPORT_SYMBOL 381 ev_ssize_t evbuffer_copyout_from(struct evbuffer *buf, const struct evbuffer_ptr *pos, void *data_out, size_t datlen); 382 383 /** 384 Read data from an evbuffer into another evbuffer, draining 385 the bytes from the source buffer. This function avoids copy 386 operations to the extent possible. 387 388 If more bytes are requested than are available in src, the src 389 buffer is drained completely. 390 391 @param src the evbuffer to be read from 392 @param dst the destination evbuffer to store the result into 393 @param datlen the maximum numbers of bytes to transfer 394 @return the number of bytes read 395 */ 396 EVENT2_EXPORT_SYMBOL 397 int evbuffer_remove_buffer(struct evbuffer *src, struct evbuffer *dst, 398 size_t datlen); 399 400 /** Used to tell evbuffer_readln what kind of line-ending to look for. 401 */ 402 enum evbuffer_eol_style { 403 /** Any sequence of CR and LF characters is acceptable as an 404 * EOL. 405 * 406 * Note that this style can produce ambiguous results: the 407 * sequence "CRLF" will be treated as a single EOL if it is 408 * all in the buffer at once, but if you first read a CR from 409 * the network and later read an LF from the network, it will 410 * be treated as two EOLs. 411 */ 412 EVBUFFER_EOL_ANY, 413 /** An EOL is an LF, optionally preceded by a CR. This style is 414 * most useful for implementing text-based internet protocols. */ 415 EVBUFFER_EOL_CRLF, 416 /** An EOL is a CR followed by an LF. */ 417 EVBUFFER_EOL_CRLF_STRICT, 418 /** An EOL is a LF. */ 419 EVBUFFER_EOL_LF, 420 /** An EOL is a NUL character (that is, a single byte with value 0) */ 421 EVBUFFER_EOL_NUL 422 }; 423 424 /** 425 * Read a single line from an evbuffer. 426 * 427 * Reads a line terminated by an EOL as determined by the evbuffer_eol_style 428 * argument. Returns a newly allocated nul-terminated string; the caller must 429 * free the returned value. The EOL is not included in the returned string. 430 * 431 * @param buffer the evbuffer to read from 432 * @param n_read_out if non-NULL, points to a size_t that is set to the 433 * number of characters in the returned string. This is useful for 434 * strings that can contain NUL characters. 435 * @param eol_style the style of line-ending to use. 436 * @return pointer to a single line, or NULL if an error occurred 437 */ 438 EVENT2_EXPORT_SYMBOL 439 char *evbuffer_readln(struct evbuffer *buffer, size_t *n_read_out, 440 enum evbuffer_eol_style eol_style); 441 442 /** 443 Move all data from one evbuffer into another evbuffer. 444 445 This is a destructive add. The data from one buffer moves into 446 the other buffer. However, no unnecessary memory copies occur. 447 448 @param outbuf the output buffer 449 @param inbuf the input buffer 450 @return 0 if successful, or -1 if an error occurred 451 452 @see evbuffer_remove_buffer() 453 */ 454 EVENT2_EXPORT_SYMBOL 455 int evbuffer_add_buffer(struct evbuffer *outbuf, struct evbuffer *inbuf); 456 457 /** 458 Copy data from one evbuffer into another evbuffer. 459 460 This is a non-destructive add. The data from one buffer is copied 461 into the other buffer. However, no unnecessary memory copies occur. 462 463 Note that buffers already containing buffer references can't be added 464 to other buffers. 465 466 @param outbuf the output buffer 467 @param inbuf the input buffer 468 @return 0 if successful, or -1 if an error occurred 469 */ 470 EVENT2_EXPORT_SYMBOL 471 int evbuffer_add_buffer_reference(struct evbuffer *outbuf, 472 struct evbuffer *inbuf); 473 474 /** 475 A cleanup function for a piece of memory added to an evbuffer by 476 reference. 477 478 @see evbuffer_add_reference() 479 */ 480 typedef void (*evbuffer_ref_cleanup_cb)(const void *data, 481 size_t datalen, void *extra); 482 483 /** 484 Reference memory into an evbuffer without copying. 485 486 The memory needs to remain valid until all the added data has been 487 read. This function keeps just a reference to the memory without 488 actually incurring the overhead of a copy. 489 490 @param outbuf the output buffer 491 @param data the memory to reference 492 @param datlen how memory to reference 493 @param cleanupfn callback to be invoked when the memory is no longer 494 referenced by this evbuffer. 495 @param cleanupfn_arg optional argument to the cleanup callback 496 @return 0 if successful, or -1 if an error occurred 497 */ 498 EVENT2_EXPORT_SYMBOL 499 int evbuffer_add_reference(struct evbuffer *outbuf, 500 const void *data, size_t datlen, 501 evbuffer_ref_cleanup_cb cleanupfn, void *cleanupfn_arg); 502 503 /** 504 Copy data from a file into the evbuffer for writing to a socket. 505 506 This function avoids unnecessary data copies between userland and 507 kernel. If sendfile is available and the EVBUFFER_FLAG_DRAINS_TO_FD 508 flag is set, it uses those functions. Otherwise, it tries to use 509 mmap (or CreateFileMapping on Windows). 510 511 The function owns the resulting file descriptor and will close it 512 when finished transferring data. 513 514 The results of using evbuffer_remove() or evbuffer_pullup() on 515 evbuffers whose data was added using this function are undefined. 516 517 For more fine-grained control, use evbuffer_add_file_segment. 518 519 @param outbuf the output buffer 520 @param fd the file descriptor 521 @param offset the offset from which to read data 522 @param length how much data to read, or -1 to read as much as possible. 523 (-1 requires that 'fd' support fstat.) 524 @return 0 if successful, or -1 if an error occurred 525 */ 526 527 EVENT2_EXPORT_SYMBOL 528 int evbuffer_add_file(struct evbuffer *outbuf, int fd, ev_off_t offset, 529 ev_off_t length); 530 531 /** 532 An evbuffer_file_segment holds a reference to a range of a file -- 533 possibly the whole file! -- for use in writing from an evbuffer to a 534 socket. It could be implemented with mmap, sendfile, splice, or (if all 535 else fails) by just pulling all the data into RAM. A single 536 evbuffer_file_segment can be added more than once, and to more than one 537 evbuffer. 538 */ 539 struct evbuffer_file_segment; 540 541 /** 542 Flag for creating evbuffer_file_segment: If this flag is set, then when 543 the evbuffer_file_segment is freed and no longer in use by any 544 evbuffer, the underlying fd is closed. 545 */ 546 #define EVBUF_FS_CLOSE_ON_FREE 0x01 547 /** 548 Flag for creating evbuffer_file_segment: Disable memory-map based 549 implementations. 550 */ 551 #define EVBUF_FS_DISABLE_MMAP 0x02 552 /** 553 Flag for creating evbuffer_file_segment: Disable direct fd-to-fd 554 implementations (including sendfile and splice). 555 556 You might want to use this option if data needs to be taken from the 557 evbuffer by any means other than writing it to the network: the sendfile 558 backend is fast, but it only works for sending files directly to the 559 network. 560 */ 561 #define EVBUF_FS_DISABLE_SENDFILE 0x04 562 /** 563 Flag for creating evbuffer_file_segment: Do not allocate a lock for this 564 segment. If this option is set, then neither the segment nor any 565 evbuffer it is added to may ever be accessed from more than one thread 566 at a time. 567 */ 568 #define EVBUF_FS_DISABLE_LOCKING 0x08 569 570 /** 571 A cleanup function for a evbuffer_file_segment added to an evbuffer 572 for reference. 573 */ 574 typedef void (*evbuffer_file_segment_cleanup_cb)( 575 struct evbuffer_file_segment const* seg, int flags, void* arg); 576 577 /** 578 Create and return a new evbuffer_file_segment for reading data from a 579 file and sending it out via an evbuffer. 580 581 This function avoids unnecessary data copies between userland and 582 kernel. Where available, it uses sendfile or splice. 583 584 The file descriptor must not be closed so long as any evbuffer is using 585 this segment. 586 587 The results of using evbuffer_remove() or evbuffer_pullup() or any other 588 function that reads bytes from an evbuffer on any evbuffer containing 589 the newly returned segment are undefined, unless you pass the 590 EVBUF_FS_DISABLE_SENDFILE flag to this function. 591 592 @param fd an open file to read from. 593 @param offset an index within the file at which to start reading 594 @param length how much data to read, or -1 to read as much as possible. 595 (-1 requires that 'fd' support fstat.) 596 @param flags any number of the EVBUF_FS_* flags 597 @return a new evbuffer_file_segment, or NULL on failure. 598 **/ 599 EVENT2_EXPORT_SYMBOL 600 struct evbuffer_file_segment *evbuffer_file_segment_new( 601 int fd, ev_off_t offset, ev_off_t length, unsigned flags); 602 603 /** 604 Free an evbuffer_file_segment 605 606 It is safe to call this function even if the segment has been added to 607 one or more evbuffers. The evbuffer_file_segment will not be freed 608 until no more references to it exist. 609 */ 610 EVENT2_EXPORT_SYMBOL 611 void evbuffer_file_segment_free(struct evbuffer_file_segment *seg); 612 613 /** 614 Add cleanup callback and argument for the callback to an 615 evbuffer_file_segment. 616 617 The cleanup callback will be invoked when no more references to the 618 evbuffer_file_segment exist. 619 **/ 620 EVENT2_EXPORT_SYMBOL 621 void evbuffer_file_segment_add_cleanup_cb(struct evbuffer_file_segment *seg, 622 evbuffer_file_segment_cleanup_cb cb, void* arg); 623 624 /** 625 Insert some or all of an evbuffer_file_segment at the end of an evbuffer 626 627 Note that the offset and length parameters of this function have a 628 different meaning from those provided to evbuffer_file_segment_new: When 629 you create the segment, the offset is the offset _within the file_, and 630 the length is the length _of the segment_, whereas when you add a 631 segment to an evbuffer, the offset is _within the segment_ and the 632 length is the length of the _part of the segment you want to use. 633 634 In other words, if you have a 10 KiB file, and you create an 635 evbuffer_file_segment for it with offset 20 and length 1000, it will 636 refer to bytes 20..1019 inclusive. If you then pass this segment to 637 evbuffer_add_file_segment and specify an offset of 20 and a length of 638 50, you will be adding bytes 40..99 inclusive. 639 640 @param buf the evbuffer to append to 641 @param seg the segment to add 642 @param offset the offset within the segment to start from 643 @param length the amount of data to add, or -1 to add it all. 644 @return 0 on success, -1 on failure. 645 */ 646 EVENT2_EXPORT_SYMBOL 647 int evbuffer_add_file_segment(struct evbuffer *buf, 648 struct evbuffer_file_segment *seg, ev_off_t offset, ev_off_t length); 649 650 /** 651 Append a formatted string to the end of an evbuffer. 652 653 The string is formated as printf. 654 655 @param buf the evbuffer that will be appended to 656 @param fmt a format string 657 @param ... arguments that will be passed to printf(3) 658 @return The number of bytes added if successful, or -1 if an error occurred. 659 660 @see evutil_printf(), evbuffer_add_vprintf() 661 */ 662 EVENT2_EXPORT_SYMBOL 663 int evbuffer_add_printf(struct evbuffer *buf, const char *fmt, ...) 664 #ifdef __GNUC__ 665 __attribute__((format(printf, 2, 3))) 666 #endif 667 ; 668 669 /** 670 Append a va_list formatted string to the end of an evbuffer. 671 672 @param buf the evbuffer that will be appended to 673 @param fmt a format string 674 @param ap a varargs va_list argument array that will be passed to vprintf(3) 675 @return The number of bytes added if successful, or -1 if an error occurred. 676 */ 677 EVENT2_EXPORT_SYMBOL 678 int evbuffer_add_vprintf(struct evbuffer *buf, const char *fmt, va_list ap) 679 #ifdef __GNUC__ 680 __attribute__((format(printf, 2, 0))) 681 #endif 682 ; 683 684 685 /** 686 Remove a specified number of bytes data from the beginning of an evbuffer. 687 688 @param buf the evbuffer to be drained 689 @param len the number of bytes to drain from the beginning of the buffer 690 @return 0 on success, -1 on failure. 691 */ 692 EVENT2_EXPORT_SYMBOL 693 int evbuffer_drain(struct evbuffer *buf, size_t len); 694 695 696 /** 697 Write the contents of an evbuffer to a file descriptor. 698 699 The evbuffer will be drained after the bytes have been successfully written. 700 701 @param buffer the evbuffer to be written and drained 702 @param fd the file descriptor to be written to 703 @return the number of bytes written, or -1 if an error occurred 704 @see evbuffer_read() 705 */ 706 EVENT2_EXPORT_SYMBOL 707 int evbuffer_write(struct evbuffer *buffer, evutil_socket_t fd); 708 709 /** 710 Write some of the contents of an evbuffer to a file descriptor. 711 712 The evbuffer will be drained after the bytes have been successfully written. 713 714 @param buffer the evbuffer to be written and drained 715 @param fd the file descriptor to be written to 716 @param howmuch the largest allowable number of bytes to write, or -1 717 to write as many bytes as we can. 718 @return the number of bytes written, or -1 if an error occurred 719 @see evbuffer_read() 720 */ 721 EVENT2_EXPORT_SYMBOL 722 int evbuffer_write_atmost(struct evbuffer *buffer, evutil_socket_t fd, 723 ev_ssize_t howmuch); 724 725 /** 726 Read from a file descriptor and store the result in an evbuffer. 727 728 @param buffer the evbuffer to store the result 729 @param fd the file descriptor to read from 730 @param howmuch the number of bytes to be read. If the given number is negative 731 or out of maximum bytes per one read, as many bytes as we can will be read. 732 @return the number of bytes read, or -1 if an error occurred 733 @see evbuffer_write() 734 */ 735 EVENT2_EXPORT_SYMBOL 736 int evbuffer_read(struct evbuffer *buffer, evutil_socket_t fd, int howmuch); 737 738 /** 739 Search for a string within an evbuffer. 740 741 @param buffer the evbuffer to be searched 742 @param what the string to be searched for 743 @param len the length of the search string 744 @param start NULL or a pointer to a valid struct evbuffer_ptr. 745 @return a struct evbuffer_ptr whose 'pos' field has the offset of the 746 first occurrence of the string in the buffer after 'start'. The 'pos' 747 field of the result is -1 if the string was not found. 748 */ 749 EVENT2_EXPORT_SYMBOL 750 struct evbuffer_ptr evbuffer_search(struct evbuffer *buffer, const char *what, size_t len, const struct evbuffer_ptr *start); 751 752 /** 753 Search for a string within part of an evbuffer. 754 755 @param buffer the evbuffer to be searched 756 @param what the string to be searched for 757 @param len the length of the search string 758 @param start NULL or a pointer to a valid struct evbuffer_ptr that 759 indicates where we should start searching. 760 @param end NULL or a pointer to a valid struct evbuffer_ptr that 761 indicates where we should stop searching. 762 @return a struct evbuffer_ptr whose 'pos' field has the offset of the 763 first occurrence of the string in the buffer after 'start'. The 'pos' 764 field of the result is -1 if the string was not found. 765 */ 766 EVENT2_EXPORT_SYMBOL 767 struct evbuffer_ptr evbuffer_search_range(struct evbuffer *buffer, const char *what, size_t len, const struct evbuffer_ptr *start, const struct evbuffer_ptr *end); 768 769 /** 770 Defines how to adjust an evbuffer_ptr by evbuffer_ptr_set() 771 772 @see evbuffer_ptr_set() */ 773 enum evbuffer_ptr_how { 774 /** Sets the pointer to the position; can be called on with an 775 uninitialized evbuffer_ptr. */ 776 EVBUFFER_PTR_SET, 777 /** Advances the pointer by adding to the current position. */ 778 EVBUFFER_PTR_ADD 779 }; 780 781 /** 782 Sets the search pointer in the buffer to position. 783 784 There are two ways to use this function: you can call 785 evbuffer_ptr_set(buf, &pos, N, EVBUFFER_PTR_SET) 786 to move 'pos' to a position 'N' bytes after the start of the buffer, or 787 evbuffer_ptr_set(buf, &pos, N, EVBUFFER_PTR_ADD) 788 to move 'pos' forward by 'N' bytes. 789 790 If evbuffer_ptr is not initialized, this function can only be called 791 with EVBUFFER_PTR_SET. 792 793 An evbuffer_ptr can represent any position from the start of the buffer to 794 a position immediately after the end of the buffer. 795 796 @param buffer the evbuffer to be search 797 @param ptr a pointer to a struct evbuffer_ptr 798 @param position the position at which to start the next search 799 @param how determines how the pointer should be manipulated. 800 @returns 0 on success or -1 otherwise 801 */ 802 EVENT2_EXPORT_SYMBOL 803 int 804 evbuffer_ptr_set(struct evbuffer *buffer, struct evbuffer_ptr *ptr, 805 size_t position, enum evbuffer_ptr_how how); 806 807 /** 808 Search for an end-of-line string within an evbuffer. 809 810 @param buffer the evbuffer to be searched 811 @param start NULL or a pointer to a valid struct evbuffer_ptr to start 812 searching at. 813 @param eol_len_out If non-NULL, the pointed-to value will be set to 814 the length of the end-of-line string. 815 @param eol_style The kind of EOL to look for; see evbuffer_readln() for 816 more information 817 @return a struct evbuffer_ptr whose 'pos' field has the offset of the 818 first occurrence EOL in the buffer after 'start'. The 'pos' 819 field of the result is -1 if the string was not found. 820 */ 821 EVENT2_EXPORT_SYMBOL 822 struct evbuffer_ptr evbuffer_search_eol(struct evbuffer *buffer, 823 struct evbuffer_ptr *start, size_t *eol_len_out, 824 enum evbuffer_eol_style eol_style); 825 826 /** Function to peek at data inside an evbuffer without removing it or 827 copying it out. 828 829 Pointers to the data are returned by filling the 'vec_out' array 830 with pointers to one or more extents of data inside the buffer. 831 832 The total data in the extents that you get back may be more than 833 you requested (if there is more data last extent than you asked 834 for), or less (if you do not provide enough evbuffer_iovecs, or if 835 the buffer does not have as much data as you asked to see). 836 837 @param buffer the evbuffer to peek into, 838 @param len the number of bytes to try to peek. If len is negative, we 839 will try to fill as much of vec_out as we can. If len is negative 840 and vec_out is not provided, we return the number of evbuffer_iovecs 841 that would be needed to get all the data in the buffer. 842 @param start_at an evbuffer_ptr indicating the point at which we 843 should start looking for data. NULL means, "At the start of the 844 buffer." 845 @param vec_out an array of evbuffer_iovec 846 @param n_vec the length of vec_out. If 0, we only count how many 847 extents would be necessary to point to the requested amount of 848 data. 849 @return The number of extents needed. This may be less than n_vec 850 if we didn't need all the evbuffer_iovecs we were given, or more 851 than n_vec if we would need more to return all the data that was 852 requested. 853 */ 854 EVENT2_EXPORT_SYMBOL 855 int evbuffer_peek(struct evbuffer *buffer, ev_ssize_t len, 856 struct evbuffer_ptr *start_at, 857 struct evbuffer_iovec *vec_out, int n_vec); 858 859 860 /** Structure passed to an evbuffer_cb_func evbuffer callback 861 862 @see evbuffer_cb_func, evbuffer_add_cb() 863 */ 864 struct evbuffer_cb_info { 865 /** The number of bytes in this evbuffer when callbacks were last 866 * invoked. */ 867 size_t orig_size; 868 /** The number of bytes added since callbacks were last invoked. */ 869 size_t n_added; 870 /** The number of bytes removed since callbacks were last invoked. */ 871 size_t n_deleted; 872 }; 873 874 /** Type definition for a callback that is invoked whenever data is added or 875 removed from an evbuffer. 876 877 An evbuffer may have one or more callbacks set at a time. The order 878 in which they are executed is undefined. 879 880 A callback function may add more callbacks, or remove itself from the 881 list of callbacks, or add or remove data from the buffer. It may not 882 remove another callback from the list. 883 884 If a callback adds or removes data from the buffer or from another 885 buffer, this can cause a recursive invocation of your callback or 886 other callbacks. If you ask for an infinite loop, you might just get 887 one: watch out! 888 889 @param buffer the buffer whose size has changed 890 @param info a structure describing how the buffer changed. 891 @param arg a pointer to user data 892 */ 893 typedef void (*evbuffer_cb_func)(struct evbuffer *buffer, const struct evbuffer_cb_info *info, void *arg); 894 895 struct evbuffer_cb_entry; 896 /** Add a new callback to an evbuffer. 897 898 Subsequent calls to evbuffer_add_cb() add new callbacks. To remove this 899 callback, call evbuffer_remove_cb or evbuffer_remove_cb_entry. 900 901 @param buffer the evbuffer to be monitored 902 @param cb the callback function to invoke when the evbuffer is modified, 903 or NULL to remove all callbacks. 904 @param cbarg an argument to be provided to the callback function 905 @return a handle to the callback on success, or NULL on failure. 906 */ 907 EVENT2_EXPORT_SYMBOL 908 struct evbuffer_cb_entry *evbuffer_add_cb(struct evbuffer *buffer, evbuffer_cb_func cb, void *cbarg); 909 910 /** Remove a callback from an evbuffer, given a handle returned from 911 evbuffer_add_cb. 912 913 Calling this function invalidates the handle. 914 915 @return 0 if a callback was removed, or -1 if no matching callback was 916 found. 917 */ 918 EVENT2_EXPORT_SYMBOL 919 int evbuffer_remove_cb_entry(struct evbuffer *buffer, 920 struct evbuffer_cb_entry *ent); 921 922 /** Remove a callback from an evbuffer, given the function and argument 923 used to add it. 924 925 @return 0 if a callback was removed, or -1 if no matching callback was 926 found. 927 */ 928 EVENT2_EXPORT_SYMBOL 929 int evbuffer_remove_cb(struct evbuffer *buffer, evbuffer_cb_func cb, void *cbarg); 930 931 /** If this flag is not set, then a callback is temporarily disabled, and 932 * should not be invoked. 933 * 934 * @see evbuffer_cb_set_flags(), evbuffer_cb_clear_flags() 935 */ 936 #define EVBUFFER_CB_ENABLED 1 937 938 /** Change the flags that are set for a callback on a buffer by adding more. 939 940 @param buffer the evbuffer that the callback is watching. 941 @param cb the callback whose status we want to change. 942 @param flags EVBUFFER_CB_ENABLED to re-enable the callback. 943 @return 0 on success, -1 on failure. 944 */ 945 EVENT2_EXPORT_SYMBOL 946 int evbuffer_cb_set_flags(struct evbuffer *buffer, 947 struct evbuffer_cb_entry *cb, ev_uint32_t flags); 948 949 /** Change the flags that are set for a callback on a buffer by removing some 950 951 @param buffer the evbuffer that the callback is watching. 952 @param cb the callback whose status we want to change. 953 @param flags EVBUFFER_CB_ENABLED to disable the callback. 954 @return 0 on success, -1 on failure. 955 */ 956 EVENT2_EXPORT_SYMBOL 957 int evbuffer_cb_clear_flags(struct evbuffer *buffer, 958 struct evbuffer_cb_entry *cb, ev_uint32_t flags); 959 960 #if 0 961 /** Postpone calling a given callback until unsuspend is called later. 962 963 This is different from disabling the callback, since the callback will get 964 invoked later if the buffer size changes between now and when we unsuspend 965 it. 966 967 @param the buffer that the callback is watching. 968 @param cb the callback we want to suspend. 969 */ 970 EVENT2_EXPORT_SYMBOL 971 void evbuffer_cb_suspend(struct evbuffer *buffer, struct evbuffer_cb_entry *cb); 972 /** Stop postponing a callback that we postponed with evbuffer_cb_suspend. 973 974 If data was added to or removed from the buffer while the callback was 975 suspended, the callback will get called once now. 976 977 @param the buffer that the callback is watching. 978 @param cb the callback we want to stop suspending. 979 */ 980 EVENT2_EXPORT_SYMBOL 981 void evbuffer_cb_unsuspend(struct evbuffer *buffer, struct evbuffer_cb_entry *cb); 982 #endif 983 984 /** 985 Makes the data at the beginning of an evbuffer contiguous. 986 987 @param buf the evbuffer to make contiguous 988 @param size the number of bytes to make contiguous, or -1 to make the 989 entire buffer contiguous. 990 @return a pointer to the contiguous memory array, or NULL if param size 991 requested more data than is present in the buffer. 992 */ 993 994 EVENT2_EXPORT_SYMBOL 995 unsigned char *evbuffer_pullup(struct evbuffer *buf, ev_ssize_t size); 996 997 /** 998 Prepends data to the beginning of the evbuffer 999 1000 @param buf the evbuffer to which to prepend data 1001 @param data a pointer to the memory to prepend 1002 @param size the number of bytes to prepend 1003 @return 0 if successful, or -1 otherwise 1004 */ 1005 1006 EVENT2_EXPORT_SYMBOL 1007 int evbuffer_prepend(struct evbuffer *buf, const void *data, size_t size); 1008 1009 /** 1010 Prepends all data from the src evbuffer to the beginning of the dst 1011 evbuffer. 1012 1013 @param dst the evbuffer to which to prepend data 1014 @param src the evbuffer to prepend; it will be emptied as a result 1015 @return 0 if successful, or -1 otherwise 1016 */ 1017 EVENT2_EXPORT_SYMBOL 1018 int evbuffer_prepend_buffer(struct evbuffer *dst, struct evbuffer* src); 1019 1020 /** 1021 Prevent calls that modify an evbuffer from succeeding. A buffer may 1022 frozen at the front, at the back, or at both the front and the back. 1023 1024 If the front of a buffer is frozen, operations that drain data from 1025 the front of the buffer, or that prepend data to the buffer, will 1026 fail until it is unfrozen. If the back a buffer is frozen, operations 1027 that append data from the buffer will fail until it is unfrozen. 1028 1029 @param buf The buffer to freeze 1030 @param at_front If true, we freeze the front of the buffer. If false, 1031 we freeze the back. 1032 @return 0 on success, -1 on failure. 1033 */ 1034 EVENT2_EXPORT_SYMBOL 1035 int evbuffer_freeze(struct evbuffer *buf, int at_front); 1036 /** 1037 Re-enable calls that modify an evbuffer. 1038 1039 @param buf The buffer to un-freeze 1040 @param at_front If true, we unfreeze the front of the buffer. If false, 1041 we unfreeze the back. 1042 @return 0 on success, -1 on failure. 1043 */ 1044 EVENT2_EXPORT_SYMBOL 1045 int evbuffer_unfreeze(struct evbuffer *buf, int at_front); 1046 1047 struct event_base; 1048 /** 1049 Force all the callbacks on an evbuffer to be run, not immediately after 1050 the evbuffer is altered, but instead from inside the event loop. 1051 1052 This can be used to serialize all the callbacks to a single thread 1053 of execution. 1054 */ 1055 EVENT2_EXPORT_SYMBOL 1056 int evbuffer_defer_callbacks(struct evbuffer *buffer, struct event_base *base); 1057 1058 /** 1059 Append data from 1 or more iovec's to an evbuffer 1060 1061 Calculates the number of bytes needed for an iovec structure and guarantees 1062 all data will fit into a single chain. Can be used in lieu of functionality 1063 which calls evbuffer_add() constantly before being used to increase 1064 performance. 1065 1066 @param buffer the destination buffer 1067 @param vec the source iovec 1068 @param n_vec the number of iovec structures. 1069 @return the number of bytes successfully written to the output buffer. 1070 */ 1071 EVENT2_EXPORT_SYMBOL 1072 size_t evbuffer_add_iovec(struct evbuffer * buffer, struct evbuffer_iovec * vec, int n_vec); 1073 1074 #ifdef __cplusplus 1075 } 1076 #endif 1077 1078 #endif /* EVENT2_BUFFER_H_INCLUDED_ */ 1079