PGRAB(3PROC) | Process Control Library Functions | PGRAB(3PROC) |
Pgrab
—
#include <libproc.h>
struct ps_prochandle *
Pgrab
(pid_t pid,
int flags, int *perr);
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:
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
Normally extant tracing flags are cleared when a process is grabbed.
PGRAB_FORCE
Normally an attempt will be made to grab the process exclusively and fail if it is already in use.
PGRAB_RDONLY
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
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.
Pgrab
() function returns
a control handle to the process. Otherwise, NULL
is
returned with perr containing the error code.
Pgrab
() function will fail if:
G_BUSY
PGRAB_FORCE
flag was not passed in
flags.G_LP64
G_NOFD
EMFILE
.G_NOPROC
G_PERM
G_SYS
G_SELF
PGRAB_RDONLY
was not passed. A
process may only grab itself if it's read-only.G_STRANGE
G_ZOMB
May 11, 2016 | OmniOS |