lib/libc/sys/ptrace.2

   1 .\" $FreeBSD: src/lib/libc/sys/ptrace.2,v 1.12.2.12 2001/12/14 18:34:01 ru Exp $
   2 .\" $DragonFly: src/lib/libc/sys/ptrace.2,v 1.4 2006/05/26 19:39:37 swildner Exp $
   3 .\"     $NetBSD: ptrace.2,v 1.2 1995/02/27 12:35:37 cgd Exp $
   4 .\"
   5 .\" This file is in the public domain.
   6 .Dd January 20, 1996
   7 .Dt PTRACE 2
   8 .Os
   9 .Sh NAME
  10 .Nm ptrace
  11 .Nd process tracing and debugging
  12 .Sh LIBRARY
  13 .Lb libc
  14 .Sh SYNOPSIS
  15 .In sys/types.h
  16 .In sys/ptrace.h
  17 .Ft int
  18 .Fn ptrace "int request" "pid_t pid" "caddr_t addr" "int data"
  19 .Sh DESCRIPTION
  20 .Fn ptrace
  21 provides tracing and debugging facilities.  It allows one process (the
  22 .Em tracing
  23 process) to control another (the
  24 .Em traced
  25 process).  Most of the time, the traced process runs normally, but when
  26 it receives a signal
  27 (see
  28 .Xr sigaction 2 ) ,
  29 it stops.  The tracing process is expected to notice this via
  30 .Xr wait 2
  31 or the delivery of a
  32 .Dv SIGCHLD
  33 signal, examine the state of the stopped process, and cause it to
  34 terminate or continue as appropriate.
  35 .Fn ptrace
  36 is the mechanism by which all this happens.
  37 .Pp
  38 The
  39 .Fa request
  40 argument specifies what operation is being performed; the meaning of
  41 the rest of the arguments depends on the operation, but except for one
  42 special case noted below, all
  43 .Fn ptrace
  44 calls are made by the tracing process, and the
  45 .Fa pid
  46 argument specifies the process ID of the traced process.
  47 .Fa request
  48 can be:
  49 .Bl -tag -width 12n
  50 .It Dv PT_TRACE_ME
  51 This request is the only one used by the traced process; it declares
  52 that the process expects to be traced by its parent.  All the other
  53 arguments are ignored.  (If the parent process does not expect to trace
  54 the child, it will probably be rather confused by the results; once the
  55 traced process stops, it cannot be made to continue except via
  56 .Fn ptrace . )
  57 When a process has used this request and calls
  58 .Xr execve 2
  59 or any of the routines built on it
  60 (such as
  61 .Xr execv 3 ) ,
  62 it will stop before executing the first instruction of the new image.
  63 Also, any setuid or setgid bits on the executable being executed will
  64 be ignored.
  65 .It Dv PT_READ_I , Dv PT_READ_D
  66 These requests read a single
  67 .Vt int
  68 of data from the traced process' address space.  Traditionally,
  69 .Fn ptrace
  70 has allowed for machines with distinct address spaces for instruction
  71 and data, which is why there are two requests: conceptually,
  72 .Dv PT_READ_I
  73 reads from the instruction space and
  74 .Dv PT_READ_D
  75 reads from the data space.  In the current
  76 .Dx
  77 implementation, these
  78 two requests are completely identical.  The
  79 .Fa addr
  80 argument specifies the address (in the traced process' virtual address
  81 space) at which the read is to be done.  This address does not have to
  82 meet any alignment constraints.  The value read is returned as the
  83 return value from
  84 .Eo \&
  85 .Fn ptrace
  86 .Ec .
  87 .It Dv PT_WRITE_I , Dv PT_WRITE_D
  88 These requests parallel
  89 .Dv PT_READ_I
  90 and
  91 .Dv PT_READ_D ,
  92 except that they write rather than read.  The
  93 .Fa data
  94 argument supplies the value to be written.
  95 .It Dv PT_CONTINUE
  96 The traced process continues execution.
  97 .Fa addr
  98 is an address specifying the place where execution is to be resumed (a
  99 new value for the program counter), or
 100 .Po Vt caddr_t Pc Ns 1
 101 to indicate that execution is to pick up where it left off.
 102 .Fa data
 103 provides a signal number to be delivered to the traced process as it
 104 resumes execution, or 0 if no signal is to be sent.
 105 .It Dv PT_STEP
 106 The traced process is single stepped one instruction.
 107 .Fa addr
 108 should be passed
 109 .Po Vt caddr_t Pc Ns 1 .
 110 .Fa data
 111 is not used.
 112 .It Dv PT_KILL
 113 The traced process terminates, as if
 114 .Dv PT_CONTINUE
 115 had been used with
 116 .Dv SIGKILL
 117 given as the signal to be delivered.
 118 .It Dv PT_ATTACH
 119 This request allows a process to gain control of an otherwise unrelated
 120 process and begin tracing it.  It does not need any cooperation from
 121 the to-be-traced process.  In this case,
 122 .Fa pid
 123 specifies the process ID of the to-be-traced process, and the other two
 124 arguments are ignored.  This request requires that the target process
 125 must have the same real UID as the tracing process, and that it must
 126 not be executing a setuid or setgid executable.  (If the tracing
 127 process is running as root, these restrictions do not apply.)  The
 128 tracing process will see the newly-traced process stop and may then
 129 control it as if it had been traced all along.
 130 .It Dv PT_DETACH
 131 This request is like PT_CONTINUE, except that it does not allow
 132 specifying an alternate place to continue execution, and after it
 133 succeeds, the traced process is no longer traced and continues
 134 execution normally.
 135 .El
 136 .Pp
 137 Additionally, machine-specific requests can exist.  On the i386, these
 138 are:
 139 .Bl -tag -width 12n
 140 .It Dv PT_GETREGS
 141 This request reads the traced process' machine registers into the
 142 .Do
 143 .Vt "struct reg"
 144 .Dc
 145 (defined in
 146 .In machine/reg.h )
 147 pointed to by
 148 .Fa addr .
 149 .It Dv PT_SETREGS
 150 This request is the converse of
 151 .Dv PT_GETREGS ;
 152 it loads the traced process' machine registers from the
 153 .Do
 154 .Vt "struct reg"
 155 .Dc
 156 (defined in
 157 .In machine/reg.h )
 158 pointed to by
 159 .Fa addr .
 160 .It Dv PT_GETFPREGS
 161 This request reads the traced process' floating-point registers into
 162 the
 163 .Do
 164 .Vt "struct fpreg"
 165 .Dc
 166 (defined in
 167 .In machine/reg.h )
 168 pointed to by
 169 .Fa addr .
 170 .It Dv PT_SETFPREGS
 171 This request is the converse of
 172 .Dv PT_GETFPREGS ;
 173 it loads the traced process' floating-point registers from the
 174 .Do
 175 .Vt "struct fpreg"
 176 .Dc
 177 (defined in
 178 .In machine/reg.h )
 179 pointed to by
 180 .Fa addr .
 181 .It Dv PT_GETDBREGS
 182 This request reads the traced process' debug registers into
 183 the
 184 .Do
 185 .Vt "struct dbreg"
 186 .Dc
 187 (defined in
 188 .In machine/reg.h )
 189 pointed to by
 190 .Fa addr .
 191 .It Dv PT_SETDBREGS
 192 This request is the converse of
 193 .Dv PT_GETDBREGS ;
 194 it loads the traced process' debug registers from the
 195 .Do
 196 .Vt "struct dbreg"
 197 .Dc
 198 (defined in
 199 .In machine/reg.h )
 200 pointed to by
 201 .Fa addr .
 202 .El
 203 .Sh RETURN VALUES
 204 Some requests can cause
 205 .Fn ptrace
 206 to return
 207 .Li -1
 208 as a non-error value; to disambiguate,
 209 .Va errno
 210 can be set to 0 before the call and checked afterwards.
 211 .Sh ERRORS
 212 The
 213 .Fn ptrace
 214 function may fail if:
 215 .Bl -tag -width Er
 216 .It Bq Er ESRCH
 217 .Bl -bullet -compact
 218 .It
 219 No process having the specified process ID exists.
 220 .El
 221 .It Bq Er EINVAL
 222 .Bl -bullet -compact
 223 .It
 224 A process attempted to use
 225 .Dv PT_ATTACH
 226 on itself.
 227 .It
 228 The
 229 .Fa request
 230 was not one of the legal requests.
 231 .It
 232 The signal number (in
 233 .Fa data )
 234 to
 235 .Dv PT_CONTINUE
 236 was neither 0 nor a legal signal number.
 237 .It
 238 .Dv PT_GETREGS ,
 239 .Dv PT_SETREGS ,
 240 .Dv PT_GETFPREGS ,
 241 .Dv PT_SETFPREGS ,
 242 .Dv PT_GETDBREGS ,
 243 or
 244 .Dv PT_SETDBREGS
 245 was attempted on a process with no valid register set.  (This is
 246 normally true only of system processes.)
 247 .El
 248 .It Bq Er EBUSY
 249 .Bl -bullet -compact
 250 .It
 251 .Dv PT_ATTACH
 252 was attempted on a process that was already being traced.
 253 .It
 254 A request attempted to manipulate a process that was being traced by
 255 some process other than the one making the request.
 256 .It
 257 A request (other than
 258 .Dv PT_ATTACH )
 259 specified a process that wasn't stopped.
 260 .El
 261 .It Bq Er EPERM
 262 .Bl -bullet -compact
 263 .It
 264 A request (other than
 265 .Dv PT_ATTACH )
 266 attempted to manipulate a process that wasn't being traced at all.
 267 .It
 268 An attempt was made to use
 269 .Dv PT_ATTACH
 270 on a process in violation of the requirements listed under
 271 .Dv PT_ATTACH
 272 above.
 273 .El
 274 .El
 275 .Sh SEE ALSO
 276 .Xr execve 2 ,
 277 .Xr sigaction 2 ,
 278 .Xr wait 2 ,
 279 .Xr execv 3 ,
 280 .Xr i386_clr_watch 3 ,
 281 .Xr i386_set_watch 3
 282 .Sh HISTORY
 283 A
 284 .Fn ptrace
 285 function call appeared in
 286 .At v7 .