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