poll Subroutine

Purpose

Checks the I/O status of multiple file descriptors and message queues.

Library

Standard C Library (libc.a)

Syntax

#include <sys/poll.h>
#include <sys/select.h>
#include <sys/types.h>

int poll( ListPointer, Nfdsmsgs, Timeout) void *ListPointer; unsigned long Nfdsmsgs; long Timeout;

Description

The poll subroutine checks the specified file descriptors and message queues to see if they are ready for reading (receiving) or writing (sending), or to see if they have an exceptional condition pending. Even though there are OPEN_MAX number of file descriptors available, only FD_SETSIZE number of file descriptors are accessible with this subroutine.

Note: The poll subroutine applies only to character devices, pipes, message queues, and sockets. Not all character device drivers support it. See the descriptions of individual character devices for information about whether and how specific device drivers support the poll and select subroutines.

For compatibility with previous releases of this operating system and with BSD systems, the select subroutine is also supported.

In AIX® 5.3 and later versions, if a program needs to use message queue support, the program source code should be compiled with the -D_MSGQSUPPORT compilation flag.

Parameters

Item Description

Item	Description
ListPointer	Specifies a pointer to an array of pollfd structures, pollmsg structures, or to apollist structure. Each structure specifies a file descriptor or message queue ID and the events of interest for this file or message queue. The pollfd, pollmsg, and pollist structures are defined in the /usr/include/sys/poll.h file. If a pollist structure is to be used, a structure similar to the following should be defined in a user program. The pollfd structure must precede the pollmsg structure. `struct pollist { struct pollfd fds[3]; struct pollmsg msgs[2]; } list;` The structure can then be initialized as follows: `list.fds[0].fd = file_descriptorA; list.fds[0].events = requested_events; list.msgs[0].msgid = message_id; list.msgs[0].events = requested_events;` The rest of the elements in thefdsandmsgsarrays can be initialized the same way. The poll subroutine can then be called, as follows: `nfds = 3; /* number of pollfd structs / nmsgs = 2; / number of pollmsg structs / timeout = 1000 / number of milliseconds to timeout / poll(&list, (nmsgs<<16)\|(nfds), 1000);` The exact number of elements in the fds* and msgs arrays must be used in the calculation of the Nfdsmsgs parameter.
Nfdsmsgs	Specifies the number of file descriptors and the exact number of message queues to check. The low-order 16 bits give the number of elements in the array of pollfd structures, while the high-order 16 bits give the exact number of elements in the array of pollmsg structures. If either half of theNfdsmsgs parameter is equal to a value of 0, the corresponding array is assumed not to be present.
Timeout	Specifies the maximum length of time (in milliseconds) to wait for at least one of the specified events to occur. If the Timeout parameter value is -1, the poll subroutine does not return until at least one of the specified events has occurred. If the value of the Timeout parameter is 0, the poll subroutine does not wait for an event to occur but returns immediately, even if none of the specified events have occurred.

ListPointer

Specifies a pointer to an array of pollfd structures, pollmsg structures, or to apollist structure. Each structure specifies a file descriptor or message queue ID and the events of interest for this file or message queue. The pollfd, pollmsg, and pollist structures are defined in the /usr/include/sys/poll.h file. If a pollist structure is to be used, a structure similar to the following should be defined in a user program. The pollfd structure must precede the pollmsg structure.

struct pollist {
   struct pollfd fds[3];
   struct pollmsg msgs[2];
   } list;

The structure can then be initialized as follows:

list.fds[0].fd = file_descriptorA;
list.fds[0].events = requested_events;
list.msgs[0].msgid = message_id;
list.msgs[0].events = requested_events;

The rest of the elements in thefdsandmsgsarrays can be initialized the same way. The poll subroutine can then be called, as follows:

nfds = 3;   /* number of pollfd structs */
nmsgs = 2;   /* number of pollmsg structs */
timeout = 1000   /* number of milliseconds to timeout */
poll(&list, (nmsgs<<16)|(nfds), 1000);

The exact number of elements in the fds and msgs arrays must be used in the calculation of the Nfdsmsgs parameter.

Nfdsmsgs Specifies the number of file descriptors and the exact number of message queues to check. The low-order 16 bits give the number of elements in the array of pollfd structures, while the high-order 16 bits give the exact number of elements in the array of pollmsg structures. If either half of theNfdsmsgs parameter is equal to a value of 0, the corresponding array is assumed not to be present.

Timeout Specifies the maximum length of time (in milliseconds) to wait for at least one of the specified events to occur. If the Timeout parameter value is -1, the poll subroutine does not return until at least one of the specified events has occurred. If the value of the Timeout parameter is 0, the poll subroutine does not wait for an event to occur but returns immediately, even if none of the specified events have occurred.

poll Subroutine STREAMS Extensions

In addition to the functions described above, the poll subroutine multiplexes input/output over a set of file descriptors that reference open streams. The poll subroutine identifies those streams on which you can send or receive messages, or on which certain events occurred.

You can receive messages using the read subroutine or the getmsg system call. You can send messages using the write subroutine or the putmsg system call. Certain streamio operations, such as I_RECVFD and I_SENDFD can also be used to send and receive messages. See the streamio operations.

The ListPointer parameter specifies the file descriptors to be examined and the events of interest for each file descriptor. It points to an array having one element for each open file descriptor of interest. The array's elements are pollfd structures. In addition to the pollfd structure in the /usr/include/sys/poll.h file, STREAMS supports the following members:

int fd; /* file descriptor */ short events; /* requested events */ short revents; /* returned events */

The fd field specifies an open file descriptor and the events and revents fields are bit-masks constructed by ORing any combination of the following event flags:

Item	Description
POLLIN	A nonpriority or file descriptor-passing message is present on the stream-head read queue. This flag is set even if the message is of 0 length. In the `revents` field this flag is mutually exclusive with the POLLPRI flag. See the I_RECVFD command.
POLLRDNORM	A nonpriority message is present on the stream-head read queue.
POLLRDBAND	A priority message (band > 0) is present on the stream-head read queue.
POLLPRI	A high-priority message is present on the stream-head read queue. This flag is set even if the message is of 0 length. In the `revents` field, this flag is mutually exclusive with the POLLIN flag.
POLLOUT	The first downstream write queue in the stream is not full. Normal priority messages can be sent at any time. See the putmsg system call.
POLLWRNORM	The same as POLLOUT.
POLLWRBAND	A priority band greater than 0 exists downstream and priority messages can be sent at anytime.
POLLMSG	A message containing the SIGPOLL signal has reached the front of the stream-head read queue.

Return Values

On successful completion, the poll subroutine returns a value that indicates the total number of file descriptors and message queues that satisfy the selection criteria. The return value is similar to the Nfdsmsgs parameter in that the low-order 16 bits give the number of file descriptors, and the high-order 16 bits give the number of message queue identifiers that had nonzero revents values. The NFDS and NMSGS macros, found in the sys/select.h file, can be used to separate these two values from the return value. The NFDS macro returns NFDS#, where the number returned indicates the number of files reporting some event or error, and the NMSGS macro returns NMSGS#, where the number returned indicates the number of message queues reporting some event or error.

A value of 0 indicates that the poll subroutine timed out and that none of the specified files or message queues indicated the presence of an event (all revents fields were values of 0).

If unsuccessful, a value of -1 is returned and the global variable errno is set to indicate the error.

Error Codes

The poll subroutine does not run successfully if one or more of the following are true:

Item	Description
EAGAIN	Allocation of internal data structures was unsuccessful.
EINTR	A signal was caught during the poll system call and the signal handler was installed with an indication that subroutines are not to be restarted.
EINVAL	The number of pollfd structures specified by the Nfdsmsgs parameter is greater than FD_SETSIZE. This error is also returned if the number of pollmsg structures specified by the Nfdsmsgs parameter is greater than the maximum number of allowable message queues.
EFAULT	The ListPointer parameter in conjunction with the Nfdsmsgs parameter addresses a location outside of the allocated address space of the process.