2 '\" Copyright (c)1996-2002 by Hartmut Brandt
3 '\" All rights reserved.
5 '\" Author: Hartmut Brandt
7 '\" Redistribution of this software and documentation and use in source and
8 '\" binary forms, with or without modification, are permitted provided that
9 '\" the following conditions are met:
11 '\" 1. Redistributions of source code or documentation must retain the above
12 '\" copyright notice, this list of conditions and the following disclaimer.
13 '\" 2. Redistributions in binary form must reproduce the above copyright
14 '\" notice, this list of conditions and the following disclaimer in the
15 '\" documentation and/or other materials provided with the distribution.
17 '\" THIS SOFTWARE AND DOCUMENTATION IS PROVIDED BY THE AUTHOR
18 '\" AND ITS CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
19 '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
20 '\" FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
21 '\" THE AUTHOR OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
22 '\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
23 '\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
24 '\" OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
25 '\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
26 '\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
27 '\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29 '\" $Begemot: libbegemot/rpoll.man,v 1.4 2004/09/21 15:59:00 brandt Exp $
31 .TH rpoll 3 "21 Oct 1996" "BEGEMOT" "BEGEMOT Library"
33 rpoll - callback functions for file descriptors and timers
36 .B "# include <rpoll.h>"
38 .BR "typedef void (*poll_f)(int " "fd" ", int " "mask" ", void *" "arg);"
40 .BR "typedef void (*timer_f)(int " "tid" ", void *" "arg);"
42 .BR "int poll_register(int " "fd" ", poll_f "
43 .RB "func" ", void *" "arg" ", int " "mask" ");"
45 .BR "void poll_unregister(int " "handle" ");"
47 .BR "int poll_start_timer(u_int " "msecs" ", int " "repeat" ", timer_f " "func,"
51 .BR "void poll_stop_timer(int " "handle" ");"
53 .BR "void poll_dispatch(int " "wait" ");"
55 Many programs need to read from several file descriptors at the same time.
56 Typically in these programs one of
61 These calls are however clumsy to use and the usage of one of these calls is
62 probably not portable to other systems - not all systems support both calls.
66 family of functions is designed to overcome these restrictions.
67 They support the well known and understood technique of event driven
68 programing and, in addition to
74 Each event on a file descriptor or each timer event is translated into a call to a user
75 defined callback function. These functions need to be registered.
76 A file descriptor is registered with
79 is the file descriptor to watch,
82 It may be any combination of
84 to get informed when input on the file descriptor is possible,
86 to get informed when output is possible or
88 to get informed when an exceptional condition occures.
89 An example of an exceptional condition is the arrival of urgent data.
90 (Note, that an end of file condition is signaled via POLL_IN).
92 is the user function to be called and
94 is a user supplied argument for this function.
95 The callback functions is called with the file descriptor, a mask
96 describing the actual events (from the set supplied in the registration) and
99 returns a handle, which may be used later to de-register the file descriptor.
100 A file descriptor may be registered more than once, if the function, the user arguments
101 or both differ in the call to
107 are the same, then no new registration is done, instead the event mask of the registration
108 is changed to reflect the new mask.
110 A registered file descriptor may be de-registered by calling
112 with the handle returned by
115 A timer is created with
116 .BR poll_start_timer .
118 is the number of milliseconds, after which the timer event will be generated.
120 selects one-short behavior (if 0) or a repeatable timer (if not 0). A one-short timer
121 will automatically unregistered after expiry.
123 is the user function which will be called with a timer id and the user supplied
126 returnes a timer id, which may be used to cancel the timer with
127 .BR poll_stop_timer .
128 A one-short timer should be canceled only if it has not yet fired.
131 must be called to actually dispatch events.
133 is a flag, which should be 0, if only a poll should be done. In this case, the function returns,
134 after polling the registered file descriptors and timers. If
138 waits until an event occures. All events are dispatch (i.e. callback functions called) and
139 .B poll_dispatch returns.
152 .BR poll (2), select (3C)
157 return a handle which may be used to unregister the file descriptor or cancel the timer.
166 System call or memory allocation errors are fatal and are handle by calling
168 The one exception is a return of EINTR from
182 in callback functions may probably break the code.
188 Hartmut Brandt, harti@freebsd.org