[RESEND] RFC: pidfd_getfd(2) manual page

[RESEND] RFC: pidfd_getfd(2) manual page

[Michael Kerrisk (man-pages)]

[No response on my mail of a week ago, so I try again; the page
text is unchanged since the draft sent out on 31 March]

Hello Sargun et al.

I've taken a shot at writing a manual page for pidfd_getfd().
I would be happy to receive comments, suggestions for
improvements, etc. The text is as follows (the groff source 
is at the foot of this mail):

NAME
       pidfd_getfd  -  obtain  a  duplicate  of  another  process's  file
       descriptor

SYNOPSIS
       int pidfd_getfd(int pidfd, int targetfd, unsigned int flags);

DESCRIPTION
       The pidfd_getfd() system call allocates a new file  descriptor  in
       the  calling  process.  This new file descriptor is a duplicate of
       an existing file descriptor, targetfd, in the process referred  to
       by the PID file descriptor pidfd.

       The  duplicate  file  descriptor  refers  to  the  same  open file
       description (see open(2)) as the original file descriptor  in  the
       process referred to by pidfd.  The two file descriptors thus share
       file status flags and file offset.  Furthermore, operations on the
       underlying  file  object  (for  example, assigning an address to a
       socket object using bind(2)) can be equally be performed  via  the
       duplicate file descriptor.

       The  close-on-exec  flag  (FD_CLOEXEC; see fcntl(2)) is set on the
       file descriptor returned by pidfd_getfd().

       The flags argument is reserved for future use.  Currently, it must
       be specified as 0.

       Permission  to duplicate another process's file descriptor is gov‐
       erned by a ptrace access mode  PTRACE_MODE_ATTACH_REALCREDS  check
       (see ptrace(2)).

RETURN VALUE
       On  success,  pidfd_getfd() returns a nonnegative file descriptor.
       On error, -1 is returned and errno is set to indicate the cause of
       the error.

ERRORS
       EBADF  pidfd is not a valid PID file descriptor.

       EBADF  targetfd  is  not  an  open  file descriptor in the process
              referred to by pidfd.

       EINVAL flags is not 0.

       EMFILE The per-process limit on the number of open  file  descrip‐
              tors has been reached (see the description of RLIMIT_NOFILE
              in getrlimit(2)).

       ENFILE The system-wide limit on the total number of open files has
              been reached.

       ESRCH  The  process  referred to by pidfd does not exist (i.e., it
              has terminated and been waited on).

VERSIONS
       pidfd_getfd() first appeared in Linux 5.6.

CONFORMING TO
       pidfd_getfd() is Linux specific.

NOTES
       Currently, there is no glibc wrapper for this system call; call it
       using syscall(2).

       For a description of PID file descriptors, see pidfd_open(2).

SEE ALSO
       clone3(2), kcmp(2), pidfd_open(2)

Cheers,

Michael

.\" Copyright (c) 2020 by Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one.
.\"
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\" %%%LICENSE_END
.\"
.TH PIDFD_GETFD 2 2020-03-31 "Linux" "Linux Programmer's Manual"
.SH NAME
pidfd_getfd \- obtain a duplicate of another process's file descriptor
.SH SYNOPSIS
.nf
.BI "int pidfd_getfd(int " pidfd ", int " targetfd ", unsigned int " flags );
.fi
.SH DESCRIPTION
The
.BR pidfd_getfd ()
system call allocates a new file descriptor in the calling process.
This new file descriptor is a duplicate of an existing file descriptor,
.IR targetfd ,
in the process referred to by the PID file descriptor
.IR pidfd .
.PP
The duplicate file descriptor refers to the same open file description (see
.BR open (2))
as the original file descriptor in the process referred to by
.IR pidfd .
The two file descriptors thus share file status flags and file offset.
Furthermore, operations on the underlying file object
(for example, assigning an address to a socket object using
.BR bind (2))
can be equally be performed via the duplicate file descriptor.
.PP
The close-on-exec flag
.RB ( FD_CLOEXEC ;
see
.BR fcntl (2))
is set on the file descriptor returned by
.BR pidfd_getfd ().
.PP
The
.I flags
argument is reserved for future use.
Currently, it must be specified as 0.
.PP
Permission to duplicate another process's file descriptor
is governed by a ptrace access mode
.B PTRACE_MODE_ATTACH_REALCREDS
check (see
.BR ptrace (2)).
.SH RETURN VALUE
On success,
.BR pidfd_getfd ()
returns a nonnegative file descriptor.
On error, \-1 is returned and
.I errno
is set to indicate the cause of the error.
.SH ERRORS
.TP
.B EBADF
.I pidfd
is not a valid PID file descriptor.
.TP
.B EBADF
.I targetfd
is not an open file descriptor in the process referred to by
.IR pidfd .
.BR 
.TP
.B EINVAL
.I flags
is not 0.
.TP
.B EMFILE
The per-process limit on the number of open file descriptors has been reached
(see the description of
.BR RLIMIT_NOFILE
in
.BR getrlimit (2)).
.TP
.B ENFILE
The system-wide limit on the total number of open files has been reached.
.TP
.B ESRCH
The process referred to by
.I pidfd
does not exist
(i.e., it has terminated and been waited on).
.SH VERSIONS
.BR pidfd_getfd ()
first appeared in Linux 5.6.
.\" commit 8649c322f75c96e7ced2fec201e123b2b073bf09
.SH CONFORMING TO
.BR pidfd_getfd ()
is Linux specific.
.SH NOTES
Currently, there is no glibc wrapper for this system call; call it using
.BR syscall (2).
.PP
For a description of PID file descriptors, see
.BR pidfd_open (2).
.SH SEE ALSO
.BR clone3 (2),
.BR kcmp (2),
.BR pidfd_open (2)

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [RESEND] RFC: pidfd_getfd(2) manual page

[Christian Brauner]

On Tue, Apr 07, 2020 at 08:49:35PM +0200, Michael Kerrisk (man-pages) wrote:
> [No response on my mail of a week ago, so I try again; the page
> text is unchanged since the draft sent out on 31 March]

Sorry for the delay.

> 
> Hello Sargun et al.
> 
> I've taken a shot at writing a manual page for pidfd_getfd().
> I would be happy to receive comments, suggestions for
> improvements, etc. The text is as follows (the groff source 
> is at the foot of this mail):

Thanks for that! Really appreciated. Just a few nits below.

> 
> NAME
>        pidfd_getfd  -  obtain  a  duplicate  of  another  process's  file
>        descriptor
> 
> SYNOPSIS
>        int pidfd_getfd(int pidfd, int targetfd, unsigned int flags);
> 
> DESCRIPTION
>        The pidfd_getfd() system call allocates a new file  descriptor  in
>        the  calling  process.  This new file descriptor is a duplicate of
>        an existing file descriptor, targetfd, in the process referred  to
>        by the PID file descriptor pidfd.
> 
>        The  duplicate  file  descriptor  refers  to  the  same  open file
>        description (see open(2)) as the original file descriptor  in  the
>        process referred to by pidfd.  The two file descriptors thus share
>        file status flags and file offset.  Furthermore, operations on the
>        underlying  file  object  (for  example, assigning an address to a
>        socket object using bind(2)) can be equally be performed  via  the

s/can be equally be performed/can be equally performed
?

>        duplicate file descriptor.
> 
>        The  close-on-exec  flag  (FD_CLOEXEC; see fcntl(2)) is set on the
>        file descriptor returned by pidfd_getfd().
> 
>        The flags argument is reserved for future use.  Currently, it must
>        be specified as 0.
> 
>        Permission  to duplicate another process's file descriptor is gov‐
>        erned by a ptrace access mode  PTRACE_MODE_ATTACH_REALCREDS  check
>        (see ptrace(2)).
> 
> RETURN VALUE
>        On  success,  pidfd_getfd() returns a nonnegative file descriptor.

Imho, this makes it sound like there are negative file descriptor
numbers. But as a non-native speaker that might just be a subtle
misreading on my part. Maybe just like open() just mention:
"On success, pidfd_getfd() returns a file descriptor."

>        On error, -1 is returned and errno is set to indicate the cause of
>        the error.
> 
> ERRORS
>        EBADF  pidfd is not a valid PID file descriptor.
> 
>        EBADF  targetfd  is  not  an  open  file descriptor in the process
>               referred to by pidfd.
> 
>        EINVAL flags is not 0.
> 
>        EMFILE The per-process limit on the number of open  file  descrip‐
>               tors has been reached (see the description of RLIMIT_NOFILE
>               in getrlimit(2)).
> 
>        ENFILE The system-wide limit on the total number of open files has
>               been reached.
> 
>        ESRCH  The  process  referred to by pidfd does not exist (i.e., it
>               has terminated and been waited on).

EPERM	The calling process did not have PTRACE_MODE_ATTACH_REALCREDS
	permissions (see ptrace(2)) over the process referred to by
	pidfd.

Technically, there should also be a disclaimer that other errno values
are possible because of LSM denials, e.g. selinux could return EACCES or
any other errno code in their file_receive() hook. But I'm not whether we
generally do this. In any case, I would find it useful as a developer.

(Is there actually a place where all LSMs are forced to record their
errno returns for their security hooks for each syscall they hook into and
that's visible to userspace? Because that'd be really useful...)

Christian

Re: [RESEND] RFC: pidfd_getfd(2) manual page

[Michael Kerrisk (man-pages)]

Hello Christian,

On Wed, 8 Apr 2020 at 09:45, Christian Brauner
<christian.brauner@ubuntu.com> wrote:
>
> On Tue, Apr 07, 2020 at 08:49:35PM +0200, Michael Kerrisk (man-pages) wrote:
> > [No response on my mail of a week ago, so I try again; the page
> > text is unchanged since the draft sent out on 31 March]
>
> Sorry for the delay.
>
> >
> > Hello Sargun et al.
> >
> > I've taken a shot at writing a manual page for pidfd_getfd().
> > I would be happy to receive comments, suggestions for
> > improvements, etc. The text is as follows (the groff source
> > is at the foot of this mail):
>
> Thanks for that! Really appreciated. Just a few nits below.

Thanks for the review!

> > NAME
> >        pidfd_getfd  -  obtain  a  duplicate  of  another  process's  file
> >        descriptor
> >
> > SYNOPSIS
> >        int pidfd_getfd(int pidfd, int targetfd, unsigned int flags);
> >
> > DESCRIPTION
> >        The pidfd_getfd() system call allocates a new file  descriptor  in
> >        the  calling  process.  This new file descriptor is a duplicate of
> >        an existing file descriptor, targetfd, in the process referred  to
> >        by the PID file descriptor pidfd.
> >
> >        The  duplicate  file  descriptor  refers  to  the  same  open file
> >        description (see open(2)) as the original file descriptor  in  the
> >        process referred to by pidfd.  The two file descriptors thus share
> >        file status flags and file offset.  Furthermore, operations on the
> >        underlying  file  object  (for  example, assigning an address to a
> >        socket object using bind(2)) can be equally be performed  via  the
>
> s/can be equally be performed/can be equally performed
> ?

Thanks. I made it: "can equally be performed"

> >        duplicate file descriptor.
> >
> >        The  close-on-exec  flag  (FD_CLOEXEC; see fcntl(2)) is set on the
> >        file descriptor returned by pidfd_getfd().
> >
> >        The flags argument is reserved for future use.  Currently, it must
> >        be specified as 0.
> >
> >        Permission  to duplicate another process's file descriptor is gov‐
> >        erned by a ptrace access mode  PTRACE_MODE_ATTACH_REALCREDS  check
> >        (see ptrace(2)).
> >
> > RETURN VALUE
> >        On  success,  pidfd_getfd() returns a nonnegative file descriptor.
>
> Imho, this makes it sound like there are negative file descriptor
> numbers. But as a non-native speaker that might just be a subtle
> misreading on my part. Maybe just like open() just mention:
> "On success, pidfd_getfd() returns a file descriptor."

You're right. That wording is just clumsy! I fixed it.

    On success, pidfd_getfd() returns a file descriptor (a
    nonnegative integer).

And I also fixed similar clumsy wordings in a number of other pages.

> >        On error, -1 is returned and errno is set to indicate the cause of
> >        the error.
> >
> > ERRORS
> >        EBADF  pidfd is not a valid PID file descriptor.
> >
> >        EBADF  targetfd  is  not  an  open  file descriptor in the process
> >               referred to by pidfd.
> >
> >        EINVAL flags is not 0.
> >
> >        EMFILE The per-process limit on the number of open  file  descrip‐
> >               tors has been reached (see the description of RLIMIT_NOFILE
> >               in getrlimit(2)).
> >
> >        ENFILE The system-wide limit on the total number of open files has
> >               been reached.
> >
> >        ESRCH  The  process  referred to by pidfd does not exist (i.e., it
> >               has terminated and been waited on).
>
> EPERM   The calling process did not have PTRACE_MODE_ATTACH_REALCREDS
>         permissions (see ptrace(2)) over the process referred to by
>         pidfd.

Oh yes. Thanks. Added.

> Technically, there should also be a disclaimer that other errno values
> are possible because of LSM denials, e.g. selinux could return EACCES or
> any other errno code in their file_receive() hook. But I'm not whether we
> generally do this. In any case, I would find it useful as a developer.

No, the manual pages don't generally include this. Mainly because I
just don't know all the details.

> (Is there actually a place where all LSMs are forced to record their
> errno returns for their security hooks for each syscall they hook into and
> that's visible to userspace? Because that'd be really useful...)

Nothing that I'm aware of, unfortunately.

Thanks again for the review!

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

AW: [RESEND] RFC: pidfd_getfd(2) manual page

[Walter Harms]

________________________________________
Von: linux-man-owner@vger.kernel.org <linux-man-owner@vger.kernel.org> im Auftrag von Michael Kerrisk (man-pages) <mtk.manpages@gmail.com>
Gesendet: Mittwoch, 8. April 2020 10:32
An: Christian Brauner
Cc: Sargun Dhillon; linux-man; Linux API; lkml; Tycho Andersen; Jann Horn; Aleksa Sarai; Christian Brauner; Oleg Nesterov; Andy Lutomirski; Alexander Viro; jld@mozilla.com; Arnd Bergmann; Florian Weimer; gpascutto@mozilla.com; ealvarez@mozilla.com
Betreff: Re: [RESEND] RFC: pidfd_getfd(2) manual page

Hello Christian,

On Wed, 8 Apr 2020 at 09:45, Christian Brauner
<christian.brauner@ubuntu.com> wrote:
>
> On Tue, Apr 07, 2020 at 08:49:35PM +0200, Michael Kerrisk (man-pages) wrote:
> > [No response on my mail of a week ago, so I try again; the page
> > text is unchanged since the draft sent out on 31 March]
>
> Sorry for the delay.
>
> >
> > Hello Sargun et al.
> >
> > I've taken a shot at writing a manual page for pidfd_getfd().
> > I would be happy to receive comments, suggestions for
> > improvements, etc. The text is as follows (the groff source
> > is at the foot of this mail):
>
> Thanks for that! Really appreciated. Just a few nits below.

Thanks for the review!

> > NAME
> >        pidfd_getfd  -  obtain  a  duplicate  of  another  process's  file
> >        descriptor
> >
> > SYNOPSIS
> >        int pidfd_getfd(int pidfd, int targetfd, unsigned int flags);
> >
> > DESCRIPTION
> >        The pidfd_getfd() system call allocates a new file  descriptor  in
> >        the  calling  process.  This new file descriptor is a duplicate of
> >        an existing file descriptor, targetfd, in the process referred  to
> >        by the PID file descriptor pidfd.
> >
> >        The  duplicate  file  descriptor  refers  to  the  same  open file
> >        description (see open(2)) as the original file descriptor  in  the
> >        process referred to by pidfd.  The two file descriptors thus share
> >        file status flags and file offset.  Furthermore, operations on the
> >        underlying  file  object  (for  example, assigning an address to a
> >        socket object using bind(2)) can be equally be performed  via  the
>
> s/can be equally be performed/can be equally performed
> ?

Thanks. I made it: "can equally be performed"

> >        duplicate file descriptor.
> >
> >        The  close-on-exec  flag  (FD_CLOEXEC; see fcntl(2)) is set on the
> >        file descriptor returned by pidfd_getfd().
> >
> >        The flags argument is reserved for future use.  Currently, it must
> >        be specified as 0.
> >
> >        Permission  to duplicate another process's file descriptor is gov‐
> >        erned by a ptrace access mode  PTRACE_MODE_ATTACH_REALCREDS  check
> >        (see ptrace(2)).
> >
> > RETURN VALUE
> >        On  success,  pidfd_getfd() returns a nonnegative file descriptor.
>
> Imho, this makes it sound like there are negative file descriptor
> numbers. But as a non-native speaker that might just be a subtle
> misreading on my part. Maybe just like open() just mention:
> "On success, pidfd_getfd() returns a file descriptor."

You're right. That wording is just clumsy! I fixed it.

    On success, pidfd_getfd() returns a file descriptor (a
    nonnegative integer).

And I also fixed similar clumsy wordings in a number of other pages.


perhaps "greater or equal 0" instead on nonnegativ, people are
bad with negations.
re,
 wh

> >        On error, -1 is returned and errno is set to indicate the cause of
> >        the error.
> >
> > ERRORS
> >        EBADF  pidfd is not a valid PID file descriptor.
> >
> >        EBADF  targetfd  is  not  an  open  file descriptor in the process
> >               referred to by pidfd.
> >
> >        EINVAL flags is not 0.
> >
> >        EMFILE The per-process limit on the number of open  file  descrip‐
> >               tors has been reached (see the description of RLIMIT_NOFILE
> >               in getrlimit(2)).
> >
> >        ENFILE The system-wide limit on the total number of open files has
> >               been reached.
> >
> >        ESRCH  The  process  referred to by pidfd does not exist (i.e., it
> >               has terminated and been waited on).
>
> EPERM   The calling process did not have PTRACE_MODE_ATTACH_REALCREDS
>         permissions (see ptrace(2)) over the process referred to by
>         pidfd.

Oh yes. Thanks. Added.

> Technically, there should also be a disclaimer that other errno values
> are possible because of LSM denials, e.g. selinux could return EACCES or
> any other errno code in their file_receive() hook. But I'm not whether we
> generally do this. In any case, I would find it useful as a developer.

No, the manual pages don't generally include this. Mainly because I
just don't know all the details.

> (Is there actually a place where all LSMs are forced to record their
> errno returns for their security hooks for each syscall they hook into and
> that's visible to userspace? Because that'd be really useful...)

Nothing that I'm aware of, unfortunately.

Thanks again for the review!

Cheers,

Michael


--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/