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

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

[Emanuele Torre]

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

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

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 2138 bytes --]

Hi Emanuele,

On 2023-08-25 01:25, Emanuele Torre wrote:
> 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.

Would you mind sending a patch?  If you do, please include in the commit
message the source code _and_ the execution of all of the programs you
mentioned above.

Thanks,
Alex

> 
> Thank you.
> 
> o/
>  emanuele6

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]