Tribblix: manual page: Pgrab.3proc

PGRAB(3PROC) Process Control Library Functions PGRAB(3PROC)

NAME

Pgrab - grab and control a process

LIBRARY

Process Control Library (libproc, -lproc)

SYNOPSIS

#include <libproc.h>

struct ps_prochandle *
Pgrab(pid_t pid, int flags, int *perr);

DESCRIPTION

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:

+o The process is stopped

+o All other tracing flags are cleared

+o 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.

+o 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.

Permissions

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(5).

RETURN VALUES

Upon successful completion, the Pgrab() function returns a control
handle to the process. Otherwise, NULL is returned with perr
containing the error code.

ERRORS

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.

INTERFACE STABILITY

Uncommitted

MT-LEVEL
MT-Safe