include/event2/buffer.h

33   An evbuffer can be used for preparing data before sending it to
39   A new evbuffer can be allocated with evbuffer_new(), and can be
67   As the contents of an evbuffer can be stored in multiple different
92    An evbuffer is an opaque data type for efficiently buffering data to be
97 struct evbuffer
104     Pointer to a position within an evbuffer.
127 /** Describes a single extent of memory inside an evbuffer.  Used for
146   Allocate storage for a new evbuffer.
148   @return a pointer to a newly allocated evbuffer struct, or NULL if an error
152 struct evbuffer *evbuffer_new(void);
154   Deallocate storage for an evbuffer.
156   @param buf pointer to the evbuffer to be freed
159 void evbuffer_free(struct evbuffer *buf);
162    Enable locking on an evbuffer so that it can safely be used by multiple
169    @param buf An evbuffer to make lockable.
174 int evbuffer_enable_locking(struct evbuffer *buf, void *lock);
177    Acquire the lock on an evbuffer.  Has no effect if locking was not enabled
181 void evbuffer_lock(struct evbuffer *buf);
184    Release the lock on an evbuffer.  Has no effect if locking was not enabled
188 void evbuffer_unlock(struct evbuffer *buf);
208 /** Change the flags that are set for an evbuffer by adding more.
210  * @param buffer the evbuffer that the callback is watching.
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.
219  * @param buffer the evbuffer that the callback is watching.
225 int evbuffer_clear_flags(struct evbuffer *buf, ev_uint64_t flags);
228   Returns the total number of bytes stored in the evbuffer
230   @param buf pointer to the evbuffer
231   @return the number of bytes stored in the evbuffer
234 size_t evbuffer_get_length(const struct evbuffer *buf);
244    @param buf pointer to the evbuffer
249 size_t evbuffer_get_contiguous_space(const struct evbuffer *buf);
252   Expands the available space in an evbuffer.
254   Expands the available space in the evbuffer to at least datlen, so that
257   @param buf the evbuffer to be expanded
262 int evbuffer_expand(struct evbuffer *buf, size_t datlen);
265    Reserves space in the last chain or chains of an evbuffer.
267    Makes space available in the last chain or chains of an evbuffer that can
286    @param buf the evbuffer in which to reserve space.
299 evbuffer_reserve_space(struct evbuffer *buf, ev_ssize_t size,
317    @param buf the evbuffer in which to reserve space.
324 int evbuffer_commit_space(struct evbuffer *buf,
328   Append data to the end of an evbuffer.
330   @param buf the evbuffer to be appended to
336 int evbuffer_add(struct evbuffer *buf, const void *data, size_t datlen);
340   Read data from an evbuffer and drain the bytes read.
342   If more bytes are requested than are available in the evbuffer, we
345   @param buf the evbuffer to be read from
351 int evbuffer_remove(struct evbuffer *buf, void *data, size_t datlen);
354   Read data from an evbuffer, and leave the buffer unchanged.
356   If more bytes are requested than are available in the evbuffer, we
359   @param buf the evbuffer to be read from
365 ev_ssize_t evbuffer_copyout(struct evbuffer *buf, void *data_out, size_t datlen);
368   Read data from the middle of an evbuffer, and leave the buffer unchanged.
370   If more bytes are requested than are available in the evbuffer, we
373   @param buf the evbuffer to be read from
380 ev_ssize_t evbuffer_copyout_from(struct evbuffer *buf, const struct evbuffer_ptr *pos, void *data_out, size_t datlen);
383   Read data from an evbuffer into another evbuffer, draining
390   @param src the evbuffer to be read from
391   @param dst the destination evbuffer to store the result into
396 int evbuffer_remove_buffer(struct evbuffer *src, struct evbuffer *dst,
424  * Read a single line from an evbuffer.
430  * @param buffer the evbuffer to read from
438 char *evbuffer_readln(struct evbuffer *buffer, size_t *n_read_out,
442   Move all data from one evbuffer into another evbuffer.
454 int evbuffer_add_buffer(struct evbuffer *outbuf, struct evbuffer *inbuf);
457   Copy data from one evbuffer into another evbuffer.
470 int evbuffer_add_buffer_reference(struct evbuffer *outbuf,
471     struct evbuffer *inbuf);
474    A cleanup function for a piece of memory added to an evbuffer by
483   Reference memory into an evbuffer without copying.
493 	referenced by this evbuffer.
498 int evbuffer_add_reference(struct evbuffer *outbuf,
503   Copy data from a file into the evbuffer for writing to a socket.
527 int evbuffer_add_file(struct evbuffer *outbuf, int fd, ev_off_t offset,
532   possibly the whole file! -- for use in writing from an evbuffer to a
536   evbuffer.
543     evbuffer, the underlying fd is closed.
556    evbuffer by any means other than writing it to the network: the sendfile
564    evbuffer it is added to may ever be accessed from more than one thread
570    A cleanup function for a evbuffer_file_segment added to an evbuffer
578    file and sending it out via an evbuffer.
583    The file descriptor must not be closed so long as any evbuffer is using
587    function that reads bytes from an evbuffer on any evbuffer containing
624    Insert some or all of an evbuffer_file_segment at the end of an evbuffer
630    segment to an evbuffer, the offset is _within the segment_ and the
639    @param buf the evbuffer to append to
646 int evbuffer_add_file_segment(struct evbuffer *buf,
650   Append a formatted string to the end of an evbuffer.
654   @param buf the evbuffer that will be appended to
662 int evbuffer_add_printf(struct evbuffer *buf, const char *fmt, ...)
669   Append a va_list formatted string to the end of an evbuffer.
671   @param buf the evbuffer that will be appended to
677 int evbuffer_add_vprintf(struct evbuffer *buf, const char *fmt, va_list ap)
685   Remove a specified number of bytes data from the beginning of an evbuffer.
687   @param buf the evbuffer to be drained
692 int evbuffer_drain(struct evbuffer *buf, size_t len);
696   Write the contents of an evbuffer to a file descriptor.
698   The evbuffer will be drained after the bytes have been successfully written.
700   @param buffer the evbuffer to be written and drained
706 int evbuffer_write(struct evbuffer *buffer, evutil_socket_t fd);
709   Write some of the contents of an evbuffer to a file descriptor.
711   The evbuffer will be drained after the bytes have been successfully written.
713   @param buffer the evbuffer to be written and drained
721 int evbuffer_write_atmost(struct evbuffer *buffer, evutil_socket_t fd,
725   Read from a file descriptor and store the result in an evbuffer.
727   @param buffer the evbuffer to store the result
734 int evbuffer_read(struct evbuffer *buffer, evutil_socket_t fd, int howmuch);
737    Search for a string within an evbuffer.
739    @param buffer the evbuffer to be searched
748 struct evbuffer_ptr evbuffer_search(struct evbuffer *buffer, const char *what, size_t len, const struct evbuffer_ptr *start);
751    Search for a string within part of an evbuffer.
753    @param buffer the evbuffer to be searched
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);
794    @param buffer the evbuffer to be search
802 evbuffer_ptr_set(struct evbuffer *buffer, struct evbuffer_ptr *ptr,
806    Search for an end-of-line string within an evbuffer.
808    @param buffer the evbuffer to be searched
820 struct evbuffer_ptr evbuffer_search_eol(struct evbuffer *buffer,
824 /** Function to peek at data inside an evbuffer without removing it or
835     @param buffer the evbuffer to peek into,
853 int evbuffer_peek(struct evbuffer *buffer, ev_ssize_t len,
858 /** Structure passed to an evbuffer_cb_func evbuffer callback
863 	/** The number of bytes in this evbuffer when callbacks were last
873     removed from an evbuffer.
875     An evbuffer may have one or more callbacks set at a time.  The order
891 typedef void (*evbuffer_cb_func)(struct evbuffer *buffer, const struct evbuffer_cb_info *info, void *arg);
894 /** Add a new callback to an evbuffer.
899   @param buffer the evbuffer to be monitored
900   @param cb the callback function to invoke when the evbuffer is modified,
906 struct evbuffer_cb_entry *evbuffer_add_cb(struct evbuffer *buffer, evbuffer_cb_func cb, void *cbarg);
908 /** Remove a callback from an evbuffer, given a handle returned from
917 int evbuffer_remove_cb_entry(struct evbuffer *buffer,
920 /** Remove a callback from an evbuffer, given the function and argument
927 int evbuffer_remove_cb(struct evbuffer *buffer, evbuffer_cb_func cb, void *cbarg);
938     @param buffer the evbuffer that the callback is watching.
944 int evbuffer_cb_set_flags(struct evbuffer *buffer,
949     @param buffer the evbuffer that the callback is watching.
955 int evbuffer_cb_clear_flags(struct evbuffer *buffer,
969 void evbuffer_cb_suspend(struct evbuffer *buffer, struct evbuffer_cb_entry *cb);
979 void evbuffer_cb_unsuspend(struct evbuffer *buffer, struct evbuffer_cb_entry *cb);
983   Makes the data at the beginning of an evbuffer contiguous.
985   @param buf the evbuffer to make contiguous
993 unsigned char *evbuffer_pullup(struct evbuffer *buf, ev_ssize_t size);
996   Prepends data to the beginning of the evbuffer
998   @param buf the evbuffer to which to prepend data
1005 int evbuffer_prepend(struct evbuffer *buf, const void *data, size_t size);
1008   Prepends all data from the src evbuffer to the beginning of the dst
1009   evbuffer.
1011   @param dst the evbuffer to which to prepend data
1012   @param src the evbuffer to prepend; it will be emptied as a result
1016 int evbuffer_prepend_buffer(struct evbuffer *dst, struct evbuffer* src);
1019    Prevent calls that modify an evbuffer from succeeding. A buffer may
1033 int evbuffer_freeze(struct evbuffer *buf, int at_front);
1035    Re-enable calls that modify an evbuffer.
1043 int evbuffer_unfreeze(struct evbuffer *buf, int at_front);
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.
1054 int evbuffer_defer_callbacks(struct evbuffer *buffer, struct event_base *base);
1057   Append data from 1 or more iovec's to an evbuffer
1070 size_t evbuffer_add_iovec(struct evbuffer * buffer, struct evbuffer_iovec * vec, int n_vec);