Checks the I/O status of multiple file descriptors and message queues.
#include <sys/poll.h> #include <sys/select.h> #include <sys/types.h>
int poll(ListPointer, Nfdsmsgs, Timeout) void *ListPointer; unsigned long Nfdsmsgs; long Timeout;
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.
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.
| ListPointer | Specifies a pointer to an array of pollfd structures, pollmsg structures, or to a
pollist 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 the Nfdsmsgs 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. |
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 */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:
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.
The poll subroutine does not run successfully if one or more of the following are true:
This subroutine is part of Base Operating System (BOS) Runtime.
For compatibility with previous releases of this operating system and with BSD systems, the select subroutine is also supported.
The read subroutine, select subroutine, write subroutine.
The getmsg system call, putmsg system call.
The streamio operations.
The STREAMS Overview and the Input and Output Handling Programmer's Overview in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.