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