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