IPnom Home • Manuals • FreeBSD

 FreeBSD Man Pages

Man Sections:Commands (1)System Calls (2)Library Functions (3)Device Drivers (4)File Formats (5)Miscellaneous (7)System Utilities (8)
Keyword Live Search (10 results max):
 Type in part of a command in the search box.
 


poll_register(3)

NAME

       rpoll - callback functions for file descriptors and timers


SYNOPSIS

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


DESCRIPTION

       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
       descriptor 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_unregister with the handle returned by poll_register.

       A timer is created with poll_start_timer.  msecs is the number of  mil-
       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:

	      while(1)
		   poll_dispatch(1);


SEE ALSO

       poll(2),select(3C)


RETURN VALUES

       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
       panic(l).


ERRORS

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


BUGS

       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.


AUTHORS

       Hartmut Brandt, harti@freebsd.org

BEGEMOT 			  21 Oct 1996			      rpoll(l)

SPONSORED LINKS




Man(1) output converted with man2html , sed , awk