1.\" $OpenBSD: event_base_new.3,v 1.6 2023/04/28 17:31:58 schwarze Exp $ 2.\" Copyright (c) 2023 Ted Bullock <tbullock@comlore.com> 3.\" 4.\" Permission to use, copy, modify, and distribute this software for any 5.\" purpose with or without fee is hereby granted, provided that the above 6.\" copyright notice and this permission notice appear in all copies. 7.\" 8.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 9.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 10.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 11.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 12.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 13.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 14.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 15.\" 16.Dd $Mdocdate: April 28 2023 $ 17.Dt EVENT_BASE_NEW 3 18.Os 19.Sh NAME 20.Nm event_base_new , 21.Nm event_init , 22.Nm event_reinit , 23.Nm event_base_free 24.Nd event_base structure initialization 25.Sh SYNOPSIS 26.In event.h 27.Ft "struct event_base *" 28.Fn event_base_new void 29.Ft "struct event_base *" 30.Fn event_init void 31.Ft int 32.Fn event_reinit "struct event_base *base" 33.Ft void 34.Fn event_base_free "struct event_base *base" 35.Sh DESCRIPTION 36The functions 37.Fn event_base_new 38and 39.Fn event_init 40allocate and initialize an opaque 41.Vt event_base 42structure. 43This structure is used to schedule and monitor events using the operating 44system's most efficient or stable kernel notification method. 45.Pp 46Kernel notification methods are ways for a program to be notified of 47events that occur in the operating system's kernel. 48Examples of such events include changes to file descriptors, file I/O 49operations or network activity. 50The library chooses from several methods to notify programs about events. 51Each method is implemented using a system call, including 52.Xr kqueue 2 , 53.Xr poll 2 , 54or 55.Xr select 2 . 56By default, 57.Ox 58uses the 59.Xr kqueue 2 60method. 61.Pp 62The function 63.Fn event_init 64behaves like 65.Fn event_base_new , 66except it additionally saves a pointer to the returned structure 67in an internal global variable. 68It is designed for programs that need only one single event loop. 69.Pp 70If 71.Fn event_init 72was not invoked before using an event API function that requires it, 73or if such a function is called after 74.Fn event_base_free 75has destroyed the structure that was returned from 76.Fn event_init , 77a 78.Dv NULL 79pointer access occurs unless otherwise documented. 80.Pp 81After calling 82.Xr fork 2 , 83invoke 84.Fn event_reinit 85in the child process for each initialized 86.Vt event_base 87structure to reset the event queues and any registered events. 88.Pp 89The 90.Fn event_base_free 91function releases all resources associated with the 92.Fa base 93structure returned by an earlier call to 94.Fn event_base_new 95or 96.Fn event_init . 97It is intended to be called after the event loop has been stopped. 98.Pp 99If 100.Fn event_init 101has been used and 102.Fn event_base_free 103is called with the 104.Fa base 105structure returned from 106.Fn event_init 107or with a 108.Dv NULL 109pointer argument, the structure that was returned from 110.Fn event_init 111is freed as usual, and the pointer to it is also deleted 112from the internal global variable. 113If 114.Fn event_init 115was not used, calling 116.Fn event_base_free 117with a 118.Dv NULL 119pointer argument triggers an 120.Xr assert 3 121call. 122.Sh RETURN VALUES 123.Fn event_base_new 124and 125.Fn event_init 126return the newly allocated 127.Vt event_base 128structure. 129If no kernel notification method can be initialized, both functions call 130.Xr exit 3 131with a status of 1 and do not return. 132.Pp 133On success, 134.Fn event_reinit 135returns 0. 136If one or more events fail to reinitialize, the function returns -1. 137.Pp 138If the 139.Xr poll 2 140or 141.Xr select 2 142kernel notification method is used but 143.Xr socketpair 2 144fails, all three functions do not return but 145.Xr exit 3 146the program with a status of 1. 147This may also happen in some cases of 148.Xr malloc 3 149failure. 150.Sh ENVIRONMENT 151Environment variables can modify the behavior of 152.Fn event_base_new 153and 154.Fn event_init 155to disable individual kernel notification methods for the returned 156.Vt event_base 157structure and to enable additional diagnostic reporting: 158.Bl -tag -width Ds 159.It Ev EVENT_NOKQUEUE 160Disable support for 161.Xr kqueue 2 . 162.It Ev EVENT_NOPOLL 163Disable support for 164.Xr poll 2 . 165.It Ev EVENT_NOSELECT 166Disable support for 167.Xr select 2 . 168.It Ev EVENT_SHOW_METHOD 169If the log callback is configured, 170report which kernel notification method the returned 171.Vt event_base 172structure is using. 173.El 174.Pp 175These environment variables are ignored if 176.Xr issetugid 2 177reports that the program was executed as setuid or setgid. 178The values of the environment variables are always ignored, even if they are 179empty or zero. 180.Sh DIAGNOSTICS 181Many event library functions report error and diagnostic messages via 182the log callback system that can optionally be enabled with 183.Xr event_set_log_callback 3 . 184.Pp 185The following error messages can occur: 186.Bl -tag -width Ds 187.It Dq evsignal_init: socketpair: Em reason 188While trying to initialize the 189.Xr poll 2 190or 191.Xr select 2 192kernel notification method in 193.Fn event_base_new 194or 195.Fn event_init , 196.Xr socketpair 2 197failed for the given 198.Em reason . 199.It Dq event_base_new: no event mechanism available 200Each kernel notification method is either disabled via the 201.Sx ENVIRONMENT , 202or trying to initialize it failed. 203Some memory allocation failures may also cause this error. 204.It Dq event_base_reinit: could not reinitialize event mechanism 205Failed to reinitialize the kernel notification method. 206.El 207.Pp 208In addition, all three functions may issue various error messages 209indicating memory allocation failure, but not all such failures are 210reported in this manner. 211.Pp 212The following diagnostic messages can occur: 213.Bl -tag -width Ds 214.It Dq libevent using: Em method 215The environment variable 216.Ev EVENT_SHOW_METHOD 217is defined and the event library is using the given kernel notification 218.Em method , 219which is either 220.Qq kqueue , 221.Qq poll , 222or 223.Qq select . 224.It Dq kqueue: Em reason 225Calling 226.Xr kqueue 2 227failed in 228.Fn event_base_new 229or 230.Fn event_init 231for the given 232.Em reason . 233Other kernel notification methods are automatically tried. 234.El 235.Sh ERRORS 236Even when they fail, most event library functions do not explicitly set 237.Xr errno 2 . 238Exceptions are mentioned in individual manual pages. 239.Pp 240However, many event library functions call C library functions 241or system calls internally that do set 242.Xr errno 2 243when they fail. 244Consequently, many event library functions set 245.Xr errno 2 246in some cases of failure but not in others. 247.Pp 248The functions 249.Fn event_base_new , 250.Fn event_init , 251and 252.Fn event_reinit 253may fail and set 254.Va errno 255for any of the errors specified for the library functions 256.Xr kqueue 2 257and 258.Xr malloc 3 . 259.Pp 260The same three functions may overwrite 261.Xr errno 2 262even if successful, for example when one kernel notification method 263fails to initialize and another succeeds, or when a disregarded 264memory allocation failure occurs. 265.Sh SEE ALSO 266.Xr fork 2 , 267.Xr kqueue 2 , 268.Xr poll 2 , 269.Xr select 2 , 270.Xr event_base_loop 3 , 271.Xr event_set_log_callback 3 272.Sh HISTORY 273The 274.Ox 275event library is a modified version of libevent-1.4. 276.Pp 277The function 278.Fn event_init 279first appeared in libevent-0.1 and has been available since 280.Ox 3.2 . 281.Pp 282.Fn event_base_free 283first appeared in libevent-1.2 and has been available since 284.Ox 4.0 . 285.Pp 286.Fn event_base_new 287and 288.Fn event_reinit 289first appeared in libevent-1.4.1 and have been available since 290.Ox 4.8 . 291.Pp 292Support for 293.Dv EVENT_NOKQUEUE 294first appeared in libevent-0.4 and has been available since 295.Ox 3.2 . 296Support for the other environment variables first appeared in libevent-0.7a. 297.Dv EVENT_NOSELECT 298and 299.Dv EVENT_SHOW_METHOD 300have been available since 301.Ox 3.4 302and 303.Dv EVENT_NOPOLL 304since 305.Ox 3.5 . 306.Sh AUTHORS 307The event library and these functions were written by 308.An -nosplit 309.An Niels Provos . 310.Pp 311This manual page was written by 312.An Ted Bullock Aq Mt tbullock@comlore.com . 313.Sh CAVEATS 314The event API is not thread safe if any 315.Vt "event_base" 316structure, no matter whether created using 317.Fn event_base_new 318or 319.Fn event_init , 320is accessed by more than one thread, 321unless the application program implements its own locking mechanism. 322