Re: For review: pidfd_open(2) manual page

* Michael Kerrisk:

SYNOPSIS
       int pidfd_open(pid_t pid, unsigned int flags);

Should this mention <sys/types.h> for pid_t?

ERRORS
       EINVAL flags is not 0.

       EINVAL pid is not valid.

       ESRCH  The process specified by pid does not exist.

Presumably, EMFILE and ENFILE are also possible errors, and so is
ENOMEM.

       A  PID  file descriptor can be monitored using poll(2), select(2),
       and epoll(7).  When the process that it refers to terminates,  the
       file descriptor indicates as readable.  Note, however, that in the
       current implementation, nothing can be read from the file descrip‐
       tor.

“is indicated as readable” or “becomes readable”?  Will reading block?

       The  pidfd_open()  system call is the preferred way of obtaining a
       PID file descriptor.  The alternative is to obtain a file descrip‐
       tor by opening a /proc/[pid] directory.  However, the latter tech‐
       nique is possible only if the proc(5) file system is mounted; fur‐
       thermore,  the  file  descriptor  obtained in this way is not pol‐
       lable.

One question is whether the glibc wrapper should fall back back to the
/proc subdirectory if it is not available.  Probably not.

       static
       int pidfd_open(pid_t pid, unsigned int flags)
       {
           return syscall(__NR_pidfd_open, pid, flags);
       }

Please call this function something else (not pidfd_open), so that the
example continues to work if glibc provides the system call wrapper.