1.\" $NetBSD: ptrace.2,v 1.69 2018/05/01 16:37:23 kamil Exp $ 2.\" 3.\" This file is in the public domain. 4.Dd May 1, 2018 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 37.Po 38see 39.Xr siginfo 2 40.Pc , 41examine the state of the stopped process, and cause it to 42terminate or continue as appropriate. 43.Fn ptrace 44is the mechanism by which all this happens. 45.Pp 46When a process that is traced by a debugger requests and calls 47.Xr execve 2 48or any of the routines built on it 49.Po 50such as 51.Xr execv 3 52.Pc , 53it will stop before executing the first instruction of the new image and emit 54.Dv SIGTRAP 55with 56.Dv si_code 57set to 58.Dv TRAP_EXEC . 59If a program is traced with the 60.Dv PT_SYSCALL 61option enabled, 62this event notifier is disabled. 63If a traced program calls 64.Xr execve 2 65any setuid or setgid bits on the executable being executed will be ignored. 66.Pp 67Program (software) breakpoints are reported with 68.Dv SIGTRAP 69and the 70.Dv si_code 71value set to 72.Dv TRAP_BKPT . 73These breakpoints are machine specific instructions that interrupt the process. 74In order to put a trap by a tracer into the tracee's program, 75debugger must violate the 76.Dv PaX MPROTECT 77restrictions. 78For details check the 79.Dv security.pax.mprotect.ptrace 80option described in 81.Xr sysctl 7 . 82When a tracee is interrupted by a trap, 83the trap is not removed by the kernel and it must be handled by a debugger. 84.Pp 85If a program is traced with single steps 86.Dv ( PT_STEP ) 87it reports each step with 88.Dv SIGTRAP 89with 90.Dv si_code 91set to 92.Dv TRAP_TRACE . 93This event is not maskable 94.Dv PT_SET_EVENT_MASK . 95.Pp 96Child program traps are reported with 97.Dv SIGTRAP 98and the 99.Dv si_code 100value set to 101.Dv TRAP_CHLD . 102These events are by default disabled and can be configured with 103.Dv PT_SET_EVENT_MASK . 104If this event occurs, 105check with 106.Dv PT_GET_PROCESS_STATE 107the details of the process state associated with this event. 108.Pp 109Design choices for Debug Register accessors 110.Bl -dash 111.It 112.Fn exec 113.Dv ( TRAP_EXEC 114event) must remove debug registers from LWP 115.It 116debug registers are only per-LWP, not per-process globally 117.It 118debug registers must not be inherited after (v)forking a process 119.It 120debug registers must not be inherited after forking a thread 121.It 122a debugger is responsible to set global watchpoints/breakpoints with the 123debug registers, 124to achieve this 125.Dv PTRACE_LWP_CREATE 126/ 127.Dv PTRACE_LWP_EXIT 128event monitoring function is designed to be used 129.It 130debug register traps must generate 131.Dv SIGTRAP with 132.Dv si_code 133.Dv TRAP_DBREG 134.It 135debugger is responsible to retrieve debug register state to distinguish 136the exact debug register trap 137.It 138kernel must not remove debug register traps after triggering a trap event; 139a debugger is responsible to detach this trap with appropriate 140.Dv PT_SETDBREGS 141call 142.It 143debug registers must not be exposed in mcontext 144.It 145userland must not be allowed to set a trap on the kernel 146.El 147.Pp 148A debugger might reuse port specific symbols, 149to help writing portable code as described in the port specific part of the 150.In sys/ptrace.h 151header. 152Among these symbols, 153there are: 154.Bl -dash 155.It 156.Dv PTRACE_REG_PC 157.It 158.Dv PTRACE_REG_SET_PC 159.It 160.Dv PTRACE_REG_SP 161.It 162.Dv PTRACE_REG_INTRV 163.It 164.Dv PTRACE_BREAKPOINT 165.It 166.Dv PTRACE_BREAKPOINT_SIZE 167.It 168.Dv PTRACE_BREAKPOINT_ADJ 169.El 170.Pp 171The 172.Fa request 173argument 174of 175.Nm 176specifies what operation is being performed; the meaning of 177the rest of the arguments depends on the operation, but except for one 178special case noted below, all 179.Nm 180calls are made by the tracing process, and the 181.Fa pid 182argument specifies the process ID of the traced process. 183.Fa request 184can be: 185.Bl -tag -width 12n 186.It Dv PT_TRACE_ME 187This request is the only one used by the traced process; it declares 188that the process expects to be traced by its parent. 189All the other arguments are ignored. 190If the parent process does not expect to trace 191the child, it will probably be rather confused by the results; once the 192traced process stops, it cannot be made to continue except via 193.Fn ptrace . 194.Pp 195This call does not stop the process neither emit 196.Dv SIGSTOP 197to parent. 198.It Dv PT_READ_I , Dv PT_READ_D 199These requests read a single 200.Li int 201of data from the traced process' address space. 202Traditionally, 203.Fn ptrace 204has allowed for machines with distinct address spaces for instruction 205and data, which is why there are two requests: conceptually, 206.Dv PT_READ_I 207reads from the instruction space and 208.Dv PT_READ_D 209reads from the data space. 210In the current 211.Nx 212implementation, these 213two requests are completely identical. 214The 215.Fa addr 216argument specifies the address (in the traced process' virtual address 217space) at which the read is to be done. 218This address does not have to meet any alignment constraints. 219The value read is returned as the return value from 220.Eo \& 221.Fn ptrace 222.Ec . 223.It Dv PT_WRITE_I , Dv PT_WRITE_D 224These requests parallel 225.Dv PT_READ_I 226and 227.Dv PT_READ_D , 228except that they write rather than read. 229The 230.Fa data 231argument supplies the value to be written. 232.It Dv PT_CONTINUE 233The traced process continues execution. 234.Fa addr 235is an address specifying the place where execution is to be resumed (a 236new value for the program counter), or 237.Li (void *)1 238to indicate that execution is to pick up where it left off. 239.Fa data 240provides a signal number to be delivered to the traced process as it 241resumes execution, or 0 if no signal is to be sent. 242If a negative value is supplied, that is the negative of the LWP 243ID of the thread to be resumed, and only that thread executes. 244.It Dv PT_KILL 245The traced process terminates, as if 246.Dv PT_CONTINUE 247had been used with 248.Dv SIGKILL 249given as the signal to be delivered. 250.It Dv PT_ATTACH 251This request allows a process to gain control of an otherwise unrelated 252process and begin tracing it. 253It does not need any cooperation from the to-be-traced process. 254In this case, 255.Fa pid 256specifies the process ID of the to-be-traced process, and the other two 257arguments are ignored. 258This request requires that the target process 259must have the same real UID as the tracing process, and that it must 260not be executing a setuid or setgid executable. 261(If the tracing process is running as root, 262these restrictions do not apply.) 263.Pp 264The tracing process will see the newly-traced process stop and may then 265control it as if it had been traced all along. 266It means that the 267.Dv SIGSTOP 268signal is emitted to tracer. 269It is different behavior to the one from 270.Dv PT_TRACE_ME . 271.Pp 272Three other restrictions apply to all tracing processes, even those 273running as root. 274First, no process may trace a system process. 275Second, no process may trace the process running 276.Xr init 8 . 277Third, if a process has its root directory set with 278.Xr chroot 2 , 279it may not trace another process unless that process' root directory 280is at or below the tracing process' root. 281.It Dv PT_DETACH 282This request is like PT_CONTINUE, except that after it 283succeeds, the traced process is no longer traced and continues 284execution normally. 285.It Dv PT_IO 286This request is a more general interface that can be used instead of 287.Dv PT_READ_D , 288.Dv PT_WRITE_D , 289.Dv PT_READ_I , 290and 291.Dv PT_WRITE_I . 292The I/O request is encoded in a 293.Dq Li "struct ptrace_io_desc" 294defined as: 295.Bd -literal -offset indent 296struct ptrace_io_desc { 297 int piod_op; 298 void *piod_offs; 299 void *piod_addr; 300 size_t piod_len; 301}; 302.Ed 303.Pp 304where 305.Fa piod_offs 306is the offset within the traced process where the I/O operation should 307take place, 308.Fa piod_addr 309is the buffer in the tracing process, and 310.Fa piod_len 311is the length of the I/O request. 312The 313.Fa piod_op 314field specifies which type of I/O operation to perform. 315Possible values are: 316.Pp 317.Bl -tag -width 18n -offset indent -compact 318.It Dv PIOD_READ_D 319.It Dv PIOD_WRITE_D 320.It Dv PIOD_READ_I 321.It Dv PIOD_WRITE_I 322.It Dv PIOD_READ_AUXV 323.El 324.Pp 325See the description of 326.Dv PT_READ_I 327for the difference between I and D spaces. 328.Pp 329The 330.Dv PIOD_READ_AUXV 331operation can be used to read from the ELF auxiliary vector. 332The 333.Fa piod_offs 334argument sets the offset within the tracee's vector. 335To read from the beginning of it, this value must be set to 0 and cast to 336.Dv (void *) . 337.Pp 338A pointer to the I/O descriptor is passed in the 339.Fa addr 340argument to 341.Fn ptrace . 342On return, the 343.Fa piod_len 344field in the I/O descriptor will be updated with the actual number of 345bytes transferred. 346If the requested I/O could not be successfully performed, 347.Fn ptrace 348will return 349.Li \-1 350and set 351.Va errno . 352.It Dv PT_DUMPCORE 353Makes the process specified in the 354.Fa pid 355pid generate a core dump. 356The 357.Fa addr 358argument should contain the name of the core file to be generated 359and the 360.Fa data 361argument should contain the length of the core filename. 362.It Dv PT_LWPINFO 363Returns information about a thread from the list of threads for the 364process specified in the 365.Fa pid 366argument. 367The 368.Fa addr 369argument should contain a 370.Dq Li "struct ptrace_lwpinfo" 371defined as: 372.Bd -literal -offset indent 373struct ptrace_lwpinfo { 374 lwpid_t pl_lwpid; 375 int pl_event; 376}; 377.Ed 378.Pp 379where 380.Fa pl_lwpid 381contains a thread LWP ID. 382Information is returned for the thread following the one with the 383specified ID in the process thread list, or for the first thread 384if 385.Fa pl_lwpid 386is 0. 387Upon return 388.Fa pl_lwpid 389contains the LWP ID of the thread that was found, or 0 if there is 390no thread after the one whose LWP ID was supplied in the call. 391.Fa pl_event 392contains the event that stopped the thread. 393Possible values are: 394.Pp 395.Bl -tag -width 30n -offset indent -compact 396.It Dv PL_EVENT_NONE 397.It Dv PL_EVENT_SIGNAL 398.It Dv PL_EVENT_SUSPENDED 399.El 400.Pp 401The 402.Fa data 403argument should contain 404.Dq Li "sizeof(struct ptrace_lwpinfo)" . 405.It Dv PT_SYSCALL 406Stops a process before and after executing each system call. 407Otherwise this operation is the same as 408.Dv PT_CONTINUE . 409.It Dv PT_SYSCALLEMU 410Intercept and ignore a system call before it has been executed, for use with 411.Dv PT_SYSCALL . 412This operation shall be called for syscall entry trap from 413.Dv PT_SYSCALL . 414To resume execution after intercepting the system call, 415another 416.Dv PT_SYSCALL 417shall be used. 418.It Dv PT_SET_EVENT_MASK 419This request can be used to specify which events in the traced process 420should be reported to the tracing process. 421These events are specified in a 422.Dq Li "struct ptrace_event" 423defined as: 424.Bd -literal -offset indent 425typedef struct ptrace_event { 426 int pe_set_event; 427} ptrace_event_t; 428.Ed 429.Pp 430.Fa pe_set_event 431is the set of events to be reported. 432This set is formed by OR'ing together the following values: 433.Bl -tag -width 18n 434.It PTRACE_FORK 435Report 436.Xr fork 2 . 437.It PTRACE_VFORK 438Report 439.Xr vfork 2 . 440.It PTRACE_VFORK_DONE 441Report parent resumed after 442.Xr vfork 2 . 443.It PTRACE_LWP_CREATE 444Report thread birth. 445.It PTRACE_LWP_EXIT 446Report thread termination. 447.El 448.Pp 449The 450.Xr fork 2 451and 452.Xr vfork 2 453events can occur with similar operations, 454like 455.Xr clone 2 456or 457.Xr posix_spawn 3 . 458The 459.Dv PTRACE_FORK 460value means that process gives birth to its child 461without pending on its termination or 462.Xr execve 2 463operation. 464If enabled, 465the child is also traced by the debugger and 466.Dv SIGRAP 467is generated twice, 468first for the parent and second for the child. 469The 470.Dv PTRACE_VFORK 471event is the same as 472.Dv PTRACE_FORK , 473but the parent blocks after giving birth to the child. 474The 475.Dv PTRACE_VFORK_DONE 476event can be used to report unblocking of the parent. 477.Pp 478A pointer to this structure is passed in 479.Fa addr . 480The 481.Fa data 482argument should be set to 483.Li sizeof(struct ptrace_event) . 484.It Dv PT_GET_EVENT_MASK 485This request can be used to determine which events in the traced 486process will be reported. 487The information is read into the 488.Dq Li struct ptrace_event 489pointed to by 490.Fa addr . 491The 492.Fa data 493argument should be set to 494.Li sizeof(struct ptrace_event) . 495.It Dv PT_GET_PROCESS_STATE 496This request reads the state information associated with the event 497that stopped the traced process. 498The information is reported in a 499.Dq Li "struct ptrace_state" 500defined as: 501.Bd -literal -offset indent 502typedef struct ptrace_state { 503 int pe_report_event; 504 pid_t pe_other_pid; 505} ptrace_state_t; 506.Ed 507.Pp 508A pointer to this structure is passed in 509.Fa addr . 510The 511.Fa data 512argument should be set to 513.Li sizeof(struct ptrace_state) . 514.It Dv PT_SET_SIGINFO 515This request can be used to specify signal information emitted to tracee. 516This signal information is specified in 517.Dq Li "struct ptrace_siginfo" 518defined as: 519.Bd -literal -offset indentq 520typedef struct ptrace_siginfo { 521 siginfo_t psi_siginfo; 522 lwpid_t psi_lwpid; 523} ptrace_siginfo_t; 524.Ed 525.Pp 526Where 527.Fa psi_siginfo 528is the set to signal information structure. 529The 530.Fa psi_lwpid 531field describes LWP address of the signal. 532Value 533.Dv 0 534means the whole process 535(route signal to all LWPs). 536.Pp 537A pointer to this structure is passed in 538.Fa addr . 539The 540.Fa data 541argument should be set to 542.Li sizeof(struct ptrace_siginfo) . 543.Pp 544In order to pass faked signal to the tracee, 545the signal type must match the signal passed to the process with 546.Dv PT_CONTINUE 547or 548.Dv PT_SYSCALL . 549.It Dv PT_GET_SIGINFO 550This request can be used to determine signal information that was received by 551a debugger 552.Po 553see 554.Xr siginfo 2 555.Pc . 556The information is read into the 557.Dq Li struct ptrace_siginfo 558pointed to by 559.Fa addr . 560The 561.Fa data 562argument should be set to 563.Li sizeof(struct ptrace_siginfo) . 564.It Dv PT_RESUME 565Allow execution of a specified thread, 566change its state from suspended to continued. 567The 568.Fa addr 569argument is unused. 570The 571.Fa data 572argument specifies the LWP ID. 573.Pp 574This call is equivalent to 575.Xr _lwp_continue 2 576called by a traced process. 577This call does not change the general process state from stopped to continued. 578.It Dv PT_SUSPEND 579Prevent execution of a specified thread, 580change its state from continued to suspended. 581The 582.Fa addr 583argument is unused. 584The 585.Fa data 586argument specifies the requested LWP ID. 587.Pp 588This call is equivalent to 589.Xr _lwp_suspend 2 590called by a traced process. 591This call does not change the general process state from continued to stopped. 592.El 593.Pp 594Additionally, the following requests exist but are 595not available on all machine architectures. 596The file 597.In machine/ptrace.h 598lists which requests exist on a given machine. 599.Bl -tag -width 12n 600.It Dv PT_STEP 601Execution continues as in request PT_CONTINUE; however 602as soon as possible after execution of at least one 603instruction, execution stops again. 604If the 605.Fa data 606argument is greater than 0, it contains the LWP ID of the thread to be 607stepped, and any other threads are continued. 608If the 609.Fa data 610argument is less than zero, it contains the negative of the LWP ID of 611the thread to be stepped, and only that thread executes. 612.It Dv PT_SETSTEP 613This request will turn on single stepping of the specified process. 614.It Dv PT_CLEARSTEP 615This request will turn off single stepping of the specified process. 616.It Dv PT_GETREGS 617This request reads the traced process' machine registers into the 618.Dq Li "struct reg" 619(defined in 620.In machine/reg.h ) 621pointed to by 622.Fa addr . 623The 624.Fa data 625argument contains the LWP ID of the thread whose registers are to 626be read. 627If zero is supplied, the first thread of the process is read. 628.It Dv PT_SETREGS 629This request is the converse of 630.Dv PT_GETREGS ; 631it loads the traced process' machine registers from the 632.Dq Li "struct reg" 633(defined in 634.In machine/reg.h ) 635pointed to by 636.Fa addr . 637The 638.Fa data 639argument contains the LWP ID of the thread whose registers are to 640be written. 641If zero is supplied, the first thread of the process is written. 642.It Dv PT_GETFPREGS 643This request reads the traced process' floating-point registers into 644the 645.Dq Li "struct fpreg" 646(defined in 647.In machine/reg.h ) 648pointed to by 649.Fa addr . 650The 651.Fa data 652argument contains the LWP ID of the thread whose registers are to 653be read. 654If zero is supplied, the first thread of the process is read. 655.It Dv PT_SETFPREGS 656This request is the converse of 657.Dv PT_GETFPREGS ; 658it loads the traced process' floating-point registers from the 659.Dq Li "struct fpreg" 660(defined in 661.In machine/reg.h ) 662pointed to by 663.Fa addr . 664The 665.Fa data 666argument contains the LWP ID of the thread whose registers are to 667be written. 668If zero is supplied, the first thread of the process is written. 669.It Dv PT_GETDBREGS 670This request reads the traced process' debug registers into 671the 672.Dq Li "struct dbreg" 673(defined in 674.In machine/reg.h ) 675pointed to by 676.Fa addr . 677The 678.Fa data 679argument contains the LWP ID of the thread whose registers are to 680be read. 681If zero is supplied, the first thread of the process is read. 682.It Dv PT_SETDBREGS 683This request is the converse of 684.Dv PT_GETDBREGS ; 685it loads the traced process' debug registers from the 686.Dq Li "struct dbreg" 687(defined in 688.In machine/reg.h ) 689pointed to by 690.Fa addr . 691The 692.Fa data 693argument contains the LWP ID of the thread whose registers are to 694be written. 695If zero is supplied, the first thread of the process is written. 696.It Dv PT_GETXMMREGS 697This request reads the traced process' XMM registers into 698the 699.Dq Li "struct xmmregs" 700(defined in 701.In machine/reg.h ) 702pointed to by 703.Fa addr . 704The 705.Fa data 706argument contains the LWP ID of the thread whose registers are to 707be read. 708If zero is supplied, the first thread of the process is read. 709.It Dv PT_SETXMMREGS 710This request is the converse of 711.Dv PT_GETXMMREGS ; 712it loads the traced process' XMM registers from the 713.Dq Li "struct xmmregs" 714(defined in 715.In machine/reg.h ) 716pointed to by 717.Fa addr . 718The 719.Fa data 720argument contains the LWP ID of the thread whose registers are to 721be written. 722If zero is supplied, the first thread of the process is written. 723.It Dv PT_GETVECREGS 724This request reads the traced process' vector registers into 725the 726.Dq Li "struct vreg" 727(defined in 728.In machine/reg.h ) 729pointed to by 730.Fa addr . 731The 732.Fa data 733argument contains the LWP ID of the thread whose registers are to 734be read. 735If zero is supplied, the first thread of the process is read. 736.It Dv PT_SETVECREGS 737This request is the converse of 738.Dv PT_GETVECREGS ; 739it loads the traced process' vector registers from the 740.Dq Li "struct vreg" 741(defined in 742.In machine/reg.h ) 743pointed to by 744.Fa addr . 745The 746.Fa data 747argument contains the LWP ID of the thread whose registers are to 748be written. 749If zero is supplied, the first thread of the process is written. 750.El 751.Sh ERRORS 752Some requests can cause 753.Fn ptrace 754to return 755.Li \-1 756as a non-error value; to disambiguate, 757.Va errno 758can be set to 0 before the call and checked afterwards. 759The possible errors are: 760.Bl -tag -width "[EINVAL]" 761.It Bq Er EAGAIN 762Process is currently exec'ing and cannot be traced. 763.It Bq Er EBUSY 764.Bl -bullet -compact 765.It 766.Dv PT_ATTACH 767was attempted on a process that was already being traced. 768.It 769A request attempted to manipulate a process that was being traced by 770some process other than the one making the request. 771.It 772A request (other than 773.Dv PT_ATTACH ) 774specified a process that wasn't stopped. 775.El 776.It Bq Er EDEADLK 777An attempt to unstop a process with locked threads. 778.It Bq Er EINVAL 779.Bl -bullet -compact 780.It 781A process attempted to use 782.Dv PT_ATTACH 783on itself. 784.It 785The 786.Fa request 787was not a legal request on this machine architecture. 788.It 789The signal number (in 790.Fa data ) 791to 792.Dv PT_CONTINUE 793was neither 0 nor a legal signal number. 794.It 795.Dv PT_GETREGS , 796.Dv PT_SETREGS , 797.Dv PT_GETFPREGS , 798or 799.Dv PT_SETFPREGS 800was attempted on a process with no valid register set. 801(This is normally true only of system processes.) 802.El 803.It Bq Er EPERM 804.Bl -bullet -compact 805.It 806A request (other than 807.Dv PT_ATTACH ) 808attempted to manipulate a process that wasn't being traced at all. 809.It 810An attempt was made to use 811.Dv PT_ATTACH 812on a process in violation of the requirements listed under 813.Dv PT_ATTACH 814above. 815.El 816.It Bq Er ESRCH 817No process having the specified process ID exists. 818.El 819.Sh SEE ALSO 820.Xr sigaction 2 , 821.Xr signal 7 822.Sh HISTORY 823The 824.Fn ptrace 825function appeared in 826.At v7 . 827.Sh BUGS 828On the SPARC, the PC is set to the provided PC value for 829.Dv PT_CONTINUE 830and similar calls, 831but the NPC is set willy-nilly to 4 greater than the PC value. 832Using 833.Dv PT_GETREGS 834and 835.Dv PT_SETREGS 836to modify the PC, passing 837.Li (void *)1 838to 839.Eo \& 840.Fn ptrace 841.Ec , 842should be able to sidestep this. 843.Pp 844.Dv PT_SET_SIGINFO , 845.Dv PT_RESUME 846and 847.Dv PT_SUSPEND 848can change the image of process returned by 849.Dv PT_LWPINFO . 850