-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathevent_pending.3
171 lines (171 loc) · 4.09 KB
/
event_pending.3
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
.\" $OpenBSD$
.\" 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$
.Dt EVENT_PENDING 3
.Os
.Sh NAME
.Nm event_pending ,
.Nm evtimer_pending ,
.Nm signal_pending ,
.Nm event_initialized ,
.Nm evtimer_initialized ,
.Nm signal_initialized
.Nd query status of an event
.Sh SYNOPSIS
.In event.h
.Ft int
.Fn event_pending "struct event *ev" "short events" "struct timeval *tv"
.Fd #define evtimer_pending(ev, tv)
.Fd #define signal_pending(ev, tv)
.Pp
.Fd #define event_initialized(ev)
.Fd #define evtimer_initialized(ev)
.Fd #define signal_initialized(ev)
.Sh DESCRIPTION
It is possible to query whether an event is scheduled with an event loop using
.Fn event_pending .
.Pp
An event is considered
.Sy scheduled
if any these conditions are true:
.Bl -bullet -width Ds
.It
A file descriptor or signal was configured with
.Xr event_set 3
and then registered with
.Xr event_add 3 .
.It
An expiration timeout was configured.
.It
The event is
.Sy activated
and awaiting processing.
Refer to
.Xr event_base_loop 3
for definitions of event states
.Dq Sy activated
and
.Dq Sy initialized .
.El
.Pp
This function checks whether an event was configured with
.Xr event_add 3
and, if it has a timeout, how long until that expires.
The arguments of
.Fn event_pending
are as follows:
.Bl -tag -width Ds
.It Va ev :
A pointer to the
.Vt event
structure being queried.
The behavior is undefined if
.Va ev
is
.Dv NULL .
.It Va event :
Flags matching
.Dv EV_TIMEOUT ,
.Dv EV_READ ,
.Dv EV_WRITE
or
.Dv EV_SIGNAL .
.It Va tv :
If a timeout event is being queried with
.Dv EV_TIMEOUT
and the
.Va tv
argument is not
.Dv NULL ,
the function calculates the time remaining until the timeout occurs and
store it in
.Va tv .
.El
.Pp
.Fn event_pending
causes a segmentation fault if executed without previously invoking at least
.Xr event_set 3 .
.Xr event_base_set 3
is
.Em also
required for programs initialized with
.Xr event_base_new 3 .
.Pp
Helper macros make it easier to query a timeout or signal event.
The argument
.Va ev
must be a pointer to an
.Vt event
structure.
The timeout macro
.Fn evtimer_pending
is equivalent to calling
.Fn event_pending
as follows:
.Bd -literal -offset indent
evtimer_pending(ev, tv);
event_pending(ev, EV_TIMEOUT, tv);
.Ed
.Pp
Likewise, the signal macro
.Fn signal_pending
is equivalent to calling
.Fn event_pending
as follows:
.Bd -literal -offset indent
signal_pending(ev, tv);
event_pending(ev, EV_SIGNAL, tv);
.Ed
.Pp
The macros
.Fn event_initialized ,
.Fn evtimer_initialized
and
.Fn signal_initialized
evaluate to a non-zero value indicating whether the event was initialized with
.Xr event_set 3
or not.
The behavior is undefined if
.Va ev
is
.Dv NULL .
.Sh RETURN VALUES
.Fn event_pending
returns 0 if the event is not scheduled or a non-zero bitmap comprised of the
queried event flags
.Pq Dv EV_READ , Dv EV_WRITE , Dv EV_SIGNAL or Dv EV_TIMEOUT
if it is.
.Pp
The
.Fn event_initialized
and related macros evaluate to 0 if the event is not initialized and evaluate
to a non-zero value if it is.
.Sh SEE ALSO
.Xr event_set 3
.Sh HISTORY
.Fn event_pending
first appeared in libevent-0.1 and has been available since
.Ox 3.2 .
.Pp
The helper macros first appeared in libevent-0.6 and have been available since
.Ox 3.2 .
.Sh AUTHORS
The event library, this function and set of macros were written by
.An -nosplit
.An Niels Provos .
.Pp
This manual page was written by
.An Ted Bullock Aq Mt tbullock@comlore.com .