[thirdparty/man-pages.git] / man2 / pidfd_getfd.2

.\" 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 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 file descriptor (a nonnegative integer).
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 EPERM
The calling process did not have
.B PTRACE_MODE_ATTACH_REALCREDS
permissions (see
.BR ptrace (2))
over the process referred to by
.IR pidfd .
.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).
.PP
The effect of
.BR pidfd_getfd ()
is similar to the use of
.BR SCM_RIGHTS
messages described in
.BR unix (7),
but differs in the following respects:
.IP \(bu 2
In order to pass a file descriptor using an
.BR SCM_RIGHTS
message,
the two processes must first establish a UNIX domain socket connection.
.IP \(bu
The use of
.BR SCM_RIGHTS
requires cooperation on the part of the process whose
file descriptor is being copied.
By contrast, no such cooperation is necessary when using
.BR pidfd_getfd ().
.IP \(bu
The ability to use
.BR pidfd_getfd ()
is restricted by a
.BR PTRACE_MODE_ATTACH_REALCREDS
ptrace  access  mode check.
.SH SEE ALSO
.BR clone3 (2),
.BR dup (2),
.BR kcmp (2),
.BR pidfd_open (2)
Commit	Line	Data
13aa2b30 MK	1	.\" Copyright (c) 2020 by Michael Kerrisk <mtk.manpages@gmail.com>
	2	.\"
	3	.\" %%%LICENSE_START(VERBATIM)
	4	.\" Permission is granted to make and distribute verbatim copies of this
	5	.\" manual provided the copyright notice and this permission notice are
	6	.\" preserved on all copies.
	7	.\"
	8	.\" Permission is granted to copy and distribute modified versions of this
	9	.\" manual under the conditions for verbatim copying, provided that the
	10	.\" entire resulting derived work is distributed under the terms of a
	11	.\" permission notice identical to this one.
	12	.\"
	13	.\" Since the Linux kernel and libraries are constantly changing, this
	14	.\" manual page may be incorrect or out-of-date. The author(s) assume no
	15	.\" responsibility for errors or omissions, or for damages resulting from
	16	.\" the use of the information contained herein. The author(s) may not
	17	.\" have taken the same level of care in the production of this manual,
	18	.\" which is licensed free of charge, as they might when working
	19	.\" professionally.
	20	.\"
	21	.\" Formatted or processed versions of this manual, if unaccompanied by
	22	.\" the source, must acknowledge the copyright and authors of this work.
	23	.\" %%%LICENSE_END
	24	.\"
	25	.TH PIDFD_GETFD 2 2020-03-31 "Linux" "Linux Programmer's Manual"
	26	.SH NAME
	27	pidfd_getfd \- obtain a duplicate of another process's file descriptor
	28	.SH SYNOPSIS
	29	.nf
	30	.BI "int pidfd_getfd(int " pidfd ", int " targetfd ", unsigned int " flags );
	31	.fi
	32	.SH DESCRIPTION
	33	The
	34	.BR pidfd_getfd ()
	35	system call allocates a new file descriptor in the calling process.
	36	This new file descriptor is a duplicate of an existing file descriptor,
	37	.IR targetfd ,
	38	in the process referred to by the PID file descriptor
	39	.IR pidfd .
	40	.PP
	41	The duplicate file descriptor refers to the same open file description (see
	42	.BR open (2))
	43	as the original file descriptor in the process referred to by
	44	.IR pidfd .
	45	The two file descriptors thus share file status flags and file offset.
	46	Furthermore, operations on the underlying file object
	47	(for example, assigning an address to a socket object using
	48	.BR bind (2))
8b4baee7	49	can equally be performed via the duplicate file descriptor.
13aa2b30 MK	50	.PP
	51	The close-on-exec flag
	52	.RB ( FD_CLOEXEC ;
	53	see
	54	.BR fcntl (2))
	55	is set on the file descriptor returned by
	56	.BR pidfd_getfd ().
	57	.PP
	58	The
	59	.I flags
	60	argument is reserved for future use.
	61	Currently, it must be specified as 0.
	62	.PP
	63	Permission to duplicate another process's file descriptor
	64	is governed by a ptrace access mode
	65	.B PTRACE_MODE_ATTACH_REALCREDS
	66	check (see
	67	.BR ptrace (2)).
	68	.SH RETURN VALUE
	69	On success,
	70	.BR pidfd_getfd ()
8b4baee7	71	returns a file descriptor (a nonnegative integer).
13aa2b30 MK	72	On error, \-1 is returned and
	73	.I errno
	74	is set to indicate the cause of the error.
	75	.SH ERRORS
	76	.TP
	77	.B EBADF
	78	.I pidfd
	79	is not a valid PID file descriptor.
	80	.TP
	81	.B EBADF
	82	.I targetfd
	83	is not an open file descriptor in the process referred to by
	84	.IR pidfd .
8678102a	85	.BR
13aa2b30 MK	86	.TP
	87	.B EINVAL
	88	.I flags
	89	is not 0.
	90	.TP
	91	.B EMFILE
	92	The per-process limit on the number of open file descriptors has been reached
	93	(see the description of
	94	.BR RLIMIT_NOFILE
	95	in
	96	.BR getrlimit (2)).
	97	.TP
	98	.B ENFILE
	99	The system-wide limit on the total number of open files has been reached.
	100	.TP
8b4baee7 MK	101	.B EPERM
	102	The calling process did not have
	103	.B PTRACE_MODE_ATTACH_REALCREDS
	104	permissions (see
	105	.BR ptrace (2))
	106	over the process referred to by
	107	.IR pidfd .
	108	.TP
13aa2b30 MK	109	.B ESRCH
	110	The process referred to by
	111	.I pidfd
	112	does not exist
	113	(i.e., it has terminated and been waited on).
	114	.SH VERSIONS
	115	.BR pidfd_getfd ()
	116	first appeared in Linux 5.6.
	117	.\" commit 8649c322f75c96e7ced2fec201e123b2b073bf09
	118	.SH CONFORMING TO
	119	.BR pidfd_getfd ()
	120	is Linux specific.
	121	.SH NOTES
	122	Currently, there is no glibc wrapper for this system call; call it using
	123	.BR syscall (2).
	124	.PP
	125	For a description of PID file descriptors, see
	126	.BR pidfd_open (2).
be04cb50 MK	127	.PP
	128	The effect of
	129	.BR pidfd_getfd ()
	130	is similar to the use of
	131	.BR SCM_RIGHTS
	132	messages described in
	133	.BR unix (7),
	134	but differs in the following respects:
	135	.IP \(bu 2
	136	In order to pass a file descriptor using an
	137	.BR SCM_RIGHTS
	138	message,
	139	the two processes must first establish a UNIX domain socket connection.
	140	.IP \(bu
	141	The use of
	142	.BR SCM_RIGHTS
	143	requires cooperation on the part of the process whose
	144	file descriptor is being copied.
	145	By contrast, no such cooperation is necessary when using
	146	.BR pidfd_getfd ().
	147	.IP \(bu
	148	The ability to use
	149	.BR pidfd_getfd ()
	150	is restricted by a
	151	.BR PTRACE_MODE_ATTACH_REALCREDS
	152	ptrace access mode check.
13aa2b30 MK	153	.SH SEE ALSO
	154	.BR clone3 (2),
	155	.BR dup (2),
	156	.BR kcmp (2),
	157	.BR pidfd_open (2)