---
name: "xs_poll"
section: "3"
platform: "linux"
package: "libxs-dev"
version: "1.2.0-2"
release: "Debian 10 (Buster)"
platforms: ["linux"]
url: "https://new.carta.tech/xs_poll"
---

# xs\_poll(3)

input/output multiplexing

## 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_socket/3.md) [**xs\_send**(3)](/xs_send/3.md) [**xs\_recv**(3)](/xs_recv/3.md) [**xs**(7)](/xs/7.md)

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