PSTOPSTATUS(3PROC) Process Control Library Functions PSTOPSTATUS(3PROC)
NAME
Pdstop,
Pstopstatus,
Pstop,
Pwait,
Ldstop,
Lstop,
Lwait - process and
thread stop operations
LIBRARY
Process Control Library (libproc, -lproc)
SYNOPSIS
#include <libproc.h> int Pdstop(
struct ps_prochandle *P);
int Pstopstatus(
struct ps_prochandle *P,
long request,
uint_t msec);
int Pstop(
struct ps_prochandle *P,
uint_t msec);
int Pwait(
struct ps_prochandle *P,
uint_t msec);
int Ldstop(
struct ps_lwphandle *L);
int Lstop(
struct ps_lwphandle *L,
uint_t msec);
int Lwait(
struct ps_lwphandle *L,
uint_t msec);
DESCRIPTION
The
Pstopstatus() function allows the caller to stop and optionally
wait for the process handle referred to by
P to be stopped. Stopping a
process causes all of its threads to stop execution. Where in their
execution the threads will halt is not defined. Threads may be resumed
with
Psetrun(3PROC) and
prun(1).
The
request argument should be one of the following symbols:
PCSTOP Stop the process; wait for completion before
returning.
PCDSTOP Stop the process; do not wait for completion before
returning. That is, the stopping of the process is
performed asynchronously in relation to the caller.
PCWSTOP Do not direct the process to stop; simply wait for
it to stop.
PCNULL Do not direct the process to stop; simply refreshes
the state of the process.
Both the PCSTOP and PCWSTOP requests allow an upper bound on the amount
of time to wait for the process to stop. The
msec argument indicates
the number of milliseconds to wait for the stop to complete. If the
value of
msec is
0, then it will wait forever. Callers should pass
0 for
msec when the request is PCDSTOP or PCNULL.
When a non-zero timeout is specified, the process may or may not be
stopped upon return. The return value does not reflect the current
state of the process. For example, if the timeout expires during a
PCWSTOP request, the return value will be
0 regardless of the actual
state of the process.
Only active processes may be stopped. Handles that refer to core
files, zombie processes, or files cannot be used; unless the value of
request is set to PCNULL.
The
Pstop() function is is equivalent to calling the
Pstopstatus()
function with the request set to PCSTOP.
The
Pwait() function is is equivalent to calling the
Pstopstatus()
function with the request set to PCWSTOP.
The
Pdstop() function is is equivalent to calling the
Pstopstatus()
function with the request set to PCDSTOP.
The
Ldstop(),
Lstop(), and
Lwait() functions are equivalent to the
Pdstop(),
Pstop(), and
Pwait() functions, respectively. Except, rather
than operating on a process, they operate on the thread handle
L. A
call to
Lstop() stops only a single thread; whereas
Pstop() stops every
thread in the process.
RETURN VALUES
Upon successful completion, the
Pdstop(),
Pstopstatus(),
Pstop(),
Pwait(),
Ldstop(),
Lstop(), and
Lwait() functions return
0. Otherwise,
-1 is returned and errno is set to indicate the error that occurred.
ERRORS
For a full list of possible errors see the
DIAGNOSTICS section in
proc(5).
The
Pdstop(),
Pstopstatus(),
Pstop(),
Pwait(),
Ldstop(),
Lstop(), and
Lwait() functions will fail if:
EAGAIN Control over the handle
P was lost. Callers should
call
Preopen(3PROC). For more information on losing
control, see
PROGRAMMING NOTES in
proc(5).
ENOENT The request was not PCNULL and the process handle
P does not refer to an active process, but refers to a
core file, a zombie process, or a file.
EINVAL
request is not valid or the process is in an unknown
state.
EPROTO A fatal protocol error occurred and the process
could not be stopped.
INTERFACE STABILITY
UncommittedMT-LEVEL See
LOCKING in
libproc(3LIB).
SEE ALSO
libproc(3LIB),
Lgrab(3PROC),
Pcreate(3PROC),
Pgrab(3PROC),
Pgrab_core(3PROC),
Pgrab_file(3PROC),
proc(5)illumos May 2, 2020 illumos
