[PATCH manpages] epoll_wait.2: add epoll_pwait2

[PATCH manpages] epoll_wait.2: add epoll_pwait2

[Willem de Bruijn]

From: Willem de Bruijn <willemb@google.com>

Expand the epoll_wait page with epoll_pwait2, an epoll_wait variant
that takes a struct timespec to enable nanosecond resolution timeout.

    int epoll_pwait2(int fd, struct epoll_event *events,
                     int maxevents,
                     const struct timespec *timeout,
                     const sigset_t *sigset);

Signed-off-by: Willem de Bruijn <willemb@google.com>

---

This is the same as an RFC sent earlier.

epoll_pwait2 is now merged in 5.11-rc1.

I'm not sure whether to send for manpages inclusion before 5.11
reaches stable ABI, or after. Erring on the side of caution. It
could still be reverted before then, of course.
---
 man2/epoll_wait.2 | 31 +++++++++++++++++++++++++++++--
 1 file changed, 29 insertions(+), 2 deletions(-)

diff --git a/man2/epoll_wait.2 b/man2/epoll_wait.2
index 36001e02bde3..21d63503a87f 100644
--- a/man2/epoll_wait.2
+++ b/man2/epoll_wait.2
@@ -22,7 +22,7 @@
 .\"
 .TH EPOLL_WAIT 2 2020-04-11 "Linux" "Linux Programmer's Manual"
 .SH NAME
-epoll_wait, epoll_pwait \- wait for an I/O event on an epoll file descriptor
+epoll_wait, epoll_pwait, epoll_pwait2 \- wait for an I/O event on an epoll file descriptor
 .SH SYNOPSIS
 .nf
 .B #include <sys/epoll.h>
@@ -32,6 +32,9 @@ epoll_wait, epoll_pwait \- wait for an I/O event on an epoll file descriptor
 .BI "int epoll_pwait(int " epfd ", struct epoll_event *" events ,
 .BI "               int " maxevents ", int " timeout ,
 .BI "               const sigset_t *" sigmask );
+.BI "int epoll_pwait2(int " epfd ", struct epoll_event *" events ,
+.BI "                int " maxevents ", const struct timespec *" timeout ,
+.BI "                const sigset_t *" sigmask );
 .fi
 .SH DESCRIPTION
 The
@@ -170,6 +173,25 @@ argument may be specified as NULL, in which case
 .BR epoll_pwait ()
 is equivalent to
 .BR epoll_wait ().
+.SS epoll_pwait2 ()
+The
+.BR epoll_pwait2 ()
+system call is equivalent to
+.BR epoll_pwait ()
+except for the
+.I timeout
+argument. It takes an argument of type
+.I timespec
+to be able to specify nanosecond resolution timeout. This argument functions
+the same as in
+.BR pselect (2)
+and
+.BR ppoll (2).
+If
+.I timeout
+is NULL, then
+.BR epoll_pwait2 ()
+can block indefinitely.
 .SH RETURN VALUE
 On success,
 .BR epoll_wait ()
@@ -217,6 +239,9 @@ Library support is provided in glibc starting with version 2.3.2.
 .BR epoll_pwait ()
 was added to Linux in kernel 2.6.19.
 Library support is provided in glibc starting with version 2.6.
+.PP
+.BR epoll_pwait2 ()
+was added to Linux in kernel 5.11.
 .SH CONFORMING TO
 .BR epoll_wait ()
 and
@@ -269,7 +294,9 @@ this means that timeouts greater than 35.79 minutes are treated as infinity.
 .SS C library/kernel differences
 The raw
 .BR epoll_pwait ()
-system call has a sixth argument,
+and
+.BR epoll_pwait2 ()
+system calls have a sixth argument,
 .IR "size_t sigsetsize" ,
 which specifies the size in bytes of the
 .IR sigmask
-- 
2.30.0.284.gd98b1dd5eaa7-goog

Re: [PATCH manpages] epoll_wait.2: add epoll_pwait2

[Michael Kerrisk (man-pages)]

Hello Willem,

On 1/12/21 1:48 AM, Willem de Bruijn wrote:
> From: Willem de Bruijn <willemb@google.com>
> 
> Expand the epoll_wait page with epoll_pwait2, an epoll_wait variant
> that takes a struct timespec to enable nanosecond resolution timeout.
> 
>     int epoll_pwait2(int fd, struct epoll_event *events,
>                      int maxevents,
>                      const struct timespec *timeout,
>                      const sigset_t *sigset);
> 
> Signed-off-by: Willem de Bruijn <willemb@google.com>

Thank you for the patch. And thanks for fixing epoll_(p)wait!
Patch applied.

Cheers,

Michael

> ---
> 
> This is the same as an RFC sent earlier.
> 
> epoll_pwait2 is now merged in 5.11-rc1.
> 
> I'm not sure whether to send for manpages inclusion before 5.11
> reaches stable ABI, or after. Erring on the side of caution. It
> could still be reverted before then, of course.
> ---
>  man2/epoll_wait.2 | 31 +++++++++++++++++++++++++++++--
>  1 file changed, 29 insertions(+), 2 deletions(-)
> 
> diff --git a/man2/epoll_wait.2 b/man2/epoll_wait.2
> index 36001e02bde3..21d63503a87f 100644
> --- a/man2/epoll_wait.2
> +++ b/man2/epoll_wait.2
> @@ -22,7 +22,7 @@
>  .\"
>  .TH EPOLL_WAIT 2 2020-04-11 "Linux" "Linux Programmer's Manual"
>  .SH NAME
> -epoll_wait, epoll_pwait \- wait for an I/O event on an epoll file descriptor
> +epoll_wait, epoll_pwait, epoll_pwait2 \- wait for an I/O event on an epoll file descriptor
>  .SH SYNOPSIS
>  .nf
>  .B #include <sys/epoll.h>
> @@ -32,6 +32,9 @@ epoll_wait, epoll_pwait \- wait for an I/O event on an epoll file descriptor
>  .BI "int epoll_pwait(int " epfd ", struct epoll_event *" events ,
>  .BI "               int " maxevents ", int " timeout ,
>  .BI "               const sigset_t *" sigmask );
> +.BI "int epoll_pwait2(int " epfd ", struct epoll_event *" events ,
> +.BI "                int " maxevents ", const struct timespec *" timeout ,
> +.BI "                const sigset_t *" sigmask );
>  .fi
>  .SH DESCRIPTION
>  The
> @@ -170,6 +173,25 @@ argument may be specified as NULL, in which case
>  .BR epoll_pwait ()
>  is equivalent to
>  .BR epoll_wait ().
> +.SS epoll_pwait2 ()
> +The
> +.BR epoll_pwait2 ()
> +system call is equivalent to
> +.BR epoll_pwait ()
> +except for the
> +.I timeout
> +argument. It takes an argument of type
> +.I timespec
> +to be able to specify nanosecond resolution timeout. This argument functions
> +the same as in
> +.BR pselect (2)
> +and
> +.BR ppoll (2).
> +If
> +.I timeout
> +is NULL, then
> +.BR epoll_pwait2 ()
> +can block indefinitely.
>  .SH RETURN VALUE
>  On success,
>  .BR epoll_wait ()
> @@ -217,6 +239,9 @@ Library support is provided in glibc starting with version 2.3.2.
>  .BR epoll_pwait ()
>  was added to Linux in kernel 2.6.19.
>  Library support is provided in glibc starting with version 2.6.
> +.PP
> +.BR epoll_pwait2 ()
> +was added to Linux in kernel 5.11.
>  .SH CONFORMING TO
>  .BR epoll_wait ()
>  and
> @@ -269,7 +294,9 @@ this means that timeouts greater than 35.79 minutes are treated as infinity.
>  .SS C library/kernel differences
>  The raw
>  .BR epoll_pwait ()
> -system call has a sixth argument,
> +and
> +.BR epoll_pwait2 ()
> +system calls have a sixth argument,
>  .IR "size_t sigsetsize" ,
>  which specifies the size in bytes of the
>  .IR sigmask
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH manpages] epoll_wait.2: add epoll_pwait2

[Florian Weimer]

* Willem de Bruijn:

> From: Willem de Bruijn <willemb@google.com>
>
> Expand the epoll_wait page with epoll_pwait2, an epoll_wait variant
> that takes a struct timespec to enable nanosecond resolution timeout.
>
>     int epoll_pwait2(int fd, struct epoll_event *events,
>                      int maxevents,
>                      const struct timespec *timeout,
>                      const sigset_t *sigset);

Does it really use struct timespec?  With 32-bit times on most 32-bit
targets?

Thanks,
Florian
-- 
Red Hat GmbH, https://de.redhat.com/ , Registered seat: Grasbrunn,
Commercial register: Amtsgericht Muenchen, HRB 153243,
Managing Directors: Charles Cachera, Brian Klemm, Laurie Krebs, Michael O'Neill

Re: [PATCH manpages] epoll_wait.2: add epoll_pwait2

[Michael Kerrisk (man-pages)]

Hi Florian,

On Tue, 12 Jan 2021 at 13:33, Florian Weimer <fweimer@redhat.com> wrote:
>
> * Willem de Bruijn:
>
> > From: Willem de Bruijn <willemb@google.com>
> >
> > Expand the epoll_wait page with epoll_pwait2, an epoll_wait variant
> > that takes a struct timespec to enable nanosecond resolution timeout.
> >
> >     int epoll_pwait2(int fd, struct epoll_event *events,
> >                      int maxevents,
> >                      const struct timespec *timeout,
> >                      const sigset_t *sigset);
>
> Does it really use struct timespec?  With 32-bit times on most 32-bit
> targets?

The type inside the kernel seems to be:

[[
SYSCALL_DEFINE6(epoll_pwait2, int, epfd, struct epoll_event __user *, events,
                int, maxevents, const struct __kernel_timespec __user
*, timeout,

struct __kernel_timespec {
        __kernel_time64_t       tv_sec;                 /* seconds */
        long long               tv_nsec;                /* nanoseconds */
};
]]

So, 64 bits by the look of things.

Thanks,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH manpages] epoll_wait.2: add epoll_pwait2

[Willem de Bruijn]

On Tue, Jan 12, 2021 at 8:05 AM Michael Kerrisk (man-pages)
<mtk.manpages@gmail.com> wrote:
>
> Hi Florian,
>
> On Tue, 12 Jan 2021 at 13:33, Florian Weimer <fweimer@redhat.com> wrote:
> >
> > * Willem de Bruijn:
> >
> > > From: Willem de Bruijn <willemb@google.com>
> > >
> > > Expand the epoll_wait page with epoll_pwait2, an epoll_wait variant
> > > that takes a struct timespec to enable nanosecond resolution timeout.
> > >
> > >     int epoll_pwait2(int fd, struct epoll_event *events,
> > >                      int maxevents,
> > >                      const struct timespec *timeout,
> > >                      const sigset_t *sigset);
> >
> > Does it really use struct timespec?  With 32-bit times on most 32-bit
> > targets?
>
> The type inside the kernel seems to be:
>
> [[
> SYSCALL_DEFINE6(epoll_pwait2, int, epfd, struct epoll_event __user *, events,
>                 int, maxevents, const struct __kernel_timespec __user
> *, timeout,
>
> struct __kernel_timespec {
>         __kernel_time64_t       tv_sec;                 /* seconds */
>         long long               tv_nsec;                /* nanoseconds */
> };
> ]]
>
> So, 64 bits by the look of things.

Yes. The C library is expected to define the function as shown here,
and internally call the syscall with __kernel_timespec.

This is similar to modern time64 variants of other timespec syscall,
such as ppoll.

For 64-bit archs like x86_64, ppoll maps onto sys_ppoll with native
__kernel_timespec.
For 32-bit archs like x86, the library is expected to call new
ppoll_time64 , with the same type.

On 32-bit archs, the existing ppoll maps onto a syscall that expects
the __old_timespec32. Legacy C libraries and direct callers will
continue to call this.

For the new epoll_pwait2 syscall we do not add this non-y2038
compliant version, as there is no need for backward compatibility with
legacy users.