Skip to contentSkip to conversation

epoll_wait.2: add epoll_pwait2

PATCH In review Willem de Bruijn 3 participants 5 messages Jan 12, 2021

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

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
index 36001e02bde3..21d63503a87f 100644
@@ -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
#1 lore raw

Hello Willem,

Quoted 11 lines · Willem de Bruijn

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);

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_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
index 36001e02bde3..21d63503a87f 100644
@@ -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/
#2 lore raw
In reply to Willem de Bruijn

* Willem de Bruijn:

Quoted 9 lines

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);

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
#3 lore raw

Hi Florian,

Quoted 8 lines · Florian Weimer

* Willem de Bruijn:

Quoted 5 lines

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.

Quoted 7 lines
Quoted 4 lines

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

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/
#4 lore raw
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_wait page with epoll_pwait2, an epoll_wait variant 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, 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,

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.