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
730   @return the number of bytes read, or -1 if an error occurred
731   @see evbuffer_write()
732  */
733 EVENT2_EXPORT_SYMBOL
734 int evbuffer_read(struct evbuffer *buffer, evutil_socket_t fd, int howmuch);
735 
736 /**
737    Search for a string within an evbuffer.
738 
739    @param buffer the evbuffer to be searched
740    @param what the string to be searched for
741    @param len the length of the search string
742    @param start NULL or a pointer to a valid struct evbuffer_ptr.
743    @return a struct evbuffer_ptr whose 'pos' field has the offset of the
744      first occurrence of the string in the buffer after 'start'.  The 'pos'
745      field of the result is -1 if the string was not found.
746  */
747 EVENT2_EXPORT_SYMBOL
748 struct evbuffer_ptr evbuffer_search(struct evbuffer *buffer, const char *what, size_t len, const struct evbuffer_ptr *start);
749 
750 /**
751    Search for a string within part of an evbuffer.
752 
753    @param buffer the evbuffer to be searched
754    @param what the string to be searched for
755    @param len the length of the search string
756    @param start NULL or a pointer to a valid struct evbuffer_ptr that
757      indicates where we should start searching.
758    @param end NULL or a pointer to a valid struct evbuffer_ptr that
759      indicates where we should stop searching.
760    @return a struct evbuffer_ptr whose 'pos' field has the offset of the
761      first occurrence of the string in the buffer after 'start'.  The 'pos'
762      field of the result is -1 if the string was not found.
763  */
764 EVENT2_EXPORT_SYMBOL
765 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);
766 
767 /**
768    Defines how to adjust an evbuffer_ptr by evbuffer_ptr_set()
769 
770    @see evbuffer_ptr_set() */
771 enum evbuffer_ptr_how {
772 	/** Sets the pointer to the position; can be called on with an
773 	    uninitialized evbuffer_ptr. */
774 	EVBUFFER_PTR_SET,
775 	/** Advances the pointer by adding to the current position. */
776 	EVBUFFER_PTR_ADD
777 };
778 
779 /**
780    Sets the search pointer in the buffer to position.
781 
782    There are two ways to use this function: you can call
783       evbuffer_ptr_set(buf, &pos, N, EVBUFFER_PTR_SET)
784    to move 'pos' to a position 'N' bytes after the start of the buffer, or
785       evbuffer_ptr_set(buf, &pos, N, EVBUFFER_PTR_ADD)
786    to move 'pos' forward by 'N' bytes.
787 
788    If evbuffer_ptr is not initialized, this function can only be called
789    with EVBUFFER_PTR_SET.
790 
791    An evbuffer_ptr can represent any position from the start of the buffer to
792    a position immediately after the end of the buffer.
793 
794    @param buffer the evbuffer to be search
795    @param ptr a pointer to a struct evbuffer_ptr
796    @param position the position at which to start the next search
797    @param how determines how the pointer should be manipulated.
798    @returns 0 on success or -1 otherwise
799 */
800 EVENT2_EXPORT_SYMBOL
801 int
802 evbuffer_ptr_set(struct evbuffer *buffer, struct evbuffer_ptr *ptr,
803     size_t position, enum evbuffer_ptr_how how);
804 
805 /**
806    Search for an end-of-line string within an evbuffer.
807 
808    @param buffer the evbuffer to be searched
809    @param start NULL or a pointer to a valid struct evbuffer_ptr to start
810       searching at.
811    @param eol_len_out If non-NULL, the pointed-to value will be set to
812       the length of the end-of-line string.
813    @param eol_style The kind of EOL to look for; see evbuffer_readln() for
814       more information
815    @return a struct evbuffer_ptr whose 'pos' field has the offset of the
816      first occurrence EOL in the buffer after 'start'.  The 'pos'
817      field of the result is -1 if the string was not found.
818  */
819 EVENT2_EXPORT_SYMBOL
820 struct evbuffer_ptr evbuffer_search_eol(struct evbuffer *buffer,
821     struct evbuffer_ptr *start, size_t *eol_len_out,
822     enum evbuffer_eol_style eol_style);
823 
824 /** Function to peek at data inside an evbuffer without removing it or
825     copying it out.
826 
827     Pointers to the data are returned by filling the 'vec_out' array
828     with pointers to one or more extents of data inside the buffer.
829 
830     The total data in the extents that you get back may be more than
831     you requested (if there is more data last extent than you asked
832     for), or less (if you do not provide enough evbuffer_iovecs, or if
833     the buffer does not have as much data as you asked to see).
834 
835     @param buffer the evbuffer to peek into,
836     @param len the number of bytes to try to peek.  If len is negative, we
837        will try to fill as much of vec_out as we can.  If len is negative
838        and vec_out is not provided, we return the number of evbuffer_iovecs
839        that would be needed to get all the data in the buffer.
840     @param start_at an evbuffer_ptr indicating the point at which we
841        should start looking for data.  NULL means, "At the start of the
842        buffer."
843     @param vec_out an array of evbuffer_iovec
844     @param n_vec the length of vec_out.  If 0, we only count how many
845        extents would be necessary to point to the requested amount of
846        data.
847     @return The number of extents needed.  This may be less than n_vec
848        if we didn't need all the evbuffer_iovecs we were given, or more
849        than n_vec if we would need more to return all the data that was
850        requested.
851  */
852 EVENT2_EXPORT_SYMBOL
853 int evbuffer_peek(struct evbuffer *buffer, ev_ssize_t len,
854     struct evbuffer_ptr *start_at,
855     struct evbuffer_iovec *vec_out, int n_vec);
856 
857 
858 /** Structure passed to an evbuffer_cb_func evbuffer callback
859 
860     @see evbuffer_cb_func, evbuffer_add_cb()
861  */
862 struct evbuffer_cb_info {
863 	/** The number of bytes in this evbuffer when callbacks were last
864 	 * invoked. */
865 	size_t orig_size;
866 	/** The number of bytes added since callbacks were last invoked. */
867 	size_t n_added;
868 	/** The number of bytes removed since callbacks were last invoked. */
869 	size_t n_deleted;
870 };
871 
872 /** Type definition for a callback that is invoked whenever data is added or
873     removed from an evbuffer.
874 
875     An evbuffer may have one or more callbacks set at a time.  The order
876     in which they are executed is undefined.
877 
878     A callback function may add more callbacks, or remove itself from the
879     list of callbacks, or add or remove data from the buffer.  It may not
880     remove another callback from the list.
881 
882     If a callback adds or removes data from the buffer or from another
883     buffer, this can cause a recursive invocation of your callback or
884     other callbacks.  If you ask for an infinite loop, you might just get
885     one: watch out!
886 
887     @param buffer the buffer whose size has changed
888     @param info a structure describing how the buffer changed.
889     @param arg a pointer to user data
890 */
891 typedef void (*evbuffer_cb_func)(struct evbuffer *buffer, const struct evbuffer_cb_info *info, void *arg);
892 
893 struct evbuffer_cb_entry;
894 /** Add a new callback to an evbuffer.
895 
896   Subsequent calls to evbuffer_add_cb() add new callbacks.  To remove this
897   callback, call evbuffer_remove_cb or evbuffer_remove_cb_entry.
898 
899   @param buffer the evbuffer to be monitored
900   @param cb the callback function to invoke when the evbuffer is modified,
901 	or NULL to remove all callbacks.
902   @param cbarg an argument to be provided to the callback function
903   @return a handle to the callback on success, or NULL on failure.
904  */
905 EVENT2_EXPORT_SYMBOL
906 struct evbuffer_cb_entry *evbuffer_add_cb(struct evbuffer *buffer, evbuffer_cb_func cb, void *cbarg);
907 
908 /** Remove a callback from an evbuffer, given a handle returned from
909     evbuffer_add_cb.
910 
911     Calling this function invalidates the handle.
912 
913     @return 0 if a callback was removed, or -1 if no matching callback was
914     found.
915  */
916 EVENT2_EXPORT_SYMBOL
917 int evbuffer_remove_cb_entry(struct evbuffer *buffer,
918 			     struct evbuffer_cb_entry *ent);
919 
920 /** Remove a callback from an evbuffer, given the function and argument
921     used to add it.
922 
923     @return 0 if a callback was removed, or -1 if no matching callback was
924     found.
925  */
926 EVENT2_EXPORT_SYMBOL
927 int evbuffer_remove_cb(struct evbuffer *buffer, evbuffer_cb_func cb, void *cbarg);
928 
929 /** If this flag is not set, then a callback is temporarily disabled, and
930  * should not be invoked.
931  *
932  * @see evbuffer_cb_set_flags(), evbuffer_cb_clear_flags()
933  */
934 #define EVBUFFER_CB_ENABLED 1
935 
936 /** Change the flags that are set for a callback on a buffer by adding more.
937 
938     @param buffer the evbuffer that the callback is watching.
939     @param cb the callback whose status we want to change.
940     @param flags EVBUFFER_CB_ENABLED to re-enable the callback.
941     @return 0 on success, -1 on failure.
942  */
943 EVENT2_EXPORT_SYMBOL
944 int evbuffer_cb_set_flags(struct evbuffer *buffer,
945 			  struct evbuffer_cb_entry *cb, ev_uint32_t flags);
946 
947 /** Change the flags that are set for a callback on a buffer by removing some
948 
949     @param buffer the evbuffer that the callback is watching.
950     @param cb the callback whose status we want to change.
951     @param flags EVBUFFER_CB_ENABLED to disable the callback.
952     @return 0 on success, -1 on failure.
953  */
954 EVENT2_EXPORT_SYMBOL
955 int evbuffer_cb_clear_flags(struct evbuffer *buffer,
956 			  struct evbuffer_cb_entry *cb, ev_uint32_t flags);
957 
958 #if 0
959 /** Postpone calling a given callback until unsuspend is called later.
960 
961     This is different from disabling the callback, since the callback will get
962 	invoked later if the buffer size changes between now and when we unsuspend
963 	it.
964 
965 	@param the buffer that the callback is watching.
966 	@param cb the callback we want to suspend.
967  */
968 EVENT2_EXPORT_SYMBOL
969 void evbuffer_cb_suspend(struct evbuffer *buffer, struct evbuffer_cb_entry *cb);
970 /** Stop postponing a callback that we postponed with evbuffer_cb_suspend.
971 
972 	If data was added to or removed from the buffer while the callback was
973 	suspended, the callback will get called once now.
974 
975 	@param the buffer that the callback is watching.
976 	@param cb the callback we want to stop suspending.
977  */
978 EVENT2_EXPORT_SYMBOL
979 void evbuffer_cb_unsuspend(struct evbuffer *buffer, struct evbuffer_cb_entry *cb);
980 #endif
981 
982 /**
983   Makes the data at the beginning of an evbuffer contiguous.
984 
985   @param buf the evbuffer to make contiguous
986   @param size the number of bytes to make contiguous, or -1 to make the
987 	entire buffer contiguous.
988   @return a pointer to the contiguous memory array, or NULL if param size
989 	requested more data than is present in the buffer.
990 */
991 
992 EVENT2_EXPORT_SYMBOL
993 unsigned char *evbuffer_pullup(struct evbuffer *buf, ev_ssize_t size);
994 
995 /**
996   Prepends data to the beginning of the evbuffer
997 
998   @param buf the evbuffer to which to prepend data
999   @param data a pointer to the memory to prepend
1000   @param size the number of bytes to prepend
1001   @return 0 if successful, or -1 otherwise
1002 */
1003 
1004 EVENT2_EXPORT_SYMBOL
1005 int evbuffer_prepend(struct evbuffer *buf, const void *data, size_t size);
1006 
1007 /**
1008   Prepends all data from the src evbuffer to the beginning of the dst
1009   evbuffer.
1010 
1011   @param dst the evbuffer to which to prepend data
1012   @param src the evbuffer to prepend; it will be emptied as a result
1013   @return 0 if successful, or -1 otherwise
1014 */
1015 EVENT2_EXPORT_SYMBOL
1016 int evbuffer_prepend_buffer(struct evbuffer *dst, struct evbuffer* src);
1017 
1018 /**
1019    Prevent calls that modify an evbuffer from succeeding. A buffer may
1020    frozen at the front, at the back, or at both the front and the back.
1021 
1022    If the front of a buffer is frozen, operations that drain data from
1023    the front of the buffer, or that prepend data to the buffer, will
1024    fail until it is unfrozen.   If the back a buffer is frozen, operations
1025    that append data from the buffer will fail until it is unfrozen.
1026 
1027    @param buf The buffer to freeze
1028    @param at_front If true, we freeze the front of the buffer.  If false,
1029       we freeze the back.
1030    @return 0 on success, -1 on failure.
1031 */
1032 EVENT2_EXPORT_SYMBOL
1033 int evbuffer_freeze(struct evbuffer *buf, int at_front);
1034 /**
1035    Re-enable calls that modify an evbuffer.
1036 
1037    @param buf The buffer to un-freeze
1038    @param at_front If true, we unfreeze the front of the buffer.  If false,
1039       we unfreeze the back.
1040    @return 0 on success, -1 on failure.
1041  */
1042 EVENT2_EXPORT_SYMBOL
1043 int evbuffer_unfreeze(struct evbuffer *buf, int at_front);
1044 
1045 struct event_base;
1046 /**
1047    Force all the callbacks on an evbuffer to be run, not immediately after
1048    the evbuffer is altered, but instead from inside the event loop.
1049 
1050    This can be used to serialize all the callbacks to a single thread
1051    of execution.
1052  */
1053 EVENT2_EXPORT_SYMBOL
1054 int evbuffer_defer_callbacks(struct evbuffer *buffer, struct event_base *base);
1055 
1056 /**
1057   Append data from 1 or more iovec's to an evbuffer
1058 
1059   Calculates the number of bytes needed for an iovec structure and guarantees
1060   all data will fit into a single chain. Can be used in lieu of functionality
1061   which calls evbuffer_add() constantly before being used to increase
1062   performance.
1063 
1064   @param buffer the destination buffer
1065   @param vec the source iovec
1066   @param n_vec the number of iovec structures.
1067   @return the number of bytes successfully written to the output buffer.
1068 */
1069 EVENT2_EXPORT_SYMBOL
1070 size_t evbuffer_add_iovec(struct evbuffer * buffer, struct evbuffer_iovec * vec, int n_vec);
1071 
1072 #ifdef __cplusplus
1073 }
1074 #endif
1075 
1076 #endif /* EVENT2_BUFFER_H_INCLUDED_ */
1077