mirror of
https://github.com/freebsd/freebsd-src.git
synced 2026-10-28 11:25:21 +01:00
Konstantin Belousov
45633600ac
Reviewed by: markj Sponsored by: The FreeBSD Foundation MFC after: 1 week Differential revision: https://reviews.freebsd.org/D58586
514 lines
12 KiB
Plaintext
514 lines
12 KiB
Plaintext
.\"
|
|
.\" Copyright (c) 2009-2010, 2012-2013 Robert N. M. Watson
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This software was developed at the University of Cambridge Computer
|
|
.\" Laboratory with support from a grant from Google, Inc.
|
|
.\"
|
|
.\" This software was developed by SRI International and the University of
|
|
.\" Cambridge Computer Laboratory under DARPA/AFRL contract (FA8750-10-C-0237)
|
|
.\" ("CTSRD"), as part of the DARPA CRASH research programme.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.Dd April 19, 2026
|
|
.Dt PDFORK 2
|
|
.Os
|
|
.Sh NAME
|
|
.Nm pdfork ,
|
|
.Nm pdrfork ,
|
|
.Nm pdopenpid ,
|
|
.Nm pdgetpid ,
|
|
.Nm pdkill ,
|
|
.Nm pdwait ,
|
|
.Nm pddupfd
|
|
.Nd System calls to manage process descriptors
|
|
.Sh LIBRARY
|
|
.Lb libc
|
|
.Sh SYNOPSIS
|
|
.In sys/procdesc.h
|
|
.Ft pid_t
|
|
.Fn pdfork "int *fdp" "int pdflags"
|
|
.Ft pid_t
|
|
.Fn pdrfork "int *fdp" "int pdflags" "int rfflags"
|
|
.Ft int
|
|
.Fn pdopenpid "pid_t pid" "int pdflags"
|
|
.Ft int
|
|
.Fn pdgetpid "int fd" "pid_t *pidp"
|
|
.Ft int
|
|
.Fn pdkill "int fd" "int signum"
|
|
.Ft int
|
|
.Fo pdwait
|
|
.Fa "int fd"
|
|
.Fa "int *status"
|
|
.Fa "int options"
|
|
.Fa "struct __wrusage *wrusage"
|
|
.Fa "struct __siginfo *info"
|
|
.Fc
|
|
.Ft int
|
|
.Fn pddupfd "int fd" "int remotefd" "int flags"
|
|
.Ft int
|
|
.Fo pdptrace
|
|
.Fa "int req"
|
|
.Fa "int fd"
|
|
.Fa "int lwpid"
|
|
.Fa "void *addr"
|
|
.Fa "int data"
|
|
.Fc
|
|
.Sh DESCRIPTION
|
|
Process descriptors are special file descriptors that represent processes,
|
|
and are created using
|
|
.Fn pdfork ,
|
|
a variant of
|
|
.Xr fork 2 ,
|
|
which, if successful, returns a process descriptor in the integer pointed to
|
|
by
|
|
.Fa fdp .
|
|
Processes created via
|
|
.Fn pdfork
|
|
will not cause
|
|
.Dv SIGCHLD
|
|
on termination.
|
|
.Fn pdfork
|
|
can accept the
|
|
.Fa pdflags:
|
|
.Bl -tag -width PD_PTRACE_CAP
|
|
.It Dv PD_DAEMON
|
|
Instead of the default terminate-on-close behaviour, allow the process to
|
|
live until it is explicitly killed with
|
|
.Xr kill 2 .
|
|
.Pp
|
|
This option is not permitted in
|
|
.Xr capsicum 4
|
|
capability mode (see
|
|
.Xr cap_enter 2 ) .
|
|
.Pp
|
|
Note: the option changes the behavior of
|
|
.Xr close 2
|
|
for the process descriptor returned by the operation.
|
|
If there is another process descriptor for the same process, created without
|
|
specifying the
|
|
.Dv PD_DAEMON
|
|
flag, closing that descriptor kills the process.
|
|
.It Dv PD_CLOEXEC
|
|
Set close-on-exec on process descriptor.
|
|
.It Dv PD_NOWAITPID
|
|
The parent cannot obtain the child's status with
|
|
.Xr waitpid 2 .
|
|
.It Dv PD_PTRACE_CAP
|
|
Enable
|
|
.Xr pdptrace 2
|
|
requests on the resulting file descriptor.
|
|
Otherwise the descriptor cannot be used to debug the child process.
|
|
See
|
|
.Xr rights 4
|
|
for the description of the
|
|
.Dv CAP_PTRACE
|
|
capability.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fn pdrfork
|
|
system call is a variant of
|
|
.Fn pdfork
|
|
that also takes the
|
|
.Fa rfflags
|
|
argument to control sharing of process resources between the caller
|
|
and the new process.
|
|
Like
|
|
.Fn pdfork ,
|
|
the function writes the process descriptor referencing the created
|
|
process into the location pointed to by the
|
|
.Fa fdp
|
|
argument.
|
|
See
|
|
.Xr rfork 2
|
|
for a description of the possible
|
|
.Fa rfflag
|
|
flags.
|
|
The
|
|
.Fn pdrfork
|
|
system call requires that both the
|
|
.Va RFPROC
|
|
and
|
|
.Va RFPROCDESC
|
|
flags, or
|
|
.Va RFSPAWN
|
|
flag are specified.
|
|
.Pp
|
|
The
|
|
.Fn pdopenpid
|
|
function opens the process descriptor for the process
|
|
specified by the argument
|
|
.Fa pid .
|
|
It takes the same flags in the
|
|
.Fa pdflags
|
|
argument as
|
|
.Fn pdfork .
|
|
The caller must have permission to debug the target process in order for
|
|
.Fn pdopenpid
|
|
to succeed.
|
|
Zombie processes cannot be opened.
|
|
.Pp
|
|
There might be more that one file descriptor referencing the process.
|
|
After the zombie is reaped, calls to
|
|
.Fn pdwait
|
|
specifying any file descriptors for the same process fail with the
|
|
.Er ESRCH
|
|
error.
|
|
.Pp
|
|
.Fn pdgetpid
|
|
queries the process ID (PID) in the process descriptor
|
|
.Fa fd .
|
|
.Pp
|
|
.Fn pdkill
|
|
is functionally identical to
|
|
.Xr kill 2 ,
|
|
except that it accepts a process descriptor,
|
|
.Fa fd ,
|
|
rather than a PID.
|
|
.Pp
|
|
The
|
|
.Fn pdwait
|
|
system call allows the calling thread to wait and retrieve
|
|
the status information on the process referenced by the
|
|
.Fa fd
|
|
process descriptor.
|
|
See the description of the
|
|
.Xr wait6 2
|
|
system call for the behavior specification.
|
|
.Pp
|
|
The
|
|
.Fn pddupfd
|
|
function allows the caller to duplicate a file descriptor
|
|
across the process boundaries.
|
|
The function returns the new file descriptor that points to the same file
|
|
as the file descriptor
|
|
.Fa remotefd
|
|
in the process specified by the
|
|
.Fa fd
|
|
process descriptor.
|
|
The returned file descriptor has the
|
|
.Va O_CLOEXEC
|
|
flag set.
|
|
The
|
|
.Fa flags
|
|
argument is reserved and must be zero.
|
|
Certain file descriptor types cannot be copied this way, namely
|
|
kqueues.
|
|
.Pp
|
|
The
|
|
.Fn pdptrace
|
|
function enables execution of
|
|
.Xr ptrace 2
|
|
requests on the process specified by the process descriptor
|
|
.Fa fd .
|
|
.Pp
|
|
In addition to the arguments taken by the
|
|
.Xr ptrace 2 ,
|
|
system call, the
|
|
.Fa lwpid
|
|
thread identifier can designate the thread on which the request
|
|
must operate.
|
|
The
|
|
.Fa lwpid
|
|
argument can be specified as \-1 if the call is not thread-specific,
|
|
or kernel is allowed to select some thread on its own.
|
|
.Pp
|
|
Unlike the
|
|
.Xr ptrace 2
|
|
implementation,
|
|
.Fn pdptrace
|
|
does not clear the
|
|
.Dv errno
|
|
variable before executing the system call.
|
|
.Sh INTERACTION OF PROCESS DESCRIPTORS AND Xr WAITPID 2
|
|
.Pp
|
|
The
|
|
.Fn pdwait
|
|
system call may be called on a process descriptor
|
|
an unlimited number of times.
|
|
In particular, it does not reap the target process,
|
|
even if that process has exited.
|
|
Each time, it returns the same status.
|
|
.Bl -dash
|
|
.It
|
|
If the process was forked with
|
|
.Fn pdfork ,
|
|
and the
|
|
.Dv PD_NOWAITPID
|
|
flag was specified, then the process is automatically reaped after the
|
|
last process descriptor referencing that process is closed.
|
|
No
|
|
.Xr waitpid 2
|
|
call
|
|
.Pq or a call from the same family of the wait functions which operate on PIDs
|
|
are needed to reap the zombie process.
|
|
.It
|
|
If the process was created by
|
|
.Fn pdfork ,
|
|
and the
|
|
.Dv PD_NOWAITPID
|
|
flag was not specified, then after exiting,
|
|
the process will not be reaped until the parent or reaper has called
|
|
.Xr waitpid 2
|
|
and all process descriptors referencing the process are closed.
|
|
.It
|
|
If the process was created by the
|
|
.Xr fork 2
|
|
system call
|
|
.Pq which does not allocate a process descriptor for the child ,
|
|
and later the process was opened by
|
|
.Fn pdopenpid ,
|
|
then a
|
|
.Xr waitpid 2
|
|
call from the parent is needed to reap the exited child.
|
|
.El
|
|
.Pp
|
|
In any case, the PID of the process is not reused until its zombie
|
|
is reaped, and all its process descriptors are closed.
|
|
.Pp
|
|
A debugger attached by
|
|
.Xr ptrace 2
|
|
can execute the
|
|
.Fn waitpid
|
|
calls against the alive target regardless of the way
|
|
the target process was forked.
|
|
.Sh INTERACTION OF PROCESS DESCRIPTORS WITH OTHER SYSTEM CALLS
|
|
.Pp
|
|
The following system calls also have effects specific to process descriptors:
|
|
.Pp
|
|
.Xr fstat 2
|
|
queries status of a process descriptor; currently only the
|
|
.Fa st_mode ,
|
|
.Fa st_birthtime ,
|
|
.Fa st_atime ,
|
|
.Fa st_ctime
|
|
and
|
|
.Fa st_mtime
|
|
fields are defined.
|
|
If the owner read, write, and execute bits are set then the
|
|
process represented by the process descriptor is still alive.
|
|
.Pp
|
|
.Xr poll 2
|
|
and
|
|
.Xr select 2
|
|
allow waiting for process state transitions; currently only
|
|
.Dv POLLHUP
|
|
is defined, and will be raised when the process dies.
|
|
Process state transitions can also be monitored using
|
|
.Xr kqueue 2
|
|
filter
|
|
.Dv EVFILT_PROCDESC ;
|
|
currently only
|
|
.Dv NOTE_EXIT
|
|
is implemented.
|
|
.Pp
|
|
.Xr close 2
|
|
will close the process descriptor unless
|
|
.Dv PD_DAEMON
|
|
is set; if the process is still alive and this is
|
|
the last reference to the process descriptor, the process will be terminated
|
|
with the signal
|
|
.Dv SIGKILL .
|
|
The PID of the referenced process is not reused until the process
|
|
descriptor is closed,
|
|
whether or not the zombie process is reaped by
|
|
.Fn pdwait ,
|
|
.Xr wait6 ,
|
|
or similar system calls.
|
|
.Sh RETURN VALUES
|
|
.Fn pdfork
|
|
and
|
|
.Fn pdrfork
|
|
return a PID, 0 or -1, as
|
|
.Xr fork 2
|
|
does.
|
|
.Pp
|
|
.Fn pdopenpid ,
|
|
.Fn pdgetpid ,
|
|
.Fn pdkill ,
|
|
.Fn pdwait ,
|
|
and
|
|
.Fn pddupfd
|
|
return 0 on success and -1 on failure.
|
|
.Sh ERRORS
|
|
These functions may return the same error numbers as their PID-based equivalents
|
|
(e.g.
|
|
.Fn pdfork
|
|
may return the same error numbers as
|
|
.Xr fork 2 ) ,
|
|
with the following additions:
|
|
.Bl -tag -width Er
|
|
.It Bq Er EFAULT
|
|
The copyout of the resulting file descriptor value to the memory pointed
|
|
to by
|
|
.Fa fdp
|
|
failed.
|
|
.Pp
|
|
Note that the child process was already created when this condition
|
|
is detected,
|
|
and the child continues execution, same as the parent.
|
|
If this error must be handled, it is advisable to memoize the
|
|
.Fn getpid
|
|
result before the call to
|
|
.Fn pdfork
|
|
or
|
|
.Fn pdrfork ,
|
|
and compare it to the value returned by
|
|
.Fn getpid
|
|
after, to see if code is executing in parent or child.
|
|
.It Bq Er EINVAL
|
|
The signal number given to
|
|
.Fn pdkill
|
|
is invalid.
|
|
.It Bq Er ENOTCAPABLE
|
|
The process descriptor being operated on has insufficient rights (e.g.
|
|
.Dv CAP_PDKILL
|
|
for
|
|
.Fn pdkill ) .
|
|
.It Bq Er EINVAL
|
|
The
|
|
.Fn pdwait
|
|
function is called with reserved bits set in
|
|
.Fa options .
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fn pdopenpid
|
|
might return the same errors as
|
|
.Xr open 2 ,
|
|
related to the file descriptor allocation problems, as well as the
|
|
following specific errors:
|
|
.Bl -tag -width Er
|
|
.It Bq Er EINVAL
|
|
The
|
|
.Fa flags
|
|
argument has reserved bits set.
|
|
.It Bq Er ECAPMODE
|
|
.Fn pdopenpid
|
|
is called by the process in capability mode.
|
|
.It Bq Er EBUSY
|
|
The process specified by the
|
|
.Fa pid
|
|
argument already terminated.
|
|
.It Bq Er ESRCH
|
|
The process specified by the
|
|
.Fa pid
|
|
argument does not exist, or the caller does not have enough privileges
|
|
to open the process.
|
|
.It Bq Er EMFILE
|
|
The calling process already reached its limit for open file descriptors.
|
|
.Pp
|
|
Current implementation installs the opened process descriptor into the
|
|
calling process's file descriptors table.
|
|
If the descriptor cannot be installed, the process descriptor is closed,
|
|
which executes all actions performed by
|
|
.Xr close 2
|
|
on it.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fn pddupfd
|
|
returns the following errors:
|
|
.Bl -tag -width Er
|
|
.It Bq Er EINVAL
|
|
The
|
|
.Fa flags
|
|
argument is not zero.
|
|
.It Bq Er EINVAL
|
|
The file descriptor
|
|
.Fa fd
|
|
is not a process file descriptor.
|
|
.It Bq Er ESRCH
|
|
The process specified by the file descriptor
|
|
.Fa fd
|
|
exited.
|
|
.It Bq Er EBADF
|
|
The file descriptor
|
|
.Fa remotefd
|
|
is not a valid file descriptor in the specified process.
|
|
.It Bq Er ENOENT
|
|
The specified process does not have a file descriptor table.
|
|
.It Bq Er EOPNOTSUPP
|
|
.Fa remotefd
|
|
refers to a file that cannot be duplicated across a process boundary,
|
|
such as a kqueue.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr close 2 ,
|
|
.Xr fork 2 ,
|
|
.Xr fstat 2 ,
|
|
.Xr kill 2 ,
|
|
.Xr kqueue 2 ,
|
|
.Xr poll 2 ,
|
|
.Xr wait4 2 ,
|
|
.Xr capsicum 4 ,
|
|
.Xr procdesc 4
|
|
.Sh HISTORY
|
|
The
|
|
.Fn pdfork ,
|
|
.Fn pdgetpid ,
|
|
and
|
|
.Fn pdkill
|
|
system calls first appeared in
|
|
.Fx 9.0 .
|
|
The
|
|
.Fn pdrfork
|
|
and
|
|
.Fn pdwait
|
|
system calls first appeared in
|
|
.Fx 15.1 .
|
|
The
|
|
.Fn pdopenpid
|
|
and
|
|
.Fn pddupfd
|
|
system calls first appeared in
|
|
.Fx 16.0 .
|
|
.Pp
|
|
Support for process descriptors mode was developed as part of the
|
|
.Tn TrustedBSD
|
|
Project.
|
|
.Sh AUTHORS
|
|
.An -nosplit
|
|
These functions and the capability facility were created by
|
|
.An Robert N. M. Watson Aq Mt [email protected]
|
|
and
|
|
.An Jonathan Anderson Aq Mt [email protected]
|
|
at the University of Cambridge Computer Laboratory with support from a grant
|
|
from Google, Inc.
|
|
The
|
|
.Fn pdrfork
|
|
and
|
|
.Fn pdwait
|
|
functions were developed by
|
|
.An Konstantin Belousov Aq Mt [email protected]
|
|
with input from
|
|
.An Alan Somers Aq Mt [email protected] .
|
|
The
|
|
.Fn pdopenpid ,
|
|
.Fn pddupfd ,
|
|
and
|
|
.Fn pdptrace
|
|
functions were developed by
|
|
.An Konstantin Belousov Aq Mt [email protected] .
|