1.\" $FreeBSD: stable/12/lib/libc/sys/ptrace.2 360439 2020-04-28 15:44:39Z jhb $ 2.\" $NetBSD: ptrace.2,v 1.2 1995/02/27 12:35:37 cgd Exp $ 3.\" 4.\" This file is in the public domain. 5.Dd July 15, 2019 6.Dt PTRACE 2 7.Os 8.Sh NAME 9.Nm ptrace 10.Nd process tracing and debugging 11.Sh LIBRARY 12.Lb libc 13.Sh SYNOPSIS 14.In sys/types.h 15.In sys/ptrace.h 16.Ft int 17.Fn ptrace "int request" "pid_t pid" "caddr_t addr" "int data" 18.Sh DESCRIPTION 19The 20.Fn ptrace 21system call 22provides tracing and debugging facilities. 23It allows one process 24(the 25.Em tracing 26process) 27to control another 28(the 29.Em traced 30process). 31The tracing process must first attach to the traced process, and then 32issue a series of 33.Fn ptrace 34system calls to control the execution of the process, as well as access 35process memory and register state. 36For the duration of the tracing session, the traced process will be 37.Dq re-parented , 38with its parent process ID (and resulting behavior) 39changed to the tracing process. 40It is permissible for a tracing process to attach to more than one 41other process at a time. 42When the tracing process has completed its work, it must detach the 43traced process; if a tracing process exits without first detaching all 44processes it has attached, those processes will be killed. 45.Pp 46Most of the time, the traced process runs normally, but when it 47receives a signal 48(see 49.Xr sigaction 2 ) , 50it stops. 51The tracing process is expected to notice this via 52.Xr wait 2 53or the delivery of a 54.Dv SIGCHLD 55signal, examine the state of the stopped process, and cause it to 56terminate or continue as appropriate. 57The signal may be a normal process signal, generated as a result of 58traced process behavior, or use of the 59.Xr kill 2 60system call; alternatively, it may be generated by the tracing facility 61as a result of attaching, stepping by the tracing 62process, 63or an event in the traced process. 64The tracing process may choose to intercept the signal, using it to 65observe process behavior (such as 66.Dv SIGTRAP ) , 67or forward the signal to the process if appropriate. 68The 69.Fn ptrace 70system call 71is the mechanism by which all this happens. 72.Pp 73A traced process may report additional signal stops corresponding to 74events in the traced process. 75These additional signal stops are reported as 76.Dv SIGTRAP 77or 78.Dv SIGSTOP 79signals. 80The tracing process can use the 81.Dv PT_LWPINFO 82request to determine which events are associated with a 83.Dv SIGTRAP 84or 85.Dv SIGSTOP 86signal. 87Note that multiple events may be associated with a single signal. 88For example, events indicated by the 89.Dv PL_FLAG_BORN , 90.Dv PL_FLAG_FORKED , 91and 92.Dv PL_FLAG_EXEC 93flags are also reported as a system call exit event 94.Pq Dv PL_FLAG_SCX . 95The signal stop for a new child process enabled via 96.Dv PTRACE_FORK 97will report a 98.Dv SIGSTOP 99signal. 100All other additional signal stops use 101.Dv SIGTRAP . 102.Pp 103Each traced process has a tracing event mask. 104An event in the traced process only reports a 105signal stop if the corresponding flag is set in the tracing event mask. 106The current set of tracing event flags include: 107.Bl -tag -width "Dv PTRACE_SYSCALL" 108.It Dv PTRACE_EXEC 109Report a stop for a successful invocation of 110.Xr execve 2 . 111This event is indicated by the 112.Dv PL_FLAG_EXEC 113flag in the 114.Va pl_flags 115member of 116.Vt "struct ptrace_lwpinfo" . 117.It Dv PTRACE_SCE 118Report a stop on each system call entry. 119This event is indicated by the 120.Dv PL_FLAG_SCE 121flag in the 122.Va pl_flags 123member of 124.Vt "struct ptrace_lwpinfo" . 125.It Dv PTRACE_SCX 126Report a stop on each system call exit. 127This event is indicated by the 128.Dv PL_FLAG_SCX 129flag in the 130.Va pl_flags 131member of 132.Vt "struct ptrace_lwpinfo" . 133.It Dv PTRACE_SYSCALL 134Report stops for both system call entry and exit. 135.It Dv PTRACE_FORK 136This event flag controls tracing for new child processes of a traced process. 137.Pp 138When this event flag is enabled, 139new child processes will enable tracing and stop before executing their 140first instruction. 141The new child process will include the 142.Dv PL_FLAG_CHILD 143flag in the 144.Va pl_flags 145member of 146.Vt "struct ptrace_lwpinfo" . 147The traced process will report a stop that includes the 148.Dv PL_FLAG_FORKED 149flag. 150The process ID of the new child process will also be present in the 151.Va pl_child_pid 152member of 153.Vt "struct ptrace_lwpinfo" . 154If the new child process was created via 155.Xr vfork 2 , 156the traced process's stop will also include the 157.Dv PL_FLAG_VFORKED 158flag. 159Note that new child processes will be attached with the default 160tracing event mask; 161they do not inherit the event mask of the traced process. 162.Pp 163When this event flag is not enabled, 164new child processes will execute without tracing enabled. 165.It Dv PTRACE_LWP 166This event flag controls tracing of LWP 167.Pq kernel thread 168creation and destruction. 169When this event is enabled, 170new LWPs will stop and report an event with 171.Dv PL_FLAG_BORN 172set before executing their first instruction, 173and exiting LWPs will stop and report an event with 174.Dv PL_FLAG_EXITED 175set before completing their termination. 176.Pp 177Note that new processes do not report an event for the creation of their 178initial thread, 179and exiting processes do not report an event for the termination of the 180last thread. 181.It Dv PTRACE_VFORK 182Report a stop event when a parent process resumes after a 183.Xr vfork 2 . 184.Pp 185When a thread in the traced process creates a new child process via 186.Xr vfork 2 , 187the stop that reports 188.Dv PL_FLAG_FORKED 189and 190.Dv PL_FLAG_SCX 191occurs just after the child process is created, 192but before the thread waits for the child process to stop sharing process 193memory. 194If a debugger is not tracing the new child process, 195it must ensure that no breakpoints are enabled in the shared process 196memory before detaching from the new child process. 197This means that no breakpoints are enabled in the parent process either. 198.Pp 199The 200.Dv PTRACE_VFORK 201flag enables a new stop that indicates when the new child process stops 202sharing the process memory of the parent process. 203A debugger can reinsert breakpoints in the parent process and resume it 204in response to this event. 205This event is indicated by setting the 206.Dv PL_FLAG_VFORK_DONE 207flag. 208.El 209.Pp 210The default tracing event mask when attaching to a process via 211.Dv PT_ATTACH , 212.Dv PT_TRACE_ME , 213or 214.Dv PTRACE_FORK 215includes only 216.Dv PTRACE_EXEC 217events. 218All other event flags are disabled. 219.Pp 220The 221.Fa request 222argument specifies what operation is being performed; the meaning of 223the rest of the arguments depends on the operation, but except for one 224special case noted below, all 225.Fn ptrace 226calls are made by the tracing process, and the 227.Fa pid 228argument specifies the process ID of the traced process 229or a corresponding thread ID. 230The 231.Fa request 232argument 233can be: 234.Bl -tag -width "Dv PT_GET_EVENT_MASK" 235.It Dv PT_TRACE_ME 236This request is the only one used by the traced process; it declares 237that the process expects to be traced by its parent. 238All the other arguments are ignored. 239(If the parent process does not expect to trace the child, it will 240probably be rather confused by the results; once the traced process 241stops, it cannot be made to continue except via 242.Fn ptrace . ) 243When a process has used this request and calls 244.Xr execve 2 245or any of the routines built on it 246(such as 247.Xr execv 3 ) , 248it will stop before executing the first instruction of the new image. 249Also, any setuid or setgid bits on the executable being executed will 250be ignored. 251If the child was created by 252.Xr vfork 2 253system call or 254.Xr rfork 2 255call with the 256.Dv RFMEM 257flag specified, the debugging events are reported to the parent 258only after the 259.Xr execve 2 260is executed. 261.It Dv PT_READ_I , Dv PT_READ_D 262These requests read a single 263.Vt int 264of data from the traced process's address space. 265Traditionally, 266.Fn ptrace 267has allowed for machines with distinct address spaces for instruction 268and data, which is why there are two requests: conceptually, 269.Dv PT_READ_I 270reads from the instruction space and 271.Dv PT_READ_D 272reads from the data space. 273In the current 274.Fx 275implementation, these two requests are completely identical. 276The 277.Fa addr 278argument specifies the address 279(in the traced process's virtual address space) 280at which the read is to be done. 281This address does not have to meet any alignment constraints. 282The value read is returned as the return value from 283.Fn ptrace . 284.It Dv PT_WRITE_I , Dv PT_WRITE_D 285These requests parallel 286.Dv PT_READ_I 287and 288.Dv PT_READ_D , 289except that they write rather than read. 290The 291.Fa data 292argument supplies the value to be written. 293.It Dv PT_IO 294This request allows reading and writing arbitrary amounts of data in 295the traced process's address space. 296The 297.Fa addr 298argument specifies a pointer to a 299.Vt "struct ptrace_io_desc" , 300which is defined as follows: 301.Bd -literal 302struct ptrace_io_desc { 303 int piod_op; /* I/O operation */ 304 void *piod_offs; /* child offset */ 305 void *piod_addr; /* parent offset */ 306 size_t piod_len; /* request length */ 307}; 308 309/* 310 * Operations in piod_op. 311 */ 312#define PIOD_READ_D 1 /* Read from D space */ 313#define PIOD_WRITE_D 2 /* Write to D space */ 314#define PIOD_READ_I 3 /* Read from I space */ 315#define PIOD_WRITE_I 4 /* Write to I space */ 316.Ed 317.Pp 318The 319.Fa data 320argument is ignored. 321The actual number of bytes read or written is stored in 322.Va piod_len 323upon return. 324.It Dv PT_CONTINUE 325The traced process continues execution. 326The 327.Fa addr 328argument 329is an address specifying the place where execution is to be resumed 330(a new value for the program counter), 331or 332.Po Vt caddr_t Pc Ns 1 333to indicate that execution is to pick up where it left off. 334The 335.Fa data 336argument 337provides a signal number to be delivered to the traced process as it 338resumes execution, or 0 if no signal is to be sent. 339.It Dv PT_STEP 340The traced process is single stepped one instruction. 341The 342.Fa addr 343argument 344should be passed 345.Po Vt caddr_t Pc Ns 1 . 346The 347.Fa data 348argument 349provides a signal number to be delivered to the traced process as it 350resumes execution, or 0 if no signal is to be sent. 351.It Dv PT_KILL 352The traced process terminates, as if 353.Dv PT_CONTINUE 354had been used with 355.Dv SIGKILL 356given as the signal to be delivered. 357.It Dv PT_ATTACH 358This request allows a process to gain control of an otherwise 359unrelated process and begin tracing it. 360It does not need any cooperation from the to-be-traced process. 361In 362this case, 363.Fa pid 364specifies the process ID of the to-be-traced process, and the other 365two arguments are ignored. 366This request requires that the target process must have the same real 367UID as the tracing process, and that it must not be executing a setuid 368or setgid executable. 369(If the tracing process is running as root, these restrictions do not 370apply.) 371The tracing process will see the newly-traced process stop and may 372then control it as if it had been traced all along. 373.It Dv PT_DETACH 374This request is like PT_CONTINUE, except that it does not allow 375specifying an alternate place to continue execution, and after it 376succeeds, the traced process is no longer traced and continues 377execution normally. 378.It Dv PT_GETREGS 379This request reads the traced process's machine registers into the 380.Do 381.Vt "struct reg" 382.Dc 383(defined in 384.In machine/reg.h ) 385pointed to by 386.Fa addr . 387.It Dv PT_SETREGS 388This request is the converse of 389.Dv PT_GETREGS ; 390it loads the traced process's machine registers from the 391.Do 392.Vt "struct reg" 393.Dc 394(defined in 395.In machine/reg.h ) 396pointed to by 397.Fa addr . 398.It Dv PT_GETFPREGS 399This request reads the traced process's floating-point registers into 400the 401.Do 402.Vt "struct fpreg" 403.Dc 404(defined in 405.In machine/reg.h ) 406pointed to by 407.Fa addr . 408.It Dv PT_SETFPREGS 409This request is the converse of 410.Dv PT_GETFPREGS ; 411it loads the traced process's floating-point registers from the 412.Do 413.Vt "struct fpreg" 414.Dc 415(defined in 416.In machine/reg.h ) 417pointed to by 418.Fa addr . 419.It Dv PT_GETDBREGS 420This request reads the traced process's debug registers into 421the 422.Do 423.Vt "struct dbreg" 424.Dc 425(defined in 426.In machine/reg.h ) 427pointed to by 428.Fa addr . 429.It Dv PT_SETDBREGS 430This request is the converse of 431.Dv PT_GETDBREGS ; 432it loads the traced process's debug registers from the 433.Do 434.Vt "struct dbreg" 435.Dc 436(defined in 437.In machine/reg.h ) 438pointed to by 439.Fa addr . 440.It Dv PT_LWPINFO 441This request can be used to obtain information about the kernel thread, 442also known as light-weight process, that caused the traced process to stop. 443The 444.Fa addr 445argument specifies a pointer to a 446.Vt "struct ptrace_lwpinfo" , 447which is defined as follows: 448.Bd -literal 449struct ptrace_lwpinfo { 450 lwpid_t pl_lwpid; 451 int pl_event; 452 int pl_flags; 453 sigset_t pl_sigmask; 454 sigset_t pl_siglist; 455 siginfo_t pl_siginfo; 456 char pl_tdname[MAXCOMLEN + 1]; 457 pid_t pl_child_pid; 458 u_int pl_syscall_code; 459 u_int pl_syscall_narg; 460}; 461.Ed 462.Pp 463The 464.Fa data 465argument is to be set to the size of the structure known to the caller. 466This allows the structure to grow without affecting older programs. 467.Pp 468The fields in the 469.Vt "struct ptrace_lwpinfo" 470have the following meaning: 471.Bl -tag -width indent -compact 472.It Va pl_lwpid 473LWP id of the thread 474.It Va pl_event 475Event that caused the stop. 476Currently defined events are: 477.Bl -tag -width "Dv PL_EVENT_SIGNAL" -compact 478.It Dv PL_EVENT_NONE 479No reason given 480.It Dv PL_EVENT_SIGNAL 481Thread stopped due to the pending signal 482.El 483.It Va pl_flags 484Flags that specify additional details about observed stop. 485Currently defined flags are: 486.Bl -tag -width indent -compact 487.It Dv PL_FLAG_SCE 488The thread stopped due to system call entry, right after the kernel is entered. 489The debugger may examine syscall arguments that are stored in memory and 490registers according to the ABI of the current process, and modify them, 491if needed. 492.It Dv PL_FLAG_SCX 493The thread is stopped immediately before syscall is returning to the usermode. 494The debugger may examine system call return values in the ABI-defined registers 495and/or memory. 496.It Dv PL_FLAG_EXEC 497When 498.Dv PL_FLAG_SCX 499is set, this flag may be additionally specified to inform that the 500program being executed by debuggee process has been changed by successful 501execution of a system call from the 502.Fn execve 2 503family. 504.It Dv PL_FLAG_SI 505Indicates that 506.Va pl_siginfo 507member of 508.Vt "struct ptrace_lwpinfo" 509contains valid information. 510.It Dv PL_FLAG_FORKED 511Indicates that the process is returning from a call to 512.Fn fork 2 513that created a new child process. 514The process identifier of the new process is available in the 515.Va pl_child_pid 516member of 517.Vt "struct ptrace_lwpinfo" . 518.It Dv PL_FLAG_CHILD 519The flag is set for first event reported from a new child which is 520automatically attached when 521.Dv PTRACE_FORK 522is enabled. 523.It Dv PL_FLAG_BORN 524This flag is set for the first event reported from a new LWP when 525.Dv PTRACE_LWP 526is enabled. 527It is reported along with 528.Dv PL_FLAG_SCX . 529.It Dv PL_FLAG_EXITED 530This flag is set for the last event reported by an exiting LWP when 531.Dv PTRACE_LWP 532is enabled. 533Note that this event is not reported when the last LWP in a process exits. 534The termination of the last thread is reported via a normal process exit 535event. 536.It Dv PL_FLAG_VFORKED 537Indicates that the thread is returning from a call to 538.Xr vfork 2 539that created a new child process. 540This flag is set in addition to 541.Dv PL_FLAG_FORKED . 542.It Dv PL_FLAG_VFORK_DONE 543Indicates that the thread has resumed after a child process created via 544.Xr vfork 2 545has stopped sharing its address space with the traced process. 546.El 547.It Va pl_sigmask 548The current signal mask of the LWP 549.It Va pl_siglist 550The current pending set of signals for the LWP. 551Note that signals that are delivered to the process would not appear 552on an LWP siglist until the thread is selected for delivery. 553.It Va pl_siginfo 554The siginfo that accompanies the signal pending. 555Only valid for 556.Dv PL_EVENT_SIGNAL 557stop when 558.Dv PL_FLAG_SI 559is set in 560.Va pl_flags . 561.It Va pl_tdname 562The name of the thread. 563.It Va pl_child_pid 564The process identifier of the new child process. 565Only valid for a 566.Dv PL_EVENT_SIGNAL 567stop when 568.Dv PL_FLAG_FORKED 569is set in 570.Va pl_flags . 571.It Va pl_syscall_code 572The ABI-specific identifier of the current system call. 573Note that for indirect system calls this field reports the indirected 574system call. 575Only valid when 576.Dv PL_FLAG_SCE 577or 578.Dv PL_FLAG_SCX 579is set in 580.Va pl_flags. 581.It Va pl_syscall_narg 582The number of arguments passed to the current system call not counting 583the system call identifier. 584Note that for indirect system calls this field reports the arguments 585passed to the indirected system call. 586Only valid when 587.Dv PL_FLAG_SCE 588or 589.Dv PL_FLAG_SCX 590is set in 591.Va pl_flags. 592.El 593.It Dv PT_GETNUMLWPS 594This request returns the number of kernel threads associated with the 595traced process. 596.It Dv PT_GETLWPLIST 597This request can be used to get the current thread list. 598A pointer to an array of type 599.Vt lwpid_t 600should be passed in 601.Fa addr , 602with the array size specified by 603.Fa data . 604The return value from 605.Fn ptrace 606is the count of array entries filled in. 607.It Dv PT_SETSTEP 608This request will turn on single stepping of the specified process. 609Stepping is automatically disabled when a single step trap is caught. 610.It Dv PT_CLEARSTEP 611This request will turn off single stepping of the specified process. 612.It Dv PT_SUSPEND 613This request will suspend the specified thread. 614.It Dv PT_RESUME 615This request will resume the specified thread. 616.It Dv PT_TO_SCE 617This request will set the 618.Dv PTRACE_SCE 619event flag to trace all future system call entries and continue the process. 620The 621.Fa addr 622and 623.Fa data 624arguments are used the same as for 625.Dv PT_CONTINUE. 626.It Dv PT_TO_SCX 627This request will set the 628.Dv PTRACE_SCX 629event flag to trace all future system call exits and continue the process. 630The 631.Fa addr 632and 633.Fa data 634arguments are used the same as for 635.Dv PT_CONTINUE. 636.It Dv PT_SYSCALL 637This request will set the 638.Dv PTRACE_SYSCALL 639event flag to trace all future system call entries and exits and continue 640the process. 641The 642.Fa addr 643and 644.Fa data 645arguments are used the same as for 646.Dv PT_CONTINUE. 647.It Dv PT_GET_SC_ARGS 648For the thread which is stopped in either 649.Dv PL_FLAG_SCE 650or 651.Dv PL_FLAG_SCX 652state, that is, on entry or exit to a syscall, 653this request fetches the syscall arguments. 654.Pp 655The arguments are copied out into the buffer pointed to by the 656.Fa addr 657pointer, sequentially. 658Each syscall argument is stored as the machine word. 659Kernel copies out as many arguments as the syscall accepts, 660see the 661.Va pl_syscall_narg 662member of the 663.Vt struct ptrace_lwpinfo , 664but not more than the 665.Fa data 666bytes in total are copied. 667.It Dv PT_GET_SC_RET 668Fetch the system call return values on exit from a syscall. 669This request is only valid for threads stopped in a syscall 670exit (the 671.Dv PL_FLAG_SCX 672state). 673The 674.Fa addr 675argument specifies a pointer to a 676.Vt "struct ptrace_sc_ret" , 677which is defined as follows: 678.Bd -literal 679struct ptrace_sc_ret { 680 register_t sr_retval[2]; 681 int sr_error; 682}; 683.Ed 684.Pp 685The 686.Fa data 687argument is set to the size of the structure. 688.Pp 689If the system call completed successfully, 690.Va sr_error 691is set to zero and the return values of the system call are saved in 692.Va sr_retval . 693If the system call failed to execute, 694.Va sr_error 695field is set to a positive 696.Xr errno 2 697value. 698If the system call completed in an unusual fashion, 699.Va sr_error 700is set to a negative value: 701.Pp 702.Bl -tag -width Dv EJUSTRETURN -compact 703.It Dv ERESTART 704System call will be restarted. 705.It Dv EJUSTRETURN 706System call completed sucessfully but did not set a return value 707.Po for example, 708.Xr setcontext 2 709and 710.Xr sigreturn 2 711.Pc . 712.El 713.It Dv PT_FOLLOW_FORK 714This request controls tracing for new child processes of a traced process. 715If 716.Fa data 717is non-zero, 718.Dv PTRACE_FORK 719is set in the traced process's event tracing mask. 720If 721.Fa data 722is zero, 723.Dv PTRACE_FORK 724is cleared from the traced process's event tracing mask. 725.It Dv PT_LWP_EVENTS 726This request controls tracing of LWP creation and destruction. 727If 728.Fa data 729is non-zero, 730.Dv PTRACE_LWP 731is set in the traced process's event tracing mask. 732If 733.Fa data 734is zero, 735.Dv PTRACE_LWP 736is cleared from the traced process's event tracing mask. 737.It Dv PT_GET_EVENT_MASK 738This request reads the traced process's event tracing mask into the 739integer pointed to by 740.Fa addr . 741The size of the integer must be passed in 742.Fa data . 743.It Dv PT_SET_EVENT_MASK 744This request sets the traced process's event tracing mask from the 745integer pointed to by 746.Fa addr . 747The size of the integer must be passed in 748.Fa data . 749.It Dv PT_VM_TIMESTAMP 750This request returns the generation number or timestamp of the memory map of 751the traced process as the return value from 752.Fn ptrace . 753This provides a low-cost way for the tracing process to determine if the 754VM map changed since the last time this request was made. 755.It Dv PT_VM_ENTRY 756This request is used to iterate over the entries of the VM map of the traced 757process. 758The 759.Fa addr 760argument specifies a pointer to a 761.Vt "struct ptrace_vm_entry" , 762which is defined as follows: 763.Bd -literal 764struct ptrace_vm_entry { 765 int pve_entry; 766 int pve_timestamp; 767 u_long pve_start; 768 u_long pve_end; 769 u_long pve_offset; 770 u_int pve_prot; 771 u_int pve_pathlen; 772 long pve_fileid; 773 uint32_t pve_fsid; 774 char *pve_path; 775}; 776.Ed 777.Pp 778The first entry is returned by setting 779.Va pve_entry 780to zero. 781Subsequent entries are returned by leaving 782.Va pve_entry 783unmodified from the value returned by previous requests. 784The 785.Va pve_timestamp 786field can be used to detect changes to the VM map while iterating over the 787entries. 788The tracing process can then take appropriate action, such as restarting. 789By setting 790.Va pve_pathlen 791to a non-zero value on entry, the pathname of the backing object is returned 792in the buffer pointed to by 793.Va pve_path , 794provided the entry is backed by a vnode. 795The 796.Va pve_pathlen 797field is updated with the actual length of the pathname (including the 798terminating null character). 799The 800.Va pve_offset 801field is the offset within the backing object at which the range starts. 802The range is located in the VM space at 803.Va pve_start 804and extends up to 805.Va pve_end 806(inclusive). 807.Pp 808The 809.Fa data 810argument is ignored. 811.El 812.Sh ARM MACHINE-SPECIFIC REQUESTS 813.Bl -tag -width "Dv PT_SETVFPREGS" 814.It Dv PT_GETVFPREGS 815Return the thread's 816.Dv VFP 817machine state in the buffer pointed to by 818.Fa addr . 819.Pp 820The 821.Fa data 822argument is ignored. 823.It Dv PT_SETVFPREGS 824Set the thread's 825.Dv VFP 826machine state from the buffer pointed to by 827.Fa addr . 828.Pp 829The 830.Fa data 831argument is ignored. 832.El 833.Pp 834.Sh x86 MACHINE-SPECIFIC REQUESTS 835.Bl -tag -width "Dv PT_GETXSTATE_INFO" 836.It Dv PT_GETXMMREGS 837Copy the XMM FPU state into the buffer pointed to by the 838argument 839.Fa addr . 840The buffer has the same layout as the 32-bit save buffer for the 841machine instruction 842.Dv FXSAVE . 843.Pp 844This request is only valid for i386 programs, both on native 32-bit 845systems and on amd64 kernels. 846For 64-bit amd64 programs, the XMM state is reported as part of 847the FPU state returned by the 848.Dv PT_GETFPREGS 849request. 850.Pp 851The 852.Fa data 853argument is ignored. 854.It Dv PT_SETXMMREGS 855Load the XMM FPU state for the thread from the buffer pointed to 856by the argument 857.Fa addr . 858The buffer has the same layout as the 32-bit load buffer for the 859machine instruction 860.Dv FXRSTOR . 861.Pp 862As with 863.Dv PT_GETXMMREGS, 864this request is only valid for i386 programs. 865.Pp 866The 867.Fa data 868argument is ignored. 869.It Dv PT_GETXSTATE_INFO 870Report which XSAVE FPU extensions are supported by the CPU 871and allowed in userspace programs. 872The 873.Fa addr 874argument must point to a variable of type 875.Vt struct ptrace_xstate_info , 876which contains the information on the request return. 877.Vt struct ptrace_xstate_info 878is defined as follows: 879.Bd -literal 880struct ptrace_xstate_info { 881 uint64_t xsave_mask; 882 uint32_t xsave_len; 883}; 884.Ed 885The 886.Dv xsave_mask 887field is a bitmask of the currently enabled extensions. 888The meaning of the bits is defined in the Intel and AMD 889processor documentation. 890The 891.Dv xsave_len 892field reports the length of the XSAVE area for storing the hardware 893state for currently enabled extensions in the format defined by the x86 894.Dv XSAVE 895machine instruction. 896.Pp 897The 898.Fa data 899argument value must be equal to the size of the 900.Vt struct ptrace_xstate_info . 901.It Dv PT_GETXSTATE 902Return the content of the XSAVE area for the thread. 903The 904.Fa addr 905argument points to the buffer where the content is copied, and the 906.Fa data 907argument specifies the size of the buffer. 908The kernel copies out as much content as allowed by the buffer size. 909The buffer layout is specified by the layout of the save area for the 910.Dv XSAVE 911machine instruction. 912.It Dv PT_SETXSTATE 913Load the XSAVE state for the thread from the buffer specified by the 914.Fa addr 915pointer. 916The buffer size is passed in the 917.Fa data 918argument. 919The buffer must be at least as large as the 920.Vt struct savefpu 921(defined in 922.Pa x86/fpu.h ) 923to allow the complete x87 FPU and XMM state load. 924It must not be larger than the XSAVE state length, as reported by the 925.Dv xsave_len 926field from the 927.Vt struct ptrace_xstate_info 928of the 929.Dv PT_GETXSTATE_INFO 930request. 931Layout of the buffer is identical to the layout of the load area for the 932.Dv XRSTOR 933machine instruction. 934.It Dv PT_GETFSBASE 935Return the value of the base used when doing segmented 936memory addressing using the %fs segment register. 937The 938.Fa addr 939argument points to an 940.Vt unsigned long 941variable where the base value is stored. 942.Pp 943The 944.Fa data 945argument is ignored. 946.It Dv PT_GETGSBASE 947Like the 948.Dv PT_GETFSBASE 949request, but returns the base for the %gs segment register. 950.It Dv PT_SETFSBASE 951Set the base for the %fs segment register to the value pointed to 952by the 953.Fa addr 954argument. 955.Fa addr 956must point to the 957.Vt unsigned long 958variable containing the new base. 959.Pp 960The 961.Fa data 962argument is ignored. 963.It Dv PT_SETGSBASE 964Like the 965.Dv PT_SETFSBASE 966request, but sets the base for the %gs segment register. 967.El 968.Sh PowerPC MACHINE-SPECIFIC REQUESTS 969.Bl -tag -width "Dv PT_SETVRREGS" 970.It Dv PT_GETVRREGS 971Return the thread's 972.Dv ALTIVEC 973machine state in the buffer pointed to by 974.Fa addr . 975.Pp 976The 977.Fa data 978argument is ignored. 979.It Dv PT_SETVRREGS 980Set the thread's 981.Dv ALTIVEC 982machine state from the buffer pointed to by 983.Fa addr . 984.Pp 985The 986.Fa data 987argument is ignored. 988.It Dv PT_GETVSRREGS 989Return doubleword 1 of the thread's 990.Dv VSX 991registers VSR0-VSR31 in the buffer pointed to by 992.Fa addr . 993.Pp 994The 995.Fa data 996argument is ignored. 997.It Dv PT_SETVSRREGS 998Set doubleword 1 of the thread's 999.Dv VSX 1000registers VSR0-VSR31 from the buffer pointed to by 1001.Fa addr . 1002.Pp 1003The 1004.Fa data 1005argument is ignored. 1006.El 1007.Pp 1008Additionally, other machine-specific requests can exist. 1009.Sh RETURN VALUES 1010Most requests return 0 on success and \-1 on error. 1011Some requests can cause 1012.Fn ptrace 1013to return 1014\-1 1015as a non-error value, among them are 1016.Dv PT_READ_I 1017and 1018.Dv PT_READ_D , 1019which return the value read from the process memory on success. 1020To disambiguate, 1021.Va errno 1022can be set to 0 before the call and checked afterwards. 1023.Pp 1024The current 1025.Fn ptrace 1026implementation always sets 1027.Va errno 1028to 0 before calling into the kernel, both for historic reasons and for 1029consistency with other operating systems. 1030It is recommended to assign zero to 1031.Va errno 1032explicitly for forward compatibility. 1033.Sh ERRORS 1034The 1035.Fn ptrace 1036system call may fail if: 1037.Bl -tag -width Er 1038.It Bq Er ESRCH 1039.Bl -bullet -compact 1040.It 1041No process having the specified process ID exists. 1042.El 1043.It Bq Er EINVAL 1044.Bl -bullet -compact 1045.It 1046A process attempted to use 1047.Dv PT_ATTACH 1048on itself. 1049.It 1050The 1051.Fa request 1052argument 1053was not one of the legal requests. 1054.It 1055The signal number 1056(in 1057.Fa data ) 1058to 1059.Dv PT_CONTINUE 1060was neither 0 nor a legal signal number. 1061.It 1062.Dv PT_GETREGS , 1063.Dv PT_SETREGS , 1064.Dv PT_GETFPREGS , 1065.Dv PT_SETFPREGS , 1066.Dv PT_GETDBREGS , 1067or 1068.Dv PT_SETDBREGS 1069was attempted on a process with no valid register set. 1070(This is normally true only of system processes.) 1071.It 1072.Dv PT_VM_ENTRY 1073was given an invalid value for 1074.Fa pve_entry . 1075This can also be caused by changes to the VM map of the process. 1076.It 1077The size (in 1078.Fa data ) 1079provided to 1080.Dv PT_LWPINFO 1081was less than or equal to zero, or larger than the 1082.Vt ptrace_lwpinfo 1083structure known to the kernel. 1084.It 1085The size (in 1086.Fa data ) 1087provided to the x86-specific 1088.Dv PT_GETXSTATE_INFO 1089request was not equal to the size of the 1090.Vt struct ptrace_xstate_info . 1091.It 1092The size (in 1093.Fa data ) 1094provided to the x86-specific 1095.Dv PT_SETXSTATE 1096request was less than the size of the x87 plus the XMM save area. 1097.It 1098The size (in 1099.Fa data ) 1100provided to the x86-specific 1101.Dv PT_SETXSTATE 1102request was larger than returned in the 1103.Dv xsave_len 1104member of the 1105.Vt struct ptrace_xstate_info 1106from the 1107.Dv PT_GETXSTATE_INFO 1108request. 1109.It 1110The base value, provided to the amd64-specific requests 1111.Dv PT_SETFSBASE 1112or 1113.Dv PT_SETGSBASE , 1114pointed outside of the valid user address space. 1115This error will not occur in 32-bit programs. 1116.El 1117.It Bq Er EBUSY 1118.Bl -bullet -compact 1119.It 1120.Dv PT_ATTACH 1121was attempted on a process that was already being traced. 1122.It 1123A request attempted to manipulate a process that was being traced by 1124some process other than the one making the request. 1125.It 1126A request 1127(other than 1128.Dv PT_ATTACH ) 1129specified a process that was not stopped. 1130.El 1131.It Bq Er EPERM 1132.Bl -bullet -compact 1133.It 1134A request 1135(other than 1136.Dv PT_ATTACH ) 1137attempted to manipulate a process that was not being traced at all. 1138.It 1139An attempt was made to use 1140.Dv PT_ATTACH 1141on a process in violation of the requirements listed under 1142.Dv PT_ATTACH 1143above. 1144.El 1145.It Bq Er ENOENT 1146.Bl -bullet -compact 1147.It 1148.Dv PT_VM_ENTRY 1149previously returned the last entry of the memory map. 1150No more entries exist. 1151.El 1152.It Bq Er ENAMETOOLONG 1153.Bl -bullet -compact 1154.It 1155.Dv PT_VM_ENTRY 1156cannot return the pathname of the backing object because the buffer is not big 1157enough. 1158.Fa pve_pathlen 1159holds the minimum buffer size required on return. 1160.El 1161.El 1162.Sh SEE ALSO 1163.Xr execve 2 , 1164.Xr sigaction 2 , 1165.Xr wait 2 , 1166.Xr execv 3 , 1167.Xr i386_clr_watch 3 , 1168.Xr i386_set_watch 3 1169.Sh HISTORY 1170The 1171.Fn ptrace 1172function appeared in 1173.At v6 . 1174