| .\" Copyright (C) 1997 Andries Brouwer (aeb@cwi.nl) |
| .\" and Copyright (C) 2006, Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .\" Additions from Richard Gooch <rgooch@atnf.CSIRO.AU> and aeb, 971207 |
| .\" 2006-03-13, mtk, Added ppoll() + various other rewordings |
| .\" 2006-07-01, mtk, Added POLLRDHUP + various other wording and |
| .\" formatting changes. |
| .\" |
| .TH POLL 2 2017-09-15 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| poll, ppoll \- wait for some event on a file descriptor |
| .SH SYNOPSIS |
| .nf |
| .B #include <poll.h> |
| .PP |
| .BI "int poll(struct pollfd *" fds ", nfds_t " nfds ", int " timeout ); |
| |
| .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" |
| .B #include <signal.h> |
| .B #include <poll.h> |
| .PP |
| .BI "int ppoll(struct pollfd *" fds ", nfds_t " nfds ", " |
| .BI " const struct timespec *" tmo_p ", const sigset_t *" sigmask ); |
| .fi |
| .SH DESCRIPTION |
| .BR poll () |
| performs a similar task to |
| .BR select (2): |
| it waits for one of a set of file descriptors to become ready |
| to perform I/O. |
| .PP |
| The set of file descriptors to be monitored is specified in the |
| .I fds |
| argument, which is an array of structures of the following form: |
| .PP |
| .in +4n |
| .EX |
| struct pollfd { |
| int fd; /* file descriptor */ |
| short events; /* requested events */ |
| short revents; /* returned events */ |
| }; |
| .EE |
| .in |
| .PP |
| The caller should specify the number of items in the |
| .I fds |
| array in |
| .IR nfds . |
| .PP |
| The field |
| .I fd |
| contains a file descriptor for an open file. |
| If this field is negative, then the corresponding |
| .I events |
| field is ignored and the |
| .I revents |
| field returns zero. |
| (This provides an easy way of ignoring a |
| file descriptor for a single |
| .BR poll () |
| call: simply negate the |
| .I fd |
| field. |
| Note, however, that this technique can't be used to ignore file descriptor 0.) |
| .PP |
| The field |
| .I events |
| is an input parameter, a bit mask specifying the events the application |
| is interested in for the file descriptor |
| .IR fd . |
| This field may be specified as zero, |
| in which case the only events that can be returned in |
| .I revents |
| are |
| .BR POLLHUP , |
| .BR POLLERR , |
| and |
| .B POLLNVAL |
| (see below). |
| .PP |
| The field |
| .I revents |
| is an output parameter, filled by the kernel with the events that |
| actually occurred. |
| The bits returned in |
| .I revents |
| can include any of those specified in |
| .IR events , |
| or one of the values |
| .BR POLLERR , |
| .BR POLLHUP , |
| or |
| .BR POLLNVAL . |
| (These three bits are meaningless in the |
| .I events |
| field, and will be set in the |
| .I revents |
| field whenever the corresponding condition is true.) |
| .PP |
| If none of the events requested (and no error) has occurred for any |
| of the file descriptors, then |
| .BR poll () |
| blocks until one of the events occurs. |
| .PP |
| The |
| .I timeout |
| argument specifies the number of milliseconds that |
| .BR poll () |
| should block waiting for a file descriptor to become ready. |
| The call will block until either: |
| .IP * 3 |
| a file descriptor becomes ready; |
| .IP * |
| the call is interrupted by a signal handler; or |
| .IP * |
| the timeout expires. |
| .PP |
| Note that the |
| .I timeout |
| interval will be rounded up to the system clock granularity, |
| and kernel scheduling delays mean that the blocking interval |
| may overrun by a small amount. |
| Specifying a negative value in |
| .I timeout |
| means an infinite timeout. |
| Specifying a |
| .I timeout |
| of zero causes |
| .BR poll () |
| to return immediately, even if no file descriptors are ready. |
| .PP |
| The bits that may be set/returned in |
| .I events |
| and |
| .I revents |
| are defined in \fI<poll.h>\fP: |
| .TP |
| .B POLLIN |
| There is data to read. |
| .TP |
| .B POLLPRI |
| There is some exceptional condition on the file descriptor. |
| Possibilities include: |
| .RS |
| .IP * 3 |
| There is out-of-band data on a TCP socket (see |
| .BR tcp (7)). |
| .IP * |
| A pseudoterminal master in packet mode has seen a state change on the slave |
| (see |
| .BR ioctl_tty (2)). |
| .IP * |
| A |
| .I cgroup.events |
| file has been modified (see |
| .BR cgroups (7)). |
| .RE |
| .TP |
| .B POLLOUT |
| Writing is now possible, though a write larger that the available space |
| in a socket or pipe will still block (unless |
| .B O_NONBLOCK |
| is set). |
| .TP |
| .BR POLLRDHUP " (since Linux 2.6.17)" |
| Stream socket peer closed connection, |
| or shut down writing half of connection. |
| The |
| .B _GNU_SOURCE |
| feature test macro must be defined |
| (before including |
| .I any |
| header files) |
| in order to obtain this definition. |
| .TP |
| .B POLLERR |
| Error condition (only returned in |
| .IR revents ; |
| ignored in |
| .IR events ). |
| This bit is also set for a file descriptor referring |
| to the write end of a pipe when the read end has been closed. |
| .TP |
| .B POLLHUP |
| Hang up (only returned in |
| .IR revents ; |
| ignored in |
| .IR events ). |
| Note that when reading from a channel such as a pipe or a stream socket, |
| this event merely indicates that the peer closed its end of the channel. |
| Subsequent reads from the channel will return 0 (end of file) |
| only after all outstanding data in the channel has been consumed. |
| .TP |
| .B POLLNVAL |
| Invalid request: |
| .I fd |
| not open (only returned in |
| .IR revents ; |
| ignored in |
| .IR events ). |
| .PP |
| When compiling with |
| .B _XOPEN_SOURCE |
| defined, one also has the following, |
| which convey no further information beyond the bits listed above: |
| .TP |
| .B POLLRDNORM |
| Equivalent to |
| .BR POLLIN . |
| .TP |
| .B POLLRDBAND |
| Priority band data can be read (generally unused on Linux). |
| .\" POLLRDBAND is used in the DECnet protocol. |
| .TP |
| .B POLLWRNORM |
| Equivalent to |
| .BR POLLOUT . |
| .TP |
| .B POLLWRBAND |
| Priority data may be written. |
| .PP |
| Linux also knows about, but does not use |
| .BR POLLMSG . |
| .SS ppoll() |
| The relationship between |
| .BR poll () |
| and |
| .BR ppoll () |
| is analogous to the relationship between |
| .BR select (2) |
| and |
| .BR pselect (2): |
| like |
| .BR pselect (2), |
| .BR ppoll () |
| allows an application to safely wait until either a file descriptor |
| becomes ready or until a signal is caught. |
| .PP |
| Other than the difference in the precision of the |
| .I timeout |
| argument, the following |
| .BR ppoll () |
| call: |
| .PP |
| .in +4n |
| .EX |
| ready = ppoll(&fds, nfds, tmo_p, &sigmask); |
| .EE |
| .in |
| .PP |
| is equivalent to |
| .I atomically |
| executing the following calls: |
| .PP |
| .in +4n |
| .EX |
| sigset_t origmask; |
| int timeout; |
| |
| timeout = (tmo_p == NULL) ? \-1 : |
| (tmo_p\->tv_sec * 1000 + tmo_p\->tv_nsec / 1000000); |
| pthread_sigmask(SIG_SETMASK, &sigmask, &origmask); |
| ready = poll(&fds, nfds, timeout); |
| pthread_sigmask(SIG_SETMASK, &origmask, NULL); |
| .EE |
| .in |
| .PP |
| See the description of |
| .BR pselect (2) |
| for an explanation of why |
| .BR ppoll () |
| is necessary. |
| .PP |
| If the |
| .I sigmask |
| argument is specified as NULL, then |
| no signal mask manipulation is performed |
| (and thus |
| .BR ppoll () |
| differs from |
| .BR poll () |
| only in the precision of the |
| .I timeout |
| argument). |
| .PP |
| The |
| .I tmo_p |
| argument specifies an upper limit on the amount of time that |
| .BR ppoll () |
| will block. |
| This argument is a pointer to a structure of the following form: |
| .PP |
| .in +4n |
| .EX |
| struct timespec { |
| long tv_sec; /* seconds */ |
| long tv_nsec; /* nanoseconds */ |
| }; |
| .EE |
| .in |
| .PP |
| If |
| .I tmo_p |
| is specified as NULL, then |
| .BR ppoll () |
| can block indefinitely. |
| .SH RETURN VALUE |
| On success, a positive number is returned; this is |
| the number of structures which have nonzero |
| .I revents |
| fields (in other words, those descriptors with events or errors reported). |
| A value of 0 indicates that the call timed out and no file |
| descriptors were ready. |
| On error, \-1 is returned, and |
| .I errno |
| is set appropriately. |
| .SH ERRORS |
| .TP |
| .B EFAULT |
| The array given as argument was not contained in the calling program's |
| address space. |
| .TP |
| .B EINTR |
| A signal occurred before any requested event; see |
| .BR signal (7). |
| .TP |
| .B EINVAL |
| The |
| .I nfds |
| value exceeds the |
| .B RLIMIT_NOFILE |
| value. |
| .TP |
| .B ENOMEM |
| There was no space to allocate file descriptor tables. |
| .SH VERSIONS |
| The |
| .BR poll () |
| system call was introduced in Linux 2.1.23. |
| On older kernels that lack this system call, |
| .\" library call was introduced in libc 5.4.28 |
| the glibc (and the old Linux libc) |
| .BR poll () |
| wrapper function provides emulation using |
| .BR select (2). |
| .PP |
| The |
| .BR ppoll () |
| system call was added to Linux in kernel 2.6.16. |
| The |
| .BR ppoll () |
| library call was added in glibc 2.4. |
| .SH CONFORMING TO |
| .BR poll () |
| conforms to POSIX.1-2001 and POSIX.1-2008. |
| .BR ppoll () |
| is Linux-specific. |
| .\" NetBSD 3.0 has a pollts() which is like Linux ppoll(). |
| .SH NOTES |
| On some other UNIX systems, |
| .\" Darwin, according to a report by Jeremy Sequoia, relayed by Josh Triplett |
| .BR poll () |
| can fail with the error |
| .B EAGAIN |
| if the system fails to allocate kernel-internal resources, rather than |
| .B ENOMEM |
| as Linux does. |
| POSIX permits this behavior. |
| Portable programs may wish to check for |
| .B EAGAIN |
| and loop, just as with |
| .BR EINTR . |
| .PP |
| Some implementations define the nonstandard constant |
| .B INFTIM |
| with the value \-1 for use as a |
| .IR timeout |
| for |
| .BR poll (). |
| This constant is not provided in glibc. |
| .PP |
| For a discussion of what may happen if a file descriptor being monitored by |
| .BR poll () |
| is closed in another thread, see |
| .BR select (2). |
| .SS C library/kernel differences |
| The Linux |
| .BR ppoll () |
| system call modifies its |
| .I tmo_p |
| argument. |
| However, the glibc wrapper function hides this behavior |
| by using a local variable for the timeout argument that |
| is passed to the system call. |
| Thus, the glibc |
| .BR ppoll () |
| function does not modify its |
| .I tmo_p |
| argument. |
| .PP |
| The raw |
| .BR ppoll () |
| system call has a fifth argument, |
| .IR "size_t sigsetsize" , |
| which specifies the size in bytes of the |
| .IR sigmask |
| argument. |
| The glibc |
| .BR ppoll () |
| wrapper function specifies this argument as a fixed value |
| (equal to |
| .IR sizeof(kernel_sigset_t) ). |
| See |
| .BR sigprocmask (2) |
| for a discussion on the differences between the kernel and the libc |
| notion of the sigset. |
| .SH BUGS |
| See the discussion of spurious readiness notifications under the |
| BUGS section of |
| .BR select (2). |
| .SH SEE ALSO |
| .BR restart_syscall (2), |
| .BR select (2), |
| .BR select_tut (2), |
| .BR epoll (7), |
| .BR time (7) |