share/man/man3proc/ps_pstop.3proc

   1 '\" te
   2 .\"  Copyright (c) 2001 Sun Microsystems, Inc.  All Rights Reserved
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH PS_PSTOP 3PROC "Mar 22, 2001"
   7 .SH NAME
   8 ps_pstop, ps_pcontinue, ps_lstop, ps_lcontinue, ps_lrolltoaddr, ps_kill \-
   9 process and LWP control in libthread_db
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <proc_service.h>
  14
  15 \fBps_err_e\fR \fBps_pstop\fR(\fBstruct ps_prochandle *\fR\fIph\fR);
  16 .fi
  17
  18 .LP
  19 .nf
  20 \fBps_err_e\fR \fBps_pcontinue\fR(\fBstruct ps_prochandle *\fR\fIph\fR);
  21 .fi
  22
  23 .LP
  24 .nf
  25 \fBps_err_e\fR \fBps_lstop\fR(\fBstruct ps_prochandle *\fR\fIph\fR, \fBlwpid_t\fR \fIlwpid\fR);
  26 .fi
  27
  28 .LP
  29 .nf
  30 \fBps_err_e\fR \fBps_lcontinue\fR(\fBstruct ps_prochandle *\fR\fIph\fR,
  31      \fBlwpid_t\fR \fIlwpid\fR);
  32 .fi
  33
  34 .LP
  35 .nf
  36 \fBps_err_e\fR \fBps_lrolltoaddr\fR(\fBstruct ps_prochandle *\fR\fIph\fR,
  37      \fBlwpid_t\fR \fIlwpid\fR, \fBpsaddr_t\fR \fIgo_addr\fR, \fBpsaddr_t\fR \fIstop_addr\fR);
  38 .fi
  39
  40 .LP
  41 .nf
  42 \fBps_err_e\fR \fBps_kill\fR(\fBstruct ps_prochandle *\fR\fIph\fR, \fBint\fR \fIsignum\fR);
  43 .fi
  44
  45 .SH DESCRIPTION
  46 .LP
  47 \fBThe ps_pstop()\fR function stops the target process identified by \fIph\fR,
  48 while the \fBps_pcontinue()\fR function allows it to resume.
  49 .sp
  50 .LP
  51 The \fBlibthread_db()\fR function uses \fBps_pstop()\fR to freeze the target
  52 process while it is under inspection. Within the scope of any single call from
  53 outside \fBlibthread_db\fR to a \fBlibthread_db\fR routine, \fBlibthread_db\fR
  54 will call \fBps_pstop()\fR, at most once. If it does, it will call
  55 \fBps_pcontinue()\fR within the scope of the same routine.
  56 .sp
  57 .LP
  58 The controlling process may already have stopped the target process when it
  59 calls \fBlibthread_db\fR. In that case, it is not obligated to resume the
  60 target process when \fBlibthread_db\fR calls \fBps_pcontinue()\fR. In other
  61 words, \fBps_pstop()\fR is mandatory, while \fBps_pcontinue()\fR is advisory.
  62 After \fBps_pstop()\fR, the target process must be stopped; after
  63 \fBps_pcontinue()\fR, the target process may be running.
  64 .sp
  65 .LP
  66 The \fBps_lstop()\fR and \fBps_lcontinue()\fR functions stop and resume a
  67 single lightweight process (\fBLWP\fR) within the target process \fIph\fR.
  68 .sp
  69 .LP
  70 The \fBps_lrolltoaddr()\fR function is used to roll an \fBLWP\fR forward out of
  71 a critical section when the process is stopped. It is also used to run the
  72 \fBlibthread_db\fR agent thread on behalf of \fBlibthread\fR. The
  73 \fBps_lrolltoaddr()\fR function is always called with the target process
  74 stopped, that is, there has been a preceding call to \fBps_pstop()\fR. The
  75 specified \fBLWP\fR must be continued at the address \fIgo_addr\fR, or at its
  76 current address if \fIgo_addr\fR is \fINULL\fR. It should then be stopped when
  77 its execution reaches \fIstop_addr\fR. This routine does not return until the
  78 \fBLWP\fR has stopped at \fIstop_addr\fR.
  79 .sp
  80 .LP
  81 The \fBps_kill()\fR function directs the signal \fIsignum\fR to the target
  82 process for which the handle is \fIph\fR. It has the same semantics as
  83 \fBkill\fR(2).
  84 .SH RETURN VALUES
  85 .ne 2
  86 .na
  87 \fB\fBPS_OK\fR \fR
  88 .ad
  89 .RS 14n
  90 The call completed successfully. In the case of \fBps_pstop()\fR, the target
  91 process is stopped.
  92 .RE
  93
  94 .sp
  95 .ne 2
  96 .na
  97 \fB\fBPS_BADLID\fR \fR
  98 .ad
  99 .RS 14n
 100 For \fBps_lstop()\fR, \fBps_lcontinue()\fR and \fBps_lrolltoaddr()\fR; there is
 101 no \fBLWP\fR with id \fIlwpid\fR in the target process.
 102 .RE
 103
 104 .sp
 105 .ne 2
 106 .na
 107 \fB\fBPS_ERR\fR \fR
 108 .ad
 109 .RS 14n
 110 The function did not return successfully.
 111 .RE
 112
 113 .SH ATTRIBUTES
 114 .LP
 115 See \fBattributes\fR(5) for description of the following attributes:
 116 .sp
 117
 118 .sp
 119 .TS
 120 box;
 121 c | c
 122 l | l .
 123 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 124 _
 125 MT Level        Safe
 126 .TE
 127
 128 .SH SEE ALSO
 129 .LP
 130 \fBkill\fR(2), \fBlibc_db\fR(3LIB), \fBproc_service\fR(3PROC),
 131 \fBattributes\fR(5), \fBthreads\fR(5)