1.\" $NetBSD: ptrace.2,v 1.16 2002/01/11 21:17:30 christos 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.Fn ptrace . ) 57When a process has used this request and calls 58.Xr execve 2 59or any of the routines built on it 60.Po 61such as 62.Xr execv 3 63.Pc , 64it will stop before executing the first instruction of the new image. 65Also, any setuid or setgid bits on the executable being executed will 66be ignored. 67.It Dv PT_READ_I , Dv PT_READ_D 68These requests read a single 69.Li int 70of data from the traced process' address space. Traditionally, 71.Fn ptrace 72has allowed for machines with distinct address spaces for instruction 73and data, which is why there are two requests: conceptually, 74.Dv PT_READ_I 75reads from the instruction space and 76.Dv PT_READ_D 77reads from the data space. In the current 78.Nx 79implementation, these 80two requests are completely identical. The 81.Fa addr 82argument specifies the address (in the traced process' virtual address 83space) at which the read is to be done. This address does not have to 84meet any alignment constraints. The value read is returned as the 85return value from 86.Eo \& 87.Fn ptrace 88.Ec . 89.It Dv PT_WRITE_I , Dv PT_WRITE_D 90These requests parallel 91.Dv PT_READ_I 92and 93.Dv PT_READ_D , 94except that they write rather than read. The 95.Fa data 96argument supplies the value to be written. 97.\" .It Dv PT_READ_U 98.\" This request reads an 99.\" .Li int 100.\" from the traced process' user structure. The 101.\" .Fa addr 102.\" argument specifies the location of the int relative to the base of the 103.\" user structure; it will usually be an integer value cast to 104.\" .Li caddr_t 105.\" either explicitly or via the presence of a prototype for 106.\" .Eo \& 107.\" .Fn ptrace 108.\" .Ec . 109.\" Unlike 110.\" .Dv PT_READ_I 111.\" and 112.\" .Dv PT_READ_D , 113.\" .Fa addr 114.\" must be aligned on an 115.\" .Li int 116.\" boundary. The value read is returned as the return value from 117.\" .Eo \& 118.\" .Fn ptrace 119.\" .Ec . 120.\" .It Dv PT_WRITE_U 121.\" This request writes an 122.\" .Li int 123.\" into the traced process' user structure. 124.\" .Fa addr 125.\" specifies the offset, just as for 126.\" .Dv PT_READ_U , 127.\" and 128.\" .Fa data 129.\" specifies the value to be written, just as for 130.\" .Dv PT_WRITE_I 131.\" and 132.\" .Dv PT_WRITE_D . 133.It Dv PT_CONTINUE 134The traced process continues execution. 135.Fa addr 136is an address specifying the place where execution is to be resumed (a 137new value for the program counter), or 138.Li (caddr_t)1 139to indicate that execution is to pick up where it left off. 140.Fa data 141provides a signal number to be delivered to the traced process as it 142resumes execution, or 0 if no signal is to be sent. 143.It Dv PT_KILL 144The traced process terminates, as if 145.Dv PT_CONTINUE 146had been used with 147.Dv SIGKILL 148given as the signal to be delivered. 149.It Dv PT_ATTACH 150This request allows a process to gain control of an otherwise unrelated 151process and begin tracing it. It does not need any cooperation from 152the to-be-traced process. In this case, 153.Fa pid 154specifies the process ID of the to-be-traced process, and the other two 155arguments are ignored. This request requires that the target process 156must have the same real UID as the tracing process, and that it must 157not be executing a setuid or setgid executable. (If the tracing 158process is running as root, these restrictions do not apply.) The 159tracing process will see the newly-traced process stop and may then 160control it as if it had been traced all along. 161.Pp 162Three other restrictions apply to all tracing processes, even those 163running as root. First, no process may trace a system process. 164Second, no process may trace the process running 165.Xr init 8 . 166Third, if a process has its root directory set with 167.Xr chroot 2 , 168it may not trace another process unless that process's root directory 169is at or below the tracing process's root. 170.It Dv PT_DETACH 171This request is like PT_CONTINUE, except that after it 172succeeds, the traced process is no longer traced and continues 173execution normally. 174.El 175.Pp 176Additionally, the following requests exist but are 177not avaliable on all machine architectures. The file 178.Aq Pa machine/ptrace.h 179lists which requests exist on a given machine. 180.Bl -tag -width 12n 181.It Dv PT_STEP 182Execution continues as in request PT_CONTINUE; however 183as soon as possible after execution of at least one 184instruction, execution stops again. 185.It Dv PT_GETREGS 186This request reads the traced process' machine registers into the 187.Dq Li "struct reg" 188(defined in 189.Aq Pa machine/reg.h ) 190pointed to by 191.Fa addr . 192.It Dv PT_SETREGS 193This request is the converse of 194.Dv PT_GETREGS ; 195it loads the traced process' machine registers from the 196.Dq Li "struct reg" 197(defined in 198.Aq Pa machine/reg.h ) 199pointed to by 200.Fa addr . 201.It Dv PT_GETFPREGS 202This request reads the traced process' floating-point registers into 203the 204.Dq Li "struct fpreg" 205(defined in 206.Aq Pa machine/reg.h ) 207pointed to by 208.Fa addr . 209.It Dv PT_SETFPREGS 210This request is the converse of 211.Dv PT_GETFPREGS ; 212it loads the traced process' floating-point registers from the 213.Dq Li "struct fpreg" 214(defined in 215.Aq Pa machine/reg.h ) 216pointed to by 217.Fa addr . 218.\" .It Dv PT_SYSCALL 219.\" This request is like 220.\" .Dv PT_CONTINUE 221.\" except that the process will stop next time it executes any system 222.\" call. Information about the system call can be examined with 223.\" .Dv PT_READ_U 224.\" and potentially modified with 225.\" .Dv PT_WRITE_U 226.\" through the 227.\" .Li u_kproc.kp_proc.p_md 228.\" element of the user structure (see below). If the process is continued 229.\" with another 230.\" .Dv PT_SYSCALL 231.\" request, it will stop again on exit from the syscall, at which point 232.\" the return values can be examined and potentially changed. The 233.\" .Li u_kproc.kp_proc.p_md 234.\" element is of type 235.\" .Dq Li "struct mdproc" , 236.\" which should be declared by including 237.\" .Aq Pa sys/param.h , 238.\" .Aq Pa sys/user.h , 239.\" and 240.\" .Aq Pa machine/proc.h , 241.\" and contains the following fields (among others): 242.\" .Bl -item -compact -offset indent 243.\" .It 244.\" .Li syscall_num 245.\" .It 246.\" .Li syscall_nargs 247.\" .It 248.\" .Li syscall_args[8] 249.\" .It 250.\" .Li syscall_err 251.\" .It 252.\" .Li syscall_rv[2] 253.\" .El 254.\" When a process stops on entry to a syscall, 255.\" .Li syscall_num 256.\" holds the number of the syscall, 257.\" .Li syscall_nargs 258.\" holds the number of arguments it expects, and 259.\" .Li syscall_args 260.\" holds the arguments themselves. (Only the first 261.\" .Li syscall_nargs 262.\" elements of 263.\" .Li syscall_args 264.\" are guaranteed to be useful.) When a process stops on exit from a 265.\" syscall, 266.\" .Li syscall_num 267.\" is 268.\" .Eo \& 269.\" .Li -1 270.\" .Ec , 271.\" .Li syscall_err 272.\" holds the error number 273.\" .Po 274.\" see 275.\" .Xr errno 2 276.\" .Pc , 277.\" or 0 if no error occurred, and 278.\" .Li syscall_rv 279.\" holds the return values. (If the syscall returns only one value, only 280.\" .Li syscall_rv[0] 281.\" is useful.) The tracing process can modify any of these with 282.\" .Dv PT_WRITE_U ; 283.\" only some modifications are useful. 284.\" .Pp 285.\" On entry to a syscall, 286.\" .Li syscall_num 287.\" can be changed, and the syscall actually performed will correspond to 288.\" the new number (it is the responsibility of the tracing process to fill 289.\" in 290.\" .Li syscall_args 291.\" appropriately for the new call, but there is no need to modify 292.\" .Eo \& 293.\" .Li syscall_nargs 294.\" .Ec ). 295.\" If the new syscall number is 0, no syscall is actually performed; 296.\" instead, 297.\" .Li syscall_err 298.\" and 299.\" .Li syscall_rv 300.\" are passed back to the traced process directly (and therefore should be 301.\" filled in). If the syscall number is otherwise out of range, a dummy 302.\" syscall which simply produces an 303.\" .Er ENOSYS 304.\" error is effectively performed. 305.\" .Pp 306.\" On exit from a syscall, only 307.\" .Li syscall_err 308.\" and 309.\" .Li syscall_rv 310.\" can usefully be changed; they are set to the values returned by the 311.\" syscall and will be passed back to the traced process by the normal 312.\" syscall return mechanism. 313.El 314.Sh ERRORS 315Some requests can cause 316.Fn ptrace 317to return 318.Li -1 319as a non-error value; to disambiguate, 320.Va errno 321can be set to 0 before the call and checked afterwards. The possible 322errors are: 323.Bl -tag -width 4n 324.It Bq Er EAGAIN 325Process is currently exec'ing and cannot be traced. 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