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

["Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>]

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/