epoll_wait.2: add epoll_pwait2
PATCH 1/1 epoll_wait.2: add epoll_pwait2
From: Willem de Bruijn <[email protected]>
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);
---
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(-)
man2/epoll_wait.2 +29 -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
Signature · 1 line
2.30.0.284.gd98b1dd5eaa7-goog
Hello Willem,
Quoted 11 lines · Willem de Bruijn
From: Willem de Bruijn <[email protected]>
Expand the
epoll_waitpage withepoll_pwait2, anepoll_waitvariant 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, constsigset_t*sigset);Signed-off-by Willem de Bruijn <[email protected]>
Thank you for the patch. And thanks for fixing epoll_(p)wait! Patch applied.
Cheers,
Michael
Quoted 84 lines
---
This is the same as an RFC sent earlier.
epoll_pwait2is 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(-)man2/epoll_wait.2 +29
-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
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
* Willem de Bruijn:
Quoted 9 lines
From: Willem de Bruijn <[email protected]>
Expand the
epoll_waitpage withepoll_pwait2, anepoll_waitvariant 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, constsigset_t*sigset);
Does it really use struct timespec? With 32-bit times on most 32-bit targets?
Thanks,
Florian
Signature · 3 lines
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
Hi Florian,
Quoted 8 lines · Florian Weimer
* Willem de Bruijn:
Quoted 5 lines
From: Willem de Bruijn <[email protected]>
Expand the
epoll_waitpage withepoll_pwait2, anepoll_waitvariant that takes a struct timespec to enable nanosecond resolution timeout.
Quoted 7 lines
Quoted 4 lines
int epoll_pwait2(int fd, struct
epoll_event*events,
int maxevents,
const struct timespec *timeout, constsigset_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
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
Quoted 27 lines · Michael Kerrisk (man-pages)
Hi Florian,
Quoted 8 lines · Florian Weimer
* Willem de Bruijn:
Quoted 5 lines
From: Willem de Bruijn <[email protected]>
Expand the
epoll_waitpage withepoll_pwait2, anepoll_waitvariant that takes a struct timespec to enable nanosecond resolution timeout.Quoted 7 lines
Quoted 4 lines
int epoll_pwait2(int fd, struct
epoll_event*events,
int maxevents,
const struct timespec *timeout, constsigset_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, structepoll_event__user*, events,
int, maxevents, const struct__kernel_timespec__user
*, timeout,
Quoted 7 lines
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.