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