path: root/lib/libevent/event_base_new.3

.\" $OpenBSD: event_base_new.3,v 1.5 2023/04/25 17:57:55 schwarze Exp $
.\" 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: April 25 2023 $
.Dt EVENT_BASE_NEW 3
.Os
.Sh NAME
.Nm event_base_new ,
.Nm event_init ,
.Nm event_reinit ,
.Nm event_base_free
.Nd event_base structure initialization
.Sh SYNOPSIS
.In event.h
.Ft "struct event_base *"
.Fn event_base_new void
.Ft "struct event_base *"
.Fn event_init void
.Ft int
.Fn event_reinit "struct event_base *base"
.Ft void
.Fn event_base_free "struct event_base *base"
.Sh DESCRIPTION
The functions
.Fn event_base_new
and
.Fn event_init
allocate memory and initialize an opaque
.Vt event_base
structure.
This structure is used to schedule and monitor events using the operating
system's most efficient or stable kernel notification method.
.Pp
Kernel notification methods are ways for a program to be notified of
events that occur in the operating system's kernel.
Examples of such events include changes to file descriptors, file I/O
operations or network activity.
The library chooses from several methods to notify programs about events.
Each method is implemented using a system call, including
.Xr kqueue 2 ,
.Xr poll 2 ,
or
.Xr select 2 .
By default,
.Ox
uses the
.Xr kqueue 2
method.
.Pp
The function
.Fn event_init
behaves like
.Fn event_base_new ,
except it additionally saves a pointer to the returned structure
in an internal global variable.
It is designed for programs that need only one single event loop.
.Pp
If
.Fn event_init
was not invoked before using an event API function that requires it,
or if such a function is called after
.Fn event_base_free
has destroyed the structure that was returned from
.Fn event_init ,
a
.Dv NULL
pointer access occurs unless otherwise documented.
.Pp
After calling
.Xr fork 2 ,
the function
.Fn event_reinit
must be invoked to reset the event queues and any events registered with
the kernel notification method in the
.Vt event_base
structure of the child process.
The function takes a single argument, a pointer to an
.Vt event_base
structure returned by
.Fn event_init
or
.Fn event_base_new .
The behavior is undefined if
.Fa base
is
.Dv NULL .
.Pp
The
.Fn event_base_free
function releases all resources associated with an
.Vt event_base
structure and is intended to be called after the event loop has been stopped.
If
.Fa base
is not
.Dv NULL
it is a pointer returned by an earlier call to
.Fn event_base_new
or
.Fn event_init .
If
.Fn event_init
has been used and
.Fn event_base_free
is called with the
.Fa base
structure returned from
.Fn event_init
or with a
.Dv NULL
pointer argument, the structure that was returned from
.Fn event_init
is freed as usual, and the pointer to it is also deleted
from the internal global variable.
If
.Fn event_init
was not used, calling
.Fn event_base_free
with a
.Dv NULL
pointer argument triggers an
.Xr assert 3
call.
.Sh RETURN VALUES
.Fn event_base_new
and
.Fn event_init
return the newly allocated
.Vt event_base
structure.
If no kernel notification method can be initialized, both functions call
.Xr exit 3
with a status of 1 and do not return.
.Pp
On success,
.Fn event_reinit
returns 0.
If one or more events fail to reinitialize, the function returns -1.
.Pp
If the
.Xr poll 2
or
.Xr select 2
kernel notification method is used but
.Xr socketpair 2
fails, all three functions do not return but
.Xr exit 3
the program with a status of 1.
This may also happen in some cases of
.Xr malloc 3
failure.
.Sh ENVIRONMENT
Environment variables can modify the behavior of
.Fn event_base_new
and
.Fn event_init
to disable individual kernel notification methods for the returned
.Vt event_base
structure and to enable additional diagnostic reporting:
.Bl -tag -width Ds
.It Ev EVENT_NOKQUEUE
Disable support for
.Xr kqueue 2 .
.It Ev EVENT_NOPOLL
Disable support for
.Xr poll 2 .
.It Ev EVENT_NOSELECT
Disable support for
.Xr select 2 .
.It Ev EVENT_SHOW_METHOD
If the log callback is configured,
report which kernel notification method the returned
.Vt event_base
structure is using.
.El
.Pp
These environment variables work unless the library detects the program
was executed as either setuid or setgid using
.Xr issetugid 2 .
The value of the environment variables is ignored, even if it is
empty or zero.
.Sh DIAGNOSTICS
Many event library functions report error and diagnostic messages via
the log callback system that can optionally be enabled with
.Xr event_set_log_callback 3 .
.Pp
The following error messages can occur:
.Bl -tag -width Ds
.It Dq evsignal_init: socketpair: Em reason
While trying to initialize the
.Xr poll 2
or
.Xr select 2
kernel notification method in
.Fn event_base_new
or
.Fn event_init ,
.Xr socketpair 2
failed for the given
.Em reason .
.It Dq event_base_new: no event mechanism available
Each kernel notification method is either disabled via the
.Sx ENVIRONMENT ,
or trying to initialize it failed.
Some memory allocation failures may also cause this error.
.It Dq event_base_reinit: could not reinitialize event mechanism
Failed to reinitialize the kernel notification method.
.El
.Pp
In addition, all three functions may issue various error messages
indicating memory allocation failure, but not all such failures are
reported in this manner.
.Pp
The following diagnostic messages can occur:
.Bl -tag -width Ds
.It Dq libevent using: Em method
The environment variable
.Ev EVENT_SHOW_METHOD
is defined and the event library is using the given kernel notification
.Em method ,
which is either
.Qq kqueue ,
.Qq poll ,
or
.Qq select .
.It Dq kqueue: Em reason
Calling
.Xr kqueue 2
failed in
.Fn event_base_new
or
.Fn event_init
for the given
.Em reason .
Other kernel notification methods are automatically tried.
.El
.Sh ERRORS
Even when they fail, most event library functions do not explicitly set
.Xr errno 2 .
Exceptions are mentioned in individual manual pages.
.Pp
However, many event library functions call C library functions
or system calls internally that do set
.Xr errno 2
when they fail.
Consequently, many event library functions set
.Xr errno 2
in some cases of failure but not in others.
.Pp
The functions
.Fn event_base_new ,
.Fn event_init ,
and
.Fn event_reinit
may fail and set
.Va errno
for any of the errors specified for the library functions
.Xr kqueue 2
and
.Xr malloc 3 .
.Pp
The same three functions may overwrite
.Xr errno 2
even if successful, for example when one kernel notification method
fails to initialize and another succeeds, or when a disregarded
memory allocation failure occurs.
.Sh SEE ALSO
.Xr fork 2 ,
.Xr kqueue 2 ,
.Xr poll 2 ,
.Xr select 2 ,
.Xr event_base_loop 3 ,
.Xr event_set_log_callback 3
.Sh HISTORY
The
.Ox
event library is a modified version of libevent-1.4.
.Pp
The function
.Fn event_init
first appeared in libevent-0.1 and has been available since
.Ox 3.2 .
.Pp
.Fn event_base_new
and
.Fn event_reinit
first appeared in libevent-1.4.1 and have been available since
.Ox 4.8 .
.Pp
Support for environment variables first appeared in libevent-0.7a and
.Ox 3.6 .
.Sh AUTHORS
The event library and 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 .
.Sh CAVEATS
The event API is not thread safe if any
.Vt "event_base"
structure, no matter whether created using
.Fn event_base_new
or
.Fn event_init ,
is accessed by more than one thread,
unless the application program implements its own locking mechanism.