From: Christian Brauner <christian.brauner@ubuntu.com>
To: "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>
Cc: Sargun Dhillon <sargun@sargun.me>,
linux-man <linux-man@vger.kernel.org>,
Linux API <linux-api@vger.kernel.org>,
lkml <linux-kernel@vger.kernel.org>,
Tycho Andersen <tycho@tycho.ws>, Jann Horn <jannh@google.com>,
Aleksa Sarai <cyphar@cyphar.com>,
Christian Brauner <christian@brauner.io>,
Oleg Nesterov <oleg@redhat.com>,
Andy Lutomirski <luto@amacapital.net>,
Alexander Viro <viro@zeniv.linux.org.uk>,
jld@mozilla.com, Arnd Bergmann <arnd@arndb.de>,
Florian Weimer <fweimer@redhat.com>,
gpascutto@mozilla.com, ealvarez@mozilla.com
Subject: Re: [RESEND] RFC: pidfd_getfd(2) manual page
Date: Wed, 8 Apr 2020 09:44:59 +0200 [thread overview]
Message-ID: <20200408074459.q3njmvizjge7timg@wittgenstein> (raw)
In-Reply-To: <d6be97d1-38a5-bf43-7c80-7c952a5a44a3@gmail.com>
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
next prev parent reply other threads:[~2020-04-08 7:45 UTC|newest]
Thread overview: 4+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-04-07 18:49 [RESEND] RFC: pidfd_getfd(2) manual page Michael Kerrisk (man-pages)
2020-04-08 7:44 ` Christian Brauner [this message]
2020-04-08 8:32 ` Michael Kerrisk (man-pages)
2020-04-08 10:58 ` AW: " Walter Harms
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20200408074459.q3njmvizjge7timg@wittgenstein \
--to=christian.brauner@ubuntu.com \
--cc=arnd@arndb.de \
--cc=christian@brauner.io \
--cc=cyphar@cyphar.com \
--cc=ealvarez@mozilla.com \
--cc=fweimer@redhat.com \
--cc=gpascutto@mozilla.com \
--cc=jannh@google.com \
--cc=jld@mozilla.com \
--cc=linux-api@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-man@vger.kernel.org \
--cc=luto@amacapital.net \
--cc=mtk.manpages@gmail.com \
--cc=oleg@redhat.com \
--cc=sargun@sargun.me \
--cc=tycho@tycho.ws \
--cc=viro@zeniv.linux.org.uk \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).