1.\" $NetBSD: ptrace.2,v 1.19 2002/04/06 04:07:13 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 \*[Lt]sys/types.h\*[Gt] 14.Fd #include \*[Lt]sys/ptrace.h\*[Gt] 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.It Dv PT_IO 175This request is a more general interface that can be used instead of 176.Dv PT_READ_D , 177.Dv PT_WRITE_D , 178.Dv PT_READ_I , 179and 180.Dv PT_WRITE_I . 181The I/O request is encoded in a 182.Dq Li "struct ptrace_io_desc" 183defined as: 184.Bd -literal -ffset indent 185struct ptrace_io_desc { 186 int piod_op; 187 void *piod_offs; 188 void *piod_addr; 189 size_t piod_len; 190}; 191.Ed 192.Pp 193where 194.Fa piod_offs 195is the offset within the traced process where the I/O operation should 196take place, 197.Fa piod_addr 198is the buffer in the tracing process, and 199.Fa piod_len 200is the length of the I/O request. The 201.Fa piod_op 202field specifies which type of I/O operation to perform. Possible 203values are: 204.Bl -tag -width 18n 205.It PIOD_READ_D 206.It PIOD_WRITE_D 207.It PIOD_READ_I 208.It PIOD_WRITE_I 209.El 210.Pp 211See the description of 212.Dv PT_READ_I 213for the difference between I and D spaces. 214A pointer to the I/O descriptor is passed in the 215.Fa addr 216argument to 217.Fn ptrace . 218On return, the 219.Fa piod_len 220field in the I/O descriptor will be updated with the actual number of 221bytes transferred. If the requested I/O could not be successfully 222performed, 223.Fn ptrace 224will return 225.Li -1 226and set 227.Va errno . 228.El 229.Pp 230Additionally, the following requests exist but are 231not avaliable on all machine architectures. The file 232.Aq Pa machine/ptrace.h 233lists which requests exist on a given machine. 234.Bl -tag -width 12n 235.It Dv PT_STEP 236Execution continues as in request PT_CONTINUE; however 237as soon as possible after execution of at least one 238instruction, execution stops again. 239.It Dv PT_GETREGS 240This request reads the traced process' machine registers into the 241.Dq Li "struct reg" 242(defined in 243.Aq Pa machine/reg.h ) 244pointed to by 245.Fa addr . 246.It Dv PT_SETREGS 247This request is the converse of 248.Dv PT_GETREGS ; 249it loads the traced process' machine registers from the 250.Dq Li "struct reg" 251(defined in 252.Aq Pa machine/reg.h ) 253pointed to by 254.Fa addr . 255.It Dv PT_GETFPREGS 256This request reads the traced process' floating-point registers into 257the 258.Dq Li "struct fpreg" 259(defined in 260.Aq Pa machine/reg.h ) 261pointed to by 262.Fa addr . 263.It Dv PT_SETFPREGS 264This request is the converse of 265.Dv PT_GETFPREGS ; 266it loads the traced process' floating-point registers from the 267.Dq Li "struct fpreg" 268(defined in 269.Aq Pa machine/reg.h ) 270pointed to by 271.Fa addr . 272.\" .It Dv PT_SYSCALL 273.\" This request is like 274.\" .Dv PT_CONTINUE 275.\" except that the process will stop next time it executes any system 276.\" call. Information about the system call can be examined with 277.\" .Dv PT_READ_U 278.\" and potentially modified with 279.\" .Dv PT_WRITE_U 280.\" through the 281.\" .Li u_kproc.kp_proc.p_md 282.\" element of the user structure (see below). If the process is continued 283.\" with another 284.\" .Dv PT_SYSCALL 285.\" request, it will stop again on exit from the syscall, at which point 286.\" the return values can be examined and potentially changed. The 287.\" .Li u_kproc.kp_proc.p_md 288.\" element is of type 289.\" .Dq Li "struct mdproc" , 290.\" which should be declared by including 291.\" .Aq Pa sys/param.h , 292.\" .Aq Pa sys/user.h , 293.\" and 294.\" .Aq Pa machine/proc.h , 295.\" and contains the following fields (among others): 296.\" .Bl -item -compact -offset indent 297.\" .It 298.\" .Li syscall_num 299.\" .It 300.\" .Li syscall_nargs 301.\" .It 302.\" .Li syscall_args[8] 303.\" .It 304.\" .Li syscall_err 305.\" .It 306.\" .Li syscall_rv[2] 307.\" .El 308.\" When a process stops on entry to a syscall, 309.\" .Li syscall_num 310.\" holds the number of the syscall, 311.\" .Li syscall_nargs 312.\" holds the number of arguments it expects, and 313.\" .Li syscall_args 314.\" holds the arguments themselves. (Only the first 315.\" .Li syscall_nargs 316.\" elements of 317.\" .Li syscall_args 318.\" are guaranteed to be useful.) When a process stops on exit from a 319.\" syscall, 320.\" .Li syscall_num 321.\" is 322.\" .Eo \& 323.\" .Li -1 324.\" .Ec , 325.\" .Li syscall_err 326.\" holds the error number 327.\" .Po 328.\" see 329.\" .Xr errno 2 330.\" .Pc , 331.\" or 0 if no error occurred, and 332.\" .Li syscall_rv 333.\" holds the return values. (If the syscall returns only one value, only 334.\" .Li syscall_rv[0] 335.\" is useful.) The tracing process can modify any of these with 336.\" .Dv PT_WRITE_U ; 337.\" only some modifications are useful. 338.\" .Pp 339.\" On entry to a syscall, 340.\" .Li syscall_num 341.\" can be changed, and the syscall actually performed will correspond to 342.\" the new number (it is the responsibility of the tracing process to fill 343.\" in 344.\" .Li syscall_args 345.\" appropriately for the new call, but there is no need to modify 346.\" .Eo \& 347.\" .Li syscall_nargs 348.\" .Ec ). 349.\" If the new syscall number is 0, no syscall is actually performed; 350.\" instead, 351.\" .Li syscall_err 352.\" and 353.\" .Li syscall_rv 354.\" are passed back to the traced process directly (and therefore should be 355.\" filled in). If the syscall number is otherwise out of range, a dummy 356.\" syscall which simply produces an 357.\" .Er ENOSYS 358.\" error is effectively performed. 359.\" .Pp 360.\" On exit from a syscall, only 361.\" .Li syscall_err 362.\" and 363.\" .Li syscall_rv 364.\" can usefully be changed; they are set to the values returned by the 365.\" syscall and will be passed back to the traced process by the normal 366.\" syscall return mechanism. 367.El 368.Sh ERRORS 369Some requests can cause 370.Fn ptrace 371to return 372.Li -1 373as a non-error value; to disambiguate, 374.Va errno 375can be set to 0 before the call and checked afterwards. The possible 376errors are: 377.Bl -tag -width 4n 378.It Bq Er EAGAIN 379Process is currently exec'ing and cannot be traced. 380.It Bq Er ESRCH 381No process having the specified process ID exists. 382.It Bq Er EINVAL 383.Bl -bullet -compact 384.It 385A process attempted to use 386.Dv PT_ATTACH 387on itself. 388.It 389The 390.Fa request 391was not a legal request on this machine architecture. 392.\" .It 393.\" The 394.\" .Fa addr 395.\" to 396.\" .Dv PT_READ_U 397.\" or 398.\" .Dv PT_WRITE_U 399.\" was not 400.\" .Li int Ns \&-aligned. 401.It 402The signal number (in 403.Fa data ) 404to 405.Dv PT_CONTINUE 406.\" or 407.\" .Dv PT_SYSCALL 408was neither 0 nor a legal signal number. 409.It 410.Dv PT_GETREGS , 411.Dv PT_SETREGS , 412.Dv PT_GETFPREGS , 413or 414.Dv PT_SETFPREGS 415was attempted on a process with no valid register set. (This is 416normally true only of system processes.) 417.El 418.It Bq Er EBUSY 419.Bl -bullet -compact 420.It 421.Dv PT_ATTACH 422was attempted on a process that was already being traced. 423.It 424A request attempted to manipulate a process that was being traced by 425some process other than the one making the request. 426.It 427A request (other than 428.Dv PT_ATTACH ) 429specified a process that wasn't stopped. 430.El 431.It Bq Er EPERM 432.Bl -bullet -compact 433.It 434A request (other than 435.Dv PT_ATTACH ) 436attempted to manipulate a process that wasn't being traced at all. 437.It 438An attempt was made to use 439.Dv PT_ATTACH 440on a process in violation of the requirements listed under 441.Dv PT_ATTACH 442above. 443.El 444.El 445.Sh SEE ALSO 446.Xr sigaction 2 , 447.Xr signal 7 448.Sh BUGS 449On the SPARC, the PC is set to the provided PC value for 450.Dv PT_CONTINUE 451and similar calls, but the NPC is set willy-nilly to 4 greater than the 452PC value. Using 453.Dv PT_GETREGS 454and 455.Dv PT_SETREGS 456to modify the PC, passing 457.Li (caddr_t)1 458to 459.Eo \& 460.Fn ptrace 461.Ec , 462should be able to sidestep this. 463.\" .Pp 464.\" When using 465.\" .Dv PT_SYSCALL , 466.\" there is no easy way to tell whether the traced process stopped because 467.\" it made a syscall or because a signal was sent at a moment that it just 468.\" happened to have valid-looking garbage in its 469.\" .Dq Li "struct mdproc" . 470