1.\" $NetBSD: ptrace.2,v 1.13 2000/09/27 22:31:43 nathanw Exp $ 2.\" 3.\" This file is in the public domain. 4.Dd November 7, 1994 5.Dt PTRACE 2 6.Os 7.Sh NAME 8.Nm ptrace 9.Nd process tracing and debugging 10.Sh LIBRARY 11.Lb libc 12.Sh SYNOPSIS 13.Fd #include <sys/types.h> 14.Fd #include <sys/ptrace.h> 15.Ft int 16.Fn ptrace "int request" "pid_t pid" "caddr_t addr" "int data" 17.Sh DESCRIPTION 18.Fn ptrace 19provides tracing and debugging facilities. It allows one process (the 20.Em tracing 21process) to control another (the 22.Em traced 23process). Most of the time, the traced process runs normally, but when 24it receives a signal 25.Po 26see 27.Xr sigaction 2 28.Pc , 29it stops. The tracing process is expected to notice this via 30.Xr wait 2 31or the delivery of a 32.Dv SIGCHLD 33signal, examine the state of the stopped process, and cause it to 34terminate or continue as appropriate. 35.Fn ptrace 36is the mechanism by which all this happens. 37.Pp 38The 39.Fa request 40argument specifies what operation is being performed; the meaning of 41the rest of the arguments depends on the operation, but except for one 42special case noted below, all 43.Fn ptrace 44calls are made by the tracing process, and the 45.Fa pid 46argument specifies the process ID of the traced process. 47.Fa request 48can be: 49.Bl -tag -width 12n 50.It Dv PT_TRACE_ME 51This request is the only one used by the traced process; it declares 52that the process expects to be traced by its parent. All the other 53arguments are ignored. (If the parent process does not expect to trace 54the child, it will probably be rather confused by the results; once the 55traced process stops, it cannot be made to continue except via 56.Eo \& 57.Fn ptrace 58.Ec \&.) 59When a process has used this request and calls 60.Xr execve 2 61or any of the routines built on it 62.Po 63such as 64.Xr execv 3 65.Pc , 66it will stop before executing the first instruction of the new image. 67Also, any setuid or setgid bits on the executable being executed will 68be ignored. 69.It Dv PT_READ_I , Dv PT_READ_D 70These requests read a single 71.Li int 72of data from the traced process' address space. Traditionally, 73.Fn ptrace 74has allowed for machines with distinct address spaces for instruction 75and data, which is why there are two requests: conceptually, 76.Dv PT_READ_I 77reads from the instruction space and 78.Dv PT_READ_D 79reads from the data space. In the current 80.Nx 81implementation, these 82two requests are completely identical. The 83.Fa addr 84argument specifies the address (in the traced process' virtual address 85space) at which the read is to be done. This address does not have to 86meet any alignment constraints. The value read is returned as the 87return value from 88.Eo \& 89.Fn ptrace 90.Ec . 91.It Dv PT_WRITE_I , Dv PT_WRITE_D 92These requests parallel 93.Dv PT_READ_I 94and 95.Dv PT_READ_D , 96except that they write rather than read. The 97.Fa data 98argument supplies the value to be written. 99.\" .It Dv PT_READ_U 100.\" This request reads an 101.\" .Li int 102.\" from the traced process' user structure. The 103.\" .Fa addr 104.\" argument specifies the location of the int relative to the base of the 105.\" user structure; it will usually be an integer value cast to 106.\" .Li caddr_t 107.\" either explicitly or via the presence of a prototype for 108.\" .Eo \& 109.\" .Fn ptrace 110.\" .Ec . 111.\" Unlike 112.\" .Dv PT_READ_I 113.\" and 114.\" .Dv PT_READ_D , 115.\" .Fa addr 116.\" must be aligned on an 117.\" .Li int 118.\" boundary. The value read is returned as the return value from 119.\" .Eo \& 120.\" .Fn ptrace 121.\" .Ec . 122.\" .It Dv PT_WRITE_U 123.\" This request writes an 124.\" .Li int 125.\" into the traced process' user structure. 126.\" .Fa addr 127.\" specifies the offset, just as for 128.\" .Dv PT_READ_U , 129.\" and 130.\" .Fa data 131.\" specifies the value to be written, just as for 132.\" .Dv PT_WRITE_I 133.\" and 134.\" .Dv PT_WRITE_D . 135.It Dv PT_CONTINUE 136The traced process continues execution. 137.Fa addr 138is an address specifying the place where execution is to be resumed (a 139new value for the program counter), or 140.Li (caddr_t)1 141to indicate that execution is to pick up where it left off. 142.Fa data 143provides a signal number to be delivered to the traced process as it 144resumes execution, or 0 if no signal is to be sent. 145.It Dv PT_KILL 146The traced process terminates, as if 147.Dv PT_CONTINUE 148had been used with 149.Dv SIGKILL 150given as the signal to be delivered. 151.It Dv PT_ATTACH 152This request allows a process to gain control of an otherwise unrelated 153process and begin tracing it. It does not need any cooperation from 154the to-be-traced process. In this case, 155.Fa pid 156specifies the process ID of the to-be-traced process, and the other two 157arguments are ignored. This request requires that the target process 158must have the same real UID as the tracing process, and that it must 159not be executing a setuid or setgid executable. (If the tracing 160process is running as root, these restrictions do not apply.) The 161tracing process will see the newly-traced process stop and may then 162control it as if it had been traced all along. 163.Pp 164Three other restrictions apply to all tracing processes, even those 165running as root. First, no process may trace a system process. 166Second, no process may trace the process running 167.Xr init 8 . 168Third, if a process has its root directory set with 169.Xr chroot 2 , 170it may not trace another process unless that process's root directory 171is at or below the tracing process's root. 172.It Dv PT_DETACH 173This request is like PT_CONTINUE, except that after it 174succeeds, the traced process is no longer traced and continues 175execution normally. 176.El 177.Pp 178Additionally, the following requests exist but are 179not avaliable on all machine architectures. The file 180.Aq Pa machine/ptrace.h 181lists which requests exist on a given machine. 182.Bl -tag -width 12n 183.It Dv PT_STEP 184Execution continues as in request PT_CONTINUE; however 185as soon as possible after execution of at least one 186instruction, execution stops again. 187.It Dv PT_GETREGS 188This request reads the traced process' machine registers into the 189.Dq Li "struct reg" 190(defined in 191.Aq Pa machine/reg.h ) 192pointed to by 193.Fa addr . 194.It Dv PT_SETREGS 195This request is the converse of 196.Dv PT_GETREGS ; 197it loads the traced process' machine registers from the 198.Dq Li "struct reg" 199(defined in 200.Aq Pa machine/reg.h ) 201pointed to by 202.Fa addr . 203.It Dv PT_GETFPREGS 204This request reads the traced process' floating-point registers into 205the 206.Dq Li "struct fpreg" 207(defined in 208.Aq Pa machine/reg.h ) 209pointed to by 210.Fa addr . 211.It Dv PT_SETFPREGS 212This request is the converse of 213.Dv PT_GETFPREGS ; 214it loads the traced process' floating-point registers from the 215.Dq Li "struct fpreg" 216(defined in 217.Aq Pa machine/reg.h ) 218pointed to by 219.Fa addr . 220.\" .It Dv PT_SYSCALL 221.\" This request is like 222.\" .Dv PT_CONTINUE 223.\" except that the process will stop next time it executes any system 224.\" call. Information about the system call can be examined with 225.\" .Dv PT_READ_U 226.\" and potentially modified with 227.\" .Dv PT_WRITE_U 228.\" through the 229.\" .Li u_kproc.kp_proc.p_md 230.\" element of the user structure (see below). If the process is continued 231.\" with another 232.\" .Dv PT_SYSCALL 233.\" request, it will stop again on exit from the syscall, at which point 234.\" the return values can be examined and potentially changed. The 235.\" .Li u_kproc.kp_proc.p_md 236.\" element is of type 237.\" .Dq Li "struct mdproc" , 238.\" which should be declared by including 239.\" .Aq Pa sys/param.h , 240.\" .Aq Pa sys/user.h , 241.\" and 242.\" .Aq Pa machine/proc.h , 243.\" and contains the following fields (among others): 244.\" .Bl -item -compact -offset indent 245.\" .It 246.\" .Li syscall_num 247.\" .It 248.\" .Li syscall_nargs 249.\" .It 250.\" .Li syscall_args[8] 251.\" .It 252.\" .Li syscall_err 253.\" .It 254.\" .Li syscall_rv[2] 255.\" .El 256.\" When a process stops on entry to a syscall, 257.\" .Li syscall_num 258.\" holds the number of the syscall, 259.\" .Li syscall_nargs 260.\" holds the number of arguments it expects, and 261.\" .Li syscall_args 262.\" holds the arguments themselves. (Only the first 263.\" .Li syscall_nargs 264.\" elements of 265.\" .Li syscall_args 266.\" are guaranteed to be useful.) When a process stops on exit from a 267.\" syscall, 268.\" .Li syscall_num 269.\" is 270.\" .Eo \& 271.\" .Li -1 272.\" .Ec , 273.\" .Li syscall_err 274.\" holds the error number 275.\" .Po 276.\" see 277.\" .Xr errno 2 278.\" .Pc , 279.\" or 0 if no error occurred, and 280.\" .Li syscall_rv 281.\" holds the return values. (If the syscall returns only one value, only 282.\" .Li syscall_rv[0] 283.\" is useful.) The tracing process can modify any of these with 284.\" .Dv PT_WRITE_U ; 285.\" only some modifications are useful. 286.\" .Pp 287.\" On entry to a syscall, 288.\" .Li syscall_num 289.\" can be changed, and the syscall actually performed will correspond to 290.\" the new number (it is the responsibility of the tracing process to fill 291.\" in 292.\" .Li syscall_args 293.\" appropriately for the new call, but there is no need to modify 294.\" .Eo \& 295.\" .Li syscall_nargs 296.\" .Ec ). 297.\" If the new syscall number is 0, no syscall is actually performed; 298.\" instead, 299.\" .Li syscall_err 300.\" and 301.\" .Li syscall_rv 302.\" are passed back to the traced process directly (and therefore should be 303.\" filled in). If the syscall number is otherwise out of range, a dummy 304.\" syscall which simply produces an 305.\" .Er ENOSYS 306.\" error is effectively performed. 307.\" .Pp 308.\" On exit from a syscall, only 309.\" .Li syscall_err 310.\" and 311.\" .Li syscall_rv 312.\" can usefully be changed; they are set to the values returned by the 313.\" syscall and will be passed back to the traced process by the normal 314.\" syscall return mechanism. 315.El 316.Sh ERRORS 317Some requests can cause 318.Fn ptrace 319to return 320.Li -1 321as a non-error value; to disambiguate, 322.Va errno 323can be set to 0 before the call and checked afterwards. The possible 324errors are: 325.Bl -tag -width 4n 326.It Bq Er ESRCH 327No process having the specified process ID exists. 328.It Bq Er EINVAL 329.Bl -bullet -compact 330.It 331A process attempted to use 332.Dv PT_ATTACH 333on itself. 334.It 335The 336.Fa request 337was not a legal request on this machine architecture. 338.\" .It 339.\" The 340.\" .Fa addr 341.\" to 342.\" .Dv PT_READ_U 343.\" or 344.\" .Dv PT_WRITE_U 345.\" was not 346.\" .Li int Ns \&-aligned. 347.It 348The signal number (in 349.Fa data ) 350to 351.Dv PT_CONTINUE 352.\" or 353.\" .Dv PT_SYSCALL 354was neither 0 nor a legal signal number. 355.It 356.Dv PT_GETREGS , 357.Dv PT_SETREGS , 358.Dv PT_GETFPREGS , 359or 360.Dv PT_SETFPREGS 361was attempted on a process with no valid register set. (This is 362normally true only of system processes.) 363.El 364.It Bq Er EBUSY 365.Bl -bullet -compact 366.It 367.Dv PT_ATTACH 368was attempted on a process that was already being traced. 369.It 370A request attempted to manipulate a process that was being traced by 371some process other than the one making the request. 372.It 373A request (other than 374.Dv PT_ATTACH ) 375specified a process that wasn't stopped. 376.El 377.It Bq Er EPERM 378.Bl -bullet -compact 379.It 380A request (other than 381.Dv PT_ATTACH ) 382attempted to manipulate a process that wasn't being traced at all. 383.It 384An attempt was made to use 385.Dv PT_ATTACH 386on a process in violation of the requirements listed under 387.Dv PT_ATTACH 388above. 389.El 390.El 391.Sh SEE ALSO 392.Xr sigaction 2 , 393.Xr signal 7 394.Sh BUGS 395On the SPARC, the PC is set to the provided PC value for 396.Dv PT_CONTINUE 397and similar calls, but the NPC is set willy-nilly to 4 greater than the 398PC value. Using 399.Dv PT_GETREGS 400and 401.Dv PT_SETREGS 402to modify the PC, passing 403.Li (caddr_t)1 404to 405.Eo \& 406.Fn ptrace 407.Ec , 408should be able to sidestep this. 409.\" .Pp 410.\" When using 411.\" .Dv PT_SYSCALL , 412.\" there is no easy way to tell whether the traced process stopped because 413.\" it made a syscall or because a signal was sent at a moment that it just 414.\" happened to have valid-looking garbage in its 415.\" .Dq Li "struct mdproc" . 416