Pgrab —
grab and control a process
Process Control Library (libproc, -lproc)
#include
<libproc.h>
struct ps_prochandle *
Pgrab(
pid_t
pid,
int flags,
int *perr);
The
Pgrab() function attempts to grab the
process identified by
pid and returns a
handle to it that allows the process to be controlled, interrogated, and
manipulated. This interface only works with processes that already exist. Use
Pgrab_core(3PROC) for core files and
Pcreate(3PROC) to create processes.
A grabbed process undergoes the following changes unless
flags is set to the contrary:
- The process is stopped
- All other tracing flags are cleared
- The grab is exclusive. If any existing handles to this process exist or
anyone else is using the underlying facilities of the /proc file system to
control this process, it will fail.
- Unless the process is already stopped, the
PR_RLC flag is set indicating the
process should run-on-last-close. Allowing the process to resume running
if its controlling process dies.
Grabbing a process is a
destructive action.
Stopping a process stops execution of all its threads. The impact of stopping
a process depends on the purpose of that process. For example, if one stops a
process that's primarily doing computation, then its computation is delayed
the entire time that it is stopped. However, if instead this is an active TCP
server, then the accept backlog may fill causing connection errors and
potentially connection time out errors.
Special care must be taken to ensure that a stopped process continues, even if
the controlling process terminates. If the controlling process disables the
PR_RLC flag or the process was already
stopped, then the process remains stopped after the controlling process
terminates. Exercise caution when changing this behavior.
Many of these default behaviors can be controlled by passing values to the
flags argument. Values for
flags are constructed by a
bitwise-inclusive-OR of flags from the following list:
-
-
PGRAB_RETAIN- Indicates that any existing tracing flags on
pid should be retained. If this flag is
not specified, they will be cleared as part of creating the
libproc handle for this process.
Normally extant tracing flags are cleared when a process is grabbed.
-
-
PGRAB_FORCE- Indicates that the process should not be grabbed exclusively. Care should
be taken with this option. If other consumers are manipulating the
process, then this may result in surprising behavior as the process is
being manipulated from multiple points of control at the same time.
Normally an attempt will be made to grab the process exclusively and fail if
it is already in use.
-
-
PGRAB_RDONLY- Indicates that the process should be grabbed in a read-only fashion. This
implies that both the
PGRAB_RETAIN and
PGRAB_NOSTOP flags should be set. If a
process is opened read-only, then a caller can only read information about
a process and cannot manipulate it, change its current state, or inject
systems calls into it.
Normally when a process is grabbed, it does so for both reading and
writing.
-
-
PGRAB_NOSTOP- Do not stop a process as it is grabbed. Note, any extant tracing flags on
the process will still be cleared unless the
PGRAB_RETAIN flag has been set.
Normally a process is stopped as a result of grabbing the process.
The
perr argument must be a
non-
NULL pointer which will store a more
detailed error in the event that the
Pgrab() function fails. A human-readable
form of the error can be obtained with
Pgrab_error(3PROC).
Once a caller is done with the library handle it should call
Prelease(3PROC) to release the grabbed process.
Failure to properly release the handle may leave a process stopped and
interfere with the ability of other software to obtain a handle.
Unprivileged users may grab and control their own processes only if both the
user and group IDs of the target process match those of the calling process.
In addition, the caller must have a super set of the target's privileges.
Processes with the
PRIV_PROC_OWNER privilege may
manipulate any process on the system, as long as it has an equal privilege
set. For more details on the security and programming considerations, please
see the section
PROGRAMMING NOTES in
proc(4).
Upon successful completion, the
Pgrab()
function returns a control handle to the process. Otherwise,
NULL is returned with
perr containing the error code.
The
Pgrab() function will fail if:
-
-
G_BUSY- The process pid is already being traced
and the
PGRAB_FORCE flag was not passed
in flags.
-
-
G_LP64- The calling process is a 32-bit process and process
pid is 64-bit.
-
-
G_NOFD- Too many files are open. This is logically equivalent to receiving
EMFILE.
-
-
G_NOPROC- The process referred to by pid does not
exist.
-
-
G_PERM- The calling process has insufficient permissions or privileges to open the
specified process. See
Permissions for more
information.
-
-
G_SYS- The process referred to by pid is a
system process and cannot be grabbed.
-
-
G_SELF- The process referred to by pid is the
process ID of the caller and the
PGRAB_RDONLY was not passed. A process
may only grab itself if it's read-only.
-
-
G_STRANGE- An unanticipated system error occurred while trying to grab the process
file and create the handle. The value of
errno indicates the system failure.
-
-
G_ZOMB- The process referred to by pid is a
zombie and cannot be grabbed.
Uncommitted
MT-Safe
errno(3C),
libproc(3LIB),
Pfree(3PROC),
Pgrab_core(3PROC),
Pgrab_error(3PROC),
Pgrab_file(3PROC),
Prelease(3PROC)