fp_poll Kernel Service

Kernel and Subsystems Technical Reference, Volume 1

fp_poll Kernel Service

Purpose

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

Syntax

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

int fp_poll (listptr, nfdsmsgs, timeout, flags)
void *listptr;
unsigned long nfdsmsgs;
long timeout;
uint flags;

Parameters

listptr

Points to an array of pollfd or pollmsg structures, or to a single pollist structure. Each structure specifies a file pointer, file descriptor, or message queue ID. The events of interest for this file or message queue are also specified.

nfdsmsgs

Specifies the number of files and message queues to check. The low-order 16 bits give the number of elements present in the array of pollfd structures. The high-order 16 bits give the number of elements present in the array of pollmsg structures. If either half of the nfdsmsgs parameter is equal to 0, then the corresponding array is presumed abse1e.

timeout

Specifies how long the service waits for a specified event to occur. If the value of this parameter is -1, the fp_poll kernel service does not return until at least one of the specified events has occurred. If the time-out value is 0, the fp_poll kernel service does not wait for an event to occur. Instead, the service returns immediately even if none of the specified events have occurred. For any other value of the timeout parameter, the fp_poll kernel service specifies the maximum length of time (in milliseconds) to wait for at least one of the specified events to occur.

flags

Specifies the type of data in the listptr parameter:

POLL_FDMSG	Input is a file descriptor and/or message queue.
0	Input is a file pointer.

Description

Note: The fp_poll service applies only to character devices, pipes, message queues, and sockets. Not all character device drivers support the fp_poll service.

The fp_poll kernel service checks the specified file pointers/descriptors and message queues to see if they are ready for reading or writing, or if they have an exceptional condition pending.

The pollfd, pollmsg, and pollist structures are defined in the /usr/include/sys/poll.h file. These are the same structures described for the poll subroutine. One difference is that the fd field in the pollfd structure contains a file pointer when the flags parameter on the fp_poll kernel service equals 0 (zero). If the flags parameter is set to a POLL_FDMSG value, the field is taken as a file descriptor in all processed pollfd structures. If either the fd or msgid fields in their respective structures has a negative value, the processing for that structure is skipped.

When performing a poll operation on both files and message queues, the listptr parameter points to a pollist structure, which can specify both files and message queues. To construct a pollist structure, use the POLLIST macro as described in the poll subroutine.

If the number of pollfd elements in the nfdsmsgs parameter is 0, then the listptr parameter must point to an array of pollmsg structures.

If the number of pollmsg elements in the nfdsmsgs parameter is 0, then the listptr parameter must point to an array of pollfd structures.

If the number of pollmsg and pollfd elements are both nonzero in the nfdsmsgs parameter, the listptr parameter must point to a pollist structure as previously defined.

Execution Environment

The fp_poll kernel service can be called from the process environment only.

Return Values

Upon successful completion, the fp_poll kernel service returns a value that indicates the total number of files and message queues that satisfy the selection criteria. The return value is similar to the nfdsmsgs parameter in the following ways:

The low-order 16 bits give the number of files.
The high-order 16 bits give the number of message queue identifiers that have nonzero revents values.

Use the NFDS and NMSGS macros to separate these two values from the return value. A return code of 0 (zero) indicates that:

The call has timed out.
None of the specified files or message queues indicates the presence of an event.

In other words, all revents fields are 0 (zero).

When the return code from the fp_poll kernel service is negative, it is set to the following value:

EINTR

Indicates that a signal was caught during the fp_poll kernel service.

Implementation Specifics

The fp_poll kernel service is part of Base Operating System (BOS) Runtime.

Related Information

The poll subroutine.

The selreg kernel service.

Logical File System Kernel Services in AIX Version 4.3 Kernel Extensions and Device Support Programming Concepts.