illumos: manual page: Lwait.3proc

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

Uncommitted

MT-LEVEL
See LOCKING in libproc(3LIB).