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