| Message ID | 20210112004820.4013953-1-willemdebruijn.kernel@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [manpages] epoll_wait.2: add epoll_pwait2 | expand |
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 >
* 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
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
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.
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