1.\" $NetBSD: ptrace.2,v 1.37 2015/07/02 03:50:21 christos Exp $ 2.\" 3.\" This file is in the public domain. 4.Dd July 1, 2015 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" "void *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 void * 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 (void *)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. 153If a negative value is supplied, that is the negative of the LWP 154ID of the thread to be resumed, and only that thread executes. 155.It Dv PT_KILL 156The traced process terminates, as if 157.Dv PT_CONTINUE 158had been used with 159.Dv SIGKILL 160given as the signal to be delivered. 161.It Dv PT_ATTACH 162This request allows a process to gain control of an otherwise unrelated 163process and begin tracing it. 164It does not need any cooperation from the to-be-traced process. 165In this case, 166.Fa pid 167specifies the process ID of the to-be-traced process, and the other two 168arguments are ignored. 169This request requires that the target process 170must have the same real UID as the tracing process, and that it must 171not be executing a setuid or setgid executable. 172(If the tracing process is running as root, 173these 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.Pp 177Three other restrictions apply to all tracing processes, even those 178running as root. 179First, no process may trace a system process. 180Second, no process may trace the process running 181.Xr init 8 . 182Third, if a process has its root directory set with 183.Xr chroot 2 , 184it may not trace another process unless that process's root directory 185is at or below the tracing process's root. 186.It Dv PT_DETACH 187This request is like PT_CONTINUE, except that after it 188succeeds, the traced process is no longer traced and continues 189execution normally. 190.It Dv PT_IO 191This request is a more general interface that can be used instead of 192.Dv PT_READ_D , 193.Dv PT_WRITE_D , 194.Dv PT_READ_I , 195and 196.Dv PT_WRITE_I . 197The I/O request is encoded in a 198.Dq Li "struct ptrace_io_desc" 199defined as: 200.Bd -literal -offset indent 201struct ptrace_io_desc { 202 int piod_op; 203 void *piod_offs; 204 void *piod_addr; 205 size_t piod_len; 206}; 207.Ed 208.Pp 209where 210.Fa piod_offs 211is the offset within the traced process where the I/O operation should 212take place, 213.Fa piod_addr 214is the buffer in the tracing process, and 215.Fa piod_len 216is the length of the I/O request. 217The 218.Fa piod_op 219field specifies which type of I/O operation to perform. 220Possible values are: 221.Pp 222.Bl -tag -width 18n -offset indent -compact 223.It Dv PIOD_READ_D 224.It Dv PIOD_WRITE_D 225.It Dv PIOD_READ_I 226.It Dv PIOD_WRITE_I 227.It Dv PIOD_READ_AUXV 228.El 229.Pp 230See the description of 231.Dv PT_READ_I 232for the difference between I and D spaces. 233The 234.Dv PIOD_READ_AUXV 235operation can be used to read from the ELF auxiliary vector. 236A pointer to the I/O descriptor is passed in the 237.Fa addr 238argument to 239.Fn ptrace . 240On return, the 241.Fa piod_len 242field in the I/O descriptor will be updated with the actual number of 243bytes transferred. 244If the requested I/O could not be successfully performed, 245.Fn ptrace 246will return 247.Li \-1 248and set 249.Va errno . 250.It Dv PT_DUMPCORE 251Makes the process specified in the 252.Fa pid 253pid generate a core dump. 254The 255.Fa addr 256argument should contain the name of the core file to be generated 257and the 258.Fa data 259argument should contain the length of the core filename. 260This 261.Nm 262call currently does not stop the child process so it can generate 263inconsistent data. 264.It Dv PT_LWPINFO 265Returns information about a thread from the list of threads for the 266process specified in the 267.Fa pid 268argument. 269The 270.Fa addr 271argument should contain a 272.Dq Li "struct ptrace_lwpinfo" 273defined as: 274.Bd -literal -offset indent 275struct ptrace_lwpinfo { 276 lwpid_t pl_lwpid; 277 int pl_event; 278}; 279.Ed 280.Pp 281where 282.Fa pl_lwpid 283contains a thread LWP ID. 284Information is returned for the thread following the one with the 285specified ID in the process thread list, or for the first thread 286if 287.Fa pl_lwpid 288is 0. 289Upon return 290.Fa pl_lwpid 291contains the LWP ID of the thread that was found, or 0 if there is 292no thread after the one whose LWP ID was supplied in the call. 293.Fa pl_event 294contains the event that stopped the thread. 295Possible values are: 296.Pp 297.Bl -tag -width 30n -offset indent -compact 298.It Dv PL_EVENT_NONE 299.It Dv PL_EVENT_SIGNAL 300.El 301.Pp 302The 303.Fa data 304argument should contain 305.Dq Li "sizeof(struct ptrace_lwpinfo)" . 306.It Dv PT_SYSCALL 307Stops a process before and after executing each system call. 308.It Dv PT_SYSCALLEMU 309Intercept and ignore a system call before it has been executed, for use with 310.Dv PT_SYSCALL . 311.El 312.Pp 313Additionally, the following requests exist but are 314not available on all machine architectures. 315The file 316.In machine/ptrace.h 317lists which requests exist on a given machine. 318.Bl -tag -width 12n 319.It Dv PT_STEP 320Execution continues as in request PT_CONTINUE; however 321as soon as possible after execution of at least one 322instruction, execution stops again. 323If the 324.Fa data 325argument is greater than 0, it contains the LWP ID of the thread to be 326stepped, and any other threads are continued. 327If the 328.Fa data 329argument is less than zero, it contains the negative of the LWP ID of 330the thread to be stepped, and only that thread executes. 331.It Dv PT_GETREGS 332This request reads the traced process' machine registers into the 333.Dq Li "struct reg" 334(defined in 335.In machine/reg.h ) 336pointed to by 337.Fa addr . 338The 339.Fa data 340argument contains the LWP ID of the thread whose registers are to 341be read. 342If zero is supplied, the first thread of the process is read. 343.It Dv PT_SETREGS 344This request is the converse of 345.Dv PT_GETREGS ; 346it loads the traced process' machine registers from the 347.Dq Li "struct reg" 348(defined in 349.In machine/reg.h ) 350pointed to by 351.Fa addr . 352The 353.Fa data 354argument contains the LWP ID of the thread whose registers are to 355be written. 356If zero is supplied, the first thread of the process is written. 357.It Dv PT_GETFPREGS 358This request reads the traced process' floating-point registers into 359the 360.Dq Li "struct fpreg" 361(defined in 362.In machine/reg.h ) 363pointed to by 364.Fa addr . 365The 366.Fa data 367argument contains the LWP ID of the thread whose registers are to 368be read. 369If zero is supplied, the first thread of the process is read. 370.It Dv PT_SETFPREGS 371This request is the converse of 372.Dv PT_GETFPREGS ; 373it loads the traced process' floating-point registers from the 374.Dq Li "struct fpreg" 375(defined in 376.In machine/reg.h ) 377pointed to by 378.Fa addr . 379The 380.Fa data 381argument contains the LWP ID of the thread whose registers are to 382be written. 383If zero is supplied, the first thread of the process is written. 384.\" .It Dv PT_SYSCALL 385.\" This request is like 386.\" .Dv PT_CONTINUE 387.\" except that the process will stop next time it executes any system 388.\" call. 389.\" Information about the system call can be examined with 390.\" .Dv PT_READ_U 391.\" and potentially modified with 392.\" .Dv PT_WRITE_U 393.\" through the 394.\" .Li u_kproc.kp_proc.p_md 395.\" element of the user structure (see below). 396.\" If the process is continued 397.\" with another 398.\" .Dv PT_SYSCALL 399.\" request, it will stop again on exit from the syscall, at which point 400.\" the return values can be examined and potentially changed. 401.\" The 402.\" .Li u_kproc.kp_proc.p_md 403.\" element is of type 404.\" .Dq Li "struct mdproc" , 405.\" which should be declared by including 406.\" .In sys/param.h , 407.\" .In sys/user.h , 408.\" and 409.\" .In machine/proc.h , 410.\" and contains the following fields (among others): 411.\" .Bl -item -compact -offset indent 412.\" .It 413.\" .Li syscall_num 414.\" .It 415.\" .Li syscall_nargs 416.\" .It 417.\" .Li syscall_args[8] 418.\" .It 419.\" .Li syscall_err 420.\" .It 421.\" .Li syscall_rv[2] 422.\" .El 423.\" When a process stops on entry to a syscall, 424.\" .Li syscall_num 425.\" holds the number of the syscall, 426.\" .Li syscall_nargs 427.\" holds the number of arguments it expects, and 428.\" .Li syscall_args 429.\" holds the arguments themselves. 430.\" (Only the first 431.\" .Li syscall_nargs 432.\" elements of 433.\" .Li syscall_args 434.\" are guaranteed to be useful.) 435.\" When a process stops on exit from a syscall, 436.\" .Li syscall_num 437.\" is 438.\" .Eo \& 439.\" .Li \-1 440.\" .Ec , 441.\" .Li syscall_err 442.\" holds the error number 443.\" .Po 444.\" see 445.\" .Xr errno 2 446.\" .Pc , 447.\" or 0 if no error occurred, and 448.\" .Li syscall_rv 449.\" holds the return values. 450.\" (If the syscall returns only one value, only 451.\" .Li syscall_rv[0] 452.\" is useful.) 453.\" The tracing process can modify any of these with 454.\" .Dv PT_WRITE_U ; 455.\" only some modifications are useful. 456.\" .Pp 457.\" On entry to a syscall, 458.\" .Li syscall_num 459.\" can be changed, and the syscall actually performed will correspond to 460.\" the new number (it is the responsibility of the tracing process to fill 461.\" in 462.\" .Li syscall_args 463.\" appropriately for the new call, but there is no need to modify 464.\" .Eo \& 465.\" .Li syscall_nargs 466.\" .Ec ). 467.\" If the new syscall number is 0, no syscall is actually performed; 468.\" instead, 469.\" .Li syscall_err 470.\" and 471.\" .Li syscall_rv 472.\" are passed back to the traced process directly (and therefore should be 473.\" filled in). 474.\" If the syscall number is otherwise out of range, a dummy 475.\" syscall which simply produces an 476.\" .Er ENOSYS 477.\" error is effectively performed. 478.\" .Pp 479.\" On exit from a syscall, only 480.\" .Li syscall_err 481.\" and 482.\" .Li syscall_rv 483.\" can usefully be changed; they are set to the values returned by the 484.\" syscall and will be passed back to the traced process by the normal 485.\" syscall return mechanism. 486.It Dv PT_DUMPCORE 487Cause the traced process to dump core. 488If the 489.Fa addr 490argument is not 491.Dv NULL 492it is taken to be the pathname of the core file to be generated and the 493.Fa data 494argument should contain the length of the pathname. 495The pathname may contain 496.Dv % 497patterns that are expanded as described in 498.Xr sysctl 8 . 499If the 500.Fa data 501argument is 502.Dv NULL , 503the default core file path generation rules are followed. 504.El 505.Sh ERRORS 506Some requests can cause 507.Fn ptrace 508to return 509.Li \-1 510as a non-error value; to disambiguate, 511.Va errno 512can be set to 0 before the call and checked afterwards. 513The possible errors are: 514.Bl -tag -width "[EINVAL]" 515.It Bq Er EAGAIN 516Process is currently exec'ing and cannot be traced. 517.It Bq Er EBUSY 518.Bl -bullet -compact 519.It 520.Dv PT_ATTACH 521was attempted on a process that was already being traced. 522.It 523A request attempted to manipulate a process that was being traced by 524some process other than the one making the request. 525.It 526A request (other than 527.Dv PT_ATTACH ) 528specified a process that wasn't stopped. 529.El 530.It Bq Er EINVAL 531.Bl -bullet -compact 532.It 533A process attempted to use 534.Dv PT_ATTACH 535on itself. 536.It 537The 538.Fa request 539was not a legal request on this machine architecture. 540.\" .It 541.\" The 542.\" .Fa addr 543.\" to 544.\" .Dv PT_READ_U 545.\" or 546.\" .Dv PT_WRITE_U 547.\" was not 548.\" .Li int Ns \&-aligned. 549.It 550The signal number (in 551.Fa data ) 552to 553.Dv PT_CONTINUE 554.\" or 555.\" .Dv PT_SYSCALL 556was neither 0 nor a legal signal number. 557.It 558.Dv PT_GETREGS , 559.Dv PT_SETREGS , 560.Dv PT_GETFPREGS , 561or 562.Dv PT_SETFPREGS 563was attempted on a process with no valid register set. 564(This is normally true only of system processes.) 565.El 566.It Bq Er EPERM 567.Bl -bullet -compact 568.It 569A request (other than 570.Dv PT_ATTACH ) 571attempted to manipulate a process that wasn't being traced at all. 572.It 573An attempt was made to use 574.Dv PT_ATTACH 575on a process in violation of the requirements listed under 576.Dv PT_ATTACH 577above. 578.El 579.It Bq Er ESRCH 580No process having the specified process ID exists. 581.El 582.Sh SEE ALSO 583.Xr sigaction 2 , 584.Xr signal 7 585.Sh BUGS 586On the SPARC, the PC is set to the provided PC value for 587.Dv PT_CONTINUE 588and similar calls, 589but the NPC is set willy-nilly to 4 greater than the PC value. 590Using 591.Dv PT_GETREGS 592and 593.Dv PT_SETREGS 594to modify the PC, passing 595.Li (void *)1 596to 597.Eo \& 598.Fn ptrace 599.Ec , 600should be able to sidestep this. 601.\" .Pp 602.\" When using 603.\" .Dv PT_SYSCALL , 604.\" there is no easy way to tell whether the traced process stopped because 605.\" it made a syscall or because a signal was sent at a moment that it just 606.\" happened to have valid-looking garbage in its 607.\" .Dq Li "struct mdproc" . 608