.\" $OpenBSD: event_base_new.3,v 1.6 2023/04/28 17:31:58 schwarze Exp $ .\" Copyright (c) 2023 Ted Bullock .\" .\" 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 28 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 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 , invoke .Fn event_reinit in the child process for each initialized .Vt event_base structure to reset the event queues and any registered events. .Pp The .Fn event_base_free function releases all resources associated with the .Fa base structure returned by an earlier call to .Fn event_base_new or .Fn event_init . It is intended to be called after the event loop has been stopped. .Pp 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 are ignored if .Xr issetugid 2 reports that the program was executed as setuid or setgid. The values of the environment variables are always ignored, even if they are 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_free first appeared in libevent-1.2 and has been available since .Ox 4.0 . .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 .Dv EVENT_NOKQUEUE first appeared in libevent-0.4 and has been available since .Ox 3.2 . Support for the other environment variables first appeared in libevent-0.7a. .Dv EVENT_NOSELECT and .Dv EVENT_SHOW_METHOD have been available since .Ox 3.4 and .Dv EVENT_NOPOLL since .Ox 3.5 . .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.