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