| .\" Copyright (C) 2006, 2019 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 2020-04-11 "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. |
| The Linux-specific |
| .BR epoll (7) |
| API performs a similar task, but offers features beyond those found in |
| .BR poll (). |
| .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 \(bu 2 |
| a file descriptor becomes ready; |
| .IP \(bu |
| the call is interrupted by a signal handler; or |
| .IP \(bu |
| 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 \(bu 2 |
| There is out-of-band data on a TCP socket (see |
| .BR tcp (7)). |
| .IP \(bu |
| A pseudoterminal device in packet mode has seen a state change on |
| the corresponding terminal device |
| (see |
| .BR ioctl_tty (2)). |
| .IP \(bu |
| A |
| .I cgroup.events |
| file has been modified (see |
| .BR cgroups (7)). |
| .RE |
| .TP |
| .B POLLOUT |
| Writing is now possible, though a write larger than 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 nearly 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 |
| The above code segment is described as |
| .I nearly |
| equivalent because whereas a negative |
| .I timeout |
| value for |
| .BR poll () |
| is interpreted as an infinite timeout, a negative value expressed in |
| .IR *tmo_p |
| results in an error from |
| .BR ppoll (). |
| .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, |
| .BR poll () |
| returns a nonnegative value which is the number of elements in the |
| .I pollfds |
| whose |
| .I revents |
| fields have been set to a nonzero value (indicating an event or an error). |
| A return value of zero indicates that the system call timed out |
| before any file descriptors became read. |
| .PP |
| On error, \-1 is returned, and |
| .I errno |
| is set to indicate the cause of the error. |
| .SH ERRORS |
| .TP |
| .B EFAULT |
| .I fds |
| points outside the process's accessible address space. |
| 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 EINVAL |
| .RB ( ppoll ()) |
| The timeout value expressed in |
| .IR *ip |
| is invalid (negative). |
| .TP |
| .B ENOMEM |
| Unable to allocate memory for kernel data structures. |
| .SH VERSIONS |
| The |
| .BR poll () |
| system call was introduced in Linux 2.1.23. |
| On older kernels that lack this system call, |
| the glibc |
| .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. |
| .\" FIXME . |
| .\" ppoll() is proposed for inclusion in POSIX: |
| .\" https://www.austingroupbugs.net/view.php?id=1263 |
| .\" NetBSD 3.0 has a pollts() which is like Linux ppoll(). |
| .SH NOTES |
| The operation of |
| .BR poll () |
| and |
| .BR ppoll () |
| is not affected by the |
| .BR O_NONBLOCK |
| flag. |
| .PP |
| 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 EXAMPLES |
| The program below opens each of the files named in its command-line |
| arguments and monitors the resulting file descriptors for readiness to read |
| .RB ( POLLIN ). |
| The program loops, repeatedly using |
| .BR poll () |
| to monitor the file descriptors, |
| printing the number of ready file descriptors on return. |
| For each ready file descriptor, the program: |
| .IP \(bu 2 |
| displays the returned |
| .I revents |
| field in a human-readable form; |
| .IP \(bu |
| if the file descriptor is readable, reads some data from it, |
| and displays that data on standard output; and |
| .IP \(bu |
| if the file descriptors was not readable, |
| but some other event occurred (presumably |
| .BR POLLHUP ), |
| closes the file descriptor. |
| .PP |
| Suppose we run the program in one terminal, asking it to open a FIFO: |
| .PP |
| .in +4n |
| .EX |
| $ \fBmkfifo myfifo\fP |
| $ \fB./poll_input myfifo\fP |
| .EE |
| .in |
| .PP |
| In a second terminal window, we then open the FIFO for writing, |
| write some data to it, and close the FIFO: |
| .PP |
| .in +4n |
| .EX |
| $ \fBecho aaaaabbbbbccccc > myfifo\fP |
| .EE |
| .in |
| .PP |
| In the terminal where we are running the program, we would then see: |
| .PP |
| .in +4n |
| .EX |
| Opened "myfifo" on fd 3 |
| About to poll() |
| Ready: 1 |
| fd=3; events: POLLIN POLLHUP |
| read 10 bytes: aaaaabbbbb |
| About to poll() |
| Ready: 1 |
| fd=3; events: POLLIN POLLHUP |
| read 6 bytes: ccccc |
| |
| About to poll() |
| Ready: 1 |
| fd=3; events: POLLHUP |
| closing fd 3 |
| All file descriptors closed; bye |
| .EE |
| .in |
| .PP |
| In the above output, we see that |
| .BR poll () |
| returned three times: |
| .IP \(bu 2 |
| On the first return, the bits returned in the |
| .I revents |
| field were |
| .BR POLLIN , |
| indicating that the file descriptor is readable, and |
| .BR POLLHUP , |
| indicating that the other end of the FIFO has been closed. |
| The program then consumed some of the available input. |
| .IP \(bu |
| The second return from |
| .BR poll () |
| also indicated |
| .BR POLLIN |
| and |
| .BR POLLHUP ; |
| the program then consumed the last of the available input. |
| .IP \(bu |
| On the final return, |
| .BR poll () |
| indicated only |
| .BR POLLHUP |
| on the FIFO, |
| at which point the file descriptor was closed and the program terminated. |
| .\" |
| .SS Program source |
| \& |
| .nf |
| /* poll_input.c |
| |
| Licensed under GNU General Public License v2 or later. |
| */ |
| #include <poll.h> |
| #include <fcntl.h> |
| #include <sys/types.h> |
| #include <stdio.h> |
| #include <stdlib.h> |
| #include <unistd.h> |
| |
| #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e |
| } while (0) |
| |
| int |
| main(int argc, char *argv[]) |
| { |
| int nfds, num_open_fds; |
| struct pollfd *pfds; |
| |
| if (argc < 2) { |
| fprintf(stderr, "Usage: %s file...\en", argv[0]); |
| exit(EXIT_FAILURE); |
| } |
| |
| num_open_fds = nfds = argc \- 1; |
| pfds = calloc(nfds, sizeof(struct pollfd)); |
| if (pfds == NULL) |
| errExit("malloc"); |
| |
| /* Open each file on command line, and add it \(aqpfds\(aq array */ |
| |
| for (int j = 0; j < nfds; j++) { |
| pfds[j].fd = open(argv[j + 1], O_RDONLY); |
| if (pfds[j].fd == \-1) |
| errExit("open"); |
| |
| printf("Opened \e"%s\e" on fd %d\en", argv[j + 1], pfds[j].fd); |
| |
| pfds[j].events = POLLIN; |
| } |
| |
| /* Keep calling poll() as long as at least one file descriptor is |
| open */ |
| |
| while (num_open_fds > 0) { |
| int ready; |
| |
| printf("About to poll()\en"); |
| ready = poll(pfds, nfds, \-1); |
| if (ready == \-1) |
| errExit("poll"); |
| |
| printf("Ready: %d\en", ready); |
| |
| /* Deal with array returned by poll() */ |
| |
| for (int j = 0; j < nfds; j++) { |
| char buf[10]; |
| |
| if (pfds[j].revents != 0) { |
| printf(" fd=%d; events: %s%s%s\en", pfds[j].fd, |
| (pfds[j].revents & POLLIN) ? "POLLIN " : "", |
| (pfds[j].revents & POLLHUP) ? "POLLHUP " : "", |
| (pfds[j].revents & POLLERR) ? "POLLERR " : ""); |
| |
| if (pfds[j].revents & POLLIN) { |
| ssize_t s = read(pfds[j].fd, buf, sizeof(buf)); |
| if (s == \-1) |
| errExit("read"); |
| printf(" read %zd bytes: %.*s\en", |
| s, (int) s, buf); |
| } else { /* POLLERR | POLLHUP */ |
| printf(" closing fd %d\en", pfds[j].fd); |
| if (close(pfds[j].fd) == \-1) |
| errExit("close"); |
| num_open_fds\-\-; |
| } |
| } |
| } |
| } |
| |
| printf("All file descriptors closed; bye\en"); |
| exit(EXIT_SUCCESS); |
| } |
| .fi |
| .SH SEE ALSO |
| .BR restart_syscall (2), |
| .BR select (2), |
| .BR select_tut (2), |
| .BR epoll (7), |
| .BR time (7) |