1.\" $OpenBSD: ptrace.2,v 1.32 2015/08/02 21:54:21 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 $Mdocdate: August 2 2015 $ 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.Fn ptrace . ) 64When a process has used this request and calls 65.Xr execve 2 66or any of the routines built on it 67.Po 68such as 69.Xr execv 3 70.Pc , 71it will stop before executing the first instruction of the new image. 72Also, any setuid or setgid bits on the executable being executed will 73be ignored. 74.It Dv PT_READ_I , Dv PT_READ_D 75These requests read a single 76.Li int 77of data from the traced process' address space. 78Traditionally, 79.Fn ptrace 80has allowed for machines with distinct address spaces for instruction 81and data, which is why there are two requests: conceptually, 82.Dv PT_READ_I 83reads from the instruction space and 84.Dv PT_READ_D 85reads from the data space. 86In the current 87.Ox 88implementation, these 89two requests are completely identical. 90The 91.Fa addr 92argument specifies the address (in the traced process' virtual address 93space) at which the read is to be done. 94This address does not have to meet any alignment constraints. 95The value read is returned as the return value from 96.Fn ptrace . 97.It Dv PT_WRITE_I , Dv PT_WRITE_D 98These requests parallel 99.Dv PT_READ_I 100and 101.Dv PT_READ_D , 102except that they write rather than read. 103The 104.Fa data 105argument supplies the value to be written. 106.\" .It Dv PT_READ_U 107.\" This request reads an 108.\" .Li int 109.\" from the traced process' user structure. 110.\" The 111.\" .Fa addr 112.\" argument specifies the location of the int relative to the base of the 113.\" user structure; it will usually be an integer value cast to 114.\" .Li caddr_t 115.\" either explicitly or via the presence of a prototype for 116.\" .Fn ptrace . 117.\" Unlike 118.\" .Dv PT_READ_I 119.\" and 120.\" .Dv PT_READ_D , 121.\" .Fa addr 122.\" must be aligned on an 123.\" .Li int 124.\" boundary. 125.\" The value read is returned as the return value from 126.\" .Fn ptrace . 127.\" .It Dv PT_WRITE_U 128.\" This request writes an 129.\" .Li int 130.\" into the traced process' user structure. 131.\" .Fa addr 132.\" specifies the offset, just as for 133.\" .Dv PT_READ_U , 134.\" and 135.\" .Fa data 136.\" specifies the value to be written, just as for 137.\" .Dv PT_WRITE_I 138.\" and 139.\" .Dv PT_WRITE_D . 140.It Dv PT_CONTINUE 141The traced process continues execution. 142.Fa addr 143is an address specifying the place where execution is to be resumed (a 144new value for the program counter), or 145.Li (caddr_t)1 146to indicate that execution is to pick up where it left off. 147.Fa data 148provides a signal number to be delivered to the traced process as it 149resumes execution, or 0 if no signal is to be sent. 150.It Dv PT_KILL 151The traced process terminates, as if 152.Dv PT_CONTINUE 153had been used with 154.Dv SIGKILL 155given as the signal to be delivered. 156.It Dv PT_ATTACH 157This request allows a process to gain control of an otherwise unrelated 158process and begin tracing it. 159It does not need any cooperation from the to-be-traced process. 160In this case, 161.Fa pid 162specifies the process ID of the to-be-traced process, and the other two 163arguments are ignored. 164This request requires that the target process must have the same real UID 165as the tracing process, and that it must not be executing a set-user-ID 166or set-group-ID executable. 167Additionally, if the 168.Dv kern.global_ptrace 169sysctl is 0, then the target process must be a descendant of the tracing 170process. 171(If the tracing process is running as root, these 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.It Dv PT_DETACH 175This request is like 176.Dv PT_CONTINUE , 177except that it does not allow 178specifying an alternate place to continue execution, and after it 179succeeds, the traced process is no longer traced and continues 180execution normally. 181.It Dv PT_IO 182This request is a more general interface that can be used instead of 183.Dv PT_READ_D , 184.Dv PT_WRITE_D , 185.Dv PT_READ_I 186and 187.Dv PT_WRITE_I . 188The I/O request is encoded in a 189.Dq Li "struct ptrace_io_desc" 190defined as: 191.Bd -literal -offset indent 192struct ptrace_io_desc { 193 int piod_op; 194 void *piod_offs; 195 void *piod_addr; 196 size_t piod_len; 197}; 198.Ed 199.Pp 200Where 201.Fa piod_offs 202is the offset within the traced process where the I/O operation should be 203made, 204.Fa piod_addr 205is the buffer in the parent and 206.Fa piod_len 207is the length of the I/O request. 208The 209.Fa piod_op 210member specifies what operation needs to be done. 211Possible values are: 212.Pp 213.Bl -tag -width Ds -offset indent -compact 214.It PIOD_READ_D 215.It PIOD_WRITE_D 216.It PIOD_READ_I 217.It PIOD_WRITE_I 218.It PIOD_READ_AUXV 219.El 220.Pp 221See also the description of 222.Dv PT_READ_I 223for the difference between D and I spaces. 224The 225.Dv PIOD_READ_AUXV 226operation can be used to read from the ELF auxiliary vector. 227A pointer to the descriptor is passed in 228.Fa addr . 229On return the 230.Fa piod_len 231field in the descriptor will be updated with the actual number of bytes 232transferred. 233If the requested I/O couldn't be successfully performed 234.Fn ptrace 235will return 236.Li -1 237and set 238.Va errno . 239.It Dv PT_SET_EVENT_MASK 240This request can be used to specify which events in the traced process 241should be reported to the tracing process. 242These events are specified in a 243.Dq Li "struct ptrace_event" 244defined as: 245.Bd -literal -offset indent 246typedef struct ptrace_event { 247 int pe_set_event; 248} ptrace_event_t; 249.Ed 250.Pp 251Where 252.Fa pe_set_event 253is the set of events to be reported. 254This set is formed by OR'ing together the following values: 255.Bl -tag -width 18n 256.It PTRACE_FORK 257Report 258.Xr fork 2 . 259.El 260.Pp 261A pointer to this structure is passed in 262.Fa addr . 263The 264.Fa data 265argument should be set to 266.Li sizeof(struct ptrace_event) . 267.It Dv PT_GET_EVENT_MASK 268This request can be used to determine which events in the traced 269process will be reported. 270The information is read into the 271.Dq Li struct ptrace_event 272pointed to by 273.Fa addr . 274The 275.Fa data 276argument should be set to 277.Li sizeof(struct ptrace_event) . 278.It Dv PT_GET_PROCESS_STATE 279This request reads the state information associated with the event 280that stopped the traced process. 281The information is reported in a 282.Dq Li "struct ptrace_state" 283defined as: 284.Bd -literal -offset indent 285typedef struct ptrace_state { 286 int pe_report_event; 287 pid_t pe_other_pid; 288} ptrace_state_t; 289.Ed 290.Pp 291Where 292.Fa pe_report_event 293is the event being reported. 294If the event being reported is 295.Dv PTRACE_FORK , 296.Fa pe_other_pid 297will be set to the process ID of the other end of the fork. 298A pointer to this structure is passed in 299.Fa addr . 300The 301.Fa data 302argument should be set to 303.Li sizeof(struct ptrace_state) . 304.El 305.Pp 306Additionally, machine-specific requests can exist. 307Depending on the architecture, the following requests may be available 308under 309.Ox : 310.Bl -tag -width 12n 311.It Dv PT_GETREGS Pq all platforms 312This request reads the traced process' machine registers into the 313.Dq Li struct reg 314(defined in 315.In machine/reg.h ) 316pointed to by 317.Fa addr . 318.It Dv PT_SETREGS Pq all platforms 319This request is the converse of 320.Dv PT_GETREGS ; 321it loads the traced process' machine registers from the 322.Dq Li struct reg 323(defined in 324.In machine/reg.h ) 325pointed to by 326.Fa addr . 327.\" .It Dv PT_SYSCALL 328.\" This request is like 329.\" .Dv PT_CONTINUE 330.\" except that the process will stop next time it executes any system 331.\" call. 332.\" Information about the system call can be examined with 333.\" .Dv PT_READ_U 334.\" and potentially modified with 335.\" .Dv PT_WRITE_U 336.\" through the 337.\" .Li u_kproc.kp_proc.p_md 338.\" element of the user structure (see below). 339.\" If the process is continued with another 340.\" .Dv PT_SYSCALL 341.\" request, it will stop again on exit from the syscall, at which point 342.\" the return values can be examined and potentially changed. 343.\" 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.\" .In sys/param.h , 349.\" .In sys/user.h , 350.\" and 351.\" .In 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. 372.\" (Only the first 373.\" .Li syscall_nargs 374.\" elements of 375.\" .Li syscall_args 376.\" are guaranteed to be useful.) When a process stops on exit from a 377.\" syscall, 378.\" .Li syscall_num 379.\" is 380.\" .Li -1 , 381.\" .Li syscall_err 382.\" holds the error number 383.\" .Po 384.\" see 385.\" .Xr errno 2 386.\" .Pc , 387.\" or 0 if no error occurred, and 388.\" .Li syscall_rv 389.\" holds the return values. 390.\" (If the syscall returns only one value, only 391.\" .Li syscall_rv[0] 392.\" is useful.) 393.\" The tracing process can modify any of these with 394.\" .Dv PT_WRITE_U ; 395.\" only some modifications are useful. 396.\" .Pp 397.\" On entry to a syscall, 398.\" .Li syscall_num 399.\" can be changed, and the syscall actually performed will correspond to 400.\" the new number (it is the responsibility of the tracing process to fill 401.\" in 402.\" .Li syscall_args 403.\" appropriately for the new call, but there is no need to modify 404.\" .Li syscall_nargs ) . 405.\" If the new syscall number is 0, no syscall is actually performed; 406.\" instead, 407.\" .Li syscall_err 408.\" and 409.\" .Li syscall_rv 410.\" are passed back to the traced process directly (and therefore should be 411.\" filled in). 412.\" 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, 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.In machine/reg.h ) 442pointed to by 443.Fa addr . 444.It Xo Dv PT_SETFPREGS 445.No (not available on aviion, luna88k, 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.In 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.In 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.In 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 HISTORY 562The 563.Fn ptrace 564system call first appeared in 565.At v6 . 566.Sh BUGS 567On several RISC architectures (such as aviion, luna88k, sparc and sparc64), 568the PC is set to the provided PC value for 569.Dv PT_CONTINUE 570and similar calls, and the remainder of the execution pipeline registers 571are set to the following instructions, even if the instruction at PC 572is a branch instruction. 573Using 574.Dv PT_GETREGS 575and 576.Dv PT_SETREGS 577to modify the PC, passing 578.Li (caddr_t)1 579to 580.Fn ptrace , 581should be able to sidestep this. 582.\" .Pp 583.\" When using 584.\" .Dv PT_SYSCALL , 585.\" there is no easy way to tell whether the traced process stopped because 586.\" it made a syscall or because a signal was sent at a moment that it just 587.\" happened to have valid-looking garbage in its 588.\" .Dq Li struct mdproc . 589