1.\" $OpenBSD: ptrace.2,v 1.21 2005/09/15 14:07:40 jmc 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 March 2, 2004 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.El 221.Pp 222See also the description of 223.Dv PT_READ_I 224for the difference between D and I spaces. 225A pointer to the descriptor is passed in 226.Fa addr . 227On return the 228.Fa piod_len 229field in the descriptor will be updated with the actual number of bytes 230transferred. 231If the requested I/O couldn't be successfully performed 232.Fn ptrace 233will return 234.Li -1 235and set 236.Va errno . 237.It Dv PT_SET_EVENT_MASK 238This request can be used to specify which events in the traced process 239should be reported to the tracing process. 240These events are specified in a 241.Dq Li "struct ptrace_event" 242defined as: 243.Bd -literal -offset indent 244typedef struct ptrace_event { 245 int pe_set_event; 246} ptrace_event_t; 247.Ed 248.Pp 249Where 250.Fa pe_set_event 251is the set of events to be reported. 252This set is formed by OR'ing together the following values: 253.Bl -tag -width 18n 254.It PTRACE_FORK 255Report 256.Xr fork 2 . 257.El 258.Pp 259A pointer to this structure is passed in 260.Fa addr . 261The 262.Fa data 263argument should be set to 264.Li sizeof(struct ptrace_event) . 265.It Dv PT_GET_EVENT_MASK 266This request can be used to determine which events in the traced 267process will be reported. 268The information is read into the 269.Dq Li struct ptrace_event 270pointed to by 271.Fa addr . 272The 273.Fa data 274argument should be set to 275.Li sizeof(struct ptrace_event) . 276.It Dv PT_GET_PROCESS_STATE 277This request reads the state information associated with the event 278that stopped the traced process. 279The information is reported in a 280.Dq Li "struct ptrace_state" 281defined as: 282.Bd -literal -offset indent 283typedef struct ptrace_state { 284 int pe_report_event; 285 pid_t pe_other_pid; 286} ptrace_state_t; 287.Ed 288.Pp 289Where 290.Fa pe_report_event 291is the event being reported. 292If the event being reported is 293.Dv PTRACE_FORK , 294.Fa pe_other_pid 295will be set to the process ID of the other end of the fork. 296A pointer to this structure is passed in 297.Fa addr . 298The 299.Fa data 300argument should be set to 301.Li sizeof(struct ptrace_state) . 302.El 303.Pp 304Additionally, machine-specific requests can exist. 305All 306.Ox 307platforms support the following requests: 308.Bl -tag -width 12n 309.It Dv PT_GETREGS 310This request reads the traced process' machine registers into the 311.Dq Li struct reg 312(defined in 313.Aq Pa machine/reg.h ) 314pointed to by 315.Fa addr . 316.It Dv PT_SETREGS 317This request is the converse of 318.Dv PT_GETREGS ; 319it loads the traced process' machine registers from the 320.Dq Li struct reg 321(defined in 322.Aq Pa machine/reg.h ) 323pointed to by 324.Fa addr . 325.\" .It Dv PT_SYSCALL 326.\" This request is like 327.\" .Dv PT_CONTINUE 328.\" except that the process will stop next time it executes any system 329.\" call. Information about the system call can be examined with 330.\" .Dv PT_READ_U 331.\" and potentially modified with 332.\" .Dv PT_WRITE_U 333.\" through the 334.\" .Li u_kproc.kp_proc.p_md 335.\" element of the user structure (see below). If the process is continued 336.\" with another 337.\" .Dv PT_SYSCALL 338.\" request, it will stop again on exit from the syscall, at which point 339.\" the return values can be examined and potentially changed. The 340.\" .Li u_kproc.kp_proc.p_md 341.\" element is of type 342.\" .Dq Li struct mdproc , 343.\" which should be declared by including 344.\" .Aq Pa sys/param.h , 345.\" .Aq Pa sys/user.h , 346.\" and 347.\" .Aq Pa machine/proc.h , 348.\" and contains the following fields (among others): 349.\" .Bl -item -compact -offset indent 350.\" .It 351.\" .Li syscall_num 352.\" .It 353.\" .Li syscall_nargs 354.\" .It 355.\" .Li syscall_args[8] 356.\" .It 357.\" .Li syscall_err 358.\" .It 359.\" .Li syscall_rv[2] 360.\" .El 361.\" When a process stops on entry to a syscall, 362.\" .Li syscall_num 363.\" holds the number of the syscall, 364.\" .Li syscall_nargs 365.\" holds the number of arguments it expects, and 366.\" .Li syscall_args 367.\" holds the arguments themselves. (Only the first 368.\" .Li syscall_nargs 369.\" elements of 370.\" .Li syscall_args 371.\" are guaranteed to be useful.) When a process stops on exit from a 372.\" syscall, 373.\" .Li syscall_num 374.\" is 375.\" .Eo \& 376.\" .Li -1 377.\" .Ec , 378.\" .Li syscall_err 379.\" holds the error number 380.\" .Po 381.\" see 382.\" .Xr errno 2 383.\" .Pc , 384.\" or 0 if no error occurred, and 385.\" .Li syscall_rv 386.\" holds the return values. (If the syscall returns only one value, only 387.\" .Li syscall_rv[0] 388.\" is useful.) The tracing process can modify any of these with 389.\" .Dv PT_WRITE_U ; 390.\" only some modifications are useful. 391.\" .Pp 392.\" On entry to a syscall, 393.\" .Li syscall_num 394.\" can be changed, and the syscall actually performed will correspond to 395.\" the new number (it is the responsibility of the tracing process to fill 396.\" in 397.\" .Li syscall_args 398.\" appropriately for the new call, but there is no need to modify 399.\" .Eo \& 400.\" .Li syscall_nargs 401.\" .Ec ). 402.\" If the new syscall number is 0, no syscall is actually performed; 403.\" instead, 404.\" .Li syscall_err 405.\" and 406.\" .Li syscall_rv 407.\" are passed back to the traced process directly (and therefore should be 408.\" filled in). If the syscall number is otherwise out of range, a dummy 409.\" syscall which simply produces an 410.\" .Er ENOSYS 411.\" error is effectively performed. 412.\" .Pp 413.\" On exit from a syscall, only 414.\" .Li syscall_err 415.\" and 416.\" .Li syscall_rv 417.\" can usefully be changed; they are set to the values returned by the 418.\" syscall and will be passed back to the traced process by the normal 419.\" syscall return mechanism. 420.El 421.Pp 422In addition, all platforms but luna88k, mvme88k, sgi and vax 423support these additional requests: 424.Bl -tag -width 12n 425.It Dv PT_GETFPREGS 426This request reads the traced process' floating-point registers into 427the 428.Dq Li struct fpreg 429(defined in 430.Aq Pa machine/reg.h ) 431pointed to by 432.Fa addr . 433.It Dv PT_SETFPREGS 434This request is the converse of 435.Dv PT_GETFPREGS ; 436it loads the traced process' floating-point registers from the 437.Dq Li struct fpreg 438(defined in 439.Aq Pa machine/reg.h ) 440pointed to by 441.Fa addr . 442.El 443.Pp 444The following requests are available on i386: 445.Bl -tag -width 12n 446.It Dv PT_GETXMMREGS 447This request reads the traced process' XMM registers into the 448.Dq Li struct xmmregs 449(defined in 450.Aq Pa machine/reg.h ) 451pointed to by 452.Fa addr . 453.It Dv PT_SETXMMREGS 454This request is the converse of 455.Dv PT_GETXMMREGS ; 456it loads the traced process' XMM registers from the 457.Dq Li struct xmmregs 458(defined in 459.Aq Pa machine/reg.h ) 460pointed to by 461.Fa addr . 462.El 463.Pp 464Finally, the following request is available on sparc and sparc64: 465.Bl -tag -width 12n 466.It Dv PT_WCOOKIE 467This request reads the traced process' 468.Sq window cookie 469into the 470.Li int 471pointed to by 472.Fa addr . 473The window cookie needs to be 474.Sq XOR'ed 475to stack-saved program counters. 476.El 477.Sh ERRORS 478Some requests can cause 479.Fn ptrace 480to return 481.Li -1 482as a non-error value; to disambiguate, 483.Va errno 484is set to zero and this should be checked. 485The possible errors are: 486.Bl -tag -width 4n 487.It Bq Er ESRCH 488No process having the specified process ID exists. 489.It Bq Er EINVAL 490.Bl -bullet -compact 491.It 492A process attempted to use 493.Dv PT_ATTACH 494on itself. 495.It 496The 497.Fa request 498was not one of the legal requests. 499.\" .It 500.\" The 501.\" .Fa addr 502.\" to 503.\" .Dv PT_READ_U 504.\" or 505.\" .Dv PT_WRITE_U 506.\" was not 507.\" .Li int Ns \&-aligned. 508.It 509The signal number (in 510.Fa data ) 511to 512.Dv PT_CONTINUE 513.\" or 514.\" .Dv PT_SYSCALL 515was neither 0 nor a legal signal number. 516.It 517.Dv PT_GETREGS , 518.Dv PT_SETREGS , 519.Dv PT_GETFPREGS , 520or 521.Dv PT_SETFPREGS 522was attempted on a process with no valid register set. 523(This is normally true only of system processes.) 524.El 525.It Bq Er EBUSY 526.Bl -bullet -compact 527.It 528.Dv PT_ATTACH 529was attempted on a process that was already being traced. 530.It 531A request attempted to manipulate a process that was being traced by 532some process other than the one making the request. 533.It 534A request (other than 535.Dv PT_ATTACH ) 536specified a process that wasn't stopped. 537.El 538.It Bq Er EPERM 539.Bl -bullet -compact 540.It 541A request (other than 542.Dv PT_ATTACH ) 543attempted to manipulate a process that wasn't being traced at all. 544.It 545An attempt was made to use 546.Dv PT_ATTACH 547on a process in violation of the requirements listed under 548.Dv PT_ATTACH 549above. 550.It 551An attempt was made to use 552.Dv PT_ATTACH 553on a system process. 554.El 555.El 556.Sh BUGS 557On the SPARC, the PC is set to the provided PC value for 558.Dv PT_CONTINUE 559and similar calls, but the NPC is set willy-nilly to 4 greater than the 560PC value. 561Using 562.Dv PT_GETREGS 563and 564.Dv PT_SETREGS 565to modify the PC, passing 566.Li (caddr_t)1 567to 568.Eo \& 569.Fn ptrace 570.Ec , 571should be able to sidestep this. 572.Pp 573Single-stepping is not available. 574.\" .Pp 575.\" When using 576.\" .Dv PT_SYSCALL , 577.\" there is no easy way to tell whether the traced process stopped because 578.\" it made a syscall or because a signal was sent at a moment that it just 579.\" happened to have valid-looking garbage in its 580.\" .Dq Li struct mdproc . 581