pidfd_open.2: PIDFD_NONBLOCK is not defined by the listed headers

[Emanuele Torre <torreemanuele6@gmail.com>]

Hello.


pidfd_open(2) only lists sys/syscall.h and unistd.h in its SYNOPSYS:

  SYNOPSIS
         #include <sys/syscall.h>      /* Definition of SYS_* constants */
         #include <unistd.h>

         int syscall(SYS_pidfd_open, pid_t pid, unsigned int flags);

         Note:  glibc provides no wrapper for pidfd_open(), necessitating
         the use of syscall(2).

Then it mentions PIDFD_NONBLOCK as one of its flags:

  PIDFD_NONBLOCK (since Linux 5.10)
         Return  a nonblocking file descriptor.  If the process referred
         to by the file descriptor has not yet terminated, then  an  at‐
         tempt to wait on the file descriptor using waitid(2) will imme‐
         diately return the error EAGAIN rather than blocking.

But PIDFD_NONBLOCK is not defined in any of the listed headers.


I have noticed that PIDFD_NONBLOCK is the same value as O_NONBLOCK,
so perhaps this flag could be listed as

  O_NONBLOCK or PIDFD_NONBLOCK (since Linux 5.10)

like O_NDELAY and O_NONBLOCK in open.2.

This way the user would know that O_NONBLOCK may be used instead of
PIDFD_NONBLOCK if PIDFD_NONBLOCK is not available.


I have also noticed that GNU libc (in its linux-api-headers submodule)
provides a linux/pidfd.h header that just defines PIDFD_NONBLOCK as
O_NONBLOCK, perhaps another solution would be to list in linux/pidfd.h
in the synopsis and say it is required to use PIDFD_NONBLOCK.


Then, I also noticed that GNU libc now also provides the sys/pidfd.h
header with the definition of PIDFD_NONBLOCK, and prototypes for
pidfd_open, pidfd_send_signal, pidfd_getfd, and also a prototype for
pidfd_getpid that is an helper function that parses the "Pid:" field
from /proc/self/fdinfo/FD and currently does not have a man page.

So probably the best solution is to just make the pidfd_open(2),
pidfd_send_signal(2), and pidfd_getfd(2) man pages tell users to include
sys/pidfd.h and call the GNU libc functions instead of including
sys/syscall.h and unistd.h and calling syscall(2) directly; now that
sys/pidfd.h exists.

And maybe to also add a pidfd_getpid(3) man page for the new pidfd
helper function.


o/
 emanuele6