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 whether they are ready for reading (receiving) or writing (sending), or to see whether 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.

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

If a program needs to use message queue support, the program source code must be compiled with the -D _MSGQSUPPORT compilation flag.

Parameters

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

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

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

Exclusive notification

For programs that use the POLLEXCL flag for exclusive notification about events, the supported policies or behavior are described in the following table. These policies determine which thread is selected for notification about the event. A single event behavior is also supported that suppresses the number of returned events from a poll request. Programs might find this behavior helpful, for example, in load balancing scenarios. Programs that are using the pollset API can achieve the same single event behavior by specifying an array length of 1 when the programs are calling the pollset_poll or pollset_poll_ext subroutine. The required policy or behavior is set for each process by using the POLLEXCL_POLICY environment variable. Some policies and behaviors are mutually exclusive. Whenever a conflict occurs between multiple policies. The default policy of the system is used.

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 by using the read subroutine or the getmsg system call. You can send messages by 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:

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: