1.\" $NetBSD: ptrace.2,v 1.86 2024/05/12 23:55:57 msaitoh Exp $ 2.\" 3.\" This file is in the public domain. 4.Dd May 14, 2020 5.Dt PTRACE 2 6.Os 7.Sh NAME 8.Nm ptrace 9.Nd process tracing and debugging 10.Sh LIBRARY 11.Lb libc 12.Sh SYNOPSIS 13.In sys/types.h 14.In sys/ptrace.h 15.Ft int 16.Fn ptrace "int request" "pid_t pid" "void *addr" "int data" 17.Sh DESCRIPTION 18.Fn ptrace 19provides tracing and debugging facilities. 20It allows one process (the 21.Em tracing 22process) to control another (the 23.Em traced 24process). 25Most of the time, the traced process runs normally, but when 26it receives a signal 27.Po 28see 29.Xr sigaction 2 30.Pc , 31it stops. 32The tracing process is expected to notice this via 33.Xr wait 2 34or the delivery of a 35.Dv SIGCHLD 36signal 37.Po 38see 39.Xr siginfo 2 40.Pc , 41examine the state of the stopped process, and cause it to 42terminate or continue as appropriate. 43.Fn ptrace 44is the mechanism by which all this happens. 45.Pp 46When a process that is traced by a debugger requests and calls 47.Xr execve 2 48or any of the routines built on it 49.Po 50such as 51.Xr execv 3 52.Pc , 53it will stop before executing the first instruction of the new image and emit 54.Dv SIGTRAP 55with 56.Dv si_code 57set to 58.Dv TRAP_EXEC . 59If a traced program calls 60.Xr execve 2 61any setuid or setgid bits on the executable being executed will be ignored. 62.Pp 63Program (software) breakpoints are reported with 64.Dv SIGTRAP 65and the 66.Dv si_code 67value set to 68.Dv TRAP_BKPT . 69These breakpoints are machine specific instructions that interrupt the process. 70In order to put a trap by a tracer into the tracee's program, 71debugger must violate the 72.Dv PaX MPROTECT 73restrictions. 74For details check the 75.Dv security.pax.mprotect.ptrace 76option described in 77.Xr sysctl 7 . 78When a tracee is interrupted by a trap, 79the trap is not removed by the kernel and it must be handled by a debugger. 80.Pp 81If a program is traced with single steps 82.Dv ( PT_STEP ) 83it reports each step with 84.Dv SIGTRAP 85with 86.Dv si_code 87set to 88.Dv TRAP_TRACE . 89This event is not maskable 90.Dv PT_SET_EVENT_MASK . 91.Pp 92Child program traps are reported with 93.Dv SIGTRAP 94and the 95.Dv si_code 96value set to 97.Dv TRAP_CHLD . 98These events are by default disabled and can be configured with 99.Dv PT_SET_EVENT_MASK . 100If this event occurs, 101check with 102.Dv PT_GET_PROCESS_STATE 103the details of the process state associated with this event. 104.Pp 105Design choices for Debug Register accessors 106.Bl -dash 107.It 108.Fn exec 109.Dv ( TRAP_EXEC 110event) must remove debug registers from LWP 111.It 112debug registers are only per-LWP, not per-process globally 113.It 114debug registers must not be inherited after (v)forking a process 115.It 116debug registers must not be inherited after forking a thread 117.It 118a debugger is responsible to set global watchpoints/breakpoints with the 119debug registers, 120to achieve this 121.Dv PTRACE_LWP_CREATE 122/ 123.Dv PTRACE_LWP_EXIT 124event monitoring function is designed to be used 125.It 126debug register traps must generate 127.Dv SIGTRAP with 128.Dv si_code 129.Dv TRAP_DBREG 130.It 131debugger is responsible to retrieve debug register state to distinguish 132the exact debug register trap 133.It 134kernel must not remove debug register traps after triggering a trap event; 135a debugger is responsible to detach this trap with appropriate 136.Dv PT_SETDBREGS 137call 138.It 139debug registers must not be exposed in mcontext 140.It 141userland must not be allowed to set a trap on the kernel 142.El 143.Pp 144A debugger might reuse port specific symbols, 145to help writing portable code as described in the port specific part of the 146.In sys/ptrace.h 147header. 148Among these symbols, 149there are: 150.Bl -dash 151.It 152.Dv PTRACE_REG_PC 153.It 154.Dv PTRACE_REG_SET_PC 155.It 156.Dv PTRACE_REG_SP 157.It 158.Dv PTRACE_REG_INTRV 159.It 160.Dv PTRACE_BREAKPOINT 161.It 162.Dv PTRACE_BREAKPOINT_SIZE 163.It 164.Dv PTRACE_BREAKPOINT_ADJ 165.El 166.Pp 167The 168.Fa request 169argument 170of 171.Nm 172specifies what operation is being performed; the meaning of 173the rest of the arguments depends on the operation, but except for one 174special case noted below, all 175.Nm 176calls are made by the tracing process, and the 177.Fa pid 178argument specifies the process ID of the traced process. 179.Fa request 180can be: 181.Bl -tag -width 12n 182.It Dv PT_TRACE_ME 183This request is the only one used by the traced process; it declares 184that the process expects to be traced by its parent. 185All the other arguments are ignored. 186If the parent process does not expect to trace 187the child, it will probably be rather confused by the results; once the 188traced process stops, it cannot be made to continue except via 189.Fn ptrace . 190.Pp 191This call does not stop the process neither emit 192.Dv SIGSTOP 193to parent. 194.It Dv PT_READ_I , Dv PT_READ_D 195These requests read a single 196.Vt int 197of data from the traced process' address space. 198Traditionally, 199.Fn ptrace 200has allowed for machines with distinct address spaces for instruction 201and data, which is why there are two requests: conceptually, 202.Dv PT_READ_I 203reads from the instruction space and 204.Dv PT_READ_D 205reads from the data space. 206In the current 207.Nx 208implementation, these 209two requests are completely identical. 210The 211.Fa addr 212argument specifies the address (in the traced process' virtual address 213space) at which the read is to be done. 214This address does not have to meet any alignment constraints. 215The value read is returned as the return value from 216.Eo \& 217.Fn ptrace 218.Ec . 219.Pp 220These operations return success on incomplete and cancelled byte transfers. 221New software shall use 222.Dv PT_IO 223as it allows to check whether a byte transfer was completed. 224.It Dv PT_WRITE_I , Dv PT_WRITE_D 225These requests parallel 226.Dv PT_READ_I 227and 228.Dv PT_READ_D , 229except that they write rather than read. 230The 231.Fa data 232argument supplies the value to be written. 233.Pp 234New software shall use 235.Dv PT_IO 236as it allows to check whether an operation was completed. 237.It Dv PT_CONTINUE 238The traced process continues execution. 239.Fa addr 240is an address specifying the place where execution is to be resumed (a 241new value for the program counter), or 242.Li (void *)1 243to indicate that execution is to pick up where it left off. 244.Fa data 245provides a signal number to be delivered to the traced process as it 246resumes execution, or 0 if no signal is to be sent. 247If a negative value is supplied, that is the negative of the LWP 248ID of the thread to be resumed, and only that thread executes. 249.It Dv PT_KILL 250The traced process terminates, as if 251.Dv PT_CONTINUE 252has been used with 253.Dv SIGKILL 254given as the signal to be delivered. 255However, unlike 256.Dv PT_CONTINUE , 257.Dv PT_KILL 258can be used on a non-stopped tracee. 259The 260.Fa addr 261and 262.Fa data 263arguments are ignored. 264.It Dv PT_STOP 265The traced process stops, as if 266.Xr kill 2 267has been used with 268.Dv SIGSTOP 269given as the signal to be delivered. 270.Xr wait 2 271will report the child (again) as stopped even if it was stopped before. 272The 273.Fa addr 274and 275.Fa data 276arguments are ignored. 277Unlike 278.Dv PT_CONTINUE 279call with 280.Dv SIGSTOP , 281.Dv PT_STOP 282works both on running and stopped processes. 283.It Dv PT_ATTACH 284This request allows a process to gain control of an otherwise unrelated 285process and begin tracing it. 286It does not need any cooperation from the to-be-traced process. 287In this case, 288.Fa pid 289specifies the process ID of the to-be-traced process, and the other two 290arguments are ignored. 291This request requires that the target process 292must have the same real UID as the tracing process, and that it must 293not be executing a setuid or setgid executable. 294(If the tracing process is running as root, 295these restrictions do not apply.) 296.Pp 297The tracing process will see the newly-traced process stop and may then 298control it as if it had been traced all along. 299It means that the 300.Dv SIGSTOP 301signal is emitted to tracer. 302It is different behavior to the one from 303.Dv PT_TRACE_ME . 304.Pp 305Three other restrictions apply to all tracing processes, even those 306running as root. 307First, no process may trace a system process. 308Second, no process may trace the process running 309.Xr init 8 . 310Third, if a process has its root directory set with 311.Xr chroot 2 , 312it may not trace another process unless that process' root directory 313is at or below the tracing process' root. 314.It Dv PT_DETACH 315This request is like PT_CONTINUE, except that after it 316succeeds, the traced process is no longer traced and continues 317execution normally. 318.It Dv PT_IO 319This request is a more general interface that can be used instead of 320.Dv PT_READ_D , 321.Dv PT_WRITE_D , 322.Dv PT_READ_I , 323and 324.Dv PT_WRITE_I . 325The I/O request is encoded in a 326.Vt struct ptrace_io_desc 327defined as: 328.Bd -literal -offset indent 329struct ptrace_io_desc { 330 int piod_op; 331 void *piod_offs; 332 void *piod_addr; 333 size_t piod_len; 334}; 335.Ed 336.Pp 337where 338.Fa piod_offs 339is the offset within the traced process where the I/O operation should 340take place, 341.Fa piod_addr 342is the buffer in the tracing process, and 343.Fa piod_len 344is the length of the I/O request. 345The 346.Fa piod_op 347field specifies which type of I/O operation to perform. 348Possible values are: 349.Pp 350.Bl -tag -width 18n -offset indent -compact 351.It Dv PIOD_READ_D 352.It Dv PIOD_WRITE_D 353.It Dv PIOD_READ_I 354.It Dv PIOD_WRITE_I 355.It Dv PIOD_READ_AUXV 356.El 357.Pp 358See the description of 359.Dv PT_READ_I 360for the difference between I and D spaces. 361.Pp 362The 363.Dv PIOD_READ_AUXV 364operation can be used to read from the ELF auxiliary vector. 365The 366.Fa piod_offs 367argument sets the offset within the tracee's vector. 368To read from the beginning of it, this value must be set to 0 and cast to 369.Dv (void *) . 370.Pp 371A pointer to the I/O descriptor is passed in the 372.Fa addr 373argument to 374.Fn ptrace . 375On return, the 376.Fa piod_len 377field in the I/O descriptor will be updated with the actual number of 378bytes transferred. 379If the requested I/O could not be successfully performed, 380.Fn ptrace 381will return \-1 and set 382.Va errno . 383.Pp 384This interface returns success for partial and cancelled byte transfers. 385For an interrupted transfer, a user shall check whether occurred at least 386a single of the following two conditions: 387.Dv piod_len == 0 388and set 389.Va errno . 390Successful but incomplete byte transfers shall be restarted in the place 391where they were stopped. 392.It Dv PT_DUMPCORE 393Makes the process specified in the 394.Fa pid 395pid generate a core dump. 396The 397.Fa addr 398argument should contain the name of the core file to be generated 399and the 400.Fa data 401argument should contain the length of the core filename. 402.It Dv PT_LWPSTATUS 403Returns information about a thread from the list of threads for the 404process specified in the 405.Fa pid 406argument. 407The 408.Fa addr 409argument should contain a 410.Vt struct ptrace_lwpstatus 411defined as: 412.Bd -literal -offset indent 413struct ptrace_lwpstatus { 414 lwpid_t pl_lwpid; 415 sigset_t pl_sigpend; 416 sigset_t pl_sigmask; 417 char pl_name[20]; 418 void *pl_private; 419}; 420.Ed 421.Pp 422where 423.Fa pl_lwpid 424contains a thread LWP ID. 425Information is returned for the thread specified in 426.Fa pl_lwpid . 427.Fa pl_sigpend 428contains the signals pending on that LWP. 429.Fa pl_sigmask 430contains the signals masked on that LWP. 431.Fa pl_name 432contains printable name of the LWP. 433The string is always NUL terminated. 434.Fa pl_private 435contains the pointer to TLS base. 436.Pp 437The 438.Fa data 439argument should contain 440.Dq Li sizeof(struct ptrace_lwpinfo) . 441.It Dv PT_LWPNEXT 442Is the same as 443.Dv PT_LWPSTATUS , 444except that information is returned for the thread following the one with the 445specified ID in the process thread list, or for the first thread 446if 447.Fa pl_lwpid 448is 0. 449.Pp 450Upon return 451.Fa pl_lwpid 452contains the LWP ID of the thread that was found, or 0 if there is 453no thread after the one whose LWP ID was supplied in the call. 454.It Dv PT_SYSCALL 455Stops a process before and after executing each system call. 456Otherwise this operation is the same as 457.Dv PT_CONTINUE . 458.It Dv PT_SYSCALLEMU 459Intercept and ignore a system call before it has been executed, for use with 460.Dv PT_SYSCALL . 461This operation shall be called for syscall entry trap from 462.Dv PT_SYSCALL . 463To resume execution after intercepting the system call, 464another 465.Dv PT_SYSCALL 466shall be used. 467.It Dv PT_SET_EVENT_MASK 468This request can be used to specify which events in the traced process 469should be reported to the tracing process. 470These events are specified in a 471.Vt struct ptrace_event 472defined as: 473.Bd -literal -offset indent 474typedef struct ptrace_event { 475 int pe_set_event; 476} ptrace_event_t; 477.Ed 478.Pp 479.Fa pe_set_event 480is the set of events to be reported. 481This set is formed by OR'ing together the following values: 482.Bl -tag -width 18n 483.It PTRACE_FORK 484Report 485.Xr fork 2 . 486.It PTRACE_VFORK 487Report 488.Xr vfork 2 . 489.It PTRACE_VFORK_DONE 490Report parent resumed after 491.Xr vfork 2 . 492.It PTRACE_LWP_CREATE 493Report thread birth. 494.It PTRACE_LWP_EXIT 495Report thread termination. 496.It PTRACE_POSIX_SPAWN 497Report 498.Xr posix_spawn 3 . 499.El 500.Pp 501The 502.Xr fork 2 503and 504.Xr vfork 2 505events can occur with 506.Xr clone 2 . 507The 508.Dv PTRACE_FORK 509value means that process gives birth to its child 510without pending on its termination or 511.Xr execve 2 512operation. 513If enabled, 514the child is also traced by the debugger and 515.Dv SIGTRAP 516is generated twice, 517first for the parent and second for the child. 518The 519.Dv PTRACE_VFORK 520event is the same as 521.Dv PTRACE_FORK , 522but the parent blocks after giving birth to the child. 523The 524.Dv PTRACE_VFORK_DONE 525event can be used to report unblocking of the parent. 526.Pp 527.Fn posix_spawn 528on 529.Nx 530directly creates the child process without intermediate fork. 531The 532.Dv PTRACE_POSIX_SPAWN 533event semantics are the same as 534.Dv PTRACE_FORK , 535but the child is reported with implied execution of a file. 536.Pp 537A pointer to this structure is passed in 538.Fa addr . 539The 540.Fa data 541argument should be set to 542.Li sizeof(struct ptrace_event) . 543.It Dv PT_GET_EVENT_MASK 544This request can be used to determine which events in the traced 545process will be reported. 546The information is read into the 547.Vt struct ptrace_event 548pointed to by 549.Fa addr . 550The 551.Fa data 552argument should be set to 553.Li sizeof(struct ptrace_event) . 554.It Dv PT_GET_PROCESS_STATE 555This request reads the state information associated with the event 556that stopped the traced process. 557The information is reported in a 558.Vt struct ptrace_state 559that is equivalent to: 560.Bd -literal -offset indent 561typedef struct ptrace_state { 562 int pe_report_event; 563 union { 564 pid_t pe_other_pid; 565 lwpid_t pe_lwp; 566 }; 567} ptrace_state_t; 568.Ed 569.Pp 570A pointer to this structure is passed in 571.Fa addr . 572The 573.Fa data 574argument should be set to 575.Li sizeof(struct ptrace_state) . 576.It Dv PT_SET_SIGINFO 577This request can be used to specify signal information emitted to tracee. 578This signal information is specified in 579.Vt struct ptrace_siginfo 580defined as: 581.Bd -literal -offset indentq 582typedef struct ptrace_siginfo { 583 siginfo_t psi_siginfo; 584 lwpid_t psi_lwpid; 585} ptrace_siginfo_t; 586.Ed 587.Pp 588Where 589.Fa psi_siginfo 590is the set to signal information structure. 591The 592.Fa psi_lwpid 593field describes LWP address of the signal. 594Value 595.Dv 0 596means the whole process 597(route signal to all LWPs). 598.Pp 599A pointer to this structure is passed in 600.Fa addr . 601The 602.Fa data 603argument should be set to 604.Li sizeof(struct ptrace_siginfo) . 605.Pp 606In order to pass faked signal to the tracee, 607the signal type must match the signal passed to the process with 608.Dv PT_CONTINUE 609or 610.Dv PT_SYSCALL . 611.It Dv PT_GET_SIGINFO 612This request can be used to determine signal information that was received by 613a debugger 614.Po 615see 616.Xr siginfo 2 617.Pc . 618The information is read into the 619.Vt struct ptrace_siginfo 620pointed to by 621.Fa addr . 622The 623.Fa data 624argument should be set to 625.Li sizeof(struct ptrace_siginfo) . 626.It Dv PT_SET_SIGPASS 627This request can be used to specify mask of signals that should be passed 628directly to the debuggee, without reporting to the tracer. 629A pointer to sigset_t is passed in 630.Fa addr . 631The 632.Fa data 633argument should be set to 634.Li sizeof(sigset_t) . 635.Pp 636It is not permitted to mask 637.Dv SIGSTOP 638and 639.Dv SIGKILL . 640All debugger related signals 641.Dv ( SIGTRAP , SIGILL , SIGSEGV , SIGBUS , SIGFPE ) 642are reported to the tracer without interruption, 643unless they were emitted by a non-crash source. 644.It Dv PT_GET_SIGPASS 645This request can be used to determine mask of signals passed directly to the debuggee. 646A pointer to sigset_t is passed in 647.Fa addr . 648The 649.Fa data 650argument should be set to 651.Li sizeof(sigset_t) . 652.Pp 653Upon debugger attach the sigpass mask shall be empty. 654.It Dv PT_RESUME 655Allow execution of a specified thread, 656change its state from suspended to continued. 657The 658.Fa addr 659argument is unused. 660The 661.Fa data 662argument specifies the LWP ID. 663.Pp 664This call is equivalent to 665.Xr _lwp_continue 2 666called by a traced process. 667This call does not change the general process state from stopped to continued. 668.It Dv PT_SUSPEND 669Prevent execution of a specified thread, 670change its state from continued to suspended. 671The 672.Fa addr 673argument is unused. 674The 675.Fa data 676argument specifies the requested LWP ID. 677.Pp 678This call is equivalent to 679.Xr _lwp_suspend 2 680called by a traced process. 681This call does not change the general process state from continued to stopped. 682.El 683.Pp 684Additionally, the following requests exist but are 685not available on all machine architectures. 686The file 687.In machine/ptrace.h 688lists which requests exist on a given machine. 689.Bl -tag -width 12n 690.It Dv PT_STEP 691Execution continues as in request PT_CONTINUE; however 692as soon as possible after execution of at least one 693instruction, execution stops again. 694If the 695.Fa data 696argument is greater than 0, it contains the LWP ID of the thread to be 697stepped, and any other threads are continued. 698If the 699.Fa data 700argument is less than zero, it contains the negative of the LWP ID of 701the thread to be stepped, and only that thread executes. 702.It Dv PT_SETSTEP 703This request will turn on single stepping of the specified thread. 704.Fa addr 705is unused. 706.Fa data 707specifies the LWP ID of the thread to be stepped. 708The execution does not continue until 709.Dv PT_CONTINUE 710is issued. 711This request permits combining single-stepping with sending signals and 712.Dv PT_SYSCALL . 713.It Dv PT_CLEARSTEP 714This request will turn off single stepping of the specified thread. 715.Fa addr 716is unused. 717.Fa data 718specifies the LWP ID of the thread to disable single-stepping. 719.It Dv PT_GETREGS 720This request reads the traced process' machine registers into the 721.Vt struct reg 722(defined in 723.In machine/reg.h ) 724pointed to by 725.Fa addr . 726The 727.Fa data 728argument contains the LWP ID of the thread whose registers are to 729be read. 730If zero is supplied, the first thread of the process is read. 731.It Dv PT_SETREGS 732This request is the converse of 733.Dv PT_GETREGS ; 734it loads the traced process' machine registers from the 735.Vt struct reg 736(defined in 737.In machine/reg.h ) 738pointed to by 739.Fa addr . 740The 741.Fa data 742argument contains the LWP ID of the thread whose registers are to 743be written. 744If zero is supplied, the first thread of the process is written. 745.It Dv PT_GETFPREGS 746This request reads the traced process' floating-point registers into 747the 748.Vt struct fpreg 749(defined in 750.In machine/reg.h ) 751pointed to by 752.Fa addr . 753The 754.Fa data 755argument contains the LWP ID of the thread whose registers are to 756be read. 757If zero is supplied, the first thread of the process is read. 758.It Dv PT_SETFPREGS 759This request is the converse of 760.Dv PT_GETFPREGS ; 761it loads the traced process' floating-point registers from the 762.Vt struct fpreg 763(defined in 764.In machine/reg.h ) 765pointed to by 766.Fa addr . 767The 768.Fa data 769argument contains the LWP ID of the thread whose registers are to 770be written. 771If zero is supplied, the first thread of the process is written. 772.It Dv PT_GETDBREGS 773This request reads the traced process' debug registers into 774the 775.Vt struct dbreg 776(defined in 777.In machine/reg.h ) 778pointed to by 779.Fa addr . 780The 781.Fa data 782argument contains the LWP ID of the thread whose registers are to 783be read. 784If zero is supplied, the first thread of the process is read. 785.It Dv PT_SETDBREGS 786This request is the converse of 787.Dv PT_GETDBREGS ; 788it loads the traced process' debug registers from the 789.Vt struct dbreg 790(defined in 791.In machine/reg.h ) 792pointed to by 793.Fa addr . 794The 795.Fa data 796argument contains the LWP ID of the thread whose registers are to 797be written. 798If zero is supplied, the first thread of the process is written. 799.It Dv PT_GETXMMREGS 800This request reads the traced process' XMM registers into 801the 802.Vt struct xmmregs 803(defined in 804.In machine/reg.h ) 805pointed to by 806.Fa addr . 807The 808.Fa data 809argument contains the LWP ID of the thread whose registers are to 810be read. 811If zero is supplied, the first thread of the process is read. 812.It Dv PT_SETXMMREGS 813This request is the converse of 814.Dv PT_GETXMMREGS ; 815it loads the traced process' XMM registers from the 816.Vt struct xmmregs 817(defined in 818.In machine/reg.h ) 819pointed to by 820.Fa addr . 821The 822.Fa data 823argument contains the LWP ID of the thread whose registers are to 824be written. 825If zero is supplied, the first thread of the process is written. 826.It Dv PT_GETVECREGS 827This request reads the traced process' vector registers into 828the 829.Vt struct vreg 830(defined in 831.In machine/reg.h ) 832pointed to by 833.Fa addr . 834The 835.Fa data 836argument contains the LWP ID of the thread whose registers are to 837be read. 838If zero is supplied, the first thread of the process is read. 839.It Dv PT_SETVECREGS 840This request is the converse of 841.Dv PT_GETVECREGS ; 842it loads the traced process' vector registers from the 843.Vt struct vreg 844(defined in 845.In machine/reg.h ) 846pointed to by 847.Fa addr . 848The 849.Fa data 850argument contains the LWP ID of the thread whose registers are to 851be written. 852If zero is supplied, the first thread of the process is written. 853.It Dv PT_GETXSTATE 854This request reads the traced process' FPU extended state into 855the 856.Vt struct xstate 857(defined in 858.In machine/cpu_extended_state.h ) . 859.Fa addr 860should be a pointer to 861.Vt struct iovec 862(defined in 863.In sys/uio.h ) 864specifying the pointer to the aforementioned struct as 865.Fa iov_base 866and its size as 867.Fa iov_len . 868The 869.Fa data 870argument contains the LWP ID of the thread whose registers are to 871be read. 872If zero is supplied, the first thread of the process is read. 873The struct will be filled up to the specified 874.Fa iov_len . 875The caller needs to check the 876.Fa xs_rfbm 877bitmap in order to determine which fields were provided by the CPU, 878and may check 879.Fa xs_xstate_bv 880to determine which component states were changed from the initial state. 881.It Dv PT_SETXSTATE 882This request is the converse of 883.Dv PT_GETXSTATE ; 884it loads the traced process' extended FPU state from the 885.Vt struct xstate 886(defined in 887.In machine/cpu_extended_state.h ) . 888.Fa addr 889should be a pointer to 890.Vt struct iovec 891(defined in 892.In sys/uio.h ) 893specifying the pointer to the aforementioned struct as 894.Fa iov_base 895and its size as 896.Fa iov_len . 897The 898.Fa data 899argument contains the LWP ID of the thread whose registers are to 900be written. 901If zero is supplied, the first thread of the process is written. 902The 903.Fa xs_rfbm 904field of the supplied xstate specifies which state components are to 905be updated. 906Other components (fields) will be ignored. 907The 908.Fa xs_xstate_bv 909field specifies whether component state should be set to provided 910values (when 1) or reset to uninitialized (when 0). 911The request will fail if 912.Fa xs_xstate_bv 913is not a subset of 914.Fa xs_rfbm , 915or any of the specified components is not supported by the CPU or kernel 916(i.e., not returned by 917.Dv PT_GETXSTATE ) . 918.El 919.Sh ERRORS 920Some requests can cause 921.Fn ptrace 922to return \-1 as a non-error value; to disambiguate, 923.Va errno 924can be set to 0 before the call and checked afterwards. 925The possible errors are: 926.Bl -tag -width "[EINVAL]" 927.It Bq Er EAGAIN 928Process is currently exec'ing and cannot be traced. 929.It Bq Er EBUSY 930.Bl -bullet -compact 931.It 932.Dv PT_ATTACH 933was attempted on a process that was already being traced. 934.It 935A request attempted to manipulate a process that was being traced by 936some process other than the one making the request. 937.It 938A request (other than 939.Dv PT_ATTACH ) 940specified a process that wasn't stopped. 941.El 942.It Bq Er EDEADLK 943An attempt to unstop a process with locked threads. 944.It Bq Er EINVAL 945.Bl -bullet -compact 946.It 947A process attempted to use 948.Dv PT_ATTACH 949on itself. 950.It 951The 952.Fa request 953was not a legal request on this machine architecture. 954.It 955The signal number (in 956.Fa data ) 957to 958.Dv PT_CONTINUE 959was neither 0 nor a legal signal number. 960.It 961.Dv PT_GETREGS , 962.Dv PT_SETREGS , 963.Dv PT_GETFPREGS , 964.Dv PT_SETFPREGS , 965.Dv PT_GETXSTATE , 966or 967.Dv PT_SETXSTATE 968was attempted on a process with no valid register set. 969(This is normally true only of system processes.) 970.It 971A process attempted to set Program Counter to 0 in 972.Dv PT_CONTINUE , 973.Dv PT_SYSCALL 974or 975.Dv PT_DETACH 976with 977.Dv vm.user_va0_disable 978set to 1. 979.It 980.Dv PT_SETXSTATE 981attempted to set state components not supported by the kernel, 982or 983.Dv xs_xstate_bv 984was not a subset of 985.Dv xs_rfbm . 986.El 987.It Bq Er EPERM 988.Bl -bullet -compact 989.It 990A request (other than 991.Dv PT_ATTACH ) 992attempted to manipulate a process that wasn't being traced at all. 993.It 994An attempt was made to use 995.Dv PT_ATTACH 996on a process in violation of the requirements listed under 997.Dv PT_ATTACH 998above. 999.El 1000.It Bq Er ESRCH 1001No process having the specified process ID exists. 1002.El 1003.Sh SEE ALSO 1004.Xr sigaction 2 , 1005.Xr signal 7 1006.Sh HISTORY 1007The 1008.Fn ptrace 1009function appeared in 1010.At v7 . 1011.Sh BUGS 1012On the SPARC, the PC is set to the provided PC value for 1013.Dv PT_CONTINUE 1014and similar calls, 1015but the NPC is set willy-nilly to 4 greater than the PC value. 1016Using 1017.Dv PT_GETREGS 1018and 1019.Dv PT_SETREGS 1020to modify the PC, passing 1021.Li (void *)1 1022to 1023.Eo \& 1024.Fn ptrace 1025.Ec , 1026should be able to sidestep this. 1027