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