Skip to contentSkip to conversation

Fix ppoll example

PATCH In review Andi Kleen 4 participants 5 messages Dec 27, 2009 – Jul 2, 2010 4 messages not in the archive Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore

Andi Kleen

author
#0 lore raw

PATCH 1/1 Fix ppoll example

The ppoll replacement example gets the timeout argument wrong. Fix that.

-Andi

man2/poll.2 +3 -1
@@ -27,6 +27,7 @@
 .\" 2006-03-13, mtk, Added ppoll() + various other rewordings
 .\" 2006-07-01, mtk, Added POLLRDHUP + various other wording and
 .\"	formatting changes.
+.\" 2009-12, ak, Fix ppoll example.
 .\"
 .TH POLL 2 2009-09-15 "Linux" "Linux Programmer's Manual"
 .SH NAME
@@ -202,9 +203,10 @@
 .nf
 
     sigset_t origmask;
+    struct timespec ts = { .tv_sec = timeout };
 
     sigprocmask(SIG_SETMASK, &sigmask, &origmask);
-    ready = poll(&fds, nfds, timeout);
+    ready = poll(&fds, nfds, timeout >= 0 ? &ts : NULL);
     sigprocmask(SIG_SETMASK, &origmask, NULL);
 .fi
 .PP
Signature · 5 lines
ak-VuQAYsv1563Yd54FQh9/[email protected] -- Speaking for myself only.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): 20091227004007.GA8638-u0/[email protected]

author
#2 lore raw
Quoted 3 lines · Andi Kleen

The ppoll replacement example gets the timeout argument wrong. Fix that.

Sorry, the first version was still wrong. This one should be correct.

-Andi

man2/poll.2 +3 -2
@@ -27,6 +27,7 @@
 .\" 2006-03-13, mtk, Added ppoll() + various other rewordings
 .\" 2006-07-01, mtk, Added POLLRDHUP + various other wording and
 .\"	formatting changes.
+.\" 2009-12, ak, Fix ppoll example.
 .\"
 .TH POLL 2 2009-09-15 "Linux" "Linux Programmer's Manual"
 .SH NAME
@@ -193,7 +194,7 @@
 call:
 .nf
 
-    ready = ppoll(&fds, nfds, timeout, &sigmask);
+    ready = ppoll(&fds, nfds, ts, &sigmask);
 
 .fi
 is equivalent to
@@ -204,7 +205,7 @@
     sigset_t origmask;
 
     sigprocmask(SIG_SETMASK, &sigmask, &origmask);
-    ready = poll(&fds, nfds, timeout);
+    ready = poll(&fds, nfds, ts ? ts.tv_sec : -1);
     sigprocmask(SIG_SETMASK, &origmask, NULL);
 .fi
 .PP

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): 20091227004422.GA8673-u0/[email protected]

#4 lore raw

Hi Andi,

Quoted 34 lines · Andi Kleen
Quoted 3 lines · Andi Kleen

The ppoll replacement example gets the timeout argument wrong. Fix that.

Sorry, the first version was still wrong. This one should be correct.

man2/poll.2   2009-12-27 01:43:31.000000000 +0100 renamed from man2/poll.2  2009-09-30 03:36:44.000000000 +0200 +0 -0
@@ -27,6 +27,7 @@

 .\" 2006-03-13, mtk, Added ppoll() + various other rewordings .\" 2006-07-01, mtk, Added POLLRDHUP + various other wording and .\"    formatting changes.
+.\" 2009-12, ak, Fix ppoll example.
 .\"
 .TH POLL 2 2009-09-15 "Linux" "Linux Programmer's Manual" .SH NAME

man2/poll.2   2009-12-27 01:43:31.000000000 +0100 renamed from man2/poll.2  2009-09-30 03:36:44.000000000 +0200 +0 -0
@@ -193,7 +194,7 @@

 call:
 .nf

-    ready = ppoll(&fds, nfds, timeout, &sigmask);
+    ready = ppoll(&fds, nfds, ts, &sigmask);

 .fi
 is equivalent to

man2/poll.2   2009-12-27 01:43:31.000000000 +0100 renamed from man2/poll.2  2009-09-30 03:36:44.000000000 +0200 +1 -1
@@ -204,7 +205,7 @@
     sigset_t origmask;
 
     sigprocmask(SIG_SETMASK, &sigmask, &origmask);
-    ready = poll(&fds, nfds, timeout);
+    ready = poll(&fds, nfds, ts ? ts.tv_sec : -1);
     sigprocmask(SIG_SETMASK, &origmask, NULL);
Quoted 2 lines

 .fi
 .PP

Thanks for spotting the problem, but this version isn't correct either. poll() use an int with milliseconds, ppoll() uses a struct with seconds + nanoseconds.

Does the following look okay to you? (It also includes a name change for the timeout argument of ppoll() to make the distinction clearer in the text.

Change for man-pages-3.25.

Cheers,

Michael

man2/poll.2 +2 -2
@@ -28,7 +28,7 @@
 .\" 2006-07-01, mtk, Added POLLRDHUP + various other wording and
 .\"    formatting changes.
 .\"
-.TH POLL 2 2009-09-15 "Linux" "Linux Programmer's Manual"
+.TH POLL 2 2010-06-12 "Linux" "Linux Programmer's Manual"
 .SH NAME
 poll, ppoll \- wait for some event on a file descriptor
 .SH SYNOPSIS
@@ -41,7 +41,7 @@ poll, ppoll \- wait for some event on a file descriptor
 .B #include <poll.h>
 .sp
 .BI "int ppoll(struct pollfd *" fds ", nfds_t " nfds ", "
-.BI "        const struct timespec *" timeout ", const sigset_t *" sigmask );
+.BI "        const struct timespec *" timeout_ts ", const sigset_t *"

sigmask );
.fi
.SH DESCRIPTION
.BR poll ()
@@ -186,14 +186,13 @@ like
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
-.I timeout
-argument, the following
+Other than the difference in the precision of the +timeout argument, the following
.BR ppoll ()
call:
.nf

- ready = ppoll(&fds, nfds, timeout, &sigmask);
+ ready = ppoll(&fds, nfds, timeout_ts, &sigmask);

.fi
is equivalent to
@@ -202,7 +201,10 @@ executing the following calls:
.nf

     sigset_t origmask;

+ int timeout;

+ timeout = (timeout_ts == NULL) ? -1 :

+              (timeout_ts.tv_sec * 1000 + timeout_ts.tv_nsec / 1000000);
     sigprocmask(SIG_SETMASK, &sigmask, &origmask);
     ready = poll(&fds, nfds, timeout);
     sigprocmask(SIG_SETMASK, &origmask, NULL);

@@ -222,12 +224,10 @@ no signal mask manipulation is performed
.BR ppoll ()
differs from
.BR poll ()
-only in the precision of the
-.I timeout
-argument).
+only in the precision of the timeout argument).

The
-.I timeout
+.I timeout_ts
argument specifies an upper limit on the amount of time that .BR ppoll ()
will block.
@@ -243,7 +243,7 @@ struct timespec {
.in

If
-.I timeout
+.I timeout_ts
is specified as NULL, then
.BR ppoll ()
can block indefinitely.
@@ -304,13 +304,15 @@ is Linux-specific.
Some implementations define the nonstandard constant
.B INFTIM
with the value \-1 for use as a
-.IR timeout .
+.IR timeout
+for
+.BR poll ()..
This constant is not provided in glibc.
.SS "Linux Notes"
The Linux
.BR ppoll ()
system call modifies its
-.I timeout
+.I timeout_ts
argument.
However, the glibc wrapper function hides this behavior
by using a local variable for the timeout argument that
@@ -318,7 +320,7 @@ is passed to the system call.
Thus, the glibc
.BR ppoll ()
function does not modify its
-.I timeout
+.I timeout_ts
argument.
.SH BUGS
See the discussion of spurious readiness notifications under the
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): AANLkTimHnSfMtcsuG8lJ-MTLeMCA3f9XQkL26bEdth1F-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org

#6 lore raw

On 2010/6/12 Michael Kerrisk wrote:
[...]

Quoted 2 lines
man2/poll.2 +0 -0

[...]

Quoted 8 lines
man2/poll.2 +0 -0
@@ -304,13 +304,15 @@ is Linux-specific.

 Some implementations define the nonstandard constant .B INFTIM
 with the value \-1 for use as a
-.IR timeout .
+.IR timeout
+for
+.BR poll ()..

Hi Michael,

There is a spurious trailing dot.

Denis
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): AANLkTimkwPS5_6yltbKsCFf-HeVVF5Ox1elT9R1rMcN--JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org

#8 lore raw

Hello Denis

Quoted 16 lines · Denis Barbier

On 2010/6/12 Michael Kerrisk wrote:
[...]

Quoted 2 lines
man2/poll.2 +0 -0

[...]

Quoted 8 lines
man2/poll.2 +0 -0
@@ -304,13 +304,15 @@ is Linux-specific.

 Some implementations define the nonstandard constant .B INFTIM
 with the value \-1 for use as a
-.IR timeout .
+.IR timeout
+for
+.BR poll ()..

Hi Michael,

Quoted 1 line

There is a spurious trailing dot.

Thanks. Fixed now.

Cheers,

Michael

Signature · 7 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface" http://blog.man7.org/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html