poll_register man page on FreeBSD

Man page or keyword search:  
man Server   9747 pages
apropos Keyword Search (all sections)
Output format
FreeBSD logo
[printable version]

rpoll(3)			BEGEMOT Library			      rpoll(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);

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

       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 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:

	      while(1)
		   poll_dispatch(1);

SEE ALSO
       poll(2),select(3C)

RETURN VALUES
       poll_register  , poll_start_timer and poll_start_utimer 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				  8 Dec 2006			      rpoll(3)
[top]

List of man pages available for FreeBSD

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
...................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net