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