summaryrefslogtreecommitdiffstats
path: root/man2/poll.2
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-15 19:41:07 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-15 19:41:07 +0000
commit3af6d22bb3850ab2bac67287e3a3d3b0e32868e5 (patch)
tree3ee7a3ec64525911fa865bb984c86d997d855527 /man2/poll.2
parentAdding debian version 6.05.01-1. (diff)
downloadmanpages-3af6d22bb3850ab2bac67287e3a3d3b0e32868e5.tar.xz
manpages-3af6d22bb3850ab2bac67287e3a3d3b0e32868e5.zip
Merging upstream version 6.7.
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'man2/poll.2')
-rw-r--r--man2/poll.274
1 files changed, 37 insertions, 37 deletions
diff --git a/man2/poll.2 b/man2/poll.2
index 2b024d3..36e89f8 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-07-08 "Linux man-pages 6.05.01"
+.TH poll 2 2023-10-31 "Linux man-pages 6.7"
.SH NAME
poll, ppoll \- wait for some event on a file descriptor
.SH LIBRARY
@@ -16,12 +16,12 @@ Standard C library
.SH SYNOPSIS
.nf
.B #include <poll.h>
-.PP
+.P
.BI "int poll(struct pollfd *" fds ", nfds_t " nfds ", int " timeout );
-.PP
+.P
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <poll.h>
-.PP
+.P
.BI "int ppoll(struct pollfd *" fds ", nfds_t " nfds ,
.BI " const struct timespec *_Nullable " tmo_p ,
.BI " const sigset_t *_Nullable " sigmask );
@@ -36,11 +36,11 @@ The Linux-specific
.BR epoll (7)
API performs a similar task, but offers features beyond those found in
.BR poll ().
-.PP
+.P
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
+.P
.in +4n
.EX
struct pollfd {
@@ -50,12 +50,12 @@ struct pollfd {
};
.EE
.in
-.PP
+.P
The caller should specify the number of items in the
.I fds
array in
.IR nfds .
-.PP
+.P
The field
.I fd
contains a file descriptor for an open file.
@@ -70,7 +70,7 @@ file descriptor for a single
call: simply set the
.I fd
field to its bitwise complement.)
-.PP
+.P
The field
.I events
is an input parameter, a bit mask specifying the events the application
@@ -85,7 +85,7 @@ are
and
.B POLLNVAL
(see below).
-.PP
+.P
The field
.I revents
is an output parameter, filled by the kernel with the events that
@@ -104,12 +104,12 @@ or
field, and will be set in the
.I revents
field whenever the corresponding condition is true.)
-.PP
+.P
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
+.P
The
.I timeout
argument specifies the number of milliseconds that
@@ -122,7 +122,7 @@ a file descriptor becomes ready;
the call is interrupted by a signal handler; or
.IP \[bu]
the timeout expires.
-.PP
+.P
Being "ready" means that the requested operation will not block; thus,
.BR poll ()ing
regular files,
@@ -130,7 +130,7 @@ block devices,
and other files with no reasonable polling semantic
.I always
returns instantly as ready to read and write.
-.PP
+.P
Note that the
.I timeout
interval will be rounded up to the system clock granularity,
@@ -144,7 +144,7 @@ Specifying a
of zero causes
.BR poll ()
to return immediately, even if no file descriptors are ready.
-.PP
+.P
The bits that may be set/returned in
.I events
and
@@ -214,7 +214,7 @@ not open (only returned in
.IR revents ;
ignored in
.IR events ).
-.PP
+.P
When compiling with
.B _XOPEN_SOURCE
defined, one also has the following,
@@ -234,7 +234,7 @@ Equivalent to
.TP
.B POLLWRBAND
Priority data may be written.
-.PP
+.P
Linux also knows about, but does not use
.BR POLLMSG .
.SS ppoll()
@@ -251,23 +251,23 @@ like
.BR ppoll ()
allows an application to safely wait until either a file descriptor
becomes ready or until a signal is caught.
-.PP
+.P
Other than the difference in the precision of the
.I timeout
argument, the following
.BR ppoll ()
call:
-.PP
+.P
.in +4n
.EX
ready = ppoll(&fds, nfds, tmo_p, &sigmask);
.EE
.in
-.PP
+.P
is nearly equivalent to
.I atomically
executing the following calls:
-.PP
+.P
.in +4n
.EX
sigset_t origmask;
@@ -280,7 +280,7 @@ ready = poll(&fds, nfds, timeout);
pthread_sigmask(SIG_SETMASK, &origmask, NULL);
.EE
.in
-.PP
+.P
The above code segment is described as
.I nearly
equivalent because whereas a negative
@@ -291,13 +291,13 @@ is interpreted as an infinite timeout, a negative value expressed in
.I *tmo_p
results in an error from
.BR ppoll ().
-.PP
+.P
See the description of
.BR pselect (2)
for an explanation of why
.BR ppoll ()
is necessary.
-.PP
+.P
If the
.I sigmask
argument is specified as NULL, then
@@ -309,7 +309,7 @@ differs from
only in the precision of the
.I timeout
argument).
-.PP
+.P
The
.I tmo_p
argument specifies an upper limit on the amount of time that
@@ -318,7 +318,7 @@ will block.
This argument is a pointer to a
.BR timespec (3)
structure.
-.PP
+.P
If
.I tmo_p
is specified as NULL, then
@@ -334,7 +334,7 @@ whose
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 ready.
-.PP
+.P
On error, \-1 is returned, and
.I errno
is set to indicate the error.
@@ -379,7 +379,7 @@ Portable programs may wish to check for
.B EAGAIN
and loop, just as with
.BR EINTR .
-.PP
+.P
Some implementations define the nonstandard constant
.B INFTIM
with the value \-1 for use as a
@@ -401,7 +401,7 @@ Thus, the glibc
function does not modify its
.I tmo_p
argument.
-.PP
+.P
The raw
.BR ppoll ()
system call has a fifth argument,
@@ -452,7 +452,7 @@ and
is not affected by the
.B O_NONBLOCK
flag.
-.PP
+.P
For a discussion of what may happen if a file descriptor being monitored by
.BR poll ()
is closed in another thread, see
@@ -482,27 +482,27 @@ if the file descriptor was not readable,
but some other event occurred (presumably
.BR POLLHUP ),
closes the file descriptor.
-.PP
+.P
Suppose we run the program in one terminal, asking it to open a FIFO:
-.PP
+.P
.in +4n
.EX
$ \fBmkfifo myfifo\fP
$ \fB./poll_input myfifo\fP
.EE
.in
-.PP
+.P
In a second terminal window, we then open the FIFO for writing,
write some data to it, and close the FIFO:
-.PP
+.P
.in +4n
.EX
$ \fBecho aaaaabbbbbccccc > myfifo\fP
.EE
.in
-.PP
+.P
In the terminal where we are running the program, we would then see:
-.PP
+.P
.in +4n
.EX
Opened "myfifo" on fd 3
@@ -522,7 +522,7 @@ Ready: 1
All file descriptors closed; bye
.EE
.in
-.PP
+.P
In the above output, we see that
.BR poll ()
returned three times: