poll (BPX1POL, BPX4POL) — Monitor activity on file descriptors and message queues

Function

The poll service checks the I/O status of multiple open file descriptors and message queues. The file descriptors can be for character special files, pipes, sockets, or files.

Requirements

Operation	Environment
Authorization:	Supervisor state or problem state, any PSW key
Dispatchable unit mode:	Task
Cross memory mode:	PASN = HASN
AMODE (BPX1POL):	31-bit
AMODE (BPX4POL):	64-bit
ASC mode:	Primary mode
Interrupt status:	Enabled for interrupts
Locks:	Unlocked
Control parameters:	All parameters must be addressable by the caller and in the primary address space.

Format

CALL BPX1POL,(PollArrayPtr,
              NMsgsFds,
              Timeout,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4POL with the same parameters. The PollArrayPtr parameter is a doubleword.

Parameters

PollArrayPtr

Supplied parameter

Type:: Pointer
Length:: Fullword (doubleword)

The name of a fullword (doubleword) field that contains a pointer to an array of Pollfd structures. The elements of the array must be arranged such that the PollFd structures that contain file descriptors precede the PollFd structures that contain message queue identifiers, if any are specified.

There is one Pollfd structure for each file descriptor or message queue that is being polled. A Pollfd structure specifies the file descriptor or message queue and the events for which it is being polled. On return, the poll service sets the corresponding bit in the response section of the Pollfd structure if the requested condition is true.

The events that can be polled are:

POLLRDNORM: Normal data can be read without blocking.
POLLRDBAND: Data from a nonzero priority band can be read without blocking. For STREAMs, this flag is set in revents, even if the message is of zero length.
POLLIN: Same as POLLRDNORM.
POLLWRNORM: Normal data may be written without blocking.
POLLWRBAND: Priority data (priority band greater than 0) may be written.
POLLPRI: Out-of-band data may be received without blocking.
POLLOUT: Same as POLLWRNORM.
POLLNVAL: The specified fd/msgid value is not valid. This flag is only valid in the revents bitmask; it is ignored in the events bitmask.
POLLERR: An error has occurred. This flag is only valid in the revents bitmask; it is ignored in the events bitmask.
POLLHUP: The device has been disconnected. This event and POLLOUT are mutually exclusive; a stream can never be writable if a hang-up has occurred. However, this event and POLLIN, POLLRDRNORM, POLLRDBAND, or POLLPRI are not mutually exclusive. This flag is valid in the revents bitmask. It is ignored in the events member.

For more information about the format of this field, see BPXYPOLL — Map poll syscall parameters. The flags in the events bitmask are defined as:

POLLEPRI, POLLEWRBAND, POLLEWRNORM, POLLEOUT, POLLEIN, POLLERDBAND, POLLERDNORM

The flags in the revents bitmask are defined as:

POLLRNVAL, POLLRHUP, POLLRERR, POLLRPRI, POLLRWRBAND, POLLRWRNORM, POLLROUT, POLLRIN, POLLRRDBAND, POLLRRDNORM

NMsgsFds

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains two numbers, the sum of which gives the total number of PollFd structures pointed to by PollArrayPtr.

The first number, which is in the first halfword of the fullword, tells how many message queue PollFd structures were specified. This number must not exceed 32,767. The second number, which is in the second halfword of the fullword, tells how many file descriptor PollFd structures were specified. This number should not exceed 65,535.

Timeout

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a field that contains a timeout value, in milliseconds, that controls how the file descriptors/message queues are checked.

No waiting:
If the Timeout value is 0, poll returns immediately after checking the selected descriptors and queues; no waiting is done.
Wait for a specified period of time:
If the Timeout value is greater than 0, it specifies the number of milliseconds to wait for one of the events to occur before returning to the caller. (1000 milliseconds equal 1 second).
Wait forever:
If the timeout value is -1, poll blocks until a requested event occurs or until the call is interrupted.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the poll service returns one of the following:

The number of events that were found to be ready.
The return_value is similar to NMsgsFds. The first halfword of return_value contains the number of message queues with ready events. The second halfword contains the number of file descriptors with ready events.
0, if the timeout value expired before any of the events were met.
-1, if the request is not successful.

Return_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the poll service stores the return code. The poll service returns Return_code only if Return_value is -1. See z/OS UNIX System Services Messages and Codes for a complete list of possible return code values. The poll service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EAGAIN	The allocation of internal data structures failed, but a subsequent request may succeed.
EINTR	The select service request was interrupted by a signal for the caller.
EINVAL	One of the parameters specified a value that was not correct. Consult the reason code to determine the exact reason for the error. The following reason codes can accompany this return code: JRWaitForever, JRInvalidNfds, JRNoFdsTooManyQIds.
EIO	One of the descriptors in the poll mask has become inoperative and it is being repeatedly included in a poll, even though other operations against this descriptor have been failing with EIO. A socket descriptor can become inoperative, for example, if TCP/IP is shut down. When a descriptor fails, a failure from poll cannot tell you which descriptor has failed, so generally poll will succeed, and these descriptors will be reported to you as being ready for whatever events were specified on the poll. When the inoperative descriptor is subsequently used on a receive or other operation, you will receive the EIO failure, and can then react to the problem with the individual descriptor. In general, you would close() the descriptor and remove it from the next poll mask. If the individual descriptor's failing return code is ignored, though, and an inoperative descriptor is repeatedly polled and used (even though each time it is used the call fails with EIO), eventually the poll call itself will fail with EIO.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the poll service stores the reason code. The poll service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. For the reason codes, see z/OS UNIX System Services Messages and Codes.

Usage notes

Poll bits are supported as follows:

Regular Files: Always poll true for reading and writing. This means that all poll read and write bits are supported. They will never return with POLLERR or POLLHUP.
FIFOs / PIPEs: Do not have the concept of out-of-band data or priority band data. They support POLLIN, POLLRDNORM, POLLOUT, POLLWRNORM, and POLLHUP. They ignore POLLPRI, POLLRDBAND, and POLLWRBAND. They never return POLLERR.
TTYs / OCS: Same support as FIFOs and PIPEs, except that TTYs may return POLLERR.
Sockets: Have the concept of out-of-band data. They support POLLIN, POLLRDNORM, POLLOUT, POLLWRNORM, and POLLPRI for out-of-band data. They ignore POLLRDBAND and POLLWRBAND. They might return POLLERR, but they will never return POLLHUP.

If the value of fd/msgid is less than 0, events is ignored and revents is set to 0 in that entry on return from poll.

In each pollfd structure, poll clears the revents member, except that where the application requested a report on a condition by setting one of the bits of events listed above, the poll service sets the corresponding bit in revents if the requested condition is true. In addition, poll sets the POLLERR flag in revents if the condition is true, even if the application did not set the corresponding bit in events.

The poll request is not affected by the O_NONBLOCK flag.

A file descriptor for a socket that is listening for connections indicates that it is ready for reading, once connections are available. A file descriptor for a socket that is connecting asynchronously indicates that it is ready for writing, once a connection has been established.

Characteristics and restrictions

There are no restrictions on the use of the poll service.

Examples

For an example using this callable service, see BPX1POL (poll) example.