[PATCH] Fix ppoll example

[PATCH] Fix ppoll example

[Andi Kleen]

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

-Andi

--- man-pages-3.23/man2/poll.2	2009-09-30 03:36:44.000000000 +0200
+++ man-pages-3.23-hacked/man2/poll.2	2009-12-27 01:36:31.000000000 +0100
@@ -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
-- 
ak-VuQAYsv1563Yd54FQh9/CA@public.gmane.org -- Speaking for myself only.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Fix ppoll example

[Andi Kleen]

On Sun, Dec 27, 2009 at 01:40:07AM +0100, Andi Kleen wrote:
> 
> The ppoll replacement example gets the timeout argument
> wrong. Fix that.

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

-Andi


--- man-pages-3.23/man2/poll.2	2009-09-30 03:36:44.000000000 +0200
+++ man-pages-3.23-hacked/man2/poll.2	2009-12-27 01:43:31.000000000 +0100
@@ -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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Fix ppoll example

[Michael Kerrisk]

Hi Andi,

On Sun, Dec 27, 2009 at 2:44 AM, Andi Kleen <andi-Vw/NltI1exuRpAAqCnN02g@public.gmane.org> wrote:
> On Sun, Dec 27, 2009 at 01:40:07AM +0100, Andi Kleen wrote:
>>
>> The ppoll replacement example gets the timeout argument
>> wrong. Fix that.
>
> Sorry, the first version was still wrong. This one
> should be correct.
>
> --- man-pages-3.23/man2/poll.2  2009-09-30 03:36:44.000000000 +0200
> +++ man-pages-3.23-hacked/man2/poll.2   2009-12-27 01:43:31.000000000 +0100
> @@ -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

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

--- a/man2/poll.2
+++ b/man2/poll.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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Fix ppoll example

[Denis Barbier]

On 2010/6/12 Michael Kerrisk wrote:
[...]
> --- a/man2/poll.2
> +++ b/man2/poll.2
[...]
> @@ -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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Fix ppoll example

[Michael Kerrisk]

Hello Denis

On Thu, Jul 1, 2010 at 11:49 PM, Denis Barbier <bouzim-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> On 2010/6/12 Michael Kerrisk wrote:
> [...]
>> --- a/man2/poll.2
>> +++ b/man2/poll.2
> [...]
>> @@ -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.

Thanks. Fixed now.

Cheers,

Michael


-- 
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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html