usr/src/man/man3c/ptrace.3c

   1 '\" te
   2 .\" Copyright 1989 AT&T  Copyright (c) 2004, 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 PTRACE 3C "Mar 22, 2004"
   7 .SH NAME
   8 ptrace \- allows a parent process to control the execution of a child process
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <unistd.h>
  13 #include <sys/types.h>
  14
  15 \fBint\fR \fBptrace\fR(\fBint\fR \fIrequest\fR, \fBpid_t\fR \fIpid\fR, \fBint\fR \fIaddr\fR, \fBint\fR \fIdata\fR);
  16 .fi
  17
  18 .SH DESCRIPTION
  19 .sp
  20 .LP
  21 The \fBptrace()\fR function allows a parent process to control the execution of
  22 a child process. Its primary use is for the implementation of breakpoint
  23 debugging. The child process behaves normally until it encounters a signal (see
  24 \fBsignal.h\fR(3HEAD)), at which time it enters a stopped state and its parent
  25 is notified by the \fBwait\fR(3C) function. When the child is in the stopped
  26 state, its parent can examine and modify its "core image" using \fBptrace()\fR.
  27 Also, the parent can cause the child either to terminate or continue, with the
  28 possibility of ignoring the signal that caused it to stop.
  29 .sp
  30 .LP
  31 The \fIrequest\fR argument determines the action to be taken by \fBptrace()\fR
  32 and is one of the following:
  33 .sp
  34 .ne 2
  35 .na
  36 \fB\fB0\fR\fR
  37 .ad
  38 .RS 5n
  39 This request must be issued by the child process if it is to be traced by its
  40 parent. It turns on the child's trace flag that stipulates that the child
  41 should be left in a stopped state on receipt of a signal rather than the state
  42 specified by \fIfunc\fR (see \fBsignal\fR(3C)). The \fIpid\fR, \fIaddr\fR, and
  43 \fIdata\fR arguments are ignored, and a return value is not defined for this
  44 request. Peculiar results ensue if the parent does not expect to trace the
  45 child.
  46 .RE
  47
  48 .sp
  49 .LP
  50 The remainder of the requests can only be used by the parent process. For each,
  51 \fIpid\fR is the process \fBID\fR of the child. The child must be in a stopped
  52 state before these requests are made.
  53 .sp
  54 .ne 2
  55 .na
  56 \fB\fB1, 2\fR\fR
  57 .ad
  58 .RS 8n
  59 With these requests, the word at location \fIaddr\fR in the address space of
  60 the child is returned to the parent process. If instruction and data space are
  61 separated, request \fB1\fR returns a word from instruction space, and request
  62 \fB2\fR returns a word from data space. If instruction and data space are not
  63 separated, either request \fB1\fR or request \fB2\fR may be used with equal
  64 results. The \fIdata\fR argument is ignored. These two requests fail if
  65 \fIaddr\fR is not the start address of a word, in which case \fB\(mi1\fR is
  66 returned to the parent process and the parent's \fBerrno\fR is set to
  67 \fBEIO\fR.
  68 .RE
  69
  70 .sp
  71 .ne 2
  72 .na
  73 \fB\fB3\fR\fR
  74 .ad
  75 .RS 8n
  76 With this request, the word at location \fIaddr\fR in the child's user area in
  77 the system's address space (see <\fBsys/user.h\fR>) is returned to the parent
  78 process. The \fIdata\fR argument is ignored. This request fails if \fIaddr\fR
  79 is not the start address of a word or is outside the user area, in which case
  80 \fB\(mi1\fR is returned to the parent process and the parent's \fBerrno\fR is
  81 set to \fBEIO\fR.
  82 .RE
  83
  84 .sp
  85 .ne 2
  86 .na
  87 \fB\fB4, 5\fR\fR
  88 .ad
  89 .RS 8n
  90 With these requests, the value given by the \fIdata\fR argument is written into
  91 the address space of the child at location \fIaddr\fR. If instruction and data
  92 space are separated, request \fB4\fR writes a word into instruction space, and
  93 request \fB5\fR writes a word into data space. If instruction and data space
  94 are not separated, either request \fB4\fR or request \fB5\fR may be used with
  95 equal results. On success, the value written into the address space of the
  96 child is returned to the parent. These two requests fail if \fIaddr\fR is not
  97 the start address of a word. On failure \fB\(mi1\fR is returned to the parent
  98 process and the parent's \fBerrno\fR is set to \fBEIO\fR.
  99 .RE
 100
 101 .sp
 102 .ne 2
 103 .na
 104 \fB\fB6\fR\fR
 105 .ad
 106 .RS 8n
 107 With this request, a few entries in the child's user area can be written.
 108 \fIdata\fR gives the value that is to be written and \fIaddr\fR is the location
 109 of the entry. The few entries that can be written are the general registers and
 110 the condition codes of the Processor Status Word.
 111 .RE
 112
 113 .sp
 114 .ne 2
 115 .na
 116 \fB\fB7\fR\fR
 117 .ad
 118 .RS 8n
 119 This request causes the child to resume execution. If the \fIdata\fR argument
 120 is 0, all pending signals including the one that caused the child to stop are
 121 canceled before it resumes execution. If the \fIdata\fR argument is a valid
 122 signal number, the child resumes execution as if it had incurred that signal,
 123 and any other pending signals are canceled. The \fIaddr\fR argument must be
 124 equal to 1 for this request. On success, the  value of \fIdata\fR is returned
 125 to the parent. This request fails if \fIdata\fR is not 0 or a valid signal
 126 number, in which case \fB\(mi1\fR is returned to the parent process and the
 127 parent's \fBerrno\fR is set to \fBEIO\fR.
 128 .RE
 129
 130 .sp
 131 .ne 2
 132 .na
 133 \fB\fB8\fR\fR
 134 .ad
 135 .RS 8n
 136 This request causes the child to terminate with the same consequences as
 137 \fBexit\fR(2).
 138 .RE
 139
 140 .sp
 141 .ne 2
 142 .na
 143 \fB\fB9\fR\fR
 144 .ad
 145 .RS 8n
 146 This request sets the trace bit in the Processor Status Word of the child and
 147 then executes the same steps as listed above for request \fB7\fR. The trace bit
 148 causes an interrupt on completion of one machine instruction. This effectively
 149 allows single stepping of the child.
 150 .RE
 151
 152 .sp
 153 .LP
 154 To forestall possible fraud, \fBptrace()\fR inhibits the set-user-ID facility
 155 on subsequent calls to one of the \fBexec\fR family of functions (see
 156 \fBexec\fR(2)). If a traced process calls one of these functions, it stops
 157 before executing the first instruction of the new image showing signal
 158 \fBSIGTRAP\fR.
 159 .SH ERRORS
 160 .sp
 161 .LP
 162 The \fBptrace()\fR function will fail if:
 163 .sp
 164 .ne 2
 165 .na
 166 \fB\fBEIO\fR\fR
 167 .ad
 168 .RS 9n
 169 The \fIrequest\fR argument is an illegal number.
 170 .RE
 171
 172 .sp
 173 .ne 2
 174 .na
 175 \fB\fBEPERM\fR\fR
 176 .ad
 177 .RS 9n
 178 The calling process does not have appropriate privileges to control the calling
 179 process. See \fBproc\fR(4).
 180 .RE
 181
 182 .sp
 183 .ne 2
 184 .na
 185 \fB\fBESRCH\fR\fR
 186 .ad
 187 .RS 9n
 188 The \fIpid\fR argument identifies a child that does not exist or has not
 189 executed a \fBptrace()\fR call with request \fB0\fR.
 190 .RE
 191
 192 .SH USAGE
 193 .sp
 194 .LP
 195 The \fBptrace()\fR function is available only with the 32-bit version of
 196 \fBlibc\fR(3LIB). It is not available with the 64-bit version of this library.
 197 .sp
 198 .LP
 199 The \fB/proc\fR debugging interfaces should be used instead of \fBptrace()\fR,
 200 which provides quite limited debugger support and is itself implemented using
 201 the \fB/proc\fR interfaces. There is no actual \fBptrace()\fR system call in
 202 the kernel. See \fBproc\fR(4) for descriptions of the \fB/proc\fR debugging
 203 interfaces.
 204 .SH ATTRIBUTES
 205 .sp
 206 .LP
 207 See \fBattributes\fR(5) for descriptions of the following attributes:
 208 .sp
 209
 210 .sp
 211 .TS
 212 box;
 213 c | c
 214 l | l .
 215 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 216 _
 217 Interface Stability     Standard
 218 _
 219 MT-Level        MT-Safe
 220 .TE
 221
 222 .SH SEE ALSO
 223 .sp
 224 .LP
 225 \fBexec\fR(2), \fBexit\fR(2), \fBlibc\fR(3LIB), \fBsignal\fR(3C),
 226 \fBsignal.h\fR(3HEAD), \fBwait\fR(3C), \fBproc\fR(4), \fBattributes\fR(5)