Go to main content

man pages section 3: Extended Library Functions, Volume 3

Exit Print View

Updated: Thursday, June 13, 2019
 
 

Pstop (3PROC)

Name

Pstop, Pstate, Pdstop, Pwait, Prefresh, Pclearsig, Pclearfault, Psetrun, Preopen - interrogate or change the state of a victim process

Synopsis

#include <libproc.h>
int Pstop(ps_prochandle_t *Pr, uint_t msec);
int Pstate(ps_prochandle_t *Pr);
int Pdstop(ps_prochandle_t *Pr);
int Pwait(ps_prochandle_t *Pr, uint_t msec);
int Prefresh(ps_prochandle_t *Pr);
int Pclearsig(ps_prochandle_t *Pr);
int Pclearfault(ps_prochandle_t *Pr);
int Psetrun(ps_prochandle_t *Pr, int sig, int flags);
int Preopen(ps_prochandle_t *Pr);

Description

The Pr argument identifies a live victim process attached to the controlling process by the create and grab interfaces. For more information, see the Pcreate(3PROC) and Pgrab(3PROC) man pages.

The Pstate() function returns the state of the victim process. One of the following return values are returned:

PS_RUN

Process is running

PS_STOP

Process is stopped

PS_LOST

Process is lost to control, needs the Preopen() function

PS_UNDEAD

Process is terminated or has become a zombie

PS_DEAD

No process has been run (examining a core file)

PS_IDLE

No process has been run (examining an ELF file)

The Pstop() function directs the victim process to stop and waits for it to stop. If the victim process is already stopped, the Pstop() function returns immediately. Else, it waits for at least msec milliseconds for the victim process to stop.

The Pdstop() function simply directs the victim process to stop and returns immediately.

The Pwait() function waits for at least msec milliseconds for the victim process to stop. If the victim process is already stopped, the Pwait() function returns immediately.

The Prefresh() function refreshes the state of the victim process. This is needed after a stop-on-exec event, at least, to reconstruct the data model of the process.

The Pclearsig() function clears the current signal, if any.

The Pclearfault() function clears the current fault, if any.

The Psetrun() function sets the stopped victim process running. If the sig argument is non-zero, it identifies a signal that will be posted to the process when it is set to running. The flags argument is constructed by a bitwise-inclusive-OR of the following flags:

PRCSIG

Clears the current signal, if any

PRCFAULT

Clears the current fault, if any

PRSTEP

Directs the thread or lwp to single-step

PRSABORT

If sleeping in a syscall, abort the syscall

PRSTOP

Sets the directed stop request (run and stop as soon as possible)

The Preopen() function should be called only if a previous process control operation returned EAGAIN, and the Pstate() function returned PS_LOST which means that the process is lost to control.

Return Values

The Pstate() function returns the current state of the victim process. It returns no errors.

On successful completion, the Pstop(), Pdstop(), Pwait(), Prefresh(), Pclearsig(), Pclearfault(), Psetrun(), and Preopen() functions return 0. On error, they return -1 and set errno to indicate the error.

Errors

On failure, these errno values may be set:

EAGAIN

Process has been lost to control, needs the Preopen() function

EBUSY

Process is not stopped (Psetrun())

EINTR

Signal received while waiting for stop

EINVAL

Invalid argument

ENOENT

The victim process has terminated

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Committed
MT-Level
Unsafe

See Also

libproc.h(3HEAD), libproc(3LIB), Pcreate(3PROC), Pgrab(3PROC), proc(5)