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