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

FreeBSD Manual Pages


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

       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);

       int poll_start_utimer(unsigned long long	usecs, int repeat,
	    timer_f func, void *arg);

       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	or  poll_start_utimer.	 msecs
       is  the	number	of milliseconds	in poll_start_timer while usecs	is the
       number of microseconds in  poll_start_utimer,  after  which  the	 timer
       event will be generated.	 If the	functions use the poll(2) system call,
       then usecs is rounded to	milliseconds and poll_start_timer  is  called.
       repeat  selects 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  and  poll_start_utimer  return  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  ,	poll_start_timer and poll_start_utimer return a	handle
       which may be used to unregister	the  file  descriptor  or  cancel  the

       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				  8 Dec	2006			      rpoll(3)


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

home | help