[man-pages] pidfd_send_signal(2) innacurately describes how to get a pidfd

[Emanuele Torre <torreemanuele6@gmail.com>]

Hi.

Today, I was reading pidfd_send_signal(2), and I was suprised to see it
mentioning that you can get a PID file descriptor by opening a /proc/pid
directory.

  NOTES
    PID file descriptors
      The pidfd argument is a PID file descriptor, a file descriptor
      that refers to  process.  Such a file descriptor can be obtained
      in any of the following ways:
       .  by opening a /proc/pid directory;
       .  using pidfd_open(2); or
       .  via the PID file descriptor that is returned by a call to
          clone(2) or clone3(2) that specifies the CLONE_PIDFD flag.

Unfortunately, if you open /proc/123, you don't get a pidfd for the
process with pid 123; as expected, you will just get a directory file
descriptor for /proc/123.

And that directory file descriptor won't be usable as a PID file
descriptor either.
(openpidfd, and pidfdgetfd are just simple wrappers for pidfd_open, and
pidfd_getfd)

  $ pidfdgetfd 9 0 0 echo hello 9</proc/1584616
  pidfd_getfd: Bad file descriptor
  $ # you must use pidfd_open
  $ openpidfd 9 1584616 pidfdgetfd 9 0 0 echo hello
  hello

I also wrote a test program that uses a /proc/pid directory file
descriptor as pidfd for  waitid(P_PID)  and that also didnd't work
(waitid fails with EINVAL).

But those directory file descriptors do work as alternative to actual
pidfds for  pidfd_send_signal(2)  specifically.

I think the documentation should be changed to say that
pidfd_send_signal accepts either a PID file descriptor (obtainable using
pidfd_open or CLONE_PIDFD), or, alternatively, a file descriptor for a
/proc/pid directory to avoid confusions.

Thank you.

o/
 emanuele6