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 December 1, 2017 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. 609.It Dv PT_CLEARSTEP 610This request will turn off single stepping of the specified process. 611.It Dv PT_SUSPEND 612This request will suspend the specified thread. 613.It Dv PT_RESUME 614This request will resume the specified thread. 615.It Dv PT_TO_SCE 616This request will set the 617.Dv PTRACE_SCE 618event flag to trace all future system call entries and continue the process. 619The 620.Fa addr 621and 622.Fa data 623arguments are used the same as for 624.Dv PT_CONTINUE. 625.It Dv PT_TO_SCX 626This request will set the 627.Dv PTRACE_SCX 628event flag to trace all future system call exits and continue the process. 629The 630.Fa addr 631and 632.Fa data 633arguments are used the same as for 634.Dv PT_CONTINUE. 635.It Dv PT_SYSCALL 636This request will set the 637.Dv PTRACE_SYSCALL 638event flag to trace all future system call entries and exits and continue 639the process. 640The 641.Fa addr 642and 643.Fa data 644arguments are used the same as for 645.Dv PT_CONTINUE. 646.It Dv PT_GET_SC_ARGS 647For the thread which is stopped in either 648.Dv PL_FLAG_SCE 649or 650.Dv PL_FLAG_SCX 651state, that is, on entry or exit to a syscall, 652this request fetches the syscall arguments. 653.Pp 654The arguments are copied out into the buffer pointed to by the 655.Fa addr 656pointer, sequentially. 657Each syscall argument is stored as the machine word. 658Kernel copies out as many arguments as the syscall accepts, 659see the 660.Va pl_syscall_narg 661member of the 662.Vt struct ptrace_lwpinfo , 663but not more than the 664.Fa data 665bytes in total are copied. 666.It Dv PT_FOLLOW_FORK 667This request controls tracing for new child processes of a traced process. 668If 669.Fa data 670is non-zero, 671.Dv PTRACE_FORK 672is set in the traced process's event tracing mask. 673If 674.Fa data 675is zero, 676.Dv PTRACE_FORK 677is cleared from the traced process's event tracing mask. 678.It Dv PT_LWP_EVENTS 679This request controls tracing of LWP creation and destruction. 680If 681.Fa data 682is non-zero, 683.Dv PTRACE_LWP 684is set in the traced process's event tracing mask. 685If 686.Fa data 687is zero, 688.Dv PTRACE_LWP 689is cleared from the traced process's event tracing mask. 690.It Dv PT_GET_EVENT_MASK 691This request reads the traced process's event tracing mask into the 692integer pointed to by 693.Fa addr . 694The size of the integer must be passed in 695.Fa data . 696.It Dv PT_SET_EVENT_MASK 697This request sets the traced process's event tracing mask from the 698integer pointed to by 699.Fa addr . 700The size of the integer must be passed in 701.Fa data . 702.It Dv PT_VM_TIMESTAMP 703This request returns the generation number or timestamp of the memory map of 704the traced process as the return value from 705.Fn ptrace . 706This provides a low-cost way for the tracing process to determine if the 707VM map changed since the last time this request was made. 708.It Dv PT_VM_ENTRY 709This request is used to iterate over the entries of the VM map of the traced 710process. 711The 712.Fa addr 713argument specifies a pointer to a 714.Vt "struct ptrace_vm_entry" , 715which is defined as follows: 716.Bd -literal 717struct ptrace_vm_entry { 718 int pve_entry; 719 int pve_timestamp; 720 u_long pve_start; 721 u_long pve_end; 722 u_long pve_offset; 723 u_int pve_prot; 724 u_int pve_pathlen; 725 long pve_fileid; 726 uint32_t pve_fsid; 727 char *pve_path; 728}; 729.Ed 730.Pp 731The first entry is returned by setting 732.Va pve_entry 733to zero. 734Subsequent entries are returned by leaving 735.Va pve_entry 736unmodified from the value returned by previous requests. 737The 738.Va pve_timestamp 739field can be used to detect changes to the VM map while iterating over the 740entries. 741The tracing process can then take appropriate action, such as restarting. 742By setting 743.Va pve_pathlen 744to a non-zero value on entry, the pathname of the backing object is returned 745in the buffer pointed to by 746.Va pve_path , 747provided the entry is backed by a vnode. 748The 749.Va pve_pathlen 750field is updated with the actual length of the pathname (including the 751terminating null character). 752The 753.Va pve_offset 754field is the offset within the backing object at which the range starts. 755The range is located in the VM space at 756.Va pve_start 757and extends up to 758.Va pve_end 759(inclusive). 760.Pp 761The 762.Fa data 763argument is ignored. 764.El 765.Sh ARM MACHINE-SPECIFIC REQUESTS 766.Bl -tag -width "Dv PT_SETVFPREGS" 767.It Dv PT_GETVFPREGS 768Return the thread's 769.Dv VFP 770machine state in the buffer pointed to by 771.Fa addr . 772.Pp 773The 774.Fa data 775argument is ignored. 776.It Dv PT_SETVFPREGS 777Set the thread's 778.Dv VFP 779machine state from the buffer pointed to by 780.Fa addr . 781.Pp 782The 783.Fa data 784argument is ignored. 785.El 786.Pp 787.Sh x86 MACHINE-SPECIFIC REQUESTS 788.Bl -tag -width "Dv PT_GETXSTATE_INFO" 789.It Dv PT_GETXMMREGS 790Copy the XMM FPU state into the buffer pointed to by the 791argument 792.Fa addr . 793The buffer has the same layout as the 32-bit save buffer for the 794machine instruction 795.Dv FXSAVE . 796.Pp 797This request is only valid for i386 programs, both on native 32-bit 798systems and on amd64 kernels. 799For 64-bit amd64 programs, the XMM state is reported as part of 800the FPU state returned by the 801.Dv PT_GETFPREGS 802request. 803.Pp 804The 805.Fa data 806argument is ignored. 807.It Dv PT_SETXMMREGS 808Load the XMM FPU state for the thread from the buffer pointed to 809by the argument 810.Fa addr . 811The buffer has the same layout as the 32-bit load buffer for the 812machine instruction 813.Dv FXRSTOR . 814.Pp 815As with 816.Dv PT_GETXMMREGS, 817this request is only valid for i386 programs. 818.Pp 819The 820.Fa data 821argument is ignored. 822.It Dv PT_GETXSTATE_INFO 823Report which XSAVE FPU extensions are supported by the CPU 824and allowed in userspace programs. 825The 826.Fa addr 827argument must point to a variable of type 828.Vt struct ptrace_xstate_info , 829which contains the information on the request return. 830.Vt struct ptrace_xstate_info 831is defined as follows: 832.Bd -literal 833struct ptrace_xstate_info { 834 uint64_t xsave_mask; 835 uint32_t xsave_len; 836}; 837.Ed 838The 839.Dv xsave_mask 840field is a bitmask of the currently enabled extensions. 841The meaning of the bits is defined in the Intel and AMD 842processor documentation. 843The 844.Dv xsave_len 845field reports the length of the XSAVE area for storing the hardware 846state for currently enabled extensions in the format defined by the x86 847.Dv XSAVE 848machine instruction. 849.Pp 850The 851.Fa data 852argument value must be equal to the size of the 853.Vt struct ptrace_xstate_info . 854.It Dv PT_GETXSTATE 855Return the content of the XSAVE area for the thread. 856The 857.Fa addr 858argument points to the buffer where the content is copied, and the 859.Fa data 860argument specifies the size of the buffer. 861The kernel copies out as much content as allowed by the buffer size. 862The buffer layout is specified by the layout of the save area for the 863.Dv XSAVE 864machine instruction. 865.It Dv PT_SETXSTATE 866Load the XSAVE state for the thread from the buffer specified by the 867.Fa addr 868pointer. 869The buffer size is passed in the 870.Fa data 871argument. 872The buffer must be at least as large as the 873.Vt struct savefpu 874(defined in 875.Pa x86/fpu.h ) 876to allow the complete x87 FPU and XMM state load. 877It must not be larger than the XSAVE state length, as reported by the 878.Dv xsave_len 879field from the 880.Vt struct ptrace_xstate_info 881of the 882.Dv PT_GETXSTATE_INFO 883request. 884Layout of the buffer is identical to the layout of the load area for the 885.Dv XRSTOR 886machine instruction. 887.It Dv PT_GETFSBASE 888Return the value of the base used when doing segmented 889memory addressing using the %fs segment register. 890The 891.Fa addr 892argument points to an 893.Vt unsigned long 894variable where the base value is stored. 895.Pp 896The 897.Fa data 898argument is ignored. 899.It Dv PT_GETGSBASE 900Like the 901.Dv PT_GETFSBASE 902request, but returns the base for the %gs segment register. 903.It Dv PT_SETFSBASE 904Set the base for the %fs segment register to the value pointed to 905by the 906.Fa addr 907argument. 908.Fa addr 909must point to the 910.Vt unsigned long 911variable containing the new base. 912.Pp 913The 914.Fa data 915argument is ignored. 916.It Dv PT_SETGSBASE 917Like the 918.Dv PT_SETFSBASE 919request, but sets the base for the %gs segment register. 920.El 921.Sh PowerPC MACHINE-SPECIFIC REQUESTS 922.Bl -tag -width "Dv PT_SETVRREGS" 923.It Dv PT_GETVRREGS 924Return the thread's 925.Dv ALTIVEC 926machine state in the buffer pointed to by 927.Fa addr . 928.Pp 929The 930.Fa data 931argument is ignored. 932.It Dv PT_SETVRREGS 933Set the thread's 934.Dv ALTIVEC 935machine state from the buffer pointed to by 936.Fa addr . 937.Pp 938The 939.Fa data 940argument is ignored. 941.El 942.Pp 943Additionally, other machine-specific requests can exist. 944.Sh RETURN VALUES 945Most requests return 0 on success and \-1 on error. 946Some requests can cause 947.Fn ptrace 948to return 949\-1 950as a non-error value, among them are 951.Dv PT_READ_I 952and 953.Dv PT_READ_D , 954which return the value read from the process memory on success. 955To disambiguate, 956.Va errno 957can be set to 0 before the call and checked afterwards. 958.Pp 959The current 960.Fn ptrace 961implementation always sets 962.Va errno 963to 0 before calling into the kernel, both for historic reasons and for 964consistency with other operating systems. 965It is recommended to assign zero to 966.Va errno 967explicitly for forward compatibility. 968.Sh ERRORS 969The 970.Fn ptrace 971system call may fail if: 972.Bl -tag -width Er 973.It Bq Er ESRCH 974.Bl -bullet -compact 975.It 976No process having the specified process ID exists. 977.El 978.It Bq Er EINVAL 979.Bl -bullet -compact 980.It 981A process attempted to use 982.Dv PT_ATTACH 983on itself. 984.It 985The 986.Fa request 987argument 988was not one of the legal requests. 989.It 990The signal number 991(in 992.Fa data ) 993to 994.Dv PT_CONTINUE 995was neither 0 nor a legal signal number. 996.It 997.Dv PT_GETREGS , 998.Dv PT_SETREGS , 999.Dv PT_GETFPREGS , 1000.Dv PT_SETFPREGS , 1001.Dv PT_GETDBREGS , 1002or 1003.Dv PT_SETDBREGS 1004was attempted on a process with no valid register set. 1005(This is normally true only of system processes.) 1006.It 1007.Dv PT_VM_ENTRY 1008was given an invalid value for 1009.Fa pve_entry . 1010This can also be caused by changes to the VM map of the process. 1011.It 1012The size (in 1013.Fa data ) 1014provided to 1015.Dv PT_LWPINFO 1016was less than or equal to zero, or larger than the 1017.Vt ptrace_lwpinfo 1018structure known to the kernel. 1019.It 1020The size (in 1021.Fa data ) 1022provided to the x86-specific 1023.Dv PT_GETXSTATE_INFO 1024request was not equal to the size of the 1025.Vt struct ptrace_xstate_info . 1026.It 1027The size (in 1028.Fa data ) 1029provided to the x86-specific 1030.Dv PT_SETXSTATE 1031request was less than the size of the x87 plus the XMM save area. 1032.It 1033The size (in 1034.Fa data ) 1035provided to the x86-specific 1036.Dv PT_SETXSTATE 1037request was larger than returned in the 1038.Dv xsave_len 1039member of the 1040.Vt struct ptrace_xstate_info 1041from the 1042.Dv PT_GETXSTATE_INFO 1043request. 1044.It 1045The base value, provided to the amd64-specific requests 1046.Dv PT_SETFSBASE 1047or 1048.Dv PT_SETGSBASE , 1049pointed outside of the valid user address space. 1050This error will not occur in 32-bit programs. 1051.El 1052.It Bq Er EBUSY 1053.Bl -bullet -compact 1054.It 1055.Dv PT_ATTACH 1056was attempted on a process that was already being traced. 1057.It 1058A request attempted to manipulate a process that was being traced by 1059some process other than the one making the request. 1060.It 1061A request 1062(other than 1063.Dv PT_ATTACH ) 1064specified a process that was not stopped. 1065.El 1066.It Bq Er EPERM 1067.Bl -bullet -compact 1068.It 1069A request 1070(other than 1071.Dv PT_ATTACH ) 1072attempted to manipulate a process that was not being traced at all. 1073.It 1074An attempt was made to use 1075.Dv PT_ATTACH 1076on a process in violation of the requirements listed under 1077.Dv PT_ATTACH 1078above. 1079.El 1080.It Bq Er ENOENT 1081.Bl -bullet -compact 1082.It 1083.Dv PT_VM_ENTRY 1084previously returned the last entry of the memory map. 1085No more entries exist. 1086.El 1087.It Bq Er ENAMETOOLONG 1088.Bl -bullet -compact 1089.It 1090.Dv PT_VM_ENTRY 1091cannot return the pathname of the backing object because the buffer is not big 1092enough. 1093.Fa pve_pathlen 1094holds the minimum buffer size required on return. 1095.El 1096.El 1097.Sh SEE ALSO 1098.Xr execve 2 , 1099.Xr sigaction 2 , 1100.Xr wait 2 , 1101.Xr execv 3 , 1102.Xr i386_clr_watch 3 , 1103.Xr i386_set_watch 3 1104.Sh HISTORY 1105The 1106.Fn ptrace 1107function appeared in 1108.At v6 . 1109