Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
rpoll(l)			BEGEMOT	Library			      rpoll(l)

       rpoll - callback	functions for file descriptors and timers

       # include <rpoll.h>

       typedef void (*poll_f)(int fd, int mask,	void *arg);
       typedef void (*timer_f)(int tid,	void *arg);

       int poll_register(int fd, poll_f	func, void *arg, int mask);

       void poll_unregister(int	handle);

       int poll_start_timer(u_int msecs, int repeat, timer_f func,
	    void *arg);

       void poll_stop_timer(int	handle);

       void poll_dispatch(int wait);

       Many  programs  need  to	read from several file descriptors at the same
       time.  Typically	in these programs one  of  select(3c)  or  poll(2)  is
       used.   These  calls  are however clumsy	to use and the usage of	one of
       these calls is probably not portable to other systems - not all systems
       support both calls.

       The rpoll(l) family of functions	is designed to overcome	these restric-
       tions.  They support the	well known and understood technique  of	 event
       driven  programing and, in addition to select(3c) and poll(2) also sup-
       port timers.

       Each event on a file descriptor or each timer event is translated  into
       a  call to a user defined callback function. These functions need to be
       registered.  A file descriptor is registered with poll_register.	 fd is
       the  file  descriptor  to  watch, mask is an event mask.	 It may	be any
       combination of POLL_IN to get informed, when input on the file descrip-
       tor  is	possible, POLL_OUT to get informed, when output	is possible or
       POLL_EXCEPT to get informed, when an exceptional	condition occures.  An
       example	of  an	exceptional  condition	is the arrival of urgent data.
       (Note, that an end of file condition is signaled	via POLL_IN).  func is
       the  user function to be	called and arg is a user supplied argument for
       this function.  The callback functions is called	with the file descrip-
       tor,  a mask describing the actual events (from the set supplied	in the
       registration) and the user argument.  poll_register returns  a  handle,
       which may be used later to de-register the file descriptor.  A file de-
       scriptor	may be registered more than once, if the  function,  the  user
       arguments or both differ	in the call to poll_register.  If func and arg
       are the same, then no new registration is done, instead the event  mask
       of the registration is changed to reflect the new mask.

       A  registered  file descriptor may be de-registered by calling poll_un-
       register	with the handle	returned by poll_register.

       A timer is created with poll_start_timer.  msecs	is the number of  mil-
       liseconds,  after  which	the timer event	will be	generated.  repeat se-
       lects one-short behavior	(if 0) or a repeatable timer  (if  not	0).  A
       one-short  timer	will automatically unregistered	after expiry.  func is
       the user	function which will be called with a timer  id	and  the  user
       supplied	 arg.  poll_start_timer	returnes a timer id, which may be used
       to cancel the timer with	poll_stop_timer.  A one-short timer should  be
       canceled	only if	it has not yet fired.

       poll_dispatch  must  be	called to actually dispatch events.  wait is a
       flag, which should be 0,	if only	a poll should be done. In  this	 case,
       the function returns, after polling the registered file descriptors and
       timers. If wait is not 0, poll_dispatch waits until an  event  occures.
       All  events are dispatch	(i.e. callback functions called) and poll_dis-
       patch returns.

       Typical use is:



       poll_register and poll_start_timer return a handle which	may be used to
       unregister the file descriptor or cancel	the timer.

       Both  functions	and  poll_dispatch  call  xrealloc(l)  and  can	end in

       System call or memory allocation	errors are fatal  and  are  handle  by
       calling	panic(l).   The	 one  exception	 is a return of	EINTR from se-
       lect(3c)	or poll(2) in poll_dispatch.  In this case poll_dispatch  sim-
       ply returns.

       Obscure	sequences  of poll_start_timer and poll_stop_timer in callback
       functions may probably break the	code.

       The semantics of	POLL_EXCEPT are	not clear.

       Hartmut Brandt,

BEGEMOT				  21 Oct 1996			      rpoll(l)


Want to link to this manual page? Use this URL:

home | help