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

FreeBSD Manual Pages

  
 
  

home | help
XS_POLL(3)		     Crossroads	I/O Manual		    XS_POLL(3)

NAME
       xs_poll - input/output multiplexing

SYNOPSIS
       int xs_poll (xs_pollitem_t *items, int nitems, int timeout);

DESCRIPTION
       The xs_poll() function provides a mechanism for applications to
       multiplex input/output events in	a level-triggered fashion over a set
       of sockets. Each	member of the array pointed to by the items argument
       is a xs_pollitem_t structure. The nitems	argument specifies the number
       of items	in the items array. The	xs_pollitem_t structure	is defined as
       follows:

	   typedef struct
	   {
	       void *socket;
	       int fd;
	       short events;
	       short revents;
	   } xs_pollitem_t;

       For each	xs_pollitem_t item, xs_poll() shall examine either the
       Crossroads socket referenced by socket or the standard socket specified
       by the file descriptor fd, for the event(s) specified in	events.	If
       both socket and fd are set in a single xs_pollitem_t, the Crossroads
       socket referenced by socket shall take precedence and the value of fd
       shall be	ignored.

       For each	xs_pollitem_t item, xs_poll() shall first clear	the revents
       member, and then	indicate any requested events that have	occurred by
       setting the bit corresponding to	the event condition in the revents
       member.

       If none of the requested	events have occurred on	any xs_pollitem_t
       item, xs_poll() shall wait timeout milliseconds for an event to occur
       on any of the requested items. If the value of timeout is 0, xs_poll()
       shall return immediately. If the	value of timeout is -1,	xs_poll()
       shall block indefinitely	until a	requested event	has occurred on	at
       least one xs_pollitem_t.

       The events and revents members of xs_pollitem_t are bit masks
       constructed by OR'ing a combination of the following event flags:

       XS_POLLIN
	   For Crossroads sockets, at least one	message	may be received	from
	   the socket without blocking.	For standard sockets this is
	   equivalent to the POLLIN flag of the	poll() system call and
	   generally means that	at least one byte of data may be read from fd
	   without blocking.

       XS_POLLOUT
	   For Crossroads sockets, at least one	message	may be sent to the
	   socket without blocking. For	standard sockets this is equivalent to
	   the POLLOUT flag of the poll() system call and generally means that
	   at least one	byte of	data may be written to fd without blocking.

       XS_POLLERR
	   For standard	sockets, this flag is passed through xs_poll() to the
	   underlying poll() system call and generally means that some sort of
	   error condition is present on the socket specified by fd. For
	   Crossroads sockets this flag	has no effect if set in	events,	and
	   shall never be returned in revents by xs_poll().

	   Note
	   The xs_poll() function may be implemented or	emulated using
	   operating system interfaces other than poll(), and as such may be
	   subject to the limits of those interfaces in	ways not defined in
	   this	documentation.

RETURN VALUE
       Upon successful completion, the xs_poll() function shall	return the
       number of xs_pollitem_t structures with events signaled in revents or 0
       if no events have been signaled.	Upon failure, xs_poll()	shall return
       -1 and set errno	to one of the values defined below.

ERRORS
       ETERM
	   At least one	of the members of the items array refers to a socket
	   whose associated context was	terminated.

       EFAULT
	   The provided	items was not valid (NULL).

       EINTR
	   The operation was interrupted by delivery of	a signal before	any
	   events were available.

EXAMPLE
       Polling indefinitely for	input events on	both a Crossroads socket and a
       standard	socket..

	   xs_pollitem_t items [2];
	   /* First item refers	to Crossroads socket 'socket' */
	   items[0].socket = socket;
	   items[0].events = XS_POLLIN;
	   /* Second item refers to standard socket 'fd' */
	   items[1].socket = NULL;
	   items[1].fd = fd;
	   items[1].events = XS_POLLIN;
	   /* Poll for events indefinitely */
	   int rc = xs_poll (items, 2, -1);
	   assert (rc >= 0);
	   /* Returned events will be stored in	items[].revents	*/

SEE ALSO
       xs_socket(3) xs_send(3) xs_recv(3) xs(7)

       Your operating system documentation for the poll() system call.

AUTHORS
       The Crossroads documentation was	written	by Martin Sustrik
       <sustrik@250bpm.com[1]> and Martin Lucina <martin@lucina.net[2]>.

NOTES
	1. sustrik@250bpm.com
	   mailto:sustrik@250bpm.com

	2. martin@lucina.net
	   mailto:martin@lucina.net

Crossroads I/O 1.2.0		  11/05/2021			    XS_POLL(3)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLE | SEE ALSO | AUTHORS | NOTES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=xs_poll&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help