3
* Copyright (c) 2002-2006, Jouni Malinen <j@w1.fi>
5
* This program is free software; you can redistribute it and/or modify
6
* it under the terms of the GNU General Public License version 2 as
7
* published by the Free Software Foundation.
9
* Alternatively, this software may be distributed under the terms of BSD
12
* See README and COPYING for more details.
14
* This file defines an event loop interface that supports processing events
15
* from registered timeouts (i.e., do something after N seconds), sockets
16
* (e.g., a new packet available for reading), and signals. eloop.c is an
17
* implementation of this interface using select() and sockets. This is
18
* suitable for most UNIX/POSIX systems. When porting to other operating
19
* systems, it may be necessary to replace that implementation with OS specific
27
* ELOOP_ALL_CTX - eloop_cancel_timeout() magic number to match all timeouts
29
#define ELOOP_ALL_CTX (void *) -1
32
* eloop_event_type - eloop socket event type for eloop_register_sock()
33
* @EVENT_TYPE_READ: Socket has data available for reading
34
* @EVENT_TYPE_WRITE: Socket has room for new data to be written
35
* @EVENT_TYPE_EXCEPTION: An exception has been reported
44
* eloop_sock_handler - eloop socket event callback type
45
* @sock: File descriptor number for the socket
46
* @eloop_ctx: Registered callback context data (eloop_data)
47
* @sock_ctx: Registered callback context data (user_data)
49
typedef void (*eloop_sock_handler)(int sock, void *eloop_ctx, void *sock_ctx);
52
* eloop_event_handler - eloop generic event callback type
53
* @eloop_ctx: Registered callback context data (eloop_data)
54
* @sock_ctx: Registered callback context data (user_data)
56
typedef void (*eloop_event_handler)(void *eloop_data, void *user_ctx);
59
* eloop_timeout_handler - eloop timeout event callback type
60
* @eloop_ctx: Registered callback context data (eloop_data)
61
* @sock_ctx: Registered callback context data (user_data)
63
typedef void (*eloop_timeout_handler)(void *eloop_data, void *user_ctx);
66
* eloop_signal_handler - eloop signal event callback type
68
* @eloop_ctx: Registered callback context data (global user_data from
70
* @signal_ctx: Registered callback context data (user_data from
71
* eloop_register_signal(), eloop_register_signal_terminate(), or
72
* eloop_register_signal_reconfig() call)
74
typedef void (*eloop_signal_handler)(int sig, void *eloop_ctx,
78
* eloop_init() - Initialize global event loop data
79
* @user_data: Pointer to global data passed as eloop_ctx to signal handlers
80
* Returns: 0 on success, -1 on failure
82
* This function must be called before any other eloop_* function. user_data
83
* can be used to configure a global (to the process) pointer that will be
84
* passed as eloop_ctx parameter to signal handlers.
86
int eloop_init(void *user_data);
89
* eloop_register_read_sock - Register handler for read events
90
* @sock: File descriptor number for the socket
91
* @handler: Callback function to be called when data is available for reading
92
* @eloop_data: Callback context data (eloop_ctx)
93
* @user_data: Callback context data (sock_ctx)
94
* Returns: 0 on success, -1 on failure
96
* Register a read socket notifier for the given file descriptor. The handler
97
* function will be called whenever data is available for reading from the
98
* socket. The handler function is responsible for clearing the event after
99
* having processed it in order to avoid eloop from calling the handler again
100
* for the same event.
102
int eloop_register_read_sock(int sock, eloop_sock_handler handler,
103
void *eloop_data, void *user_data);
106
* eloop_unregister_read_sock - Unregister handler for read events
107
* @sock: File descriptor number for the socket
109
* Unregister a read socket notifier that was previously registered with
110
* eloop_register_read_sock().
112
void eloop_unregister_read_sock(int sock);
115
* eloop_register_sock - Register handler for socket events
116
* @sock: File descriptor number for the socket
117
* @type: Type of event to wait for
118
* @handler: Callback function to be called when the event is triggered
119
* @eloop_data: Callback context data (eloop_ctx)
120
* @user_data: Callback context data (sock_ctx)
121
* Returns: 0 on success, -1 on failure
123
* Register an event notifier for the given socket's file descriptor. The
124
* handler function will be called whenever the that event is triggered for the
125
* socket. The handler function is responsible for clearing the event after
126
* having processed it in order to avoid eloop from calling the handler again
127
* for the same event.
129
int eloop_register_sock(int sock, eloop_event_type type,
130
eloop_sock_handler handler,
131
void *eloop_data, void *user_data);
134
* eloop_unregister_sock - Unregister handler for socket events
135
* @sock: File descriptor number for the socket
136
* @type: Type of event for which sock was registered
138
* Unregister a socket event notifier that was previously registered with
139
* eloop_register_sock().
141
void eloop_unregister_sock(int sock, eloop_event_type type);
144
* eloop_register_event - Register handler for generic events
145
* @event: Event to wait (eloop implementation specific)
146
* @event_size: Size of event data
147
* @handler: Callback function to be called when event is triggered
148
* @eloop_data: Callback context data (eloop_data)
149
* @user_data: Callback context data (user_data)
150
* Returns: 0 on success, -1 on failure
152
* Register an event handler for the given event. This function is used to
153
* register eloop implementation specific events which are mainly targetted for
154
* operating system specific code (driver interface and l2_packet) since the
155
* portable code will not be able to use such an OS-specific call. The handler
156
* function will be called whenever the event is triggered. The handler
157
* function is responsible for clearing the event after having processed it in
158
* order to avoid eloop from calling the handler again for the same event.
160
* In case of Windows implementation (eloop_win.c), event pointer is of HANDLE
161
* type, i.e., void*. The callers are likely to have 'HANDLE h' type variable,
162
* and they would call this function with eloop_register_event(h, sizeof(h),
165
int eloop_register_event(void *event, size_t event_size,
166
eloop_event_handler handler,
167
void *eloop_data, void *user_data);
170
* eloop_unregister_event - Unregister handler for a generic event
171
* @event: Event to cancel (eloop implementation specific)
172
* @event_size: Size of event data
174
* Unregister a generic event notifier that was previously registered with
175
* eloop_register_event().
177
void eloop_unregister_event(void *event, size_t event_size);
180
* eloop_register_timeout - Register timeout
181
* @secs: Number of seconds to the timeout
182
* @usecs: Number of microseconds to the timeout
183
* @handler: Callback function to be called when timeout occurs
184
* @eloop_data: Callback context data (eloop_ctx)
185
* @user_data: Callback context data (sock_ctx)
186
* Returns: 0 on success, -1 on failure
188
* Register a timeout that will cause the handler function to be called after
191
int eloop_register_timeout(unsigned int secs, unsigned int usecs,
192
eloop_timeout_handler handler,
193
void *eloop_data, void *user_data);
196
* eloop_cancel_timeout - Cancel timeouts
197
* @handler: Matching callback function
198
* @eloop_data: Matching eloop_data or %ELOOP_ALL_CTX to match all
199
* @user_data: Matching user_data or %ELOOP_ALL_CTX to match all
200
* Returns: Number of cancelled timeouts
202
* Cancel matching <handler,eloop_data,user_data> timeouts registered with
203
* eloop_register_timeout(). ELOOP_ALL_CTX can be used as a wildcard for
204
* cancelling all timeouts regardless of eloop_data/user_data.
206
int eloop_cancel_timeout(eloop_timeout_handler handler,
207
void *eloop_data, void *user_data);
210
* eloop_register_signal - Register handler for signals
211
* @sig: Signal number (e.g., SIGHUP)
212
* @handler: Callback function to be called when the signal is received
213
* @user_data: Callback context data (signal_ctx)
214
* Returns: 0 on success, -1 on failure
216
* Register a callback function that will be called when a signal is received.
217
* The callback function is actually called only after the system signal
218
* handler has returned. This means that the normal limits for sighandlers
219
* (i.e., only "safe functions" allowed) do not apply for the registered
222
* Signals are 'global' events and there is no local eloop_data pointer like
223
* with other handlers. The global user_data pointer registered with
224
* eloop_init() will be used as eloop_ctx for signal handlers.
226
int eloop_register_signal(int sig, eloop_signal_handler handler,
230
* eloop_register_signal_terminate - Register handler for terminate signals
231
* @handler: Callback function to be called when the signal is received
232
* @user_data: Callback context data (signal_ctx)
233
* Returns: 0 on success, -1 on failure
235
* Register a callback function that will be called when a process termination
236
* signal is received. The callback function is actually called only after the
237
* system signal handler has returned. This means that the normal limits for
238
* sighandlers (i.e., only "safe functions" allowed) do not apply for the
239
* registered callback.
241
* Signals are 'global' events and there is no local eloop_data pointer like
242
* with other handlers. The global user_data pointer registered with
243
* eloop_init() will be used as eloop_ctx for signal handlers.
245
* This function is a more portable version of eloop_register_signal() since
246
* the knowledge of exact details of the signals is hidden in eloop
247
* implementation. In case of operating systems using signal(), this function
248
* registers handlers for SIGINT and SIGTERM.
250
int eloop_register_signal_terminate(eloop_signal_handler handler,
254
* eloop_register_signal_reconfig - Register handler for reconfig signals
255
* @handler: Callback function to be called when the signal is received
256
* @user_data: Callback context data (signal_ctx)
257
* Returns: 0 on success, -1 on failure
259
* Register a callback function that will be called when a reconfiguration /
260
* hangup signal is received. The callback function is actually called only
261
* after the system signal handler has returned. This means that the normal
262
* limits for sighandlers (i.e., only "safe functions" allowed) do not apply
263
* for the registered callback.
265
* Signals are 'global' events and there is no local eloop_data pointer like
266
* with other handlers. The global user_data pointer registered with
267
* eloop_init() will be used as eloop_ctx for signal handlers.
269
* This function is a more portable version of eloop_register_signal() since
270
* the knowledge of exact details of the signals is hidden in eloop
271
* implementation. In case of operating systems using signal(), this function
272
* registers a handler for SIGHUP.
274
int eloop_register_signal_reconfig(eloop_signal_handler handler,
278
* eloop_run - Start the event loop
280
* Start the event loop and continue running as long as there are any
281
* registered event handlers. This function is run after event loop has been
282
* initialized with event_init() and one or more events have been registered.
284
void eloop_run(void);
287
* eloop_terminate - Terminate event loop
289
* Terminate event loop even if there are registered events. This can be used
290
* to request the program to be terminated cleanly.
292
void eloop_terminate(void);
295
* eloop_destroy - Free any resources allocated for the event loop
297
* After calling eloop_destroy(), other eloop_* functions must not be called
298
* before re-running eloop_init().
300
void eloop_destroy(void);
303
* eloop_terminated - Check whether event loop has been terminated
304
* Returns: 1 = event loop terminate, 0 = event loop still running
306
* This function can be used to check whether eloop_terminate() has been called
307
* to request termination of the event loop. This is normally used to abort
308
* operations that may still be queued to be run when eloop_terminate() was
311
int eloop_terminated(void);
314
* eloop_wait_for_read_sock - Wait for a single reader
315
* @sock: File descriptor number for the socket
317
* Do a blocking wait for a single read socket.
319
void eloop_wait_for_read_sock(int sock);
322
* eloop_get_user_data - Get global user data
323
* Returns: user_data pointer that was registered with eloop_init()
325
void * eloop_get_user_data(void);
added
removed
eloop.h
