1.\" $FreeBSD$ 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.Bl -tag -width Dv EJUSTRETURN -compact 702.It Dv ERESTART 703System call will be restarted. 704.It Dv EJUSTRETURN 705System call completed sucessfully but did not set a return value 706.Po for example, 707.Xr setcontext 2 708and 709.Xr sigreturn 2 710.Pc . 711.El 712.It Dv PT_FOLLOW_FORK 713This request controls tracing for new child processes of a traced process. 714If 715.Fa data 716is non-zero, 717.Dv PTRACE_FORK 718is set in the traced process's event tracing mask. 719If 720.Fa data 721is zero, 722.Dv PTRACE_FORK 723is cleared from the traced process's event tracing mask. 724.It Dv PT_LWP_EVENTS 725This request controls tracing of LWP creation and destruction. 726If 727.Fa data 728is non-zero, 729.Dv PTRACE_LWP 730is set in the traced process's event tracing mask. 731If 732.Fa data 733is zero, 734.Dv PTRACE_LWP 735is cleared from the traced process's event tracing mask. 736.It Dv PT_GET_EVENT_MASK 737This request reads the traced process's event tracing mask into the 738integer pointed to by 739.Fa addr . 740The size of the integer must be passed in 741.Fa data . 742.It Dv PT_SET_EVENT_MASK 743This request sets the traced process's event tracing mask from the 744integer pointed to by 745.Fa addr . 746The size of the integer must be passed in 747.Fa data . 748.It Dv PT_VM_TIMESTAMP 749This request returns the generation number or timestamp of the memory map of 750the traced process as the return value from 751.Fn ptrace . 752This provides a low-cost way for the tracing process to determine if the 753VM map changed since the last time this request was made. 754.It Dv PT_VM_ENTRY 755This request is used to iterate over the entries of the VM map of the traced 756process. 757The 758.Fa addr 759argument specifies a pointer to a 760.Vt "struct ptrace_vm_entry" , 761which is defined as follows: 762.Bd -literal 763struct ptrace_vm_entry { 764 int pve_entry; 765 int pve_timestamp; 766 u_long pve_start; 767 u_long pve_end; 768 u_long pve_offset; 769 u_int pve_prot; 770 u_int pve_pathlen; 771 long pve_fileid; 772 uint32_t pve_fsid; 773 char *pve_path; 774}; 775.Ed 776.Pp 777The first entry is returned by setting 778.Va pve_entry 779to zero. 780Subsequent entries are returned by leaving 781.Va pve_entry 782unmodified from the value returned by previous requests. 783The 784.Va pve_timestamp 785field can be used to detect changes to the VM map while iterating over the 786entries. 787The tracing process can then take appropriate action, such as restarting. 788By setting 789.Va pve_pathlen 790to a non-zero value on entry, the pathname of the backing object is returned 791in the buffer pointed to by 792.Va pve_path , 793provided the entry is backed by a vnode. 794The 795.Va pve_pathlen 796field is updated with the actual length of the pathname (including the 797terminating null character). 798The 799.Va pve_offset 800field is the offset within the backing object at which the range starts. 801The range is located in the VM space at 802.Va pve_start 803and extends up to 804.Va pve_end 805(inclusive). 806.Pp 807The 808.Fa data 809argument is ignored. 810.El 811.Sh ARM MACHINE-SPECIFIC REQUESTS 812.Bl -tag -width "Dv PT_SETVFPREGS" 813.It Dv PT_GETVFPREGS 814Return the thread's 815.Dv VFP 816machine state in the buffer pointed to by 817.Fa addr . 818.Pp 819The 820.Fa data 821argument is ignored. 822.It Dv PT_SETVFPREGS 823Set the thread's 824.Dv VFP 825machine state from the buffer pointed to by 826.Fa addr . 827.Pp 828The 829.Fa data 830argument is ignored. 831.El 832.Sh x86 MACHINE-SPECIFIC REQUESTS 833.Bl -tag -width "Dv PT_GETXSTATE_INFO" 834.It Dv PT_GETXMMREGS 835Copy the XMM FPU state into the buffer pointed to by the 836argument 837.Fa addr . 838The buffer has the same layout as the 32-bit save buffer for the 839machine instruction 840.Dv FXSAVE . 841.Pp 842This request is only valid for i386 programs, both on native 32-bit 843systems and on amd64 kernels. 844For 64-bit amd64 programs, the XMM state is reported as part of 845the FPU state returned by the 846.Dv PT_GETFPREGS 847request. 848.Pp 849The 850.Fa data 851argument is ignored. 852.It Dv PT_SETXMMREGS 853Load the XMM FPU state for the thread from the buffer pointed to 854by the argument 855.Fa addr . 856The buffer has the same layout as the 32-bit load buffer for the 857machine instruction 858.Dv FXRSTOR . 859.Pp 860As with 861.Dv PT_GETXMMREGS , 862this request is only valid for i386 programs. 863.Pp 864The 865.Fa data 866argument is ignored. 867.It Dv PT_GETXSTATE_INFO 868Report which XSAVE FPU extensions are supported by the CPU 869and allowed in userspace programs. 870The 871.Fa addr 872argument must point to a variable of type 873.Vt struct ptrace_xstate_info , 874which contains the information on the request return. 875.Vt struct ptrace_xstate_info 876is defined as follows: 877.Bd -literal 878struct ptrace_xstate_info { 879 uint64_t xsave_mask; 880 uint32_t xsave_len; 881}; 882.Ed 883The 884.Dv xsave_mask 885field is a bitmask of the currently enabled extensions. 886The meaning of the bits is defined in the Intel and AMD 887processor documentation. 888The 889.Dv xsave_len 890field reports the length of the XSAVE area for storing the hardware 891state for currently enabled extensions in the format defined by the x86 892.Dv XSAVE 893machine instruction. 894.Pp 895The 896.Fa data 897argument value must be equal to the size of the 898.Vt struct ptrace_xstate_info . 899.It Dv PT_GETXSTATE 900Return the content of the XSAVE area for the thread. 901The 902.Fa addr 903argument points to the buffer where the content is copied, and the 904.Fa data 905argument specifies the size of the buffer. 906The kernel copies out as much content as allowed by the buffer size. 907The buffer layout is specified by the layout of the save area for the 908.Dv XSAVE 909machine instruction. 910.It Dv PT_SETXSTATE 911Load the XSAVE state for the thread from the buffer specified by the 912.Fa addr 913pointer. 914The buffer size is passed in the 915.Fa data 916argument. 917The buffer must be at least as large as the 918.Vt struct savefpu 919(defined in 920.Pa x86/fpu.h ) 921to allow the complete x87 FPU and XMM state load. 922It must not be larger than the XSAVE state length, as reported by the 923.Dv xsave_len 924field from the 925.Vt struct ptrace_xstate_info 926of the 927.Dv PT_GETXSTATE_INFO 928request. 929Layout of the buffer is identical to the layout of the load area for the 930.Dv XRSTOR 931machine instruction. 932.It Dv PT_GETFSBASE 933Return the value of the base used when doing segmented 934memory addressing using the %fs segment register. 935The 936.Fa addr 937argument points to an 938.Vt unsigned long 939variable where the base value is stored. 940.Pp 941The 942.Fa data 943argument is ignored. 944.It Dv PT_GETGSBASE 945Like the 946.Dv PT_GETFSBASE 947request, but returns the base for the %gs segment register. 948.It Dv PT_SETFSBASE 949Set the base for the %fs segment register to the value pointed to 950by the 951.Fa addr 952argument. 953.Fa addr 954must point to the 955.Vt unsigned long 956variable containing the new base. 957.Pp 958The 959.Fa data 960argument is ignored. 961.It Dv PT_SETGSBASE 962Like the 963.Dv PT_SETFSBASE 964request, but sets the base for the %gs segment register. 965.El 966.Sh PowerPC MACHINE-SPECIFIC REQUESTS 967.Bl -tag -width "Dv PT_SETVRREGS" 968.It Dv PT_GETVRREGS 969Return the thread's 970.Dv ALTIVEC 971machine state in the buffer pointed to by 972.Fa addr . 973.Pp 974The 975.Fa data 976argument is ignored. 977.It Dv PT_SETVRREGS 978Set the thread's 979.Dv ALTIVEC 980machine state from the buffer pointed to by 981.Fa addr . 982.Pp 983The 984.Fa data 985argument is ignored. 986.It Dv PT_GETVSRREGS 987Return doubleword 1 of the thread's 988.Dv VSX 989registers VSR0-VSR31 in the buffer pointed to by 990.Fa addr . 991.Pp 992The 993.Fa data 994argument is ignored. 995.It Dv PT_SETVSRREGS 996Set doubleword 1 of the thread's 997.Dv VSX 998registers VSR0-VSR31 from the buffer pointed to by 999.Fa addr . 1000.Pp 1001The 1002.Fa data 1003argument is ignored. 1004.El 1005.Pp 1006Additionally, other machine-specific requests can exist. 1007.Sh RETURN VALUES 1008Most requests return 0 on success and \-1 on error. 1009Some requests can cause 1010.Fn ptrace 1011to return 1012\-1 1013as a non-error value, among them are 1014.Dv PT_READ_I 1015and 1016.Dv PT_READ_D , 1017which return the value read from the process memory on success. 1018To disambiguate, 1019.Va errno 1020can be set to 0 before the call and checked afterwards. 1021.Pp 1022The current 1023.Fn ptrace 1024implementation always sets 1025.Va errno 1026to 0 before calling into the kernel, both for historic reasons and for 1027consistency with other operating systems. 1028It is recommended to assign zero to 1029.Va errno 1030explicitly for forward compatibility. 1031.Sh ERRORS 1032The 1033.Fn ptrace 1034system call may fail if: 1035.Bl -tag -width Er 1036.It Bq Er ESRCH 1037.Bl -bullet -compact 1038.It 1039No process having the specified process ID exists. 1040.El 1041.It Bq Er EINVAL 1042.Bl -bullet -compact 1043.It 1044A process attempted to use 1045.Dv PT_ATTACH 1046on itself. 1047.It 1048The 1049.Fa request 1050argument 1051was not one of the legal requests. 1052.It 1053The signal number 1054(in 1055.Fa data ) 1056to 1057.Dv PT_CONTINUE 1058was neither 0 nor a legal signal number. 1059.It 1060.Dv PT_GETREGS , 1061.Dv PT_SETREGS , 1062.Dv PT_GETFPREGS , 1063.Dv PT_SETFPREGS , 1064.Dv PT_GETDBREGS , 1065or 1066.Dv PT_SETDBREGS 1067was attempted on a process with no valid register set. 1068(This is normally true only of system processes.) 1069.It 1070.Dv PT_VM_ENTRY 1071was given an invalid value for 1072.Fa pve_entry . 1073This can also be caused by changes to the VM map of the process. 1074.It 1075The size (in 1076.Fa data ) 1077provided to 1078.Dv PT_LWPINFO 1079was less than or equal to zero, or larger than the 1080.Vt ptrace_lwpinfo 1081structure known to the kernel. 1082.It 1083The size (in 1084.Fa data ) 1085provided to the x86-specific 1086.Dv PT_GETXSTATE_INFO 1087request was not equal to the size of the 1088.Vt struct ptrace_xstate_info . 1089.It 1090The size (in 1091.Fa data ) 1092provided to the x86-specific 1093.Dv PT_SETXSTATE 1094request was less than the size of the x87 plus the XMM save area. 1095.It 1096The size (in 1097.Fa data ) 1098provided to the x86-specific 1099.Dv PT_SETXSTATE 1100request was larger than returned in the 1101.Dv xsave_len 1102member of the 1103.Vt struct ptrace_xstate_info 1104from the 1105.Dv PT_GETXSTATE_INFO 1106request. 1107.It 1108The base value, provided to the amd64-specific requests 1109.Dv PT_SETFSBASE 1110or 1111.Dv PT_SETGSBASE , 1112pointed outside of the valid user address space. 1113This error will not occur in 32-bit programs. 1114.El 1115.It Bq Er EBUSY 1116.Bl -bullet -compact 1117.It 1118.Dv PT_ATTACH 1119was attempted on a process that was already being traced. 1120.It 1121A request attempted to manipulate a process that was being traced by 1122some process other than the one making the request. 1123.It 1124A request 1125(other than 1126.Dv PT_ATTACH ) 1127specified a process that was not stopped. 1128.El 1129.It Bq Er EPERM 1130.Bl -bullet -compact 1131.It 1132A request 1133(other than 1134.Dv PT_ATTACH ) 1135attempted to manipulate a process that was not being traced at all. 1136.It 1137An attempt was made to use 1138.Dv PT_ATTACH 1139on a process in violation of the requirements listed under 1140.Dv PT_ATTACH 1141above. 1142.El 1143.It Bq Er ENOENT 1144.Bl -bullet -compact 1145.It 1146.Dv PT_VM_ENTRY 1147previously returned the last entry of the memory map. 1148No more entries exist. 1149.El 1150.It Bq Er ENAMETOOLONG 1151.Bl -bullet -compact 1152.It 1153.Dv PT_VM_ENTRY 1154cannot return the pathname of the backing object because the buffer is not big 1155enough. 1156.Fa pve_pathlen 1157holds the minimum buffer size required on return. 1158.El 1159.El 1160.Sh SEE ALSO 1161.Xr execve 2 , 1162.Xr sigaction 2 , 1163.Xr wait 2 , 1164.Xr execv 3 , 1165.Xr i386_clr_watch 3 , 1166.Xr i386_set_watch 3 1167.Sh HISTORY 1168The 1169.Fn ptrace 1170function appeared in 1171.At v6 . 1172