diff options
Diffstat (limited to 'man2/poll.2')
| -rw-r--r-- | man2/poll.2 | 123 |
1 files changed, 66 insertions, 57 deletions
diff --git a/man2/poll.2 b/man2/poll.2 index 7aecf02b4..2b024d3f0 100644 --- a/man2/poll.2 +++ b/man2/poll.2 @@ -7,7 +7,7 @@ .\" 2006-07-01, mtk, Added POLLRDHUP + various other wording and .\" formatting changes. .\" -.TH poll 2 2023-02-05 "Linux man-pages 6.03" +.TH poll 2 2023-07-08 "Linux man-pages 6.05.01" .SH NAME poll, ppoll \- wait for some event on a file descriptor .SH LIBRARY @@ -123,6 +123,14 @@ the call is interrupted by a signal handler; or .IP \[bu] the timeout expires. .PP +Being "ready" means that the requested operation will not block; thus, +.BR poll ()ing +regular files, +block devices, +and other files with no reasonable polling semantic +.I always +returns instantly as ready to read and write. +.PP Note that the .I timeout interval will be rounded up to the system clock granularity, @@ -264,7 +272,7 @@ executing the following calls: .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); @@ -358,39 +366,6 @@ is invalid (negative). .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 in Linux 2.6.16. -The -.BR ppoll () -library call was added in glibc 2.4. -.SH STANDARDS -.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 -.B O_NONBLOCK -flag. -.PP On some other UNIX systems, .\" Darwin, according to a report by Jeremy Sequoia, relayed by Josh Triplett .BR poll () @@ -412,11 +387,6 @@ with the value \-1 for use as a 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 () @@ -448,6 +418,45 @@ See .BR sigprocmask (2) for a discussion on the differences between the kernel and the libc notion of the sigset. +.SH STANDARDS +.TP +.BR poll () +POSIX.1-2008. +.TP +.BR ppoll () +Linux. +.\" 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 HISTORY +.TP +.BR poll () +POSIX.1-2001. +Linux 2.1.23. +.IP +On older kernels that lack this system call, +the glibc +.BR poll () +wrapper function provides emulation using +.BR select (2). +.TP +.BR ppoll () +Linux 2.6.16, +glibc 2.4. +.SH NOTES +The operation of +.BR poll () +and +.BR ppoll () +is not affected by the +.B O_NONBLOCK +flag. +.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). .SH BUGS See the discussion of spurious readiness notifications under the BUGS section of @@ -505,7 +514,7 @@ About to poll() Ready: 1 fd=3; events: POLLIN POLLHUP read 6 bytes: ccccc - +\& About to poll() Ready: 1 fd=3; events: POLLHUP @@ -547,7 +556,7 @@ at which point the file descriptor was closed and the program terminated. .\" SRC BEGIN (poll_input.c) .EX /* poll_input.c - +\& Licensed under GNU General Public License v2 or later. */ #include <fcntl.h> @@ -555,10 +564,10 @@ at which point the file descriptor was closed and the program terminated. #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[]) { @@ -567,49 +576,49 @@ main(int argc, char *argv[]) nfds_t num_open_fds, nfds; ssize_t s; 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 to \[aq]pfds\[aq] array. */ - +\& for (nfds_t 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) { 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 (nfds_t j = 0; j < nfds; j++) { 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) { s = read(pfds[j].fd, buf, sizeof(buf)); if (s == \-1) @@ -625,7 +634,7 @@ main(int argc, char *argv[]) } } } - +\& printf("All file descriptors closed; bye\en"); exit(EXIT_SUCCESS); } |