bufferevent_new.3

.\" $OpenBSD$
.\" Copyright (c) 2023 Ted Bullock <tbullock@comlore.com>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt BUFFEREVENT_NEW 3
.Os
.Sh NAME
.Nm bufferevent_new ,
.Nm bufferevent_free ,
.Nm bufferevent_base_set ,
.Nm bufferevent_setcb
.Nd bufferevent configuration
.Sh SYNOPSIS
.In event.h
.Ft typedef void
.Fo (*evbuffercb)
.Fa "struct bufferevent *bufev"
.Fa "void *cbarg"
.Fc
.Ft typedef void
.Fo (*everrorcb)
.Fa "struct bufferevent *bufev"
.Fa "short flags"
.Fa "void *cbarg"
.Fc
.Ft struct bufferevent *
.Fo bufferevent_new
.Fa "int fd"
.Fa "evbuffercb readcb"
.Fa "evbuffercb writecb"
.Fa "everrorcb errorcb"
.Fa "void *cbarg"
.Fc
.Ft void
.Fn bufferevent_free "struct bufferevent *bufev"
.Ft int
.Fo bufferevent_base_set
.Fa "struct event_base *base"
.Fa "struct bufferevent *bufev"
.Fc
.Ft void
.Fo bufferevent_setcb
.Fa "struct bufferevent *bufev"
.Fa evbuffercb readcb
.Fa evbuffercb writecb
.Fa everrorcb errorcb
.Fa "void *cbarg"
.Fc
.Sh DESCRIPTION
The
.Sy bufferevent
API is an abstraction built on the event library's asynchronous event loop and
.Sy evbuffer
components that provides buffered reading and writing operations on a socket.
This API integrates with an event loop using an
.Vt event_base
structure and invokes optional user-defined callbacks for buffered I/O
operations.
.Pp
For each socket or file descriptor being monitored, the API requires a new
.Vt bufferevent
structure to be configured.
Each
.Vt bufferevent
maintains its own input and output buffers, as well as read, write, and error
event callbacks.
The input buffer is populated as a result of
.Dv EV_READ
operations, which are scheduled by
.Xr bufferevent_enable 3 .
Once data has been read into the input buffer, it can be retrieved by the
calling program using
.Xr bufferevent_read 3 .
.Pp
Conversely, the output buffer holds data that is to be written to the
associated file descriptor.
.Xr bufferevent_write 3
is used to add this data to the output buffer.
Once an
.Dv EV_WRITE
operation is scheduled using
.Xr bufferevent_enable 3
and activated by the event loop, the stored data is moved from the
output buffer to its destination.
This effectively drains the output buffer, preparing it for further data to be
written.
.Pp
It is advised for calling programs to define at least the read and error
callbacks to properly handle incoming data and react to errors or
disconnections.
.Pp
As discussed in
.Xr event_base_loop 3 ,
event states are categorized as
.Em initialized ,
.Em scheduled
or
.Em activated .
The bufferevent API categorizes a
.Vt bufferevent
structure into these states as follows:
.Bl -tag -width "Initialized"
.It Em Initialized
When a
.Vt bufferevent
structure is created using
.Fn bufferevent_new ,
it is in the default initialized state.
While in this state, the new structure can:
.Bl -dash
.It
Be registered to a specific
.Vt event_base
using
.Fn bufferevent_base_set .
.It
Be assigned a new file descriptor using
.Xr bufferevent_setfd 3 .
.It
Be further configured using other
.Em bufferevent_set*
functions.
.It
Have data manually appended using
.Xr bufferevent_write 3 ,
which may transition the write operations to the scheduled state if
.Xr bufferevent_enable 3
has been called for write events.
.It
Be manually drained of data using
.Xr bufferevent_read 3 .
.It
Be scheduled with the event loop for automatic I/O by using
.Xr bufferevent_enable 3 .
.It
Be deallocated by
.Fn bufferevent_free .
.El
.It Em Scheduled
When a
.Vt bufferevent
is in the scheduled state, it is registered to an event loop with an
.Vt event_base
structure and awaits activation for read or write operations.
It stays scheduled as long as there are enabled events
.Pq read or write
that are yet to be activated.
The structure can:
.Bl -dash
.It
Have data manually drained; see
.Xr bufferevent_read 3 .
.It
Be unscheduled and transitioned back to the initialized state for specific
events using
.Xr bufferevent_disable 3 .
.El
.It Em Activated
When a
.Vt bufferevent
becomes activated, it means that a read or write event has been triggered.
During this state, the read or write operations are performed as per the data
in the input or output buffers.
If there is incoming data on the file descriptor, it is read into the input
buffer and the read callback, if set, is called.
The
.Vt bufferevent
then returns to the scheduled state, ready for further reads.
.Pp
For write operations, data from the output buffer is written to the file
descriptor and the write callback, if set, is called.
If there is still data in the output buffer after the write operation, the
.Vt bufferevent
remains in the scheduled state for further write operations.
However, if all data has been written
.Pq the output buffer is empty ,
it transitions back to the initialized state for write operations.
.Pp
Both read and write operations can be in different states independently,
allowing for simultaneous reading and writing.
.El
.Pp
.Fn bufferevent_new
creates a
.Vt bufferevent
structure for I/O operations on a given file descriptor.
The function arguments are specified as follows:
.Bl -tag -width "writecb"
.It Fa fd
An open file descriptor, typically a socket set to non-blocking mode
.Dv O_NONBLOCK
with
.Xr fcntl 2 .
.It Fa readcb
.Fn evbuffercb
callback for read events.
.It Fa writecb
.Fn evbuffercb
callback for write events.
.It Fa errorcb
.Fn everrorcb
callback for error events.
.It Fa cbarg
User-defined pointer that is passed to callback functions when activated.
.El
.Pp
The callback function type
.Fn evbuffercb
is used for read and write events.
These callbacks are invoked when there is data available to read or when the
output buffer is drained.
.Fn evbuffercb
function parameters are a pointer to the
.Vt bufferevent
structure associated with the file descriptor that triggered the event, and a
user-defined pointer configured with
.Fn bufferevent_new .
.Pp
.Fn everrorcb
is a user-defined error callback function supplied to
.Fa errorcb
and activated for error events, connection closures, and timeouts.
The function parameters are:
.Bl -tag -width "8n"
.It Fa bufev
A pointer to the
.Vt bufferevent
structure associated with the file descriptor
that triggered the event.
.It Fa flags
A bitmask of flags indicating the type of event that occurred,
the possible values include:
.Bl -tag -width "EVBUFFER_TIMEOUT" -compact
.It Dv EVBUFFER_READ
The event occurred while attempting to read from the file descriptor.
.It Dv EVBUFFER_WRITE
The event occurred while attempting to write to the file descriptor.
.It Dv EVBUFFER_EOF
Indicates that the end of file or connection closure was reached during a
read or write operation.
.It Dv EVBUFFER_ERROR
Signifies that an error occurred during a read or write operation.
.It Dv EVBUFFER_TIMEOUT
Represents that a timeout occurred while waiting for a read or write operation
to complete.
.El
.It Fa cbarg
User-defined pointer configured with
.Fn bufferevent_new .
.El
.Pp
.Fn bufferevent_free
releases memory associated with a
.Vt bufferevent
structure.
The function causes undefined behavior if
.Fa bufev
is
.Dv NULL .
.Pp
.Fn bufferevent_base_set
assigns the
.Vt bufferevent
structure
.Fa bufev
to the
.Vt event_base
structure
.Fa base .
If
.Fa bufev
or
.Fa base
is
.Dv NULL ,
the function causes undefined behavior.
.Pp
If this function is not invoked, the API assumes that the event library was
initialized by
.Xr event_init 3 .
Programs using
.Xr event_base_new 3
associate the
.Vt bufferevent
with the appropriate
.Vt event_base
by calling
.Fn bufferevent_base_set .
All other bufferevent API functions, except for
.Fn bufferevent_new ,
cause a
.Dv NULL
pointer access if invoked without an initialized
.Vt event_base
structure.
.Pp
.Fn bufferevent_setcb
is used to set or update the callback functions and the user-defined argument
associated with a
.Vt bufferevent
structure
.Fa bufev .
The function arguments
.Fa readcb ,
.Fa writecb ,
.Fa errorcb
and
.Fa cbarg
are equivalent to arguments for
.Fn bufferevent_new .
.Sh RETURN VALUES
.Fn bufferevent_new
returns a pointer to a
.Vt bufferevent
data structure upon success, and returns
.Dv NULL
upon failure.
.Va errno
is preserved.
.Pp
.Fn bufferevent_base_set
returns 0 if invoked while
.Fa bufev
is in the initialized state; otherwise the value \-1 is returned.
.Sh ERRORS
On failure
.Fn bufferevent_new
preserves
.Va errno
values equivalent to
.Xr calloc 3
or
.Xr evbuffer_new 3 .
.Pp
The remaining functions do not set
.Va errno
upon failure.
.Sh SEE ALSO
.Xr bufferevent_enable 3 ,
.Xr bufferevent_priority_set 3 ,
.Xr bufferevent_read 3 ,
.Xr bufferevent_setfd 3 ,
.Xr bufferevent_settimeout 3 ,
.Xr evbuffer_new 3 ,
.Xr event_base_loop 3 ,
.Xr event_base_new 3
.Sh HISTORY
These functions first appeared in libevent-0.8 and have been available since
.Ox 3.6 .
.Sh AUTHORS
These functions were written by
.An -nosplit
.An Niels Provos .
.Pp
This manual page was written by
.An Ted Bullock Aq Mt tbullock@comlore.com .