1'\"
|
2'\" Copyright (c)1996-2002 by Hartmut Brandt
|
| 2'\" Copyright (c)1996-2006 by Hartmut Brandt |
3'\" All rights reserved.
4'\"
|
5'\" Author: Hartmut Brandt
|
| 5'\" Author: harti@freebsd.org <Hartmut Brandt> |
6'\"
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:
10'\"
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.
16'\"
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.
28'\"
29'\" $Begemot: libbegemot/rpoll.man,v 1.4 2004/09/21 15:59:00 brandt Exp $
30'\"
|
31.TH rpoll 3 "21 Oct 1996" "BEGEMOT" "BEGEMOT Library"
|
| 31.TH rpoll 3 "8 Dec 2006" "BEGEMOT" "BEGEMOT Library" |
32.SH NAME
33rpoll - callback functions for file descriptors and timers
34.SH SYNOPSIS
35.LP
36.B "# include <rpoll.h>"
37.LP
|
38.BR "typedef void (*poll_f)(int " "fd" ", int " "mask" ", void *" "arg);"
|
| 38.BR "typedef void (*poll_f)(int " "fd" ", int " "mask" ", void *" "arg" ");" |
39.br
|
40.BR "typedef void (*timer_f)(int " "tid" ", void *" "arg);"
|
| 40.BR "typedef void (*timer_f)(int " "tid" ", void *" "arg" ");" |
41.LP
42.BR "int poll_register(int " "fd" ", poll_f "
43.RB "func" ", void *" "arg" ", int " "mask" ");"
44.LP
45.BR "void poll_unregister(int " "handle" ");"
46.LP
|
47.BR "int poll_start_timer(u_int " "msecs" ", int " "repeat" ", timer_f " "func,"
|
| 47.BR "int poll_start_timer(u_int " "msecs" ", int " "repeat" ", timer_f " "func" "," |
48.if n .ti +.5i
|
49.BR "void *" "arg);"
|
| 49.BR "void *" "arg" ");" |
50.LP
51.BR "void poll_stop_timer(int " "handle" ");"
52.LP
|
53.BR "int poll_start_utimer(unsigned long long " "usecs" ", int " "repeat" ",
54.if n .ti +.5i
55.BR "timer_f " "func" ", void *" "arg" ");"
56.LP |
57.BR "void poll_dispatch(int " "wait" ");"
58.SH DESCRIPTION
59Many programs need to read from several file descriptors at the same time.
60Typically in these programs one of
61.BR select (3c)
62or
63.BR poll (2)
64is used.
65These calls are however clumsy to use and the usage of one of these calls is
66probably not portable to other systems - not all systems support both calls.
67.LP
68The
69.BR rpoll (l)
70family of functions is designed to overcome these restrictions.
71They support the well known and understood technique of event driven
72programing and, in addition to
73.BR select (3c)
74and
75.BR poll (2)
76also support timers.
77.LP
78Each event on a file descriptor or each timer event is translated into a call to a user
79defined callback function. These functions need to be registered.
80A file descriptor is registered with
81.BR poll_register .
82.I fd
83is the file descriptor to watch,
84.I mask
85is an event mask.
86It may be any combination of
87.B POLL_IN
88to get informed when input on the file descriptor is possible,
89.B POLL_OUT
90to get informed when output is possible or
91.B POLL_EXCEPT
92to get informed when an exceptional condition occures.
93An example of an exceptional condition is the arrival of urgent data.
94(Note, that an end of file condition is signaled via POLL_IN).
95.I func
96is the user function to be called and
97.I arg
98is a user supplied argument for this function.
99The callback functions is called with the file descriptor, a mask
100describing the actual events (from the set supplied in the registration) and
101the user argument.
102.B poll_register
103returns a handle, which may be used later to de-register the file descriptor.
104A file descriptor may be registered more than once, if the function, the user arguments
105or both differ in the call to
106.BR poll_register .
107If
108.I func
109and
110.I arg
111are the same, then no new registration is done, instead the event mask of the registration
112is changed to reflect the new mask.
113.LP
114A registered file descriptor may be de-registered by calling
115.B poll_unregister
116with the handle returned by
117.BR poll_register .
118.LP
119A timer is created with
|
116.BR poll_start_timer .
|
120.BR poll_start_timer
121or
122.BR poll_start_utimer . |
123.I msecs
|
118is the number of milliseconds, after which the timer event will be generated.
|
124is the number of milliseconds in
125.BR poll_start_timer
126while
127.I usecs
128is the number of microseconds in
129.BR poll_start_utimer ,
130after which the timer event will be generated.
131If the functions use the
132.BR poll (2)
133system call, then
134.I usecs
135is rounded to milliseconds and
136.BR poll_start_timer
137is called. |
138.I repeat
139selects one-short behavior (if 0) or a repeatable timer (if not 0). A one-short timer
140will automatically unregistered after expiry.
141.I func
142is the user function which will be called with a timer id and the user supplied
143.IR arg .
144.B poll_start_timer
|
126returnes a timer id, which may be used to cancel the timer with
|
145and
146.B poll_start_utimer
147return a timer id, which may be used to cancel the timer with |
148.BR poll_stop_timer .
149A one-short timer should be canceled only if it has not yet fired.
150.LP
151.B poll_dispatch
152must be called to actually dispatch events.
153.I wait
154is a flag, which should be 0, if only a poll should be done. In this case, the function returns,
155after polling the registered file descriptors and timers. If
156.I wait
157is not 0,
158.B poll_dispatch
159waits until an event occures. All events are dispatch (i.e. callback functions called) and
160.B poll_dispatch returns.
161.LP
162Typical use is:
163.LP
164.RS
165.nf
166.ft 3
167while(1)
168 poll_dispatch(1);
169.ft 1
170.fi
171.RE
172.SH "SEE ALSO"
173.BR poll (2), select (3C)
174.SH "RETURN VALUES"
|
154.B poll_register
155and
|
| 175.B poll_register , |
176.B poll_start_timer
|
157return a handle which may be used to unregister the file descriptor or cancel the timer.
|
177and
178.B poll_start_utimer
179return a handle which may be used to unregister the file descriptor or
180cancel the timer. |
181.LP
182Both functions and
183.B poll_dispatch
184call
185.BR xrealloc (l)
186and can end in
187.BR panic (l).
188.SH "ERRORS"
189System call or memory allocation errors are fatal and are handle by calling
190.BR panic (l).
191The one exception is a return of EINTR from
192.BR select (3c)
193or
194.BR poll (2)
195in
196.BR poll_dispatch .
197In this case
198.B poll_dispatch
199simply returns.
200.SH "BUGS"
201Obscure sequences of
202.B poll_start_timer
203and
204.B poll_stop_timer
205in callback functions may probably break the code.
206.LP
207The semantics of
208.B POLL_EXCEPT
209are not clear.
210.SH AUTHORS
211Hartmut Brandt, harti@freebsd.org
|