Oops, I mistyped the glibc list.  Below is included the original email.

---

On Mon, May 20, 2024 at 07:02:39AM GMT, Emanuele Torre wrote:

Hello.

Hi Emanuele,

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.

Hmmm.  Thanks!  We need to add its header.

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.

No.  That's an implementation detail, which shouldn't be abused.

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.

Yep, that's the kernel uapi header.  I didn't know glibc redistributes
those.

Anyway, we should indeed include <linux/pidfd.h> for this macro.

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.

Hmmm, I've CCed glibc for a question:  When you provide a macro like
this one, without providing a syscall wrapper, should we include the
glibc header or the kernel one?  Do you provide all kernel uapi macros,
or just select ones?

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.

Ahh, interesting.  I'm using glibc 2.38 and still don't have that one.
It seems added in 2.39.  We can directly document that in
pidfd_getfd(2).

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

No, usually we document the glibc wrapper in man2, unless there's a big
difference between the kernel syscall and the glibc wrapper.

Thanks for the detailed report!

Have a lovely day!
Alex

o/
 emanuele6

-- 
<https://www.alejandro-colomar.es/>