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)