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

NAME

ps_pstop, ps_pcontinue, ps_lstop, ps_lcontinue, ps_lrolltoaddr,
ps_kill - process and LWP control in libthread_db

SYNOPSIS

#include <proc_service.h>

ps_err_e ps_pstop(struct ps_prochandle *ph);


ps_err_e ps_pcontinue(struct ps_prochandle *ph);


ps_err_e ps_lstop(struct ps_prochandle *ph, lwpid_t lwpid);


ps_err_e ps_lcontinue(struct ps_prochandle *ph,
lwpid_t lwpid);


ps_err_e ps_lrolltoaddr(struct ps_prochandle *ph,
lwpid_t lwpid, psaddr_t go_addr, psaddr_t stop_addr);


ps_err_e ps_kill(struct ps_prochandle *ph, int signum);

DESCRIPTION

The ps_pstop() function stops the target process identified by ph,
while the ps_pcontinue() function allows it to resume.


The libthread_db() function uses ps_pstop() to freeze the target
process while it is under inspection. Within the scope of any single
call from outside libthread_db to a libthread_db routine,
libthread_db will call ps_pstop(), at most once. If it does, it will
call ps_pcontinue() within the scope of the same routine.


The controlling process may already have stopped the target process
when it calls libthread_db. In that case, it is not obligated to
resume the target process when libthread_db calls ps_pcontinue(). In
other words, ps_pstop() is mandatory, while ps_pcontinue() is
advisory. After ps_pstop(), the target process must be stopped;
after ps_pcontinue(), the target process may be running.


The ps_lstop() and ps_lcontinue() functions stop and resume a single
lightweight process (LWP) within the target process ph.


The ps_lrolltoaddr() function is used to roll an LWP forward out of a
critical section when the process is stopped. It is also used to run
the libthread_db agent thread on behalf of libthread. The
ps_lrolltoaddr() function is always called with the target process
stopped, that is, there has been a preceding call to ps_pstop(). The
specified LWP must be continued at the address go_addr, or at its
current address if go_addr is NULL. It should then be stopped when
its execution reaches stop_addr. This routine does not return until
the LWP has stopped at stop_addr.


The ps_kill() function directs the signal signum to the target
process for which the handle is ph. It has the same semantics as
kill(2).

RETURN VALUES

PS_OK
The call completed successfully. In the case of
ps_pstop(), the target process is stopped.


PS_BADLID
For ps_lstop(), ps_lcontinue() and ps_lrolltoaddr();
there is no LWP with id lwpid in the target process.


PS_ERR
The function did not return successfully.

ATTRIBUTES

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


+---------------+-----------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+-----------------+
|MT Level | Safe |
+---------------+-----------------+

SEE ALSO

kill(2), libc_db(3LIB), proc_service(3PROC), attributes(7),
threads(7)

March 22, 2001 PS_PSTOP(3PROC)