1.\" $NetBSD: ptrace.2,v 1.35 2011/08/31 23:04:33 jmcneill Exp $ 2.\" 3.\" This file is in the public domain. 4.Dd August 31, 2011 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, examine the state of the stopped process, and cause it to 37terminate or continue as appropriate. 38.Fn ptrace 39is the mechanism by which all this happens. 40.Pp 41The 42.Fa request 43argument specifies what operation is being performed; the meaning of 44the rest of the arguments depends on the operation, but except for one 45special case noted below, all 46.Fn ptrace 47calls are made by the tracing process, and the 48.Fa pid 49argument specifies the process ID of the traced process. 50.Fa request 51can be: 52.Bl -tag -width 12n 53.It Dv PT_TRACE_ME 54This request is the only one used by the traced process; it declares 55that the process expects to be traced by its parent. 56All the other arguments are ignored. 57(If the parent process does not expect to trace 58the child, it will probably be rather confused by the results; once the 59traced process stops, it cannot be made to continue except via 60.Fn ptrace . ) 61When a process has used this request and calls 62.Xr execve 2 63or any of the routines built on it 64.Po 65such as 66.Xr execv 3 67.Pc , 68it will stop before executing the first instruction of the new image. 69Also, any setuid or setgid bits on the executable being executed will 70be ignored. 71.It Dv PT_READ_I , Dv PT_READ_D 72These requests read a single 73.Li int 74of data from the traced process' address space. 75Traditionally, 76.Fn ptrace 77has allowed for machines with distinct address spaces for instruction 78and data, which is why there are two requests: conceptually, 79.Dv PT_READ_I 80reads from the instruction space and 81.Dv PT_READ_D 82reads from the data space. 83In the current 84.Nx 85implementation, these 86two requests are completely identical. 87The 88.Fa addr 89argument specifies the address (in the traced process' virtual address 90space) at which the read is to be done. 91This address does not have to meet any alignment constraints. 92The value read is returned as the return value from 93.Eo \& 94.Fn ptrace 95.Ec . 96.It Dv PT_WRITE_I , Dv PT_WRITE_D 97These requests parallel 98.Dv PT_READ_I 99and 100.Dv PT_READ_D , 101except that they write rather than read. 102The 103.Fa data 104argument supplies the value to be written. 105.\" .It Dv PT_READ_U 106.\" This request reads an 107.\" .Li int 108.\" from the traced process' user structure. 109.\" The 110.\" .Fa addr 111.\" argument specifies the location of the int relative to the base of the 112.\" user structure; it will usually be an integer value cast to 113.\" .Li caddr_t 114.\" either explicitly or via the presence of a prototype for 115.\" .Eo \& 116.\" .Fn ptrace 117.\" .Ec . 118.\" Unlike 119.\" .Dv PT_READ_I 120.\" and 121.\" .Dv PT_READ_D , 122.\" .Fa addr 123.\" must be aligned on an 124.\" .Li int 125.\" boundary. 126.\" The value read is returned as the return value from 127.\" .Eo \& 128.\" .Fn ptrace 129.\" .Ec . 130.\" .It Dv PT_WRITE_U 131.\" This request writes an 132.\" .Li int 133.\" into the traced process' user structure. 134.\" .Fa addr 135.\" specifies the offset, just as for 136.\" .Dv PT_READ_U , 137.\" and 138.\" .Fa data 139.\" specifies the value to be written, just as for 140.\" .Dv PT_WRITE_I 141.\" and 142.\" .Dv PT_WRITE_D . 143.It Dv PT_CONTINUE 144The traced process continues execution. 145.Fa addr 146is an address specifying the place where execution is to be resumed (a 147new value for the program counter), or 148.Li (caddr_t)1 149to indicate that execution is to pick up where it left off. 150.Fa data 151provides a signal number to be delivered to the traced process as it 152resumes execution, or 0 if no signal is to be sent. 153If a negative value is supplied, that is the negative of the LWP 154ID of the thread to be resumed, and only that thread executes. 155.It Dv PT_KILL 156The traced process terminates, as if 157.Dv PT_CONTINUE 158had been used with 159.Dv SIGKILL 160given as the signal to be delivered. 161.It Dv PT_ATTACH 162This request allows a process to gain control of an otherwise unrelated 163process and begin tracing it. 164It does not need any cooperation from the to-be-traced process. 165In this case, 166.Fa pid 167specifies the process ID of the to-be-traced process, and the other two 168arguments are ignored. 169This request requires that the target process 170must have the same real UID as the tracing process, and that it must 171not be executing a setuid or setgid executable. 172(If the tracing process is running as root, 173these restrictions do not apply.) 174The tracing process will see the newly-traced process stop and may then 175control it as if it had been traced all along. 176.Pp 177Three other restrictions apply to all tracing processes, even those 178running as root. 179First, no process may trace a system process. 180Second, no process may trace the process running 181.Xr init 8 . 182Third, if a process has its root directory set with 183.Xr chroot 2 , 184it may not trace another process unless that process's root directory 185is at or below the tracing process's root. 186.It Dv PT_DETACH 187This request is like PT_CONTINUE, except that after it 188succeeds, the traced process is no longer traced and continues 189execution normally. 190.It Dv PT_IO 191This request is a more general interface that can be used instead of 192.Dv PT_READ_D , 193.Dv PT_WRITE_D , 194.Dv PT_READ_I , 195and 196.Dv PT_WRITE_I . 197The I/O request is encoded in a 198.Dq Li "struct ptrace_io_desc" 199defined as: 200.Bd -literal -offset indent 201struct ptrace_io_desc { 202 int piod_op; 203 void *piod_offs; 204 void *piod_addr; 205 size_t piod_len; 206}; 207.Ed 208.Pp 209where 210.Fa piod_offs 211is the offset within the traced process where the I/O operation should 212take place, 213.Fa piod_addr 214is the buffer in the tracing process, and 215.Fa piod_len 216is the length of the I/O request. 217The 218.Fa piod_op 219field specifies which type of I/O operation to perform. 220Possible values are: 221.Pp 222.Bl -tag -width 18n -offset indent -compact 223.It Dv PIOD_READ_D 224.It Dv PIOD_WRITE_D 225.It Dv PIOD_READ_I 226.It Dv PIOD_WRITE_I 227.El 228.Pp 229See the description of 230.Dv PT_READ_I 231for the difference between I and D spaces. 232A pointer to the I/O descriptor is passed in the 233.Fa addr 234argument to 235.Fn ptrace . 236On return, the 237.Fa piod_len 238field in the I/O descriptor will be updated with the actual number of 239bytes transferred. 240If the requested I/O could not be successfully performed, 241.Fn ptrace 242will return 243.Li \-1 244and set 245.Va errno . 246.It Dv PT_DUMPCORE 247Makes the process specified in the 248.Fa pid 249pid generate a core dump. 250The 251.Fa addr 252argument should contain the name of the core file to be generated 253and the 254.Fa data 255argument should contain the length of the core filename. 256This 257.Nm 258call currently does not stop the child process so it can generate 259inconsistent data. 260.It Dv PT_LWPINFO 261Returns information about a thread from the list of threads for the 262process specified in the 263.Fa pid 264argument. 265The 266.Fa addr 267argument should contain a 268.Dq Li "struct ptrace_lwpinfo" 269defined as: 270.Bd -literal -offset indent 271struct ptrace_lwpinfo { 272 lwpid_t pl_lwpid; 273 int pl_event; 274}; 275.Ed 276.Pp 277where 278.Fa pl_lwpid 279contains a thread LWP ID. 280Information is returned for the thread following the one with the 281specified ID in the process thread list, or for the first thread 282if 283.Fa pl_lwpid 284is 0. 285Upon return 286.Fa pl_lwpid 287contains the LWP ID of the thread that was found, or 0 if there is 288no thread after the one whose LWP ID was supplied in the call. 289.Fa pl_event 290contains the event that stopped the thread. 291Possible values are: 292.Pp 293.Bl -tag -width 30n -offset indent -compact 294.It Dv PL_EVENT_NONE 295.It Dv PL_EVENT_SIGNAL 296.El 297.Pp 298The 299.Fa data 300argument should contain 301.Dq Li "sizeof(struct ptrace_lwpinfo)" . 302.It Dv PT_SYSCALL 303Stops a process before and after executing each system call. 304.It Dv PT_SYSCALLEMU 305Intercept and ignore a system call before it has been executed, for use with 306.Dv PT_SYSCALL . 307.El 308.Pp 309Additionally, the following requests exist but are 310not available on all machine architectures. 311The file 312.In machine/ptrace.h 313lists which requests exist on a given machine. 314.Bl -tag -width 12n 315.It Dv PT_STEP 316Execution continues as in request PT_CONTINUE; however 317as soon as possible after execution of at least one 318instruction, execution stops again. 319If the 320.Fa data 321argument is greater than 0, it contains the LWP ID of the thread to be 322stepped, and any other threads are continued. 323If the 324.Fa data 325argument is less than zero, it contains the negative of the LWP ID of 326the thread to be stepped, and only that thread executes. 327.It Dv PT_GETREGS 328This request reads the traced process' machine registers into the 329.Dq Li "struct reg" 330(defined in 331.In machine/reg.h ) 332pointed to by 333.Fa addr . 334The 335.Fa data 336argument contains the LWP ID of the thread whose registers are to 337be read. 338If zero is supplied, the first thread of the process is read. 339.It Dv PT_SETREGS 340This request is the converse of 341.Dv PT_GETREGS ; 342it loads the traced process' machine registers from the 343.Dq Li "struct reg" 344(defined in 345.In machine/reg.h ) 346pointed to by 347.Fa addr . 348The 349.Fa data 350argument contains the LWP ID of the thread whose registers are to 351be written. 352If zero is supplied, the first thread of the process is written. 353.It Dv PT_GETFPREGS 354This request reads the traced process' floating-point registers into 355the 356.Dq Li "struct fpreg" 357(defined in 358.In machine/reg.h ) 359pointed to by 360.Fa addr . 361The 362.Fa data 363argument contains the LWP ID of the thread whose registers are to 364be read. 365If zero is supplied, the first thread of the process is read. 366.It Dv PT_SETFPREGS 367This request is the converse of 368.Dv PT_GETFPREGS ; 369it loads the traced process' floating-point registers from the 370.Dq Li "struct fpreg" 371(defined in 372.In machine/reg.h ) 373pointed to by 374.Fa addr . 375The 376.Fa data 377argument contains the LWP ID of the thread whose registers are to 378be written. 379If zero is supplied, the first thread of the process is written. 380.\" .It Dv PT_SYSCALL 381.\" This request is like 382.\" .Dv PT_CONTINUE 383.\" except that the process will stop next time it executes any system 384.\" call. 385.\" Information about the system call can be examined with 386.\" .Dv PT_READ_U 387.\" and potentially modified with 388.\" .Dv PT_WRITE_U 389.\" through the 390.\" .Li u_kproc.kp_proc.p_md 391.\" element of the user structure (see below). 392.\" If the process is continued 393.\" with another 394.\" .Dv PT_SYSCALL 395.\" request, it will stop again on exit from the syscall, at which point 396.\" the return values can be examined and potentially changed. 397.\" The 398.\" .Li u_kproc.kp_proc.p_md 399.\" element is of type 400.\" .Dq Li "struct mdproc" , 401.\" which should be declared by including 402.\" .In sys/param.h , 403.\" .In sys/user.h , 404.\" and 405.\" .In machine/proc.h , 406.\" and contains the following fields (among others): 407.\" .Bl -item -compact -offset indent 408.\" .It 409.\" .Li syscall_num 410.\" .It 411.\" .Li syscall_nargs 412.\" .It 413.\" .Li syscall_args[8] 414.\" .It 415.\" .Li syscall_err 416.\" .It 417.\" .Li syscall_rv[2] 418.\" .El 419.\" When a process stops on entry to a syscall, 420.\" .Li syscall_num 421.\" holds the number of the syscall, 422.\" .Li syscall_nargs 423.\" holds the number of arguments it expects, and 424.\" .Li syscall_args 425.\" holds the arguments themselves. 426.\" (Only the first 427.\" .Li syscall_nargs 428.\" elements of 429.\" .Li syscall_args 430.\" are guaranteed to be useful.) 431.\" When a process stops on exit from a syscall, 432.\" .Li syscall_num 433.\" is 434.\" .Eo \& 435.\" .Li \-1 436.\" .Ec , 437.\" .Li syscall_err 438.\" holds the error number 439.\" .Po 440.\" see 441.\" .Xr errno 2 442.\" .Pc , 443.\" or 0 if no error occurred, and 444.\" .Li syscall_rv 445.\" holds the return values. 446.\" (If the syscall returns only one value, only 447.\" .Li syscall_rv[0] 448.\" is useful.) 449.\" The tracing process can modify any of these with 450.\" .Dv PT_WRITE_U ; 451.\" only some modifications are useful. 452.\" .Pp 453.\" On entry to a syscall, 454.\" .Li syscall_num 455.\" can be changed, and the syscall actually performed will correspond to 456.\" the new number (it is the responsibility of the tracing process to fill 457.\" in 458.\" .Li syscall_args 459.\" appropriately for the new call, but there is no need to modify 460.\" .Eo \& 461.\" .Li syscall_nargs 462.\" .Ec ). 463.\" If the new syscall number is 0, no syscall is actually performed; 464.\" instead, 465.\" .Li syscall_err 466.\" and 467.\" .Li syscall_rv 468.\" are passed back to the traced process directly (and therefore should be 469.\" filled in). 470.\" If the syscall number is otherwise out of range, a dummy 471.\" syscall which simply produces an 472.\" .Er ENOSYS 473.\" error is effectively performed. 474.\" .Pp 475.\" On exit from a syscall, only 476.\" .Li syscall_err 477.\" and 478.\" .Li syscall_rv 479.\" can usefully be changed; they are set to the values returned by the 480.\" syscall and will be passed back to the traced process by the normal 481.\" syscall return mechanism. 482.It Dv PT_DUMPCORE 483Cause the traced process to dump core. 484If the 485.Fa addr 486argument is not 487.Dv NULL 488it is taken to be the pathname of the core file to be generated and the 489.Fa data 490argument should contain the length of the pathname. 491The pathname may contain 492.Dv % 493patterns that are expanded as described in 494.Xr sysctl 8 . 495If the 496.Fa data 497argument is 498.Dv NULL , 499the default core file path generation rules are followed. 500.El 501.Sh ERRORS 502Some requests can cause 503.Fn ptrace 504to return 505.Li \-1 506as a non-error value; to disambiguate, 507.Va errno 508can be set to 0 before the call and checked afterwards. 509The possible errors are: 510.Bl -tag -width "[EINVAL]" 511.It Bq Er EAGAIN 512Process is currently exec'ing and cannot be traced. 513.It Bq Er EBUSY 514.Bl -bullet -compact 515.It 516.Dv PT_ATTACH 517was attempted on a process that was already being traced. 518.It 519A request attempted to manipulate a process that was being traced by 520some process other than the one making the request. 521.It 522A request (other than 523.Dv PT_ATTACH ) 524specified a process that wasn't stopped. 525.El 526.It Bq Er EINVAL 527.Bl -bullet -compact 528.It 529A process attempted to use 530.Dv PT_ATTACH 531on itself. 532.It 533The 534.Fa request 535was not a legal request on this machine architecture. 536.\" .It 537.\" The 538.\" .Fa addr 539.\" to 540.\" .Dv PT_READ_U 541.\" or 542.\" .Dv PT_WRITE_U 543.\" was not 544.\" .Li int Ns \&-aligned. 545.It 546The signal number (in 547.Fa data ) 548to 549.Dv PT_CONTINUE 550.\" or 551.\" .Dv PT_SYSCALL 552was neither 0 nor a legal signal number. 553.It 554.Dv PT_GETREGS , 555.Dv PT_SETREGS , 556.Dv PT_GETFPREGS , 557or 558.Dv PT_SETFPREGS 559was attempted on a process with no valid register set. 560(This is normally true only of system processes.) 561.El 562.It Bq Er EPERM 563.Bl -bullet -compact 564.It 565A request (other than 566.Dv PT_ATTACH ) 567attempted to manipulate a process that wasn't being traced at all. 568.It 569An attempt was made to use 570.Dv PT_ATTACH 571on a process in violation of the requirements listed under 572.Dv PT_ATTACH 573above. 574.El 575.It Bq Er ESRCH 576No process having the specified process ID exists. 577.El 578.Sh SEE ALSO 579.Xr sigaction 2 , 580.Xr signal 7 581.Sh BUGS 582On the SPARC, the PC is set to the provided PC value for 583.Dv PT_CONTINUE 584and similar calls, 585but the NPC is set willy-nilly to 4 greater than the PC value. 586Using 587.Dv PT_GETREGS 588and 589.Dv PT_SETREGS 590to modify the PC, passing 591.Li (caddr_t)1 592to 593.Eo \& 594.Fn ptrace 595.Ec , 596should be able to sidestep this. 597.\" .Pp 598.\" When using 599.\" .Dv PT_SYSCALL , 600.\" there is no easy way to tell whether the traced process stopped because 601.\" it made a syscall or because a signal was sent at a moment that it just 602.\" happened to have valid-looking garbage in its 603.\" .Dq Li "struct mdproc" . 604