I would appreciate any donations. Wishlist or send e-mail type donations to maekawa AT daemon-systems.org.

Thank you.


event2/bufferevent.h(3)    Library Functions Manual    event2/bufferevent.h(3)



NAME
       event2/bufferevent.h - Functions for buffering data for network sending
       or receiving.


SYNOPSIS
       #include <event2/visibility.h>
       #include <event2/event-config.h>
       #include <event2/util.h>


   Data Structures
           struct bufferevent
           An opaque type for handling buffered IO.

   Macros
           #define EV_RATE_LIMIT_MAX   EV_SSIZE_MAX
           Maximum configurable rate- or burst-limit.

       Bufferevent event codes
       These flags are passed as arguments to a bufferevent's event callback.

               #define BEV_EVENT_READING   0x01
               error encountered while reading  #define BEV_EVENT_WRITING
               0x02
               error encountered while writing  #define BEV_EVENT_EOF   0x10
               eof file reached  #define BEV_EVENT_ERROR   0x20
               unrecoverable error encountered  #define BEV_EVENT_TIMEOUT
               0x40
               user-specified timeout reached  #define BEV_EVENT_CONNECTED
               0x80
               connect operation finished.

   Typedefs
           typedef void(* bufferevent_data_cb) (struct bufferevent *bev, void
           *ctx)
           A read or write callback for a bufferevent.  typedef void(*
           bufferevent_event_cb) (struct bufferevent *bev, short what, void
           *ctx)
           An event/error callback for a bufferevent.

   Enumerations
           enum bufferevent_flush_mode { BEV_NORMAL = 0, BEV_FLUSH = 1,
           BEV_FINISHED = 2 } Flags that can be passed into filters to let
           them know how to deal with the incoming data. "
           enum bufferevent_options { BEV_OPT_CLOSE_ON_FREE = (1<<0),
           BEV_OPT_THREADSAFE = (1<<1), BEV_OPT_DEFER_CALLBACKS = (1<<2),
           BEV_OPT_UNLOCK_CALLBACKS = (1<<3) } Options that can be specified
           when creating a bufferevent. "
           enum bufferevent_trigger_options { BEV_TRIG_IGNORE_WATERMARKS =
           (1<<16), BEV_TRIG_DEFER_CALLBACKS = BEV_OPT_DEFER_CALLBACKS } Flags
           for bufferevent_trigger(_event) that modify when and how to trigger
           the callback. "

   Functions
           EVENT2_EXPORT_SYMBOL int bufferevent_add_to_rate_limit_group
           (struct bufferevent *bev, struct bufferevent_rate_limit_group *g)
           Add 'bev' to the list of bufferevents whose aggregate reading and
           writing is restricted by 'g'.  EVENT2_EXPORT_SYMBOL int
           bufferevent_base_set (struct event_base *base, struct bufferevent
           *bufev)
           Assign a bufferevent to a specific event_base.
           EVENT2_EXPORT_SYMBOL int bufferevent_decref (struct bufferevent
           *bufev)
           Public interface to manually decrement the reference count of a
           bufferevent.  EVENT2_EXPORT_SYMBOL int bufferevent_disable (struct
           bufferevent *bufev, short event)
           Disable a bufferevent.  EVENT2_EXPORT_SYMBOL int bufferevent_enable
           (struct bufferevent *bufev, short event)
           Enable a bufferevent.  EVENT2_EXPORT_SYMBOL int bufferevent_flush
           (struct bufferevent *bufev, short iotype, enum
           bufferevent_flush_mode mode)
           Triggers the bufferevent to produce more data if possible.
           EVENT2_EXPORT_SYMBOL void bufferevent_free (struct bufferevent
           *bufev)
           Deallocate the storage associated with a bufferevent structure.
           EVENT2_EXPORT_SYMBOL struct event_base * bufferevent_get_base
           (struct bufferevent *bev)
           Return the event_base used by a bufferevent.  EVENT2_EXPORT_SYMBOL
           short bufferevent_get_enabled (struct bufferevent *bufev)
           Return the events that are enabled on a given bufferevent.
           EVENT2_EXPORT_SYMBOL struct evbuffer * bufferevent_get_input
           (struct bufferevent *bufev)
           Returns the input buffer.  EVENT2_EXPORT_SYMBOL ev_ssize_t
           bufferevent_get_max_single_read (struct bufferevent *bev)
           Get the current size limit for single read operation.
           EVENT2_EXPORT_SYMBOL ev_ssize_t bufferevent_get_max_single_write
           (struct bufferevent *bev)
           Get the current size limit for single write operation.
           EVENT2_EXPORT_SYMBOL ev_ssize_t bufferevent_get_max_to_read (struct
           bufferevent *bev)
           EVENT2_EXPORT_SYMBOL ev_ssize_t bufferevent_get_max_to_write
           (struct bufferevent *bev)
           EVENT2_EXPORT_SYMBOL struct evbuffer * bufferevent_get_output
           (struct bufferevent *bufev)
           Returns the output buffer.  EVENT2_EXPORT_SYMBOL int
           bufferevent_get_priority (const struct bufferevent *bufev)
           Return the priority of a bufferevent.  EVENT2_EXPORT_SYMBOL const
           struct ev_token_bucket_cfg * bufferevent_get_token_bucket_cfg
           (const struct bufferevent *bev)
           EVENT2_EXPORT_SYMBOL struct bufferevent *
           bufferevent_get_underlying (struct bufferevent *bufev)
           Returns the underlying bufferevent associated with a bufferevent
           (if the bufferevent is a wrapper), or NULL if there is no
           underlying bufferevent.  EVENT2_EXPORT_SYMBOL void
           bufferevent_getcb (struct bufferevent *bufev, bufferevent_data_cb
           *readcb_ptr, bufferevent_data_cb *writecb_ptr, bufferevent_event_cb
           *eventcb_ptr, void **cbarg_ptr)
           Retrieves the callbacks for a bufferevent.  EVENT2_EXPORT_SYMBOL
           evutil_socket_t bufferevent_getfd (struct bufferevent *bufev)
           Returns the file descriptor associated with a bufferevent, or -1 if
           no file descriptor is associated with the bufferevent.
           EVENT2_EXPORT_SYMBOL int bufferevent_getwatermark (struct
           bufferevent *bufev, short events, size_t *lowmark, size_t
           *highmark)
           Retrieves the watermarks for read or write events.
           EVENT2_EXPORT_SYMBOL void bufferevent_incref (struct bufferevent
           *bufev)
           Public interface to manually increase the reference count of a
           bufferevent this is useful in situations where a user may reference
           the bufferevent somewhere eles (unknown to libevent)
           EVENT2_EXPORT_SYMBOL void bufferevent_lock (struct bufferevent
           *bufev)
           Acquire the lock on a bufferevent.  EVENT2_EXPORT_SYMBOL struct
           bufferevent * bufferevent_pair_get_partner (struct bufferevent
           *bev)
           Given one bufferevent returned by bufferevent_pair_new(), returns
           the other one if it still exists.  EVENT2_EXPORT_SYMBOL int
           bufferevent_pair_new (struct event_base *base, int options, struct
           bufferevent *pair[2])
           Allocate a pair of linked bufferevents.  EVENT2_EXPORT_SYMBOL int
           bufferevent_priority_set (struct bufferevent *bufev, int pri)
           Assign a priority to a bufferevent.  EVENT2_EXPORT_SYMBOL void
           bufferevent_rate_limit_group_free (struct
           bufferevent_rate_limit_group *)
           Free a rate-limiting group.  EVENT2_EXPORT_SYMBOL void
           bufferevent_rate_limit_group_get_totals (struct
           bufferevent_rate_limit_group *grp, ev_uint64_t *total_read_out,
           ev_uint64_t *total_written_out)
           Inspect the total bytes read/written on a group.
           EVENT2_EXPORT_SYMBOL struct bufferevent_rate_limit_group *
           bufferevent_rate_limit_group_new (struct event_base *base, const
           struct ev_token_bucket_cfg *cfg)
           Create a new rate-limit group for bufferevents.
           EVENT2_EXPORT_SYMBOL void bufferevent_rate_limit_group_reset_totals
           (struct bufferevent_rate_limit_group *grp)
           Reset the total bytes read/written on a group.
           EVENT2_EXPORT_SYMBOL int bufferevent_rate_limit_group_set_cfg
           (struct bufferevent_rate_limit_group *, const struct
           ev_token_bucket_cfg *)
           Change the rate-limiting settings for a given rate-limiting group.
           EVENT2_EXPORT_SYMBOL int bufferevent_rate_limit_group_set_min_share
           (struct bufferevent_rate_limit_group *, size_t)
           Change the smallest quantum we're willing to allocate to any single
           bufferevent in a group for reading or writing at a time.
           EVENT2_EXPORT_SYMBOL size_t bufferevent_read (struct bufferevent
           *bufev, void *data, size_t size)
           Read data from a bufferevent buffer.  EVENT2_EXPORT_SYMBOL int
           bufferevent_read_buffer (struct bufferevent *bufev, struct evbuffer
           *buf)
           Read data from a bufferevent buffer into an evbuffer.
           EVENT2_EXPORT_SYMBOL int bufferevent_remove_from_rate_limit_group
           (struct bufferevent *bev)
           Remove 'bev' from its current rate-limit group (if any).
           EVENT2_EXPORT_SYMBOL int bufferevent_set_max_single_read (struct
           bufferevent *bev, size_t size)
           Set the size limit for single read operation.  EVENT2_EXPORT_SYMBOL
           int bufferevent_set_max_single_write (struct bufferevent *bev,
           size_t size)
           Set the size limit for single write operation.
           EVENT2_EXPORT_SYMBOL int bufferevent_set_rate_limit (struct
           bufferevent *bev, struct ev_token_bucket_cfg *cfg)
           Set the rate-limit of a the bufferevent 'bev' to the one specified
           in 'cfg'.  EVENT2_EXPORT_SYMBOL int bufferevent_set_timeouts
           (struct bufferevent *bufev, const struct timeval *timeout_read,
           const struct timeval *timeout_write)
           Set the read and write timeout for a bufferevent.
           EVENT2_EXPORT_SYMBOL void bufferevent_setcb (struct bufferevent
           *bufev, bufferevent_data_cb readcb, bufferevent_data_cb writecb,
           bufferevent_event_cb eventcb, void *cbarg)
           Changes the callbacks for a bufferevent.  EVENT2_EXPORT_SYMBOL int
           bufferevent_setfd (struct bufferevent *bufev, evutil_socket_t fd)
           Changes the file descriptor on which the bufferevent operates.
           EVENT2_EXPORT_SYMBOL void bufferevent_setwatermark (struct
           bufferevent *bufev, short events, size_t lowmark, size_t highmark)
           Sets the watermarks for read and write events.
           EVENT2_EXPORT_SYMBOL int bufferevent_socket_connect (struct
           bufferevent *, const struct sockaddr *, int)
           Launch a connect() attempt with a socket-based bufferevent.
           EVENT2_EXPORT_SYMBOL int bufferevent_socket_connect_hostname
           (struct bufferevent *, struct evdns_base *, int, const char *, int)
           Resolve the hostname 'hostname' and connect to it as with
           bufferevent_socket_connect().  EVENT2_EXPORT_SYMBOL int
           bufferevent_socket_get_dns_error (struct bufferevent *bev)
           Return the error code for the last failed DNS lookup attempt made
           by bufferevent_socket_connect_hostname().  EVENT2_EXPORT_SYMBOL
           struct bufferevent * bufferevent_socket_new (struct event_base
           *base, evutil_socket_t fd, int options)
           Create a new socket bufferevent over an existing socket.
           EVENT2_EXPORT_SYMBOL void bufferevent_trigger (struct bufferevent
           *bufev, short iotype, int options)
           Triggers bufferevent data callbacks.  EVENT2_EXPORT_SYMBOL void
           bufferevent_trigger_event (struct bufferevent *bufev, short what,
           int options)
           Triggers the bufferevent event callback.  EVENT2_EXPORT_SYMBOL void
           bufferevent_unlock (struct bufferevent *bufev)
           Release the lock on a bufferevent.  EVENT2_EXPORT_SYMBOL int
           bufferevent_write (struct bufferevent *bufev, const void *data,
           size_t size)
           Write data to a bufferevent buffer.  EVENT2_EXPORT_SYMBOL int
           bufferevent_write_buffer (struct bufferevent *bufev, struct
           evbuffer *buf)
           Write data from an evbuffer to a bufferevent buffer.
           EVENT2_EXPORT_SYMBOL void ev_token_bucket_cfg_free (struct
           ev_token_bucket_cfg *cfg)
           Free all storage held in 'cfg'.  EVENT2_EXPORT_SYMBOL struct
           ev_token_bucket_cfg * ev_token_bucket_cfg_new (size_t read_rate,
           size_t read_burst, size_t write_rate, size_t write_burst, const
           struct timeval *tick_len)
           Initialize and return a new object to configure the rate-limiting
           behavior of bufferevents.

       Rate limit inspection
       Return the current read or write bucket size for a bufferevent.

       If it is not configured with a per-bufferevent ratelimit, return
       EV_SSIZE_MAX. This function does not inspect the group limit, if any.
       Note that it can return a negative value if the bufferevent has been
       made to read or write more than its limit.

               EVENT2_EXPORT_SYMBOL ev_ssize_t bufferevent_get_read_limit
               (struct bufferevent *bev)
               EVENT2_EXPORT_SYMBOL ev_ssize_t bufferevent_get_write_limit
               (struct bufferevent *bev)

       Group Rate limit inspection
       Return the read or write bucket size for a bufferevent rate limit
       group.

       Note that it can return a negative value if bufferevents in the group
       have been made to read or write more than their limits.

               EVENT2_EXPORT_SYMBOL ev_ssize_t
               bufferevent_rate_limit_group_get_read_limit (struct
               bufferevent_rate_limit_group *)
               EVENT2_EXPORT_SYMBOL ev_ssize_t
               bufferevent_rate_limit_group_get_write_limit (struct
               bufferevent_rate_limit_group *)

       Rate limit manipulation
       Subtract a number of bytes from a bufferevent's read or write bucket.

       The decrement value can be negative, if you want to manually refill the
       bucket. If the change puts the bucket above or below zero, the
       bufferevent will resume or suspend reading writing as appropriate.
       These functions make no change in the buckets for the bufferevent's
       group, if any.

       Returns 0 on success, -1 on internal error.

               EVENT2_EXPORT_SYMBOL int bufferevent_decrement_read_limit
               (struct bufferevent *bev, ev_ssize_t decr)
               EVENT2_EXPORT_SYMBOL int bufferevent_decrement_write_limit
               (struct bufferevent *bev, ev_ssize_t decr)

       Group rate limit manipulation
       Subtract a number of bytes from a bufferevent rate-limiting group's
       read or write bucket.

       The decrement value can be negative, if you want to manually refill the
       bucket. If the change puts the bucket above or below zero, the
       bufferevents in the group will resume or suspend reading writing as
       appropriate.

       Returns 0 on success, -1 on internal error.

               EVENT2_EXPORT_SYMBOL int
               bufferevent_rate_limit_group_decrement_read (struct
               bufferevent_rate_limit_group *, ev_ssize_t)
               EVENT2_EXPORT_SYMBOL int
               bufferevent_rate_limit_group_decrement_write (struct
               bufferevent_rate_limit_group *, ev_ssize_t)

   Filtering support
           enum bufferevent_filter_result { BEV_OK = 0, BEV_NEED_MORE = 1,
           BEV_ERROR = 2 } Values that filters can return. "
           typedef enum bufferevent_filter_result(* bufferevent_filter_cb)
           (struct evbuffer *src, struct evbuffer *dst, ev_ssize_t dst_limit,
           enum bufferevent_flush_mode mode, void *ctx)
           A callback function to implement a filter for a bufferevent.
           EVENT2_EXPORT_SYMBOL struct bufferevent * bufferevent_filter_new
           (struct bufferevent *underlying, bufferevent_filter_cb
           input_filter, bufferevent_filter_cb output_filter, int options,
           void(*free_context)(void *), void *ctx)
           Allocate a new filtering bufferevent on top of an existing
           bufferevent.

Detailed Description
       Functions for buffering data for network sending or receiving.

       Bufferevents are higher level than evbuffers: each has an underlying
       evbuffer for reading and one for writing, and callbacks that are
       invoked under certain circumstances.

       A bufferevent provides input and output buffers that get filled and
       drained automatically. The user of a bufferevent no longer deals
       directly with the I/O, but instead is reading from input and writing to
       output buffers.

       Once initialized, the bufferevent structure can be used repeatedly with
       bufferevent_enable() and bufferevent_disable().

       When reading is enabled, the bufferevent will try to read from the file
       descriptor onto its input buffer, and call the read callback. When
       writing is enabled, the bufferevent will try to write data onto its
       file descriptor when the output buffer has enough data, and call the
       write callback when the output buffer is sufficiently drained.

       Bufferevents come in several flavors, including:

       Socket-based bufferevents
          A bufferevent that reads and writes data onto a network socket.
          Created with bufferevent_socket_new().

       Paired bufferevents
          A pair of bufferevents that send and receive data to one another
          without touching the network. Created with bufferevent_pair_new().

       Filtering bufferevents
          A bufferevent that transforms data, and sends or receives it over
          another underlying bufferevent. Created with
          bufferevent_filter_new().

       SSL-backed bufferevents
          A bufferevent that uses the openssl library to send and receive data
          over an encrypted connection. Created with
          bufferevent_openssl_socket_new() or
          bufferevent_openssl_filter_new().


Macro Definition Documentation
   #define BEV_EVENT_CONNECTED   0x80
       connect operation finished.

   #define EV_RATE_LIMIT_MAX   EV_SSIZE_MAX
       Maximum configurable rate- or burst-limit.

Typedef Documentation
   typedef void(* bufferevent_data_cb) (struct bufferevent *bev, void *ctx)
       A read or write callback for a bufferevent. The read callback is
       triggered when new data arrives in the input buffer and the amount of
       readable data exceed the low watermark which is 0 by default.

       The write callback is triggered if the write buffer has been exhausted
       or fell below its low watermark.

       Parameters:
           bev the bufferevent that triggered the callback
           ctx the user-specified context for this bufferevent


   typedef void(* bufferevent_event_cb) (struct bufferevent *bev, short what,
       void *ctx)
       An event/error callback for a bufferevent. The event callback is
       triggered if either an EOF condition or another unrecoverable error was
       encountered.

       For bufferevents with deferred callbacks, this is a bitwise OR of all
       errors that have happened on the bufferevent since the last callback
       invocation.

       Parameters:
           bev the bufferevent for which the error condition was reached
           what a conjunction of flags: BEV_EVENT_READING or BEV_EVENT_WRITING
           to indicate if the error was encountered on the read or write path,
           and one of the following flags: BEV_EVENT_EOF, BEV_EVENT_ERROR,
           BEV_EVENT_TIMEOUT, BEV_EVENT_CONNECTED.
           ctx the user-specified context for this bufferevent


   typedef enum bufferevent_filter_result(* bufferevent_filter_cb) (struct
       evbuffer *src, struct evbuffer *dst, ev_ssize_t dst_limit, enum
       bufferevent_flush_mode mode, void *ctx)
       A callback function to implement a filter for a bufferevent.

       Parameters:
           src An evbuffer to drain data from.
           dst An evbuffer to add data to.
           limit A suggested upper bound of bytes to write to dst. The filter
           may ignore this value, but doing so means that it will overflow the
           high-water mark associated with dst. -1 means 'no limit'.
           mode Whether we should write data as may be convenient
           (BEV_NORMAL), or flush as much data as we can (BEV_FLUSH), or flush
           as much as we can, possibly including an end-of-stream marker
           (BEV_FINISH).
           ctx A user-supplied pointer.

       Returns:
           BEV_OK if we wrote some data; BEV_NEED_MORE if we can't produce any
           more output until we get some input; and BEV_ERROR on an error.


Enumeration Type Documentation
   enum bufferevent_filter_result
       Values that filters can return.

       Enumerator

       BEV_OK
              everything is okay

       BEV_NEED_MORE
              the filter needs to read more data before output

       BEV_ERROR
              the filter encountered a critical error, no further data can be
              processed.

   enum bufferevent_flush_mode
       Flags that can be passed into filters to let them know how to deal with
       the incoming data.

       Enumerator

       BEV_NORMAL
              usually set when processing data

       BEV_FLUSH
              want to checkpoint all data sent.

       BEV_FINISHED
              encountered EOF on read or done sending data

   enum bufferevent_options
       Options that can be specified when creating a bufferevent.

       Enumerator

       BEV_OPT_CLOSE_ON_FREE
              If set, we close the underlying file
              descriptor/bufferevent/whatever when this bufferevent is freed.

       BEV_OPT_THREADSAFE
              If set, and threading is enabled, operations on this bufferevent
              are protected by a lock.

       BEV_OPT_DEFER_CALLBACKS
              If set, callbacks are run deferred in the event loop.

       BEV_OPT_UNLOCK_CALLBACKS
              If set, callbacks are executed without locks being held on the
              bufferevent. This option currently requires that
              BEV_OPT_DEFER_CALLBACKS also be set; a future version of
              Libevent might remove the requirement.

   enum bufferevent_trigger_options
       Flags for bufferevent_trigger(_event) that modify when and how to
       trigger the callback.

       Enumerator

       BEV_TRIG_IGNORE_WATERMARKS
              trigger the callback regardless of the watermarks

       BEV_TRIG_DEFER_CALLBACKS
              defer even if the callbacks are not

Function Documentation
   EVENT2_EXPORT_SYMBOL int bufferevent_add_to_rate_limit_group (struct
       bufferevent * bev, struct bufferevent_rate_limit_group * g)
       Add 'bev' to the list of bufferevents whose aggregate reading and
       writing is restricted by 'g'. If 'g' is NULL, remove 'bev' from its
       current group.

       A bufferevent may belong to no more than one rate-limit group at a
       time. If 'bev' is already a member of a group, it will be removed from
       its old group before being added to 'g'.

       Return 0 on success and -1 on failure.

   EVENT2_EXPORT_SYMBOL int bufferevent_base_set (struct event_base * base,
       struct bufferevent * bufev)
       Assign a bufferevent to a specific event_base. NOTE that only socket
       bufferevents support this function.

       Parameters:
           base an event_base returned by event_init()
           bufev a bufferevent struct returned by bufferevent_new() or
           bufferevent_socket_new()

       Returns:
           0 if successful, or -1 if an error occurred

       See also:
           bufferevent_new()


   EVENT2_EXPORT_SYMBOL int bufferevent_decref (struct bufferevent * bufev)
       Public interface to manually decrement the reference count of a
       bufferevent. Warning: make sure you know what you're doing. This is
       mainly used in conjunction with bufferevent_incref(). This will free up
       all data associated with a bufferevent if the reference count hits 0.

       Parameters:
           bufev the bufferevent to decrement the refcount on

       Returns:
           1 if the bufferevent was freed, otherwise 0 (still referenced)


   EVENT2_EXPORT_SYMBOL int bufferevent_disable (struct bufferevent * bufev,
       short event)
       Disable a bufferevent.

       Parameters:
           bufev the bufferevent to be disabled
           event any combination of EV_READ | EV_WRITE.

       Returns:
           0 if successful, or -1 if an error occurred

       See also:
           bufferevent_enable()


   EVENT2_EXPORT_SYMBOL int bufferevent_enable (struct bufferevent * bufev,
       short event)
       Enable a bufferevent.

       Parameters:
           bufev the bufferevent to be enabled
           event any combination of EV_READ | EV_WRITE.

       Returns:
           0 if successful, or -1 if an error occurred

       See also:
           bufferevent_disable()


   EVENT2_EXPORT_SYMBOL struct bufferevent* bufferevent_filter_new (struct
       bufferevent * underlying, bufferevent_filter_cb input_filter,
       bufferevent_filter_cb output_filter, int options, void(*)(void *)
       free_context, void * ctx)
       Allocate a new filtering bufferevent on top of an existing bufferevent.

       Parameters:
           underlying the underlying bufferevent.
           input_filter The filter to apply to data we read from the
           underlying bufferevent
           output_filter The filer to apply to data we write to the underlying
           bufferevent
           options A bitfield of bufferevent options.
           free_context A function to use to free the filter context when this
           bufferevent is freed.
           ctx A context pointer to pass to the filter functions.


   EVENT2_EXPORT_SYMBOL int bufferevent_flush (struct bufferevent * bufev,
       short iotype, enum bufferevent_flush_mode mode)
       Triggers the bufferevent to produce more data if possible.

       Parameters:
           bufev the bufferevent object
           iotype either EV_READ or EV_WRITE or both.
           mode either BEV_NORMAL or BEV_FLUSH or BEV_FINISHED

       Returns:
           -1 on failure, 0 if no data was produces, 1 if data was produced


   EVENT2_EXPORT_SYMBOL void bufferevent_free (struct bufferevent * bufev)
       Deallocate the storage associated with a bufferevent structure. If
       there is pending data to write on the bufferevent, it probably won't be
       flushed before the bufferevent is freed.

       Parameters:
           bufev the bufferevent structure to be freed.


   EVENT2_EXPORT_SYMBOL short bufferevent_get_enabled (struct bufferevent *
       bufev)
       Return the events that are enabled on a given bufferevent.

       Parameters:
           bufev the bufferevent to inspect

       Returns:
           A combination of EV_READ | EV_WRITE


   EVENT2_EXPORT_SYMBOL struct evbuffer* bufferevent_get_input (struct
       bufferevent * bufev)
       Returns the input buffer. The user MUST NOT set the callback on this
       buffer.

       Parameters:
           bufev the bufferevent from which to get the evbuffer

       Returns:
           the evbuffer object for the input buffer


   EVENT2_EXPORT_SYMBOL ev_ssize_t bufferevent_get_max_single_read (struct
       bufferevent * bev)
       Get the current size limit for single read operation.

   EVENT2_EXPORT_SYMBOL ev_ssize_t bufferevent_get_max_single_write (struct
       bufferevent * bev)
       Get the current size limit for single write operation.

   EVENT2_EXPORT_SYMBOL struct evbuffer* bufferevent_get_output (struct
       bufferevent * bufev)
       Returns the output buffer. The user MUST NOT set the callback on this
       buffer.

       When filters are being used, the filters need to be manually triggered
       if the output buffer was manipulated.

       Parameters:
           bufev the bufferevent from which to get the evbuffer

       Returns:
           the evbuffer object for the output buffer


   EVENT2_EXPORT_SYMBOL int bufferevent_get_priority (const struct bufferevent
       * bufev)
       Return the priority of a bufferevent. Only supported for socket
       bufferevents

   EVENT2_EXPORT_SYMBOL void bufferevent_getcb (struct bufferevent * bufev,
       bufferevent_data_cb * readcb_ptr, bufferevent_data_cb * writecb_ptr,
       bufferevent_event_cb * eventcb_ptr, void ** cbarg_ptr)
       Retrieves the callbacks for a bufferevent.

       Parameters:
           bufev the bufferevent to examine.
           readcb_ptr if readcb_ptr is nonnull, *readcb_ptr is set to the
           current read callback for the bufferevent.
           writecb_ptr if writecb_ptr is nonnull, *writecb_ptr is set to the
           current write callback for the bufferevent.
           eventcb_ptr if eventcb_ptr is nonnull, *eventcb_ptr is set to the
           current event callback for the bufferevent.
           cbarg_ptr if cbarg_ptr is nonnull, *cbarg_ptr is set to the current
           callback argument for the bufferevent.

       See also:
           buffervent_setcb()


   EVENT2_EXPORT_SYMBOL int bufferevent_getwatermark (struct bufferevent *
       bufev, short events, size_t * lowmark, size_t * highmark)
       Retrieves the watermarks for read or write events. Returns non-zero if
       events contains not only EV_READ or EV_WRITE. Returns zero if events
       equal EV_READ or EV_WRITE

       Parameters:
           bufev the bufferevent to be examined
           events EV_READ or EV_WRITE
           lowmark receives the lower watermark if not NULL
           highmark receives the high watermark if not NULL


   EVENT2_EXPORT_SYMBOL void bufferevent_incref (struct bufferevent * bufev)
       Public interface to manually increase the reference count of a
       bufferevent this is useful in situations where a user may reference the
       bufferevent somewhere eles (unknown to libevent)

       Parameters:
           bufev the bufferevent to increase the refcount on


   EVENT2_EXPORT_SYMBOL void bufferevent_lock (struct bufferevent * bufev)
       Acquire the lock on a bufferevent. Has no effect if locking was not
       enabled with BEV_OPT_THREADSAFE.

   EVENT2_EXPORT_SYMBOL struct bufferevent* bufferevent_pair_get_partner
       (struct bufferevent * bev)
       Given one bufferevent returned by bufferevent_pair_new(), returns the
       other one if it still exists. Otherwise returns NULL.

   EVENT2_EXPORT_SYMBOL int bufferevent_pair_new (struct event_base * base,
       int options, struct bufferevent * pair[2])
       Allocate a pair of linked bufferevents. The bufferevents behave as
       would two bufferevent_sock instances connected to opposite ends of a
       socketpair(), except that no internal socketpair is allocated.

       Parameters:
           base The event base to associate with the socketpair.
           options A set of options for this bufferevent
           pair A pointer to an array to hold the two new bufferevent objects.

       Returns:
           0 on success, -1 on failure.


   EVENT2_EXPORT_SYMBOL int bufferevent_priority_set (struct bufferevent *
       bufev, int pri)
       Assign a priority to a bufferevent. Only supported for socket
       bufferevents.

       Parameters:
           bufev a bufferevent struct
           pri the priority to be assigned

       Returns:
           0 if successful, or -1 if an error occurred


   EVENT2_EXPORT_SYMBOL void bufferevent_rate_limit_group_free (struct
       bufferevent_rate_limit_group *)
       Free a rate-limiting group. The group must have no members when this
       function is called.

   EVENT2_EXPORT_SYMBOL void bufferevent_rate_limit_group_get_totals (struct
       bufferevent_rate_limit_group * grp, ev_uint64_t * total_read_out,
       ev_uint64_t * total_written_out)
       Inspect the total bytes read/written on a group. Set the variable
       pointed to by total_read_out to the total number of bytes ever read on
       grp, and the variable pointed to by total_written_out to the total
       number of bytes ever written on grp.

   EVENT2_EXPORT_SYMBOL struct bufferevent_rate_limit_group*
       bufferevent_rate_limit_group_new (struct event_base * base, const
       struct ev_token_bucket_cfg * cfg)
       Create a new rate-limit group for bufferevents. A rate-limit group
       constrains the maximum number of bytes sent and received, in toto, by
       all of its bufferevents.

       Parameters:
           base An event_base to run any necessary timeouts for the group.
           Note that all bufferevents in the group do not necessarily need to
           share this event_base.
           cfg The rate-limit for this group.

       Note that all rate-limits hare are currently best-effort: future
       versions of Libevent may implement them more tightly.

       Note also that only some bufferevent types currently respect rate-
       limiting. They are: socket-based bufferevents (normal and IOCP-based),
       and SSL-based bufferevents.

   EVENT2_EXPORT_SYMBOL void bufferevent_rate_limit_group_reset_totals (struct
       bufferevent_rate_limit_group * grp)
       Reset the total bytes read/written on a group. Reset the number of
       bytes read or written on grp as given by
       bufferevent_rate_limit_group_reset_totals().

   EVENT2_EXPORT_SYMBOL int bufferevent_rate_limit_group_set_cfg (struct
       bufferevent_rate_limit_group *, const struct ev_token_bucket_cfg *)
       Change the rate-limiting settings for a given rate-limiting group.
       Return 0 on success, -1 on failure.

   EVENT2_EXPORT_SYMBOL int bufferevent_rate_limit_group_set_min_share (struct
       bufferevent_rate_limit_group *, size_t)
       Change the smallest quantum we're willing to allocate to any single
       bufferevent in a group for reading or writing at a time. The rationale
       is that, because of TCP/IP protocol overheads and kernel behavior, if a
       rate-limiting group is so tight on bandwidth that you're only willing
       to send 1 byte per tick per bufferevent, you might instead want to
       batch up the reads and writes so that you send N bytes per 1/N of the
       bufferevents (chosen at random) each tick, so you still wind up send 1
       byte per tick per bufferevent on average, but you don't send so many
       tiny packets.

       The default min-share is currently 64 bytes.

       Returns 0 on success, -1 on faulre.

   EVENT2_EXPORT_SYMBOL size_t bufferevent_read (struct bufferevent * bufev,
       void * data, size_t size)
       Read data from a bufferevent buffer. The bufferevent_read() function is
       used to read data from the input buffer.

       Parameters:
           bufev the bufferevent to be read from
           data pointer to a buffer that will store the data
           size the size of the data buffer, in bytes

       Returns:
           the amount of data read, in bytes.


   EVENT2_EXPORT_SYMBOL int bufferevent_read_buffer (struct bufferevent *
       bufev, struct evbuffer * buf)
       Read data from a bufferevent buffer into an evbuffer. This avoids
       memory copies.

       Parameters:
           bufev the bufferevent to be read from
           buf the evbuffer to which to add data

       Returns:
           0 if successful, or -1 if an error occurred.


   EVENT2_EXPORT_SYMBOL int bufferevent_remove_from_rate_limit_group (struct
       bufferevent * bev)
       Remove 'bev' from its current rate-limit group (if any).

   EVENT2_EXPORT_SYMBOL int bufferevent_set_max_single_read (struct
       bufferevent * bev, size_t size)
       Set the size limit for single read operation. Set to 0 for a reasonable
       default.

       Return 0 on success and -1 on failure.

   EVENT2_EXPORT_SYMBOL int bufferevent_set_max_single_write (struct
       bufferevent * bev, size_t size)
       Set the size limit for single write operation. Set to 0 for a
       reasonable default.

       Return 0 on success and -1 on failure.

   EVENT2_EXPORT_SYMBOL int bufferevent_set_rate_limit (struct bufferevent *
       bev, struct ev_token_bucket_cfg * cfg)
       Set the rate-limit of a the bufferevent 'bev' to the one specified in
       'cfg'. If 'cfg' is NULL, disable any per-bufferevent rate-limiting on
       'bev'.

       Note that only some bufferevent types currently respect rate-limiting.
       They are: socket-based bufferevents (normal and IOCP-based), and SSL-
       based bufferevents.

       Return 0 on sucess, -1 on failure.

   EVENT2_EXPORT_SYMBOL int bufferevent_set_timeouts (struct bufferevent *
       bufev, const struct timeval * timeout_read, const struct timeval *
       timeout_write)
       Set the read and write timeout for a bufferevent. A bufferevent's
       timeout will fire the first time that the indicated amount of time has
       elapsed since a successful read or write operation, during which the
       bufferevent was trying to read or write.

       (In other words, if reading or writing is disabled, or if the
       bufferevent's read or write operation has been suspended because
       there's no data to write, or not enough banwidth, or so on, the timeout
       isn't active. The timeout only becomes active when we we're willing to
       actually read or write.)

       Calling bufferevent_enable or setting a timeout for a bufferevent whose
       timeout is already pending resets its timeout.

       If the timeout elapses, the corresponding operation (EV_READ or
       EV_WRITE) becomes disabled until you re-enable it again. The
       bufferevent's event callback is called with the
       BEV_EVENT_TIMEOUT|BEV_EVENT_READING or
       BEV_EVENT_TIMEOUT|BEV_EVENT_WRITING.

       Parameters:
           bufev the bufferevent to be modified
           timeout_read the read timeout, or NULL
           timeout_write the write timeout, or NULL


   EVENT2_EXPORT_SYMBOL void bufferevent_setcb (struct bufferevent * bufev,
       bufferevent_data_cb readcb, bufferevent_data_cb writecb,
       bufferevent_event_cb eventcb, void * cbarg)
       Changes the callbacks for a bufferevent.

       Parameters:
           bufev the bufferevent object for which to change callbacks
           readcb callback to invoke when there is data to be read, or NULL if
           no callback is desired
           writecb callback to invoke when the file descriptor is ready for
           writing, or NULL if no callback is desired
           eventcb callback to invoke when there is an event on the file
           descriptor
           cbarg an argument that will be supplied to each of the callbacks
           (readcb, writecb, and errorcb)

       See also:
           bufferevent_new()


   EVENT2_EXPORT_SYMBOL int bufferevent_setfd (struct bufferevent * bufev,
       evutil_socket_t fd)
       Changes the file descriptor on which the bufferevent operates. Not
       supported for all bufferevent types.

       Parameters:
           bufev the bufferevent object for which to change the file
           descriptor
           fd the file descriptor to operate on


   EVENT2_EXPORT_SYMBOL void bufferevent_setwatermark (struct bufferevent *
       bufev, short events, size_t lowmark, size_t highmark)
       Sets the watermarks for read and write events. On input, a bufferevent
       does not invoke the user read callback unless there is at least low
       watermark data in the buffer. If the read buffer is beyond the high
       watermark, the bufferevent stops reading from the network.

       On output, the user write callback is invoked whenever the buffered
       data falls below the low watermark. Filters that write to this bufev
       will try not to write more bytes to this buffer than the high watermark
       would allow, except when flushing.

       Parameters:
           bufev the bufferevent to be modified
           events EV_READ, EV_WRITE or both
           lowmark the lower watermark to set
           highmark the high watermark to set


   EVENT2_EXPORT_SYMBOL int bufferevent_socket_connect (struct bufferevent *,
       const struct sockaddr *, int)
       Launch a connect() attempt with a socket-based bufferevent. When the
       connect succeeds, the eventcb will be invoked with BEV_EVENT_CONNECTED
       set.

       If the bufferevent does not already have a socket set, we allocate a
       new socket here and make it nonblocking before we begin.

       If no address is provided, we assume that the socket is already
       connecting, and configure the bufferevent so that a BEV_EVENT_CONNECTED
       event will be yielded when it is done connecting.

       Parameters:
           bufev an existing bufferevent allocated with
           bufferevent_socket_new().
           addr the address we should connect to
           socklen The length of the address

       Returns:
           0 on success, -1 on failure.


   EVENT2_EXPORT_SYMBOL int bufferevent_socket_connect_hostname (struct
       bufferevent *, struct evdns_base *, int, const char *, int)
       Resolve the hostname 'hostname' and connect to it as with
       bufferevent_socket_connect().

       Parameters:
           bufev An existing bufferevent allocated with
           bufferevent_socket_new()
           evdns_base Optionally, an evdns_base to use for resolving hostnames
           asynchronously. May be set to NULL for a blocking resolve.
           family A preferred address family to resolve addresses to, or
           AF_UNSPEC for no preference. Only AF_INET, AF_INET6, and AF_UNSPEC
           are supported.
           hostname The hostname to resolve; see below for notes on recognized
           formats
           port The port to connect to on the resolved address.

       Returns:
           0 if successful, -1 on failure.

       Recognized hostname formats are:

       www.example.com (hostname)
       1.2.3.4     (ipv4address)
       ::1     (ipv6address)
       [::1]       ([ipv6address])


       Performance note: If you do not provide an evdns_base, this function
       may block while it waits for a DNS response. This is probably not what
       you want.

   EVENT2_EXPORT_SYMBOL int bufferevent_socket_get_dns_error (struct
       bufferevent * bev)
       Return the error code for the last failed DNS lookup attempt made by
       bufferevent_socket_connect_hostname().

       Parameters:
           bev The bufferevent object.

       Returns:
           DNS error code.

       See also:
           evutil_gai_strerror()


   EVENT2_EXPORT_SYMBOL struct bufferevent* bufferevent_socket_new (struct
       event_base * base, evutil_socket_t fd, int options)
       Create a new socket bufferevent over an existing socket.

       Parameters:
           base the event base to associate with the new bufferevent.
           fd the file descriptor from which data is read and written to. This
           file descriptor is not allowed to be a pipe(2). It is safe to set
           the fd to -1, so long as you later set it with bufferevent_setfd or
           bufferevent_socket_connect().
           options Zero or more BEV_OPT_* flags

       Returns:
           a pointer to a newly allocated bufferevent struct, or NULL if an
           error occurred

       See also:
           bufferevent_free()


   EVENT2_EXPORT_SYMBOL void bufferevent_trigger (struct bufferevent * bufev,
       short iotype, int options)
       Triggers bufferevent data callbacks. The function will honor watermarks
       unless options contain BEV_TRIG_IGNORE_WATERMARKS. If the options
       contain BEV_OPT_DEFER_CALLBACKS, the callbacks are deferred.

       Parameters:
           bufev the bufferevent object
           iotype either EV_READ or EV_WRITE or both.
           options


   EVENT2_EXPORT_SYMBOL void bufferevent_trigger_event (struct bufferevent *
       bufev, short what, int options)
       Triggers the bufferevent event callback. If the options contain
       BEV_OPT_DEFER_CALLBACKS, the callbacks are deferred.

       Parameters:
           bufev the bufferevent object
           what the flags to pass onto the event callback
           options


   EVENT2_EXPORT_SYMBOL void bufferevent_unlock (struct bufferevent * bufev)
       Release the lock on a bufferevent. Has no effect if locking was not
       enabled with BEV_OPT_THREADSAFE.

   EVENT2_EXPORT_SYMBOL int bufferevent_write (struct bufferevent * bufev,
       const void * data, size_t size)
       Write data to a bufferevent buffer. The bufferevent_write() function
       can be used to write data to the file descriptor. The data is appended
       to the output buffer and written to the descriptor automatically as it
       becomes available for writing.

       Parameters:
           bufev the bufferevent to be written to
           data a pointer to the data to be written
           size the length of the data, in bytes

       Returns:
           0 if successful, or -1 if an error occurred

       See also:
           bufferevent_write_buffer()


   EVENT2_EXPORT_SYMBOL int bufferevent_write_buffer (struct bufferevent *
       bufev, struct evbuffer * buf)
       Write data from an evbuffer to a bufferevent buffer. The evbuffer is
       being drained as a result.

       Parameters:
           bufev the bufferevent to be written to
           buf the evbuffer to be written

       Returns:
           0 if successful, or -1 if an error occurred

       See also:
           bufferevent_write()


   EVENT2_EXPORT_SYMBOL void ev_token_bucket_cfg_free (struct
       ev_token_bucket_cfg * cfg)
       Free all storage held in 'cfg'. Note: 'cfg' is not currently reference-
       counted; it is not safe to free it until no bufferevent is using it.

   EVENT2_EXPORT_SYMBOL struct ev_token_bucket_cfg* ev_token_bucket_cfg_new
       (size_t read_rate, size_t read_burst, size_t write_rate, size_t
       write_burst, const struct timeval * tick_len)
       Initialize and return a new object to configure the rate-limiting
       behavior of bufferevents.

       Parameters:
           read_rate The maximum number of bytes to read per tick on average.
           read_burst The maximum number of bytes to read in any single tick.
           write_rate The maximum number of bytes to write per tick on
           average.
           write_burst The maximum number of bytes to write in any single
           tick.
           tick_len The length of a single tick. Defaults to one second. Any
           fractions of a millisecond are ignored.

       Note that all rate-limits hare are currently best-effort: future
       versions of Libevent may implement them more tightly.

Author
       Generated automatically by Doxygen for libevent from the source code.



libevent                        Tue Jan 31 2017        event2/bufferevent.h(3)