pidfd_open.2: New page documenting pidfd_open(2)
Notes from a conversation on linux-man@ with Christian Brauner:
[[
> [*} By the way, going forward, can we call these things
> "process FDs", rather than "PID FDs"? The API names are what
> they are, an that's okay, but these just as we have socket
> FDs that refer to sockets, directory FDs that refer to
> directories, and timer FDs that refer to timers, and so on,
> these are FDs that refer to *processes*, not "process IDs".
> It's a little thing, but I think the naming better, and
> it's what I propose to use in the manual pages.
The naming was another debate and we ended with this compromise.
I would just clarify that a pidfd is a process file descriptor. I
wouldn't make too much of a deal of hiding the shortcut "pidfd".
People are already using it out there in the wild and it's never
proven a good idea to go against accepted practice.
]]
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-22 21:05:48 +00:00
|
|
|
.\" Copyright (c) 2019 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
|
|
|
|
.\"
|
iconv.1, ldd.1, accept.2, access.2, add_key.2, arch_prctl.2, bpf.2, chmod.2, chown.2, close_range.2, copy_file_range.2, execve.2, execveat.2, fanotify_mark.2, futex.2, futimesat.2, getpriority.2, intro.2, ioctl_tty.2, keyctl.2, link.2, membarrier.2, mkdir.2, mknod.2, mlock.2, mount.2, mount_setattr.2, open.2, open_by_handle_at.2, perf_event_open.2, pidfd_open.2, readlink.2, readv.2, rename.2, request_key.2, seccomp.2, sigaction.2, stat.2, statx.2, symlink.2, syscalls.2, umount.2, unlink.2, utimensat.2, wait.2, bsearch.3, fflush.3, getaddrinfo.3, getauxval.3, getopt.3, getsubopt.3, mkfifo.3, pthread_mutex_consistent.3, pthread_setname_np.3, pthread_tryjoin_np.3, scandir.3, sem_wait.3, stailq.3, strlen.3, strstr.3, termios.3, tsearch.3, wcslen.3, wcstok.3, wordexp.3, proc.5, capabilities.7, cgroups.7, fanotify.7, mount_namespaces.7, namespaces.7, path_resolution.7, pipe.7, posixoptions.7, user_namespaces.7, vdso.7, iconvconfig.8, ld.so.8: tstamp
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2021-08-27 00:44:07 +00:00
|
|
|
.TH PIDFD_OPEN 2 2021-08-27 "Linux" "Linux Programmer's Manual"
|
pidfd_open.2: New page documenting pidfd_open(2)
Notes from a conversation on linux-man@ with Christian Brauner:
[[
> [*} By the way, going forward, can we call these things
> "process FDs", rather than "PID FDs"? The API names are what
> they are, an that's okay, but these just as we have socket
> FDs that refer to sockets, directory FDs that refer to
> directories, and timer FDs that refer to timers, and so on,
> these are FDs that refer to *processes*, not "process IDs".
> It's a little thing, but I think the naming better, and
> it's what I propose to use in the manual pages.
The naming was another debate and we ended with this compromise.
I would just clarify that a pidfd is a process file descriptor. I
wouldn't make too much of a deal of hiding the shortcut "pidfd".
People are already using it out there in the wild and it's never
proven a good idea to go against accepted practice.
]]
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-22 21:05:48 +00:00
|
|
|
.SH NAME
|
|
|
|
pidfd_open \- obtain a file descriptor that refers to a process
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.nf
|
2021-05-10 17:55:39 +00:00
|
|
|
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
|
|
|
|
.B #include <unistd.h>
|
|
|
|
.PP
|
|
|
|
.BI "int syscall(SYS_pidfd_open, pid_t " pid ", unsigned int " flags );
|
pidfd_open.2: New page documenting pidfd_open(2)
Notes from a conversation on linux-man@ with Christian Brauner:
[[
> [*} By the way, going forward, can we call these things
> "process FDs", rather than "PID FDs"? The API names are what
> they are, an that's okay, but these just as we have socket
> FDs that refer to sockets, directory FDs that refer to
> directories, and timer FDs that refer to timers, and so on,
> these are FDs that refer to *processes*, not "process IDs".
> It's a little thing, but I think the naming better, and
> it's what I propose to use in the manual pages.
The naming was another debate and we ended with this compromise.
I would just clarify that a pidfd is a process file descriptor. I
wouldn't make too much of a deal of hiding the shortcut "pidfd".
People are already using it out there in the wild and it's never
proven a good idea to go against accepted practice.
]]
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-22 21:05:48 +00:00
|
|
|
.fi
|
Various pages: Normalize SYNOPSIS notes about nonexistent glibc wrappers
To easily distinguish documentation about glibc wrappers from
documentation about kernel syscalls, let's have a normalized
'Note' in the SYNOPSIS, and a further explanation in the page body
(NOTES in most of them), as already happened in many (but not all)
of the manual pages for syscalls without a wrapper. Furthermore,
let's normalize the messages, following membarrier.2 (because it's
already quite extended), so that it's easy to use grep to find
those pages.
To find these pages, we used:
$ grep -rn wrapper man? | sort -V
and
$ grep -rni support.*glibc | sort -V
delete_module.2, init_module.2: glibc 2.23 is no longer
maintained, so we changed the notes about wrappers, to say that
there are no glibc wrappers for these system calls; see NOTES.
We didn't fix some obsolete pages such as create_module.2.
Signed-off-by: Ganimedes Colomar <gacoan.linux@gmail.com>
Cowritten-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-30 15:20:25 +00:00
|
|
|
.PP
|
|
|
|
.IR Note :
|
2021-05-10 17:55:39 +00:00
|
|
|
glibc provides no wrapper for
|
|
|
|
.BR pidfd_open (),
|
|
|
|
necessitating the use of
|
|
|
|
.BR syscall (2).
|
pidfd_open.2: New page documenting pidfd_open(2)
Notes from a conversation on linux-man@ with Christian Brauner:
[[
> [*} By the way, going forward, can we call these things
> "process FDs", rather than "PID FDs"? The API names are what
> they are, an that's okay, but these just as we have socket
> FDs that refer to sockets, directory FDs that refer to
> directories, and timer FDs that refer to timers, and so on,
> these are FDs that refer to *processes*, not "process IDs".
> It's a little thing, but I think the naming better, and
> it's what I propose to use in the manual pages.
The naming was another debate and we ended with this compromise.
I would just clarify that a pidfd is a process file descriptor. I
wouldn't make too much of a deal of hiding the shortcut "pidfd".
People are already using it out there in the wild and it's never
proven a good idea to go against accepted practice.
]]
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-22 21:05:48 +00:00
|
|
|
.SH DESCRIPTION
|
|
|
|
The
|
|
|
|
.BR pidfd_open ()
|
2019-09-23 19:35:13 +00:00
|
|
|
system call creates a file descriptor that refers to
|
pidfd_open.2: New page documenting pidfd_open(2)
Notes from a conversation on linux-man@ with Christian Brauner:
[[
> [*} By the way, going forward, can we call these things
> "process FDs", rather than "PID FDs"? The API names are what
> they are, an that's okay, but these just as we have socket
> FDs that refer to sockets, directory FDs that refer to
> directories, and timer FDs that refer to timers, and so on,
> these are FDs that refer to *processes*, not "process IDs".
> It's a little thing, but I think the naming better, and
> it's what I propose to use in the manual pages.
The naming was another debate and we ended with this compromise.
I would just clarify that a pidfd is a process file descriptor. I
wouldn't make too much of a deal of hiding the shortcut "pidfd".
People are already using it out there in the wild and it's never
proven a good idea to go against accepted practice.
]]
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-22 21:05:48 +00:00
|
|
|
the process whose PID is specified in
|
|
|
|
.IR pid .
|
|
|
|
The file descriptor is returned as the function result;
|
|
|
|
the close-on-exec flag is set on the file descriptor.
|
|
|
|
.PP
|
|
|
|
The
|
|
|
|
.I flags
|
2021-08-10 23:48:02 +00:00
|
|
|
argument either has the value 0, or contains the following flag:
|
|
|
|
.TP
|
|
|
|
.BR PIDFD_NONBLOCK " (since Linux 5.10)"
|
|
|
|
.\" commit 4da9af0014b51c8b015ed8c622440ef28912efe6
|
|
|
|
Return a nonblocking file descriptor.
|
|
|
|
If the process referred to by the file descriptor has not yet terminated,
|
|
|
|
then an attempt to wait on the file descriptor using
|
|
|
|
.BR waitid (2)
|
|
|
|
will immediately return the error
|
|
|
|
.BR EAGAIN
|
|
|
|
rather than blocking.
|
pidfd_open.2: New page documenting pidfd_open(2)
Notes from a conversation on linux-man@ with Christian Brauner:
[[
> [*} By the way, going forward, can we call these things
> "process FDs", rather than "PID FDs"? The API names are what
> they are, an that's okay, but these just as we have socket
> FDs that refer to sockets, directory FDs that refer to
> directories, and timer FDs that refer to timers, and so on,
> these are FDs that refer to *processes*, not "process IDs".
> It's a little thing, but I think the naming better, and
> it's what I propose to use in the manual pages.
The naming was another debate and we ended with this compromise.
I would just clarify that a pidfd is a process file descriptor. I
wouldn't make too much of a deal of hiding the shortcut "pidfd".
People are already using it out there in the wild and it's never
proven a good idea to go against accepted practice.
]]
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-22 21:05:48 +00:00
|
|
|
.SH RETURN VALUE
|
|
|
|
On success,
|
|
|
|
.BR pidfd_open ()
|
2020-04-08 08:28:45 +00:00
|
|
|
returns a file descriptor (a nonnegative integer).
|
2019-09-23 19:35:13 +00:00
|
|
|
On error, \-1 is returned and
|
pidfd_open.2: New page documenting pidfd_open(2)
Notes from a conversation on linux-man@ with Christian Brauner:
[[
> [*} By the way, going forward, can we call these things
> "process FDs", rather than "PID FDs"? The API names are what
> they are, an that's okay, but these just as we have socket
> FDs that refer to sockets, directory FDs that refer to
> directories, and timer FDs that refer to timers, and so on,
> these are FDs that refer to *processes*, not "process IDs".
> It's a little thing, but I think the naming better, and
> it's what I propose to use in the manual pages.
The naming was another debate and we ended with this compromise.
I would just clarify that a pidfd is a process file descriptor. I
wouldn't make too much of a deal of hiding the shortcut "pidfd".
People are already using it out there in the wild and it's never
proven a good idea to go against accepted practice.
]]
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-22 21:05:48 +00:00
|
|
|
.I errno
|
2021-01-07 06:50:50 +00:00
|
|
|
is set to indicate the error.
|
pidfd_open.2: New page documenting pidfd_open(2)
Notes from a conversation on linux-man@ with Christian Brauner:
[[
> [*} By the way, going forward, can we call these things
> "process FDs", rather than "PID FDs"? The API names are what
> they are, an that's okay, but these just as we have socket
> FDs that refer to sockets, directory FDs that refer to
> directories, and timer FDs that refer to timers, and so on,
> these are FDs that refer to *processes*, not "process IDs".
> It's a little thing, but I think the naming better, and
> it's what I propose to use in the manual pages.
The naming was another debate and we ended with this compromise.
I would just clarify that a pidfd is a process file descriptor. I
wouldn't make too much of a deal of hiding the shortcut "pidfd".
People are already using it out there in the wild and it's never
proven a good idea to go against accepted practice.
]]
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-22 21:05:48 +00:00
|
|
|
.SH ERRORS
|
|
|
|
.TP
|
|
|
|
.B EINVAL
|
|
|
|
.I flags
|
2021-08-10 23:48:02 +00:00
|
|
|
is not valid.
|
pidfd_open.2: New page documenting pidfd_open(2)
Notes from a conversation on linux-man@ with Christian Brauner:
[[
> [*} By the way, going forward, can we call these things
> "process FDs", rather than "PID FDs"? The API names are what
> they are, an that's okay, but these just as we have socket
> FDs that refer to sockets, directory FDs that refer to
> directories, and timer FDs that refer to timers, and so on,
> these are FDs that refer to *processes*, not "process IDs".
> It's a little thing, but I think the naming better, and
> it's what I propose to use in the manual pages.
The naming was another debate and we ended with this compromise.
I would just clarify that a pidfd is a process file descriptor. I
wouldn't make too much of a deal of hiding the shortcut "pidfd".
People are already using it out there in the wild and it's never
proven a good idea to go against accepted practice.
]]
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-22 21:05:48 +00:00
|
|
|
.TP
|
|
|
|
.B EINVAL
|
|
|
|
.I pid
|
|
|
|
is not valid.
|
|
|
|
.TP
|
2019-09-23 20:10:38 +00:00
|
|
|
.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 ENODEV
|
|
|
|
The anonymous inode filesystem is not available in this kernel.
|
|
|
|
.TP
|
|
|
|
.B ENOMEM
|
|
|
|
Insufficient kernel memory was available.
|
|
|
|
.TP
|
pidfd_open.2: New page documenting pidfd_open(2)
Notes from a conversation on linux-man@ with Christian Brauner:
[[
> [*} By the way, going forward, can we call these things
> "process FDs", rather than "PID FDs"? The API names are what
> they are, an that's okay, but these just as we have socket
> FDs that refer to sockets, directory FDs that refer to
> directories, and timer FDs that refer to timers, and so on,
> these are FDs that refer to *processes*, not "process IDs".
> It's a little thing, but I think the naming better, and
> it's what I propose to use in the manual pages.
The naming was another debate and we ended with this compromise.
I would just clarify that a pidfd is a process file descriptor. I
wouldn't make too much of a deal of hiding the shortcut "pidfd".
People are already using it out there in the wild and it's never
proven a good idea to go against accepted practice.
]]
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-22 21:05:48 +00:00
|
|
|
.B ESRCH
|
|
|
|
The process specified by
|
|
|
|
.I pid
|
|
|
|
does not exist.
|
|
|
|
.SH VERSIONS
|
|
|
|
.BR pidfd_open ()
|
|
|
|
first appeared in Linux 5.3.
|
|
|
|
.SH CONFORMING TO
|
|
|
|
.BR pidfd_open ()
|
|
|
|
is Linux specific.
|
|
|
|
.SH NOTES
|
2019-09-25 13:23:18 +00:00
|
|
|
The following code sequence can be used to obtain a file descriptor
|
|
|
|
for the child of
|
|
|
|
.BR fork (2):
|
|
|
|
.PP
|
|
|
|
.in +4n
|
|
|
|
.EX
|
|
|
|
pid = fork();
|
|
|
|
if (pid > 0) { /* If parent */
|
|
|
|
pidfd = pidfd_open(pid, 0);
|
|
|
|
...
|
|
|
|
}
|
|
|
|
.EE
|
|
|
|
.in
|
|
|
|
.PP
|
2019-09-25 13:59:12 +00:00
|
|
|
Even if the child has already terminated by the time of the
|
2019-09-25 13:23:18 +00:00
|
|
|
.BR pidfd_open ()
|
2019-09-25 13:59:12 +00:00
|
|
|
call, its PID will not have been recycled and the returned
|
|
|
|
file descriptor will refer to the resulting zombie process.
|
|
|
|
Note, however, that this is guaranteed only if the following
|
|
|
|
conditions hold true:
|
2020-06-15 13:02:05 +00:00
|
|
|
.IP \(bu 2
|
2019-09-25 13:59:12 +00:00
|
|
|
the disposition of
|
|
|
|
.BR SIGCHLD
|
|
|
|
has not been explicitly set to
|
|
|
|
.BR SIG_IGN
|
|
|
|
(see
|
|
|
|
.BR sigaction (2));
|
2020-06-15 13:02:05 +00:00
|
|
|
.IP \(bu
|
2019-09-25 14:16:58 +00:00
|
|
|
the
|
2019-10-30 09:23:10 +00:00
|
|
|
.BR SA_NOCLDWAIT
|
2019-09-25 14:16:58 +00:00
|
|
|
flag was not specified while establishing a handler for
|
|
|
|
.BR SIGCHLD
|
|
|
|
or while setting the disposition of that signal to
|
|
|
|
.BR SIG_DFL
|
|
|
|
(see
|
|
|
|
.BR sigaction (2));
|
2019-09-25 13:59:12 +00:00
|
|
|
and
|
2020-06-15 13:02:05 +00:00
|
|
|
.IP \(bu
|
2019-09-25 13:59:12 +00:00
|
|
|
the zombie process was not reaped elsewhere in the program
|
|
|
|
(e.g., either by an asynchronously executed signal handler or by
|
|
|
|
.BR wait (2)
|
|
|
|
or similar in another thread).
|
|
|
|
.PP
|
2019-09-25 14:03:12 +00:00
|
|
|
If any of these conditions does not hold,
|
2019-10-12 19:12:34 +00:00
|
|
|
then the child process (along with a PID file descriptor that refers to it)
|
|
|
|
should instead be created using
|
2019-09-25 13:59:12 +00:00
|
|
|
.BR clone (2)
|
|
|
|
with the
|
2019-09-25 14:01:32 +00:00
|
|
|
.BR CLONE_PIDFD
|
2019-09-25 13:59:12 +00:00
|
|
|
flag.
|
2019-10-12 19:14:58 +00:00
|
|
|
.\"
|
|
|
|
.SS Use cases for PID file descriptors
|
2019-10-12 19:18:40 +00:00
|
|
|
A PID file descriptor returned by
|
|
|
|
.BR pidfd_open ()
|
2020-02-23 00:39:56 +00:00
|
|
|
(or by
|
2019-10-12 19:18:40 +00:00
|
|
|
.BR clone (2)
|
|
|
|
with the
|
|
|
|
.BR CLONE_PID
|
|
|
|
flag) can be used for the following purposes:
|
2020-06-15 13:02:05 +00:00
|
|
|
.IP \(bu 2
|
pidfd_open.2: New page documenting pidfd_open(2)
Notes from a conversation on linux-man@ with Christian Brauner:
[[
> [*} By the way, going forward, can we call these things
> "process FDs", rather than "PID FDs"? The API names are what
> they are, an that's okay, but these just as we have socket
> FDs that refer to sockets, directory FDs that refer to
> directories, and timer FDs that refer to timers, and so on,
> these are FDs that refer to *processes*, not "process IDs".
> It's a little thing, but I think the naming better, and
> it's what I propose to use in the manual pages.
The naming was another debate and we ended with this compromise.
I would just clarify that a pidfd is a process file descriptor. I
wouldn't make too much of a deal of hiding the shortcut "pidfd".
People are already using it out there in the wild and it's never
proven a good idea to go against accepted practice.
]]
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-22 21:05:48 +00:00
|
|
|
The
|
|
|
|
.BR pidfd_send_signal (2)
|
|
|
|
system call can be used to send a signal to the process referred to by
|
|
|
|
a PID file descriptor.
|
2020-06-15 13:02:05 +00:00
|
|
|
.IP \(bu
|
pidfd_open.2: New page documenting pidfd_open(2)
Notes from a conversation on linux-man@ with Christian Brauner:
[[
> [*} By the way, going forward, can we call these things
> "process FDs", rather than "PID FDs"? The API names are what
> they are, an that's okay, but these just as we have socket
> FDs that refer to sockets, directory FDs that refer to
> directories, and timer FDs that refer to timers, and so on,
> these are FDs that refer to *processes*, not "process IDs".
> It's a little thing, but I think the naming better, and
> it's what I propose to use in the manual pages.
The naming was another debate and we ended with this compromise.
I would just clarify that a pidfd is a process file descriptor. I
wouldn't make too much of a deal of hiding the shortcut "pidfd".
People are already using it out there in the wild and it's never
proven a good idea to go against accepted practice.
]]
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-22 21:05:48 +00:00
|
|
|
A PID file descriptor can be monitored using
|
|
|
|
.BR poll (2),
|
|
|
|
.BR select (2),
|
|
|
|
and
|
|
|
|
.BR epoll (7).
|
|
|
|
When the process that it refers to terminates,
|
2019-09-23 19:27:01 +00:00
|
|
|
these interfaces indicate the file descriptor as readable.
|
pidfd_open.2: New page documenting pidfd_open(2)
Notes from a conversation on linux-man@ with Christian Brauner:
[[
> [*} By the way, going forward, can we call these things
> "process FDs", rather than "PID FDs"? The API names are what
> they are, an that's okay, but these just as we have socket
> FDs that refer to sockets, directory FDs that refer to
> directories, and timer FDs that refer to timers, and so on,
> these are FDs that refer to *processes*, not "process IDs".
> It's a little thing, but I think the naming better, and
> it's what I propose to use in the manual pages.
The naming was another debate and we ended with this compromise.
I would just clarify that a pidfd is a process file descriptor. I
wouldn't make too much of a deal of hiding the shortcut "pidfd".
People are already using it out there in the wild and it's never
proven a good idea to go against accepted practice.
]]
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-22 21:05:48 +00:00
|
|
|
Note, however, that in the current implementation,
|
2019-09-23 19:41:50 +00:00
|
|
|
nothing can be read from the file descriptor
|
|
|
|
.RB ( read (2)
|
|
|
|
on the file descriptor fails with the error
|
|
|
|
.BR EINVAL ).
|
2020-06-15 13:02:05 +00:00
|
|
|
.IP \(bu
|
2019-10-12 20:40:09 +00:00
|
|
|
If the PID file descriptor refers to a child of the calling process,
|
|
|
|
then it can be waited on using
|
|
|
|
.BR waitid (2).
|
2020-06-15 13:02:05 +00:00
|
|
|
.IP \(bu
|
2020-03-31 12:05:24 +00:00
|
|
|
The
|
|
|
|
.BR pidfd_getfd (2)
|
|
|
|
system call can be used to obtain a duplicate of a file descriptor
|
|
|
|
of another process referred to by a PID file descriptor.
|
2020-06-15 13:04:16 +00:00
|
|
|
.IP \(bu
|
|
|
|
A PID file descriptor can be used as the argument of
|
|
|
|
.BR setns (2)
|
|
|
|
in order to move into one or more of the same namespaces as the process
|
|
|
|
referred to by the file descriptor.
|
2021-02-02 08:17:27 +00:00
|
|
|
.IP \(bu
|
|
|
|
A PID file descriptor can be used as the argument of
|
|
|
|
.BR process_madvise (2)
|
|
|
|
in order to provide advice on the memory usage patterns of the process
|
|
|
|
referred to by the file descriptor.
|
pidfd_open.2: New page documenting pidfd_open(2)
Notes from a conversation on linux-man@ with Christian Brauner:
[[
> [*} By the way, going forward, can we call these things
> "process FDs", rather than "PID FDs"? The API names are what
> they are, an that's okay, but these just as we have socket
> FDs that refer to sockets, directory FDs that refer to
> directories, and timer FDs that refer to timers, and so on,
> these are FDs that refer to *processes*, not "process IDs".
> It's a little thing, but I think the naming better, and
> it's what I propose to use in the manual pages.
The naming was another debate and we ended with this compromise.
I would just clarify that a pidfd is a process file descriptor. I
wouldn't make too much of a deal of hiding the shortcut "pidfd".
People are already using it out there in the wild and it's never
proven a good idea to go against accepted practice.
]]
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-22 21:05:48 +00:00
|
|
|
.PP
|
2019-09-23 08:00:19 +00:00
|
|
|
The
|
|
|
|
.BR pidfd_open ()
|
2019-10-12 19:05:04 +00:00
|
|
|
system call is the preferred way of obtaining a PID file descriptor
|
|
|
|
for an already existing process.
|
2019-09-23 08:00:19 +00:00
|
|
|
The alternative is to obtain a file descriptor by opening a
|
|
|
|
.I /proc/[pid]
|
|
|
|
directory.
|
|
|
|
However, the latter technique is possible only if the
|
|
|
|
.BR proc (5)
|
2019-10-13 19:04:32 +00:00
|
|
|
filesystem is mounted;
|
2019-09-23 08:00:19 +00:00
|
|
|
furthermore, the file descriptor obtained in this way is
|
|
|
|
.I not
|
2019-10-12 20:40:09 +00:00
|
|
|
pollable and can't be waited on with
|
|
|
|
.BR waitid (2).
|
2020-05-21 08:00:37 +00:00
|
|
|
.SH EXAMPLES
|
pidfd_open.2: New page documenting pidfd_open(2)
Notes from a conversation on linux-man@ with Christian Brauner:
[[
> [*} By the way, going forward, can we call these things
> "process FDs", rather than "PID FDs"? The API names are what
> they are, an that's okay, but these just as we have socket
> FDs that refer to sockets, directory FDs that refer to
> directories, and timer FDs that refer to timers, and so on,
> these are FDs that refer to *processes*, not "process IDs".
> It's a little thing, but I think the naming better, and
> it's what I propose to use in the manual pages.
The naming was another debate and we ended with this compromise.
I would just clarify that a pidfd is a process file descriptor. I
wouldn't make too much of a deal of hiding the shortcut "pidfd".
People are already using it out there in the wild and it's never
proven a good idea to go against accepted practice.
]]
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-22 21:05:48 +00:00
|
|
|
The program below opens a PID file descriptor for the
|
|
|
|
process whose PID is specified as its command-line argument.
|
2019-09-23 20:07:21 +00:00
|
|
|
It then uses
|
pidfd_open.2: New page documenting pidfd_open(2)
Notes from a conversation on linux-man@ with Christian Brauner:
[[
> [*} By the way, going forward, can we call these things
> "process FDs", rather than "PID FDs"? The API names are what
> they are, an that's okay, but these just as we have socket
> FDs that refer to sockets, directory FDs that refer to
> directories, and timer FDs that refer to timers, and so on,
> these are FDs that refer to *processes*, not "process IDs".
> It's a little thing, but I think the naming better, and
> it's what I propose to use in the manual pages.
The naming was another debate and we ended with this compromise.
I would just clarify that a pidfd is a process file descriptor. I
wouldn't make too much of a deal of hiding the shortcut "pidfd".
People are already using it out there in the wild and it's never
proven a good idea to go against accepted practice.
]]
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-22 21:05:48 +00:00
|
|
|
.BR poll (2)
|
2019-09-23 20:07:21 +00:00
|
|
|
to monitor the file descriptor for process exit, as indicated by an
|
|
|
|
.BR EPOLLIN
|
|
|
|
event.
|
pidfd_open.2: New page documenting pidfd_open(2)
Notes from a conversation on linux-man@ with Christian Brauner:
[[
> [*} By the way, going forward, can we call these things
> "process FDs", rather than "PID FDs"? The API names are what
> they are, an that's okay, but these just as we have socket
> FDs that refer to sockets, directory FDs that refer to
> directories, and timer FDs that refer to timers, and so on,
> these are FDs that refer to *processes*, not "process IDs".
> It's a little thing, but I think the naming better, and
> it's what I propose to use in the manual pages.
The naming was another debate and we ended with this compromise.
I would just clarify that a pidfd is a process file descriptor. I
wouldn't make too much of a deal of hiding the shortcut "pidfd".
People are already using it out there in the wild and it's never
proven a good idea to go against accepted practice.
]]
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-22 21:05:48 +00:00
|
|
|
.\"
|
|
|
|
.SS Program source
|
|
|
|
\&
|
2020-11-16 09:52:29 +00:00
|
|
|
.EX
|
pidfd_open.2: New page documenting pidfd_open(2)
Notes from a conversation on linux-man@ with Christian Brauner:
[[
> [*} By the way, going forward, can we call these things
> "process FDs", rather than "PID FDs"? The API names are what
> they are, an that's okay, but these just as we have socket
> FDs that refer to sockets, directory FDs that refer to
> directories, and timer FDs that refer to timers, and so on,
> these are FDs that refer to *processes*, not "process IDs".
> It's a little thing, but I think the naming better, and
> it's what I propose to use in the manual pages.
The naming was another debate and we ended with this compromise.
I would just clarify that a pidfd is a process file descriptor. I
wouldn't make too much of a deal of hiding the shortcut "pidfd".
People are already using it out there in the wild and it's never
proven a good idea to go against accepted practice.
]]
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-22 21:05:48 +00:00
|
|
|
#define _GNU_SOURCE
|
2019-09-23 19:13:11 +00:00
|
|
|
#include <sys/types.h>
|
pidfd_open.2: New page documenting pidfd_open(2)
Notes from a conversation on linux-man@ with Christian Brauner:
[[
> [*} By the way, going forward, can we call these things
> "process FDs", rather than "PID FDs"? The API names are what
> they are, an that's okay, but these just as we have socket
> FDs that refer to sockets, directory FDs that refer to
> directories, and timer FDs that refer to timers, and so on,
> these are FDs that refer to *processes*, not "process IDs".
> It's a little thing, but I think the naming better, and
> it's what I propose to use in the manual pages.
The naming was another debate and we ended with this compromise.
I would just clarify that a pidfd is a process file descriptor. I
wouldn't make too much of a deal of hiding the shortcut "pidfd".
People are already using it out there in the wild and it's never
proven a good idea to go against accepted practice.
]]
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-22 21:05:48 +00:00
|
|
|
#include <sys/syscall.h>
|
|
|
|
#include <unistd.h>
|
|
|
|
#include <poll.h>
|
|
|
|
#include <stdlib.h>
|
|
|
|
#include <stdio.h>
|
|
|
|
|
|
|
|
#ifndef __NR_pidfd_open
|
2019-09-23 19:43:07 +00:00
|
|
|
#define __NR_pidfd_open 434 /* System call # on most architectures */
|
pidfd_open.2: New page documenting pidfd_open(2)
Notes from a conversation on linux-man@ with Christian Brauner:
[[
> [*} By the way, going forward, can we call these things
> "process FDs", rather than "PID FDs"? The API names are what
> they are, an that's okay, but these just as we have socket
> FDs that refer to sockets, directory FDs that refer to
> directories, and timer FDs that refer to timers, and so on,
> these are FDs that refer to *processes*, not "process IDs".
> It's a little thing, but I think the naming better, and
> it's what I propose to use in the manual pages.
The naming was another debate and we ended with this compromise.
I would just clarify that a pidfd is a process file descriptor. I
wouldn't make too much of a deal of hiding the shortcut "pidfd".
People are already using it out there in the wild and it's never
proven a good idea to go against accepted practice.
]]
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-22 21:05:48 +00:00
|
|
|
#endif
|
|
|
|
|
2019-09-23 09:43:13 +00:00
|
|
|
static int
|
|
|
|
pidfd_open(pid_t pid, unsigned int flags)
|
pidfd_open.2: New page documenting pidfd_open(2)
Notes from a conversation on linux-man@ with Christian Brauner:
[[
> [*} By the way, going forward, can we call these things
> "process FDs", rather than "PID FDs"? The API names are what
> they are, an that's okay, but these just as we have socket
> FDs that refer to sockets, directory FDs that refer to
> directories, and timer FDs that refer to timers, and so on,
> these are FDs that refer to *processes*, not "process IDs".
> It's a little thing, but I think the naming better, and
> it's what I propose to use in the manual pages.
The naming was another debate and we ended with this compromise.
I would just clarify that a pidfd is a process file descriptor. I
wouldn't make too much of a deal of hiding the shortcut "pidfd".
People are already using it out there in the wild and it's never
proven a good idea to go against accepted practice.
]]
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-22 21:05:48 +00:00
|
|
|
{
|
|
|
|
return syscall(__NR_pidfd_open, pid, flags);
|
|
|
|
}
|
|
|
|
|
|
|
|
int
|
|
|
|
main(int argc, char *argv[])
|
|
|
|
{
|
|
|
|
struct pollfd pollfd;
|
|
|
|
int pidfd, ready;
|
|
|
|
|
|
|
|
if (argc != 2) {
|
|
|
|
fprintf(stderr, "Usage: %s <pid>\en", argv[0]);
|
|
|
|
exit(EXIT_SUCCESS);
|
|
|
|
}
|
|
|
|
|
|
|
|
pidfd = pidfd_open(atoi(argv[1]), 0);
|
|
|
|
if (pidfd == \-1) {
|
|
|
|
perror("pidfd_open");
|
|
|
|
exit(EXIT_FAILURE);
|
|
|
|
}
|
|
|
|
|
|
|
|
pollfd.fd = pidfd;
|
|
|
|
pollfd.events = POLLIN;
|
|
|
|
|
|
|
|
ready = poll(&pollfd, 1, \-1);
|
|
|
|
if (ready == \-1) {
|
|
|
|
perror("poll");
|
|
|
|
exit(EXIT_FAILURE);
|
|
|
|
}
|
|
|
|
|
eventfd.2, mprotect.2, pidfd_open.2, spu_run.2, timer_create.2, bswap.3, dl_iterate_phdr.3, endian.3, pthread_attr_init.3, pthread_getattr_np.3, vcs.4, rtld-audit.7: In printf(): s/0x%/%#/ except when followed by X instead of x
Use printf()'s '#' flag character to prepend the string "0x".
However, when the number is printed in uppercase, and the prefix
is in lowercase, the string "0x" needs to be manually written.
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-09-11 20:53:51 +00:00
|
|
|
printf("Events (%#x): POLLIN is %sset\en", pollfd.revents,
|
pidfd_open.2: New page documenting pidfd_open(2)
Notes from a conversation on linux-man@ with Christian Brauner:
[[
> [*} By the way, going forward, can we call these things
> "process FDs", rather than "PID FDs"? The API names are what
> they are, an that's okay, but these just as we have socket
> FDs that refer to sockets, directory FDs that refer to
> directories, and timer FDs that refer to timers, and so on,
> these are FDs that refer to *processes*, not "process IDs".
> It's a little thing, but I think the naming better, and
> it's what I propose to use in the manual pages.
The naming was another debate and we ended with this compromise.
I would just clarify that a pidfd is a process file descriptor. I
wouldn't make too much of a deal of hiding the shortcut "pidfd".
People are already using it out there in the wild and it's never
proven a good idea to go against accepted practice.
]]
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-22 21:05:48 +00:00
|
|
|
(pollfd.revents & POLLIN) ? "" : "not ");
|
|
|
|
|
2020-07-17 07:13:31 +00:00
|
|
|
close(pidfd);
|
pidfd_open.2: New page documenting pidfd_open(2)
Notes from a conversation on linux-man@ with Christian Brauner:
[[
> [*} By the way, going forward, can we call these things
> "process FDs", rather than "PID FDs"? The API names are what
> they are, an that's okay, but these just as we have socket
> FDs that refer to sockets, directory FDs that refer to
> directories, and timer FDs that refer to timers, and so on,
> these are FDs that refer to *processes*, not "process IDs".
> It's a little thing, but I think the naming better, and
> it's what I propose to use in the manual pages.
The naming was another debate and we ended with this compromise.
I would just clarify that a pidfd is a process file descriptor. I
wouldn't make too much of a deal of hiding the shortcut "pidfd".
People are already using it out there in the wild and it's never
proven a good idea to go against accepted practice.
]]
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-22 21:05:48 +00:00
|
|
|
exit(EXIT_SUCCESS);
|
|
|
|
}
|
2020-11-16 09:52:29 +00:00
|
|
|
.EE
|
pidfd_open.2: New page documenting pidfd_open(2)
Notes from a conversation on linux-man@ with Christian Brauner:
[[
> [*} By the way, going forward, can we call these things
> "process FDs", rather than "PID FDs"? The API names are what
> they are, an that's okay, but these just as we have socket
> FDs that refer to sockets, directory FDs that refer to
> directories, and timer FDs that refer to timers, and so on,
> these are FDs that refer to *processes*, not "process IDs".
> It's a little thing, but I think the naming better, and
> it's what I propose to use in the manual pages.
The naming was another debate and we ended with this compromise.
I would just clarify that a pidfd is a process file descriptor. I
wouldn't make too much of a deal of hiding the shortcut "pidfd".
People are already using it out there in the wild and it's never
proven a good idea to go against accepted practice.
]]
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-22 21:05:48 +00:00
|
|
|
.SH SEE ALSO
|
|
|
|
.BR clone (2),
|
|
|
|
.BR kill (2),
|
2020-03-31 12:05:24 +00:00
|
|
|
.BR pidfd_getfd (2),
|
pidfd_open.2: New page documenting pidfd_open(2)
Notes from a conversation on linux-man@ with Christian Brauner:
[[
> [*} By the way, going forward, can we call these things
> "process FDs", rather than "PID FDs"? The API names are what
> they are, an that's okay, but these just as we have socket
> FDs that refer to sockets, directory FDs that refer to
> directories, and timer FDs that refer to timers, and so on,
> these are FDs that refer to *processes*, not "process IDs".
> It's a little thing, but I think the naming better, and
> it's what I propose to use in the manual pages.
The naming was another debate and we ended with this compromise.
I would just clarify that a pidfd is a process file descriptor. I
wouldn't make too much of a deal of hiding the shortcut "pidfd".
People are already using it out there in the wild and it's never
proven a good idea to go against accepted practice.
]]
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-22 21:05:48 +00:00
|
|
|
.BR pidfd_send_signal (2),
|
|
|
|
.BR poll (2),
|
2021-02-02 08:17:27 +00:00
|
|
|
.BR process_madvise (2),
|
pidfd_open.2: New page documenting pidfd_open(2)
Notes from a conversation on linux-man@ with Christian Brauner:
[[
> [*} By the way, going forward, can we call these things
> "process FDs", rather than "PID FDs"? The API names are what
> they are, an that's okay, but these just as we have socket
> FDs that refer to sockets, directory FDs that refer to
> directories, and timer FDs that refer to timers, and so on,
> these are FDs that refer to *processes*, not "process IDs".
> It's a little thing, but I think the naming better, and
> it's what I propose to use in the manual pages.
The naming was another debate and we ended with this compromise.
I would just clarify that a pidfd is a process file descriptor. I
wouldn't make too much of a deal of hiding the shortcut "pidfd".
People are already using it out there in the wild and it's never
proven a good idea to go against accepted practice.
]]
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-22 21:05:48 +00:00
|
|
|
.BR select (2),
|
2020-06-15 13:04:16 +00:00
|
|
|
.BR setns (2),
|
2019-10-12 20:40:09 +00:00
|
|
|
.BR waitid (2),
|
pidfd_open.2: New page documenting pidfd_open(2)
Notes from a conversation on linux-man@ with Christian Brauner:
[[
> [*} By the way, going forward, can we call these things
> "process FDs", rather than "PID FDs"? The API names are what
> they are, an that's okay, but these just as we have socket
> FDs that refer to sockets, directory FDs that refer to
> directories, and timer FDs that refer to timers, and so on,
> these are FDs that refer to *processes*, not "process IDs".
> It's a little thing, but I think the naming better, and
> it's what I propose to use in the manual pages.
The naming was another debate and we ended with this compromise.
I would just clarify that a pidfd is a process file descriptor. I
wouldn't make too much of a deal of hiding the shortcut "pidfd".
People are already using it out there in the wild and it's never
proven a good idea to go against accepted practice.
]]
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-22 21:05:48 +00:00
|
|
|
.BR epoll (7)
|