1275970Scy/* 2275970Scy * Copyright (c) 2007-2012 Niels Provos and Nick Mathewson 3275970Scy * 4275970Scy * Redistribution and use in source and binary forms, with or without 5275970Scy * modification, are permitted provided that the following conditions 6275970Scy * are met: 7275970Scy * 1. Redistributions of source code must retain the above copyright 8275970Scy * notice, this list of conditions and the following disclaimer. 9275970Scy * 2. Redistributions in binary form must reproduce the above copyright 10275970Scy * notice, this list of conditions and the following disclaimer in the 11275970Scy * documentation and/or other materials provided with the distribution. 12275970Scy * 3. The name of the author may not be used to endorse or promote products 13275970Scy * derived from this software without specific prior written permission. 14275970Scy * 15275970Scy * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 16275970Scy * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 17275970Scy * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 18275970Scy * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 19275970Scy * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 20275970Scy * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 21275970Scy * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 22275970Scy * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 23275970Scy * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 24275970Scy * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25275970Scy */ 26275970Scy#ifndef EVENT2_BUFFER_H_INCLUDED_ 27275970Scy#define EVENT2_BUFFER_H_INCLUDED_ 28275970Scy 29275970Scy/** @file event2/buffer.h 30275970Scy 31275970Scy Functions for buffering data for network sending or receiving. 32275970Scy 33275970Scy An evbuffer can be used for preparing data before sending it to 34275970Scy the network or conversely for reading data from the network. 35275970Scy Evbuffers try to avoid memory copies as much as possible. As a 36275970Scy result, evbuffers can be used to pass data around without actually 37275970Scy incurring the overhead of copying the data. 38275970Scy 39275970Scy A new evbuffer can be allocated with evbuffer_new(), and can be 40275970Scy freed with evbuffer_free(). Most users will be using evbuffers via 41275970Scy the bufferevent interface. To access a bufferevent's evbuffers, use 42275970Scy bufferevent_get_input() and bufferevent_get_output(). 43275970Scy 44275970Scy There are several guidelines for using evbuffers. 45275970Scy 46275970Scy - if you already know how much data you are going to add as a result 47275970Scy of calling evbuffer_add() multiple times, it makes sense to use 48275970Scy evbuffer_expand() first to make sure that enough memory is allocated 49275970Scy before hand. 50275970Scy 51275970Scy - evbuffer_add_buffer() adds the contents of one buffer to the other 52275970Scy without incurring any unnecessary memory copies. 53275970Scy 54275970Scy - evbuffer_add() and evbuffer_add_buffer() do not mix very well: 55275970Scy if you use them, you will wind up with fragmented memory in your 56275970Scy buffer. 57275970Scy 58275970Scy - For high-performance code, you may want to avoid copying data into and out 59275970Scy of buffers. You can skip the copy step by using 60275970Scy evbuffer_reserve_space()/evbuffer_commit_space() when writing into a 61275970Scy buffer, and evbuffer_peek() when reading. 62275970Scy 63275970Scy In Libevent 2.0 and later, evbuffers are represented using a linked 64275970Scy list of memory chunks, with pointers to the first and last chunk in 65275970Scy the chain. 66275970Scy 67275970Scy As the contents of an evbuffer can be stored in multiple different 68275970Scy memory blocks, it cannot be accessed directly. Instead, evbuffer_pullup() 69275970Scy can be used to force a specified number of bytes to be contiguous. This 70275970Scy will cause memory reallocation and memory copies if the data is split 71275970Scy across multiple blocks. It is more efficient, however, to use 72275970Scy evbuffer_peek() if you don't require that the memory to be contiguous. 73275970Scy */ 74275970Scy 75275970Scy#include <event2/visibility.h> 76275970Scy 77275970Scy#ifdef __cplusplus 78275970Scyextern "C" { 79275970Scy#endif 80275970Scy 81275970Scy#include <event2/event-config.h> 82275970Scy#include <stdarg.h> 83275970Scy#ifdef EVENT__HAVE_SYS_TYPES_H 84275970Scy#include <sys/types.h> 85275970Scy#endif 86275970Scy#ifdef EVENT__HAVE_SYS_UIO_H 87275970Scy#include <sys/uio.h> 88275970Scy#endif 89275970Scy#include <event2/util.h> 90275970Scy 91275970Scy/** 92275970Scy An evbuffer is an opaque data type for efficiently buffering data to be 93275970Scy sent or received on the network. 94275970Scy 95275970Scy @see event2/event.h for more information 96275970Scy*/ 97275970Scystruct evbuffer 98275970Scy#ifdef EVENT_IN_DOXYGEN_ 99275970Scy{} 100275970Scy#endif 101275970Scy; 102275970Scy 103275970Scy/** 104275970Scy Pointer to a position within an evbuffer. 105275970Scy 106275970Scy Used when repeatedly searching through a buffer. Calling any function 107275970Scy that modifies or re-packs the buffer contents may invalidate all 108285612Sdelphij evbuffer_ptrs for that buffer. Do not modify or contruct these values 109285612Sdelphij except with evbuffer_ptr_set. 110275970Scy 111275970Scy An evbuffer_ptr can represent any position from the start of a buffer up 112275970Scy to a position immediately after the end of a buffer. 113275970Scy 114275970Scy @see evbuffer_ptr_set() 115275970Scy */ 116275970Scystruct evbuffer_ptr { 117275970Scy ev_ssize_t pos; 118275970Scy 119275970Scy /* Do not alter or rely on the values of fields: they are for internal 120275970Scy * use */ 121275970Scy struct { 122275970Scy void *chain; 123275970Scy size_t pos_in_chain; 124275970Scy } internal_; 125275970Scy}; 126275970Scy 127275970Scy/** Describes a single extent of memory inside an evbuffer. Used for 128275970Scy direct-access functions. 129275970Scy 130275970Scy @see evbuffer_reserve_space, evbuffer_commit_space, evbuffer_peek 131275970Scy */ 132275970Scy#ifdef EVENT__HAVE_SYS_UIO_H 133275970Scy#define evbuffer_iovec iovec 134275970Scy/* Internal use -- defined only if we are using the native struct iovec */ 135275970Scy#define EVBUFFER_IOVEC_IS_NATIVE_ 136275970Scy#else 137275970Scystruct evbuffer_iovec { 138275970Scy /** The start of the extent of memory. */ 139275970Scy void *iov_base; 140275970Scy /** The length of the extent of memory. */ 141275970Scy size_t iov_len; 142275970Scy}; 143275970Scy#endif 144275970Scy 145275970Scy/** 146275970Scy Allocate storage for a new evbuffer. 147275970Scy 148275970Scy @return a pointer to a newly allocated evbuffer struct, or NULL if an error 149275970Scy occurred 150275970Scy */ 151275970ScyEVENT2_EXPORT_SYMBOL 152275970Scystruct evbuffer *evbuffer_new(void); 153275970Scy/** 154275970Scy Deallocate storage for an evbuffer. 155275970Scy 156275970Scy @param buf pointer to the evbuffer to be freed 157275970Scy */ 158275970ScyEVENT2_EXPORT_SYMBOL 159275970Scyvoid evbuffer_free(struct evbuffer *buf); 160275970Scy 161275970Scy/** 162275970Scy Enable locking on an evbuffer so that it can safely be used by multiple 163275970Scy threads at the same time. 164275970Scy 165275970Scy NOTE: when locking is enabled, the lock will be held when callbacks are 166275970Scy invoked. This could result in deadlock if you aren't careful. Plan 167275970Scy accordingly! 168275970Scy 169275970Scy @param buf An evbuffer to make lockable. 170275970Scy @param lock A lock object, or NULL if we should allocate our own. 171275970Scy @return 0 on success, -1 on failure. 172275970Scy */ 173275970ScyEVENT2_EXPORT_SYMBOL 174275970Scyint evbuffer_enable_locking(struct evbuffer *buf, void *lock); 175275970Scy 176275970Scy/** 177275970Scy Acquire the lock on an evbuffer. Has no effect if locking was not enabled 178275970Scy with evbuffer_enable_locking. 179275970Scy*/ 180275970ScyEVENT2_EXPORT_SYMBOL 181275970Scyvoid evbuffer_lock(struct evbuffer *buf); 182275970Scy 183275970Scy/** 184275970Scy Release the lock on an evbuffer. Has no effect if locking was not enabled 185275970Scy with evbuffer_enable_locking. 186275970Scy*/ 187275970ScyEVENT2_EXPORT_SYMBOL 188275970Scyvoid evbuffer_unlock(struct evbuffer *buf); 189275970Scy 190275970Scy 191275970Scy/** If this flag is set, then we will not use evbuffer_peek(), 192275970Scy * evbuffer_remove(), evbuffer_remove_buffer(), and so on to read bytes 193275970Scy * from this buffer: we'll only take bytes out of this buffer by 194275970Scy * writing them to the network (as with evbuffer_write_atmost), by 195275970Scy * removing them without observing them (as with evbuffer_drain), 196275970Scy * or by copying them all out at once (as with evbuffer_add_buffer). 197275970Scy * 198275970Scy * Using this option allows the implementation to use sendfile-based 199275970Scy * operations for evbuffer_add_file(); see that function for more 200275970Scy * information. 201275970Scy * 202275970Scy * This flag is on by default for bufferevents that can take advantage 203275970Scy * of it; you should never actually need to set it on a bufferevent's 204275970Scy * output buffer. 205275970Scy */ 206275970Scy#define EVBUFFER_FLAG_DRAINS_TO_FD 1 207275970Scy 208275970Scy/** Change the flags that are set for an evbuffer by adding more. 209275970Scy * 210275970Scy * @param buffer the evbuffer that the callback is watching. 211275970Scy * @param cb the callback whose status we want to change. 212275970Scy * @param flags One or more EVBUFFER_FLAG_* options 213275970Scy * @return 0 on success, -1 on failure. 214275970Scy */ 215275970ScyEVENT2_EXPORT_SYMBOL 216275970Scyint evbuffer_set_flags(struct evbuffer *buf, ev_uint64_t flags); 217275970Scy/** Change the flags that are set for an evbuffer by removing some. 218275970Scy * 219275970Scy * @param buffer the evbuffer that the callback is watching. 220275970Scy * @param cb the callback whose status we want to change. 221275970Scy * @param flags One or more EVBUFFER_FLAG_* options 222275970Scy * @return 0 on success, -1 on failure. 223275970Scy */ 224275970ScyEVENT2_EXPORT_SYMBOL 225275970Scyint evbuffer_clear_flags(struct evbuffer *buf, ev_uint64_t flags); 226275970Scy 227275970Scy/** 228275970Scy Returns the total number of bytes stored in the evbuffer 229275970Scy 230275970Scy @param buf pointer to the evbuffer 231275970Scy @return the number of bytes stored in the evbuffer 232275970Scy*/ 233275970ScyEVENT2_EXPORT_SYMBOL 234275970Scysize_t evbuffer_get_length(const struct evbuffer *buf); 235275970Scy 236275970Scy/** 237275970Scy Returns the number of contiguous available bytes in the first buffer chain. 238275970Scy 239275970Scy This is useful when processing data that might be split into multiple 240275970Scy chains, or that might all be in the first chain. Calls to 241275970Scy evbuffer_pullup() that cause reallocation and copying of data can thus be 242275970Scy avoided. 243275970Scy 244275970Scy @param buf pointer to the evbuffer 245275970Scy @return 0 if no data is available, otherwise the number of available bytes 246275970Scy in the first buffer chain. 247275970Scy*/ 248275970ScyEVENT2_EXPORT_SYMBOL 249275970Scysize_t evbuffer_get_contiguous_space(const struct evbuffer *buf); 250275970Scy 251275970Scy/** 252275970Scy Expands the available space in an evbuffer. 253275970Scy 254275970Scy Expands the available space in the evbuffer to at least datlen, so that 255275970Scy appending datlen additional bytes will not require any new allocations. 256275970Scy 257275970Scy @param buf the evbuffer to be expanded 258275970Scy @param datlen the new minimum length requirement 259275970Scy @return 0 if successful, or -1 if an error occurred 260275970Scy*/ 261275970ScyEVENT2_EXPORT_SYMBOL 262275970Scyint evbuffer_expand(struct evbuffer *buf, size_t datlen); 263275970Scy 264275970Scy/** 265275970Scy Reserves space in the last chain or chains of an evbuffer. 266275970Scy 267275970Scy Makes space available in the last chain or chains of an evbuffer that can 268275970Scy be arbitrarily written to by a user. The space does not become 269275970Scy available for reading until it has been committed with 270275970Scy evbuffer_commit_space(). 271275970Scy 272275970Scy The space is made available as one or more extents, represented by 273275970Scy an initial pointer and a length. You can force the memory to be 274275970Scy available as only one extent. Allowing more extents, however, makes the 275275970Scy function more efficient. 276275970Scy 277275970Scy Multiple subsequent calls to this function will make the same space 278275970Scy available until evbuffer_commit_space() has been called. 279275970Scy 280275970Scy It is an error to do anything that moves around the buffer's internal 281275970Scy memory structures before committing the space. 282275970Scy 283275970Scy NOTE: The code currently does not ever use more than two extents. 284275970Scy This may change in future versions. 285275970Scy 286275970Scy @param buf the evbuffer in which to reserve space. 287275970Scy @param size how much space to make available, at minimum. The 288275970Scy total length of the extents may be greater than the requested 289275970Scy length. 290275970Scy @param vec an array of one or more evbuffer_iovec structures to 291275970Scy hold pointers to the reserved extents of memory. 292275970Scy @param n_vec The length of the vec array. Must be at least 1; 293275970Scy 2 is more efficient. 294275970Scy @return the number of provided extents, or -1 on error. 295275970Scy @see evbuffer_commit_space() 296275970Scy*/ 297275970ScyEVENT2_EXPORT_SYMBOL 298275970Scyint 299275970Scyevbuffer_reserve_space(struct evbuffer *buf, ev_ssize_t size, 300275970Scy struct evbuffer_iovec *vec, int n_vec); 301275970Scy 302275970Scy/** 303275970Scy Commits previously reserved space. 304275970Scy 305275970Scy Commits some of the space previously reserved with 306275970Scy evbuffer_reserve_space(). It then becomes available for reading. 307275970Scy 308275970Scy This function may return an error if the pointer in the extents do 309275970Scy not match those returned from evbuffer_reserve_space, or if data 310275970Scy has been added to the buffer since the space was reserved. 311275970Scy 312275970Scy If you want to commit less data than you got reserved space for, 313275970Scy modify the iov_len pointer of the appropriate extent to a smaller 314275970Scy value. Note that you may have received more space than you 315275970Scy requested if it was available! 316275970Scy 317275970Scy @param buf the evbuffer in which to reserve space. 318275970Scy @param vec one or two extents returned by evbuffer_reserve_space. 319275970Scy @param n_vecs the number of extents. 320275970Scy @return 0 on success, -1 on error 321275970Scy @see evbuffer_reserve_space() 322275970Scy*/ 323275970ScyEVENT2_EXPORT_SYMBOL 324275970Scyint evbuffer_commit_space(struct evbuffer *buf, 325275970Scy struct evbuffer_iovec *vec, int n_vecs); 326275970Scy 327275970Scy/** 328275970Scy Append data to the end of an evbuffer. 329275970Scy 330275970Scy @param buf the evbuffer to be appended to 331275970Scy @param data pointer to the beginning of the data buffer 332275970Scy @param datlen the number of bytes to be copied from the data buffer 333275970Scy @return 0 on success, -1 on failure. 334275970Scy */ 335275970ScyEVENT2_EXPORT_SYMBOL 336275970Scyint evbuffer_add(struct evbuffer *buf, const void *data, size_t datlen); 337275970Scy 338275970Scy 339275970Scy/** 340275970Scy Read data from an evbuffer and drain the bytes read. 341275970Scy 342275970Scy If more bytes are requested than are available in the evbuffer, we 343275970Scy only extract as many bytes as were available. 344275970Scy 345275970Scy @param buf the evbuffer to be read from 346275970Scy @param data the destination buffer to store the result 347275970Scy @param datlen the maximum size of the destination buffer 348275970Scy @return the number of bytes read, or -1 if we can't drain the buffer. 349275970Scy */ 350275970ScyEVENT2_EXPORT_SYMBOL 351275970Scyint evbuffer_remove(struct evbuffer *buf, void *data, size_t datlen); 352275970Scy 353275970Scy/** 354275970Scy Read data from an evbuffer, and leave the buffer unchanged. 355275970Scy 356275970Scy If more bytes are requested than are available in the evbuffer, we 357275970Scy only extract as many bytes as were available. 358275970Scy 359275970Scy @param buf the evbuffer to be read from 360275970Scy @param data_out the destination buffer to store the result 361275970Scy @param datlen the maximum size of the destination buffer 362275970Scy @return the number of bytes read, or -1 if we can't drain the buffer. 363275970Scy */ 364275970ScyEVENT2_EXPORT_SYMBOL 365275970Scyev_ssize_t evbuffer_copyout(struct evbuffer *buf, void *data_out, size_t datlen); 366275970Scy 367275970Scy/** 368275970Scy Read data from the middle of an evbuffer, and leave the buffer unchanged. 369275970Scy 370275970Scy If more bytes are requested than are available in the evbuffer, we 371275970Scy only extract as many bytes as were available. 372275970Scy 373275970Scy @param buf the evbuffer to be read from 374275970Scy @param pos the position to start reading from 375275970Scy @param data_out the destination buffer to store the result 376275970Scy @param datlen the maximum size of the destination buffer 377275970Scy @return the number of bytes read, or -1 if we can't drain the buffer. 378275970Scy */ 379275970ScyEVENT2_EXPORT_SYMBOL 380275970Scyev_ssize_t evbuffer_copyout_from(struct evbuffer *buf, const struct evbuffer_ptr *pos, void *data_out, size_t datlen); 381275970Scy 382275970Scy/** 383275970Scy Read data from an evbuffer into another evbuffer, draining 384275970Scy the bytes from the source buffer. This function avoids copy 385275970Scy operations to the extent possible. 386275970Scy 387275970Scy If more bytes are requested than are available in src, the src 388275970Scy buffer is drained completely. 389275970Scy 390275970Scy @param src the evbuffer to be read from 391275970Scy @param dst the destination evbuffer to store the result into 392275970Scy @param datlen the maximum numbers of bytes to transfer 393275970Scy @return the number of bytes read 394275970Scy */ 395275970ScyEVENT2_EXPORT_SYMBOL 396275970Scyint evbuffer_remove_buffer(struct evbuffer *src, struct evbuffer *dst, 397275970Scy size_t datlen); 398275970Scy 399275970Scy/** Used to tell evbuffer_readln what kind of line-ending to look for. 400275970Scy */ 401275970Scyenum evbuffer_eol_style { 402275970Scy /** Any sequence of CR and LF characters is acceptable as an 403275970Scy * EOL. 404275970Scy * 405275970Scy * Note that this style can produce ambiguous results: the 406275970Scy * sequence "CRLF" will be treated as a single EOL if it is 407275970Scy * all in the buffer at once, but if you first read a CR from 408275970Scy * the network and later read an LF from the network, it will 409275970Scy * be treated as two EOLs. 410275970Scy */ 411275970Scy EVBUFFER_EOL_ANY, 412275970Scy /** An EOL is an LF, optionally preceded by a CR. This style is 413275970Scy * most useful for implementing text-based internet protocols. */ 414275970Scy EVBUFFER_EOL_CRLF, 415275970Scy /** An EOL is a CR followed by an LF. */ 416275970Scy EVBUFFER_EOL_CRLF_STRICT, 417275970Scy /** An EOL is a LF. */ 418275970Scy EVBUFFER_EOL_LF, 419275970Scy /** An EOL is a NUL character (that is, a single byte with value 0) */ 420275970Scy EVBUFFER_EOL_NUL 421275970Scy}; 422275970Scy 423275970Scy/** 424275970Scy * Read a single line from an evbuffer. 425275970Scy * 426275970Scy * Reads a line terminated by an EOL as determined by the evbuffer_eol_style 427275970Scy * argument. Returns a newly allocated nul-terminated string; the caller must 428275970Scy * free the returned value. The EOL is not included in the returned string. 429275970Scy * 430275970Scy * @param buffer the evbuffer to read from 431275970Scy * @param n_read_out if non-NULL, points to a size_t that is set to the 432275970Scy * number of characters in the returned string. This is useful for 433275970Scy * strings that can contain NUL characters. 434275970Scy * @param eol_style the style of line-ending to use. 435275970Scy * @return pointer to a single line, or NULL if an error occurred 436275970Scy */ 437275970ScyEVENT2_EXPORT_SYMBOL 438275970Scychar *evbuffer_readln(struct evbuffer *buffer, size_t *n_read_out, 439275970Scy enum evbuffer_eol_style eol_style); 440275970Scy 441275970Scy/** 442275970Scy Move all data from one evbuffer into another evbuffer. 443275970Scy 444275970Scy This is a destructive add. The data from one buffer moves into 445275970Scy the other buffer. However, no unnecessary memory copies occur. 446275970Scy 447275970Scy @param outbuf the output buffer 448275970Scy @param inbuf the input buffer 449275970Scy @return 0 if successful, or -1 if an error occurred 450275970Scy 451275970Scy @see evbuffer_remove_buffer() 452275970Scy */ 453275970ScyEVENT2_EXPORT_SYMBOL 454275970Scyint evbuffer_add_buffer(struct evbuffer *outbuf, struct evbuffer *inbuf); 455275970Scy 456275970Scy/** 457275970Scy Copy data from one evbuffer into another evbuffer. 458275970Scy 459275970Scy This is a non-destructive add. The data from one buffer is copied 460275970Scy into the other buffer. However, no unnecessary memory copies occur. 461275970Scy 462275970Scy Note that buffers already containing buffer references can't be added 463275970Scy to other buffers. 464275970Scy 465275970Scy @param outbuf the output buffer 466275970Scy @param inbuf the input buffer 467275970Scy @return 0 if successful, or -1 if an error occurred 468275970Scy */ 469275970ScyEVENT2_EXPORT_SYMBOL 470275970Scyint evbuffer_add_buffer_reference(struct evbuffer *outbuf, 471275970Scy struct evbuffer *inbuf); 472275970Scy 473275970Scy/** 474275970Scy A cleanup function for a piece of memory added to an evbuffer by 475275970Scy reference. 476275970Scy 477275970Scy @see evbuffer_add_reference() 478275970Scy */ 479275970Scytypedef void (*evbuffer_ref_cleanup_cb)(const void *data, 480275970Scy size_t datalen, void *extra); 481275970Scy 482275970Scy/** 483275970Scy Reference memory into an evbuffer without copying. 484275970Scy 485275970Scy The memory needs to remain valid until all the added data has been 486275970Scy read. This function keeps just a reference to the memory without 487275970Scy actually incurring the overhead of a copy. 488275970Scy 489275970Scy @param outbuf the output buffer 490275970Scy @param data the memory to reference 491275970Scy @param datlen how memory to reference 492275970Scy @param cleanupfn callback to be invoked when the memory is no longer 493275970Scy referenced by this evbuffer. 494275970Scy @param cleanupfn_arg optional argument to the cleanup callback 495275970Scy @return 0 if successful, or -1 if an error occurred 496275970Scy */ 497275970ScyEVENT2_EXPORT_SYMBOL 498275970Scyint evbuffer_add_reference(struct evbuffer *outbuf, 499275970Scy const void *data, size_t datlen, 500275970Scy evbuffer_ref_cleanup_cb cleanupfn, void *cleanupfn_arg); 501275970Scy 502275970Scy/** 503275970Scy Copy data from a file into the evbuffer for writing to a socket. 504275970Scy 505275970Scy This function avoids unnecessary data copies between userland and 506275970Scy kernel. If sendfile is available and the EVBUFFER_FLAG_DRAINS_TO_FD 507275970Scy flag is set, it uses those functions. Otherwise, it tries to use 508275970Scy mmap (or CreateFileMapping on Windows). 509275970Scy 510275970Scy The function owns the resulting file descriptor and will close it 511275970Scy when finished transferring data. 512275970Scy 513275970Scy The results of using evbuffer_remove() or evbuffer_pullup() on 514275970Scy evbuffers whose data was added using this function are undefined. 515275970Scy 516275970Scy For more fine-grained control, use evbuffer_add_file_segment. 517275970Scy 518275970Scy @param outbuf the output buffer 519275970Scy @param fd the file descriptor 520275970Scy @param offset the offset from which to read data 521275970Scy @param length how much data to read, or -1 to read as much as possible. 522275970Scy (-1 requires that 'fd' support fstat.) 523275970Scy @return 0 if successful, or -1 if an error occurred 524275970Scy*/ 525275970Scy 526275970ScyEVENT2_EXPORT_SYMBOL 527275970Scyint evbuffer_add_file(struct evbuffer *outbuf, int fd, ev_off_t offset, 528275970Scy ev_off_t length); 529275970Scy 530275970Scy/** 531275970Scy An evbuffer_file_segment holds a reference to a range of a file -- 532275970Scy possibly the whole file! -- for use in writing from an evbuffer to a 533275970Scy socket. It could be implemented with mmap, sendfile, splice, or (if all 534275970Scy else fails) by just pulling all the data into RAM. A single 535275970Scy evbuffer_file_segment can be added more than once, and to more than one 536275970Scy evbuffer. 537275970Scy */ 538275970Scystruct evbuffer_file_segment; 539275970Scy 540275970Scy/** 541275970Scy Flag for creating evbuffer_file_segment: If this flag is set, then when 542275970Scy the evbuffer_file_segment is freed and no longer in use by any 543275970Scy evbuffer, the underlying fd is closed. 544275970Scy */ 545275970Scy#define EVBUF_FS_CLOSE_ON_FREE 0x01 546275970Scy/** 547275970Scy Flag for creating evbuffer_file_segment: Disable memory-map based 548275970Scy implementations. 549275970Scy */ 550275970Scy#define EVBUF_FS_DISABLE_MMAP 0x02 551275970Scy/** 552275970Scy Flag for creating evbuffer_file_segment: Disable direct fd-to-fd 553275970Scy implementations (including sendfile and splice). 554275970Scy 555275970Scy You might want to use this option if data needs to be taken from the 556275970Scy evbuffer by any means other than writing it to the network: the sendfile 557275970Scy backend is fast, but it only works for sending files directly to the 558275970Scy network. 559275970Scy */ 560275970Scy#define EVBUF_FS_DISABLE_SENDFILE 0x04 561275970Scy/** 562275970Scy Flag for creating evbuffer_file_segment: Do not allocate a lock for this 563275970Scy segment. If this option is set, then neither the segment nor any 564275970Scy evbuffer it is added to may ever be accessed from more than one thread 565275970Scy at a time. 566275970Scy */ 567275970Scy#define EVBUF_FS_DISABLE_LOCKING 0x08 568275970Scy 569275970Scy/** 570275970Scy A cleanup function for a evbuffer_file_segment added to an evbuffer 571275970Scy for reference. 572275970Scy */ 573275970Scytypedef void (*evbuffer_file_segment_cleanup_cb)( 574275970Scy struct evbuffer_file_segment const* seg, int flags, void* arg); 575275970Scy 576275970Scy/** 577275970Scy Create and return a new evbuffer_file_segment for reading data from a 578275970Scy file and sending it out via an evbuffer. 579275970Scy 580275970Scy This function avoids unnecessary data copies between userland and 581275970Scy kernel. Where available, it uses sendfile or splice. 582275970Scy 583275970Scy The file descriptor must not be closed so long as any evbuffer is using 584275970Scy this segment. 585275970Scy 586275970Scy The results of using evbuffer_remove() or evbuffer_pullup() or any other 587275970Scy function that reads bytes from an evbuffer on any evbuffer containing 588275970Scy the newly returned segment are undefined, unless you pass the 589275970Scy EVBUF_FS_DISABLE_SENDFILE flag to this function. 590275970Scy 591275970Scy @param fd an open file to read from. 592275970Scy @param offset an index within the file at which to start reading 593275970Scy @param length how much data to read, or -1 to read as much as possible. 594275970Scy (-1 requires that 'fd' support fstat.) 595275970Scy @param flags any number of the EVBUF_FS_* flags 596275970Scy @return a new evbuffer_file_segment, or NULL on failure. 597275970Scy **/ 598275970ScyEVENT2_EXPORT_SYMBOL 599275970Scystruct evbuffer_file_segment *evbuffer_file_segment_new( 600275970Scy int fd, ev_off_t offset, ev_off_t length, unsigned flags); 601275970Scy 602275970Scy/** 603275970Scy Free an evbuffer_file_segment 604275970Scy 605275970Scy It is safe to call this function even if the segment has been added to 606275970Scy one or more evbuffers. The evbuffer_file_segment will not be freed 607275970Scy until no more references to it exist. 608275970Scy */ 609275970ScyEVENT2_EXPORT_SYMBOL 610275970Scyvoid evbuffer_file_segment_free(struct evbuffer_file_segment *seg); 611275970Scy 612275970Scy/** 613275970Scy Add cleanup callback and argument for the callback to an 614275970Scy evbuffer_file_segment. 615275970Scy 616275970Scy The cleanup callback will be invoked when no more references to the 617275970Scy evbuffer_file_segment exist. 618275970Scy **/ 619275970ScyEVENT2_EXPORT_SYMBOL 620275970Scyvoid evbuffer_file_segment_add_cleanup_cb(struct evbuffer_file_segment *seg, 621275970Scy evbuffer_file_segment_cleanup_cb cb, void* arg); 622275970Scy 623275970Scy/** 624275970Scy Insert some or all of an evbuffer_file_segment at the end of an evbuffer 625275970Scy 626275970Scy Note that the offset and length parameters of this function have a 627275970Scy different meaning from those provided to evbuffer_file_segment_new: When 628275970Scy you create the segment, the offset is the offset _within the file_, and 629275970Scy the length is the length _of the segment_, whereas when you add a 630275970Scy segment to an evbuffer, the offset is _within the segment_ and the 631275970Scy length is the length of the _part of the segment you want to use. 632275970Scy 633275970Scy In other words, if you have a 10 KiB file, and you create an 634275970Scy evbuffer_file_segment for it with offset 20 and length 1000, it will 635275970Scy refer to bytes 20..1019 inclusive. If you then pass this segment to 636275970Scy evbuffer_add_file_segment and specify an offset of 20 and a length of 637275970Scy 50, you will be adding bytes 40..99 inclusive. 638275970Scy 639275970Scy @param buf the evbuffer to append to 640275970Scy @param seg the segment to add 641275970Scy @param offset the offset within the segment to start from 642275970Scy @param length the amount of data to add, or -1 to add it all. 643275970Scy @return 0 on success, -1 on failure. 644275970Scy */ 645275970ScyEVENT2_EXPORT_SYMBOL 646275970Scyint evbuffer_add_file_segment(struct evbuffer *buf, 647275970Scy struct evbuffer_file_segment *seg, ev_off_t offset, ev_off_t length); 648275970Scy 649275970Scy/** 650275970Scy Append a formatted string to the end of an evbuffer. 651275970Scy 652275970Scy The string is formated as printf. 653275970Scy 654275970Scy @param buf the evbuffer that will be appended to 655275970Scy @param fmt a format string 656275970Scy @param ... arguments that will be passed to printf(3) 657275970Scy @return The number of bytes added if successful, or -1 if an error occurred. 658275970Scy 659275970Scy @see evutil_printf(), evbuffer_add_vprintf() 660275970Scy */ 661275970ScyEVENT2_EXPORT_SYMBOL 662275970Scyint evbuffer_add_printf(struct evbuffer *buf, const char *fmt, ...) 663275970Scy#ifdef __GNUC__ 664275970Scy __attribute__((format(printf, 2, 3))) 665275970Scy#endif 666275970Scy; 667275970Scy 668275970Scy/** 669275970Scy Append a va_list formatted string to the end of an evbuffer. 670275970Scy 671275970Scy @param buf the evbuffer that will be appended to 672275970Scy @param fmt a format string 673275970Scy @param ap a varargs va_list argument array that will be passed to vprintf(3) 674275970Scy @return The number of bytes added if successful, or -1 if an error occurred. 675275970Scy */ 676275970ScyEVENT2_EXPORT_SYMBOL 677275970Scyint evbuffer_add_vprintf(struct evbuffer *buf, const char *fmt, va_list ap) 678275970Scy#ifdef __GNUC__ 679275970Scy __attribute__((format(printf, 2, 0))) 680275970Scy#endif 681275970Scy; 682275970Scy 683275970Scy 684275970Scy/** 685275970Scy Remove a specified number of bytes data from the beginning of an evbuffer. 686275970Scy 687275970Scy @param buf the evbuffer to be drained 688275970Scy @param len the number of bytes to drain from the beginning of the buffer 689275970Scy @return 0 on success, -1 on failure. 690275970Scy */ 691275970ScyEVENT2_EXPORT_SYMBOL 692275970Scyint evbuffer_drain(struct evbuffer *buf, size_t len); 693275970Scy 694275970Scy 695275970Scy/** 696275970Scy Write the contents of an evbuffer to a file descriptor. 697275970Scy 698275970Scy The evbuffer will be drained after the bytes have been successfully written. 699275970Scy 700275970Scy @param buffer the evbuffer to be written and drained 701275970Scy @param fd the file descriptor to be written to 702275970Scy @return the number of bytes written, or -1 if an error occurred 703275970Scy @see evbuffer_read() 704275970Scy */ 705275970ScyEVENT2_EXPORT_SYMBOL 706275970Scyint evbuffer_write(struct evbuffer *buffer, evutil_socket_t fd); 707275970Scy 708275970Scy/** 709275970Scy Write some of the contents of an evbuffer to a file descriptor. 710275970Scy 711275970Scy The evbuffer will be drained after the bytes have been successfully written. 712275970Scy 713275970Scy @param buffer the evbuffer to be written and drained 714275970Scy @param fd the file descriptor to be written to 715275970Scy @param howmuch the largest allowable number of bytes to write, or -1 716275970Scy to write as many bytes as we can. 717275970Scy @return the number of bytes written, or -1 if an error occurred 718275970Scy @see evbuffer_read() 719275970Scy */ 720275970ScyEVENT2_EXPORT_SYMBOL 721275970Scyint evbuffer_write_atmost(struct evbuffer *buffer, evutil_socket_t fd, 722275970Scy ev_ssize_t howmuch); 723275970Scy 724275970Scy/** 725275970Scy Read from a file descriptor and store the result in an evbuffer. 726275970Scy 727275970Scy @param buffer the evbuffer to store the result 728275970Scy @param fd the file descriptor to read from 729275970Scy @param howmuch the number of bytes to be read 730275970Scy @return the number of bytes read, or -1 if an error occurred 731275970Scy @see evbuffer_write() 732275970Scy */ 733275970ScyEVENT2_EXPORT_SYMBOL 734275970Scyint evbuffer_read(struct evbuffer *buffer, evutil_socket_t fd, int howmuch); 735275970Scy 736275970Scy/** 737275970Scy Search for a string within an evbuffer. 738275970Scy 739275970Scy @param buffer the evbuffer to be searched 740275970Scy @param what the string to be searched for 741275970Scy @param len the length of the search string 742275970Scy @param start NULL or a pointer to a valid struct evbuffer_ptr. 743275970Scy @return a struct evbuffer_ptr whose 'pos' field has the offset of the 744275970Scy first occurrence of the string in the buffer after 'start'. The 'pos' 745275970Scy field of the result is -1 if the string was not found. 746275970Scy */ 747275970ScyEVENT2_EXPORT_SYMBOL 748275970Scystruct evbuffer_ptr evbuffer_search(struct evbuffer *buffer, const char *what, size_t len, const struct evbuffer_ptr *start); 749275970Scy 750275970Scy/** 751275970Scy Search for a string within part of an evbuffer. 752275970Scy 753275970Scy @param buffer the evbuffer to be searched 754275970Scy @param what the string to be searched for 755275970Scy @param len the length of the search string 756275970Scy @param start NULL or a pointer to a valid struct evbuffer_ptr that 757275970Scy indicates where we should start searching. 758275970Scy @param end NULL or a pointer to a valid struct evbuffer_ptr that 759275970Scy indicates where we should stop searching. 760275970Scy @return a struct evbuffer_ptr whose 'pos' field has the offset of the 761275970Scy first occurrence of the string in the buffer after 'start'. The 'pos' 762275970Scy field of the result is -1 if the string was not found. 763275970Scy */ 764275970ScyEVENT2_EXPORT_SYMBOL 765275970Scystruct evbuffer_ptr evbuffer_search_range(struct evbuffer *buffer, const char *what, size_t len, const struct evbuffer_ptr *start, const struct evbuffer_ptr *end); 766275970Scy 767275970Scy/** 768275970Scy Defines how to adjust an evbuffer_ptr by evbuffer_ptr_set() 769275970Scy 770275970Scy @see evbuffer_ptr_set() */ 771275970Scyenum evbuffer_ptr_how { 772275970Scy /** Sets the pointer to the position; can be called on with an 773275970Scy uninitialized evbuffer_ptr. */ 774275970Scy EVBUFFER_PTR_SET, 775275970Scy /** Advances the pointer by adding to the current position. */ 776275970Scy EVBUFFER_PTR_ADD 777275970Scy}; 778275970Scy 779275970Scy/** 780275970Scy Sets the search pointer in the buffer to position. 781275970Scy 782275970Scy There are two ways to use this function: you can call 783275970Scy evbuffer_ptr_set(buf, &pos, N, EVBUFFER_PTR_SET) 784275970Scy to move 'pos' to a position 'N' bytes after the start of the buffer, or 785285612Sdelphij evbuffer_ptr_set(buf, &pos, N, EVBUFFER_PTR_ADD) 786275970Scy to move 'pos' forward by 'N' bytes. 787275970Scy 788275970Scy If evbuffer_ptr is not initialized, this function can only be called 789275970Scy with EVBUFFER_PTR_SET. 790275970Scy 791275970Scy An evbuffer_ptr can represent any position from the start of the buffer to 792275970Scy a position immediately after the end of the buffer. 793275970Scy 794275970Scy @param buffer the evbuffer to be search 795275970Scy @param ptr a pointer to a struct evbuffer_ptr 796275970Scy @param position the position at which to start the next search 797275970Scy @param how determines how the pointer should be manipulated. 798275970Scy @returns 0 on success or -1 otherwise 799275970Scy*/ 800275970ScyEVENT2_EXPORT_SYMBOL 801275970Scyint 802275970Scyevbuffer_ptr_set(struct evbuffer *buffer, struct evbuffer_ptr *ptr, 803275970Scy size_t position, enum evbuffer_ptr_how how); 804275970Scy 805275970Scy/** 806275970Scy Search for an end-of-line string within an evbuffer. 807275970Scy 808275970Scy @param buffer the evbuffer to be searched 809275970Scy @param start NULL or a pointer to a valid struct evbuffer_ptr to start 810275970Scy searching at. 811275970Scy @param eol_len_out If non-NULL, the pointed-to value will be set to 812275970Scy the length of the end-of-line string. 813275970Scy @param eol_style The kind of EOL to look for; see evbuffer_readln() for 814275970Scy more information 815275970Scy @return a struct evbuffer_ptr whose 'pos' field has the offset of the 816275970Scy first occurrence EOL in the buffer after 'start'. The 'pos' 817275970Scy field of the result is -1 if the string was not found. 818275970Scy */ 819275970ScyEVENT2_EXPORT_SYMBOL 820275970Scystruct evbuffer_ptr evbuffer_search_eol(struct evbuffer *buffer, 821275970Scy struct evbuffer_ptr *start, size_t *eol_len_out, 822275970Scy enum evbuffer_eol_style eol_style); 823275970Scy 824275970Scy/** Function to peek at data inside an evbuffer without removing it or 825275970Scy copying it out. 826275970Scy 827275970Scy Pointers to the data are returned by filling the 'vec_out' array 828275970Scy with pointers to one or more extents of data inside the buffer. 829275970Scy 830275970Scy The total data in the extents that you get back may be more than 831275970Scy you requested (if there is more data last extent than you asked 832275970Scy for), or less (if you do not provide enough evbuffer_iovecs, or if 833275970Scy the buffer does not have as much data as you asked to see). 834275970Scy 835275970Scy @param buffer the evbuffer to peek into, 836275970Scy @param len the number of bytes to try to peek. If len is negative, we 837275970Scy will try to fill as much of vec_out as we can. If len is negative 838275970Scy and vec_out is not provided, we return the number of evbuffer_iovecs 839275970Scy that would be needed to get all the data in the buffer. 840275970Scy @param start_at an evbuffer_ptr indicating the point at which we 841275970Scy should start looking for data. NULL means, "At the start of the 842275970Scy buffer." 843275970Scy @param vec_out an array of evbuffer_iovec 844275970Scy @param n_vec the length of vec_out. If 0, we only count how many 845275970Scy extents would be necessary to point to the requested amount of 846275970Scy data. 847275970Scy @return The number of extents needed. This may be less than n_vec 848275970Scy if we didn't need all the evbuffer_iovecs we were given, or more 849275970Scy than n_vec if we would need more to return all the data that was 850275970Scy requested. 851275970Scy */ 852275970ScyEVENT2_EXPORT_SYMBOL 853275970Scyint evbuffer_peek(struct evbuffer *buffer, ev_ssize_t len, 854275970Scy struct evbuffer_ptr *start_at, 855275970Scy struct evbuffer_iovec *vec_out, int n_vec); 856275970Scy 857275970Scy 858275970Scy/** Structure passed to an evbuffer_cb_func evbuffer callback 859275970Scy 860275970Scy @see evbuffer_cb_func, evbuffer_add_cb() 861275970Scy */ 862275970Scystruct evbuffer_cb_info { 863275970Scy /** The number of bytes in this evbuffer when callbacks were last 864275970Scy * invoked. */ 865275970Scy size_t orig_size; 866275970Scy /** The number of bytes added since callbacks were last invoked. */ 867275970Scy size_t n_added; 868275970Scy /** The number of bytes removed since callbacks were last invoked. */ 869275970Scy size_t n_deleted; 870275970Scy}; 871275970Scy 872275970Scy/** Type definition for a callback that is invoked whenever data is added or 873275970Scy removed from an evbuffer. 874275970Scy 875275970Scy An evbuffer may have one or more callbacks set at a time. The order 876275970Scy in which they are executed is undefined. 877275970Scy 878275970Scy A callback function may add more callbacks, or remove itself from the 879275970Scy list of callbacks, or add or remove data from the buffer. It may not 880275970Scy remove another callback from the list. 881275970Scy 882275970Scy If a callback adds or removes data from the buffer or from another 883275970Scy buffer, this can cause a recursive invocation of your callback or 884275970Scy other callbacks. If you ask for an infinite loop, you might just get 885275970Scy one: watch out! 886275970Scy 887275970Scy @param buffer the buffer whose size has changed 888275970Scy @param info a structure describing how the buffer changed. 889275970Scy @param arg a pointer to user data 890275970Scy*/ 891275970Scytypedef void (*evbuffer_cb_func)(struct evbuffer *buffer, const struct evbuffer_cb_info *info, void *arg); 892275970Scy 893275970Scystruct evbuffer_cb_entry; 894275970Scy/** Add a new callback to an evbuffer. 895275970Scy 896275970Scy Subsequent calls to evbuffer_add_cb() add new callbacks. To remove this 897275970Scy callback, call evbuffer_remove_cb or evbuffer_remove_cb_entry. 898275970Scy 899275970Scy @param buffer the evbuffer to be monitored 900275970Scy @param cb the callback function to invoke when the evbuffer is modified, 901275970Scy or NULL to remove all callbacks. 902275970Scy @param cbarg an argument to be provided to the callback function 903275970Scy @return a handle to the callback on success, or NULL on failure. 904275970Scy */ 905275970ScyEVENT2_EXPORT_SYMBOL 906275970Scystruct evbuffer_cb_entry *evbuffer_add_cb(struct evbuffer *buffer, evbuffer_cb_func cb, void *cbarg); 907275970Scy 908275970Scy/** Remove a callback from an evbuffer, given a handle returned from 909275970Scy evbuffer_add_cb. 910275970Scy 911275970Scy Calling this function invalidates the handle. 912275970Scy 913275970Scy @return 0 if a callback was removed, or -1 if no matching callback was 914275970Scy found. 915275970Scy */ 916275970ScyEVENT2_EXPORT_SYMBOL 917275970Scyint evbuffer_remove_cb_entry(struct evbuffer *buffer, 918275970Scy struct evbuffer_cb_entry *ent); 919275970Scy 920275970Scy/** Remove a callback from an evbuffer, given the function and argument 921275970Scy used to add it. 922275970Scy 923275970Scy @return 0 if a callback was removed, or -1 if no matching callback was 924275970Scy found. 925275970Scy */ 926275970ScyEVENT2_EXPORT_SYMBOL 927275970Scyint evbuffer_remove_cb(struct evbuffer *buffer, evbuffer_cb_func cb, void *cbarg); 928275970Scy 929275970Scy/** If this flag is not set, then a callback is temporarily disabled, and 930275970Scy * should not be invoked. 931275970Scy * 932275970Scy * @see evbuffer_cb_set_flags(), evbuffer_cb_clear_flags() 933275970Scy */ 934275970Scy#define EVBUFFER_CB_ENABLED 1 935275970Scy 936275970Scy/** Change the flags that are set for a callback on a buffer by adding more. 937275970Scy 938275970Scy @param buffer the evbuffer that the callback is watching. 939275970Scy @param cb the callback whose status we want to change. 940275970Scy @param flags EVBUFFER_CB_ENABLED to re-enable the callback. 941275970Scy @return 0 on success, -1 on failure. 942275970Scy */ 943275970ScyEVENT2_EXPORT_SYMBOL 944275970Scyint evbuffer_cb_set_flags(struct evbuffer *buffer, 945275970Scy struct evbuffer_cb_entry *cb, ev_uint32_t flags); 946275970Scy 947275970Scy/** Change the flags that are set for a callback on a buffer by removing some 948275970Scy 949275970Scy @param buffer the evbuffer that the callback is watching. 950275970Scy @param cb the callback whose status we want to change. 951275970Scy @param flags EVBUFFER_CB_ENABLED to disable the callback. 952275970Scy @return 0 on success, -1 on failure. 953275970Scy */ 954275970ScyEVENT2_EXPORT_SYMBOL 955275970Scyint evbuffer_cb_clear_flags(struct evbuffer *buffer, 956275970Scy struct evbuffer_cb_entry *cb, ev_uint32_t flags); 957275970Scy 958275970Scy#if 0 959275970Scy/** Postpone calling a given callback until unsuspend is called later. 960275970Scy 961275970Scy This is different from disabling the callback, since the callback will get 962275970Scy invoked later if the buffer size changes between now and when we unsuspend 963275970Scy it. 964275970Scy 965275970Scy @param the buffer that the callback is watching. 966275970Scy @param cb the callback we want to suspend. 967275970Scy */ 968275970ScyEVENT2_EXPORT_SYMBOL 969275970Scyvoid evbuffer_cb_suspend(struct evbuffer *buffer, struct evbuffer_cb_entry *cb); 970275970Scy/** Stop postponing a callback that we postponed with evbuffer_cb_suspend. 971275970Scy 972275970Scy If data was added to or removed from the buffer while the callback was 973275970Scy suspended, the callback will get called once now. 974275970Scy 975275970Scy @param the buffer that the callback is watching. 976275970Scy @param cb the callback we want to stop suspending. 977275970Scy */ 978275970ScyEVENT2_EXPORT_SYMBOL 979275970Scyvoid evbuffer_cb_unsuspend(struct evbuffer *buffer, struct evbuffer_cb_entry *cb); 980275970Scy#endif 981275970Scy 982275970Scy/** 983275970Scy Makes the data at the beginning of an evbuffer contiguous. 984275970Scy 985275970Scy @param buf the evbuffer to make contiguous 986275970Scy @param size the number of bytes to make contiguous, or -1 to make the 987275970Scy entire buffer contiguous. 988275970Scy @return a pointer to the contiguous memory array, or NULL if param size 989275970Scy requested more data than is present in the buffer. 990275970Scy*/ 991275970Scy 992275970ScyEVENT2_EXPORT_SYMBOL 993275970Scyunsigned char *evbuffer_pullup(struct evbuffer *buf, ev_ssize_t size); 994275970Scy 995275970Scy/** 996275970Scy Prepends data to the beginning of the evbuffer 997275970Scy 998275970Scy @param buf the evbuffer to which to prepend data 999275970Scy @param data a pointer to the memory to prepend 1000275970Scy @param size the number of bytes to prepend 1001275970Scy @return 0 if successful, or -1 otherwise 1002275970Scy*/ 1003275970Scy 1004275970ScyEVENT2_EXPORT_SYMBOL 1005275970Scyint evbuffer_prepend(struct evbuffer *buf, const void *data, size_t size); 1006275970Scy 1007275970Scy/** 1008275970Scy Prepends all data from the src evbuffer to the beginning of the dst 1009275970Scy evbuffer. 1010275970Scy 1011275970Scy @param dst the evbuffer to which to prepend data 1012275970Scy @param src the evbuffer to prepend; it will be emptied as a result 1013275970Scy @return 0 if successful, or -1 otherwise 1014275970Scy*/ 1015275970ScyEVENT2_EXPORT_SYMBOL 1016275970Scyint evbuffer_prepend_buffer(struct evbuffer *dst, struct evbuffer* src); 1017275970Scy 1018275970Scy/** 1019275970Scy Prevent calls that modify an evbuffer from succeeding. A buffer may 1020275970Scy frozen at the front, at the back, or at both the front and the back. 1021275970Scy 1022275970Scy If the front of a buffer is frozen, operations that drain data from 1023275970Scy the front of the buffer, or that prepend data to the buffer, will 1024275970Scy fail until it is unfrozen. If the back a buffer is frozen, operations 1025275970Scy that append data from the buffer will fail until it is unfrozen. 1026275970Scy 1027275970Scy @param buf The buffer to freeze 1028275970Scy @param at_front If true, we freeze the front of the buffer. If false, 1029275970Scy we freeze the back. 1030275970Scy @return 0 on success, -1 on failure. 1031275970Scy*/ 1032275970ScyEVENT2_EXPORT_SYMBOL 1033275970Scyint evbuffer_freeze(struct evbuffer *buf, int at_front); 1034275970Scy/** 1035275970Scy Re-enable calls that modify an evbuffer. 1036275970Scy 1037275970Scy @param buf The buffer to un-freeze 1038275970Scy @param at_front If true, we unfreeze the front of the buffer. If false, 1039275970Scy we unfreeze the back. 1040275970Scy @return 0 on success, -1 on failure. 1041275970Scy */ 1042275970ScyEVENT2_EXPORT_SYMBOL 1043275970Scyint evbuffer_unfreeze(struct evbuffer *buf, int at_front); 1044275970Scy 1045275970Scystruct event_base; 1046275970Scy/** 1047275970Scy Force all the callbacks on an evbuffer to be run, not immediately after 1048275970Scy the evbuffer is altered, but instead from inside the event loop. 1049275970Scy 1050275970Scy This can be used to serialize all the callbacks to a single thread 1051275970Scy of execution. 1052275970Scy */ 1053275970ScyEVENT2_EXPORT_SYMBOL 1054275970Scyint evbuffer_defer_callbacks(struct evbuffer *buffer, struct event_base *base); 1055275970Scy 1056275970Scy/** 1057275970Scy Append data from 1 or more iovec's to an evbuffer 1058275970Scy 1059275970Scy Calculates the number of bytes needed for an iovec structure and guarantees 1060275970Scy all data will fit into a single chain. Can be used in lieu of functionality 1061275970Scy which calls evbuffer_add() constantly before being used to increase 1062275970Scy performance. 1063275970Scy 1064275970Scy @param buffer the destination buffer 1065275970Scy @param vec the source iovec 1066275970Scy @param n_vec the number of iovec structures. 1067275970Scy @return the number of bytes successfully written to the output buffer. 1068275970Scy*/ 1069275970ScyEVENT2_EXPORT_SYMBOL 1070275970Scysize_t evbuffer_add_iovec(struct evbuffer * buffer, struct evbuffer_iovec * vec, int n_vec); 1071275970Scy 1072275970Scy#ifdef __cplusplus 1073275970Scy} 1074275970Scy#endif 1075275970Scy 1076275970Scy#endif /* EVENT2_BUFFER_H_INCLUDED_ */ 1077