The Linux Programming Interface

1338 Chapter 63

It is permissible to specify events as 0 if we are not interested in events on a particular

file descriptor. Furthermore, specifying a negative value for the fd field (e.g., negating

its value if nonzero) causes the corresponding events field to be ignored and the

revents field always to be returned as 0. Either of these techniques can be used to

(perhaps temporarily) disable monitoring of a single file descriptor, without need-

ing to rebuild the entire fds list.

Note the following further points regarding the Linux implementation of poll():

z Although defined as separate bits, POLLIN and POLLRDNORM are synonymous.

z Although defined as separate bits, POLLOUT and POLLWRNORM are synonymous.

z POLLRDBAND is generally unused; that is, it is ignored in the events field and not set

in revents.

The only place where POLLRDBAND is set is in code implementing the (obsolete)

DECnet networking protocol.

z Although set for sockets in certain circumstances, POLLWRBAND conveys no useful

information. (There are no circumstances in which POLLWRBAND is set when POLLOUT

and POLLWRNORM are not also set.)

POLLRDBAND and POLLWRBAND are meaningful on implementations that provide

System V STREAMS (which Linux does not). Under STREAMS, a message can

be assigned a nonzero priority, and such messages are queued to the receiver

in decreasing order of priority, in a band ahead of normal (priority 0) messages.

z The _XOPEN_SOURCE feature test macro must be defined in order to obtain the

definitions of the constants POLLRDNORM, POLLRDBAND, POLLWRNORM, and POLLWRBAND

from <poll.h>.

Table 63-2: Bit-mask values for events and revents fields of the pollfd structure

Bit Input in

events?

Returned

in revents?

Description

POLLIN ••Data other than high-priority data can be read

POLLRDNORM ••Equivalent to POLLIN

POLLRDBAND ••Priority data can be read (unused on Linux)

POLLPRI ••High-priority data can be read

POLLRDHUP ••Shutdown on peer socket

POLLOUT ••Normal data can be written

POLLWRNORM ••Equivalent to POLLOUT

POLLWRBAND ••Priority data can be written

POLLERR • An error has occurred

POLLHUP • A hangup has occurred

POLLNVAL • File descriptor is not open

POLLMSG Unused on Linux (and unspecified in SUSv3)