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

Pdstop, Pstopstatus, Pstop, Pwait, Ldstop, Lstop, Lwait — process and thread stop operations

Process Control Library (libproc, -lproc)

#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);

The () 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:

Stop the process; wait for completion before returning.
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.
Do not direct the process to stop; simply wait for it to stop.
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 () function is is equivalent to calling the Pstopstatus() function with the request set to PCSTOP.

The () function is is equivalent to calling the Pstopstatus() function with the request set to PCWSTOP.

The () function is is equivalent to calling the Pstopstatus() function with the request set to PCDSTOP.

The (), (), and () 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.

Upon successful completion, the Pdstop(), Pstopstatus(), Pstop(), Pwait(), Ldstop(), Lstop(), and Lwait() functions return 0. Otherwise, is returned and errno is set to indicate the error that occurred.

For a full list of possible errors see the section in proc(5).

The Pdstop(), Pstopstatus(), Pstop(), Pwait(), Ldstop(), Lstop(), and Lwait() functions will fail if:

Control over the handle P was lost. Callers should call Preopen(3PROC). For more information on losing control, see in proc(5).
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.
request is not valid or the process is in an unknown state.
A fatal protocol error occurred and the process could not be stopped.

See in libproc(3LIB).

libproc(3LIB), Lgrab(3PROC), Pcreate(3PROC), Pgrab(3PROC), Pgrab_core(3PROC), Pgrab_file(3PROC), proc(5)

May 2, 2020 OmniOS