man/man3proc/ps_pstop.3proc

         te
 Copyright (c) 2001 Sun Microsystems, Inc. All Rights Reserved
 The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
 You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
 When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
 PS_PSTOP 3PROC "Mar 22, 2001"
 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(5) for description of the following attributes:


ATTRIBUTE TYPE ATTRIBUTE VALUE
MT Level Safe


 SEE ALSO

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