1.\" $OpenBSD: event_set.3,v 1.4 2023/04/29 13:37:03 schwarze Exp $ 2.\" Copyright (c) 2023 Ted Bullock <tbullock@comore.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 29 2023 $ 17.Dt EVENT_SET 3 18.Os 19.Sh NAME 20.Nm event_set , 21.Nm evtimer_set , 22.Nm signal_set , 23.Nm event_base_set , 24.Nm event_add , 25.Nm evtimer_add , 26.Nm signal_add , 27.Nm event_del , 28.Nm evtimer_del , 29.Nm signal_del , 30.Nm event_base_once , 31.Nm event_once 32.Nd configure an event 33.Sh SYNOPSIS 34.In event.h 35.Ft void 36.Fo event_set 37.Fa "struct event *event" 38.Fa "int fd" 39.Fa "short flags" 40.Fa "void (*callback)(int, short, void *)" 41.Fa "void *arg" 42.Fc 43.Ft void 44.Fo evtimer_set 45.Fa "struct event *event" 46.Fa "void (*callback)(int, short, void *)" 47.Fa "void *arg" 48.Fc 49.Ft void 50.Fo signal_set 51.Fa "struct event *event" 52.Fa "int signal" 53.Fa "void (*callback)(int, short, void *)" 54.Fa "void *arg" 55.Fc 56.Ft int 57.Fn event_base_set "struct event_base *base" "struct event *event" 58.Ft int 59.Fn event_add "struct event *event" "const struct timeval *tv" 60.Ft int 61.Fn evtimer_add "struct event *event" "const struct timeval *tv" 62.Ft int 63.Fn signal_add "struct event *event" "const struct timeval *tv" 64.Ft int 65.Fn event_del "struct event *event" 66.Ft int 67.Fn evtimer_del "struct event *event" 68.Ft int 69.Fn signal_del "struct event *event" 70.Ft int 71.Fo event_base_once 72.Fa "struct event_base *base" 73.Fa "int fd" 74.Fa "short flags" 75.Fa "void (*callback)(int, short, void *)" 76.Fa "void *arg" 77.Fa "const struct timeval *tv" 78.Fc 79.Ft int 80.Fo event_once 81.Fa "int fd" 82.Fa "short flags" 83.Fa "void (*callback)(int, short, void *)" 84.Fa "void *arg" 85.Fa "const struct timeval *tv" 86.Fc 87.Sh DESCRIPTION 88The 89.Fn event_set 90function initializes an uninitialized, unused, 91.Fa event 92structure to monitor a file descriptor, signal, or timeout. 93Once initialized, the event can be scheduled using 94.Fn event_add . 95The event becomes activated and the 96.Fa callback 97is triggered when the file descriptor state changes, the signal arrives, 98or the timeout expires. 99Refer to 100.Xr event_base_loop 3 101for documentation on running an event loop. 102.Pp 103Arguments for 104.Fn event_set 105are as follows: 106.Bl -tag -width Ds 107.It Fa event 108The event structure to initialize. 109If 110.Fa event 111is 112.Dv NULL 113the behavior is undefined. 114.It Fa fd 115The file descriptor or signal to monitor. 116Unassociated timeout events require this set to \-1. 117.It Fa flags 118Flags indicating how to monitor events. 119Unassociated timeout events require this set to 0. 120.Bl -tag -width EV_PERSIST 121.It Dv EV_READ 122Triggered when data is available for reading from the file descriptor. 123.It Dv EV_WRITE 124Triggered when the file descriptor is ready for writing. 125Can be combined with 126.Dv EV_READ 127to indicate that the program can read from or write to the file descriptor 128without blocking. 129.It Dv EV_SIGNAL 130Refers to a signal event that is triggered when a specified signal is 131received. 132Cannot be used together with either 133.Dv EV_READ 134or 135.Dv EV_WRITE . 136.It Dv EV_PERSIST 137Indicates that the event should persist after it triggers. 138That is, it should remain active until it is removed by calling 139.Fn event_del . 140Signal events typically require this flag. 141.El 142.It Fa callback 143A user-defined function that is executed when the event triggers. 144.Pp 145.Bl -enum -width Ds -compact 146.It 147The first parameter is the file descriptor or signal to monitor. 148.It 149The second parameter is an event flag composed of at least one of 150.Dv EV_TIMEOUT , 151.Dv EV_READ , 152.Dv EV_WRITE , 153.Dv EV_SIGNAL 154and 155.Dv EV_PERSIST 156combined with a binary OR operation. 157.It 158The third parameter corresponds to a user-specified pointer passed as a 159.Vt void * . 160.El 161.It Fa arg 162User-specified pointer to pass to the 163.Fa callback 164function. 165.El 166.Pp 167There are several helper macros that make it easier to set up timeout and 168signal events in the library. 169The helper macros share a distinct naming convention. 170For example, the macros 171.Fn evtimer_set 172and 173.Fn signal_set 174are named consistently with the library function 175.Fn event_set . 176The following macro and function calls are equivalent: 177.Bd -literal -offset indent 178evtimer_set(event, callback, arg); 179event_set(event, \-1, 0, callback, arg); 180.Ed 181.Pp 182Likewise, configuring a signal event with 183.Fn signal_set 184has an equivalent call to 185.Fn event_set : 186.Bd -literal -offset indent 187signal_set(event, signal, callback, arg); 188event_set(event, signal, EV_SIGNAL|EV_PERSIST, callback, arg); 189.Ed 190.Pp 191If 192.Xr event_init 3 193was called earlier, 194.Fn event_set 195associates the 196.Fa event 197with the 198.Vt event_base 199structure it created; otherwise, the 200.Fa event 201is not associated with any 202.Vt event_base 203structure. 204If a program needs to assign an event to a specific 205.Vt event_base 206structure, it should call 207.Fn event_base_set 208after calling 209.Fn event_set . 210The first argument of 211.Fn event_base_set 212is the target 213.Vt event_base 214structure, and the second argument is the 215.Fa event 216to be reassigned. 217The behavior is undefined if either argument is 218.Dv NULL . 219Only events that have not been scheduled with 220.Fn event_add 221or corresponding helper macros or functions can be assigned to a new 222.Vt event_base 223structure. 224.Pp 225.Fn event_add 226schedules the 227.Fa event 228using the kernel notification method of its associated 229.Vt event_base 230structure; see 231.Xr event_base_new 3 232for information about kernel notification methods. 233If a timeout is specified, it is added to the event timeout list. 234Events can register as timeout events without attaching to file 235descriptors or signals. 236Programs can set the 237.Fa tv 238argument to 239.Dv NULL 240to specify that an event has no timeout. 241The behavior is undefined if the 242.Fa event 243is 244.Dv NULL 245or uninitialized. 246The effect of the macros 247.Fn evtimer_add 248and 249.Fn signal_add 250is identical to 251.Fn event_add . 252.Pp 253If 254.Fn event_add 255is called again with a new or updated timeout value before the event trigger 256is processed, the function: 257.Bl -enum 258.It 259Unschedules the existing timeout if it exists. 260.It 261Sets a new timeout starting from when the function was most recently invoked. 262.It 263Reschedules the event with the event loop. 264.El 265.Pp 266.Fn event_del 267removes the 268.Fa event 269from the event loop of its associated 270.Vt event_base 271structure. 272The behavior of the function is undefined if the 273.Fa event 274is 275.Dv NULL . 276On success, it removes the event from internal event queues and unregisters it 277with the kernel notification method. 278The function fails if the library was neither initialized with 279.Xr event_init 3 280nor was the event previously assigned to an 281.Vt event_base 282with 283.Fn event_base_set . 284The function does not free memory assigned to user-defined data structures, 285nor does it close open file descriptors. 286The effect of the macros 287.Fn evtimer_del 288and 289.Fn signal_del 290is identical to 291.Fn event_del . 292.Pp 293.Fn event_base_once 294is used to schedule a 295.Fa callback 296function to be executed exactly once without 297requiring the caller to create and manage an 298.Vt event 299structure. 300The arguments are as follows: 301.Bl -tag -width Ds 302.It Fa base 303A pointer to an 304.Vt event_base 305structure initialized by 306.Xr event_base_new 3 . 307The behavior is undefined if 308.Fa base 309is 310.Dv NULL . 311.It Fa fd 312A file descriptor to monitor. 313.It Fa flags 314.Dv EV_TIMEOUT , 315.Dv EV_READ , 316.Dv EV_WRITE , 317or 318.Dv EV_READ | EV_WRITE . 319.It Fa callback 320A user-defined function that is executed when the event triggers. 321This callback matches the same prototype and design used in 322.Fn event_set . 323.It Fa arg 324A user-specified pointer to pass to the 325.Fa callback 326function. 327.It Fa tv 328A pointer to an optional timeout 329.Vt timeval 330structure, ignored if 331.Dv NULL . 332.El 333.Pp 334.Fn event_once 335behaves similar to 336.Fn event_base_once 337and requires that the library is initialized with 338.Xr event_init 3 . 339.Pp 340To check the status of a scheduled event, refer to the 341.Xr event_pending 3 342manual page. 343If a program needs to manually trigger an event, refer to 344.Xr event_active 3 . 345.Sh RETURN VALUES 346These functions return 0 on success or \-1 on failure. 347.Pp 348.Fn event_base_set 349returns \-1 if the 350.Fa event 351has already been processed by 352.Fn event_add . 353.Pp 354.Fn event_add 355returns \-1 if a memory allocation fault occurs, 356.Va errno 357is set. 358Other internal library errors terminate the program with 359.Xr exit 3 360after reporting to the log callback (see 361.Xr event_set_log_callback 3 ) . 362.Sh ERRORS 363On failure 364.Fn event_add 365can set errno 366as follows: 367.Bl -tag -width Er 368.It Bq Er ENOMEM 369The system has insufficient memory to add the 370.Fa event 371to the event loop. 372.El 373.Sh SEE ALSO 374.Xr event_active 3 , 375.Xr event_base_loop 3 , 376.Xr event_base_new 3 , 377.Xr event_pending 3 378.Sh HISTORY 379.Fn event_set , 380.Fn event_add 381and 382.Fn event_del 383first appeared in libevent-0.1, 384.Fn signal_set , 385.Fn signal_add , 386and 387.Fn signal_del 388in libevent-0.5 , 389and 390.Fn evtimer_set , 391.Fn evtimer_add 392and 393.Fn evtimer_del 394in libevent-0.6. 395These functions have been available since 396.Ox 3.2 . 397.Pp 398.Fn event_once 399first appeared in libevent-0.8 and has been available since 400.Ox 3.6 . 401.Pp 402.Fn event_base_set 403first appeared in libevent-1.0 and has been available since 404.Ox 3.8 . 405.Pp 406.Fn event_base_once 407first appeared in libevent-1.3c and has been available since 408.Ox 4.4 . 409.Sh AUTHORS 410.An -nosplit 411.An Niels Provos 412wrote the event library and these functions except for 413.Fn event_base_once 414which was also created by 415.An Wouter Wijngaards . 416.Pp 417This manual page was written by 418.An Ted Bullock Aq Mt tbullock@comlore.com . 419