1.\" $NetBSD: ptrace.2,v 1.34 2010/04/14 08:57:21 jruoho Exp $ 2.\" 3.\" This file is in the public domain. 4.Dd April 14, 2010 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.El 305.Pp 306Additionally, the following requests exist but are 307not available on all machine architectures. 308The file 309.In machine/ptrace.h 310lists which requests exist on a given machine. 311.Bl -tag -width 12n 312.It Dv PT_STEP 313Execution continues as in request PT_CONTINUE; however 314as soon as possible after execution of at least one 315instruction, execution stops again. 316If the 317.Fa data 318argument is greater than 0, it contains the LWP ID of the thread to be 319stepped, and any other threads are continued. 320If the 321.Fa data 322argument is less than zero, it contains the negative of the LWP ID of 323the thread to be stepped, and only that thread executes. 324.It Dv PT_GETREGS 325This request reads the traced process' machine registers into the 326.Dq Li "struct reg" 327(defined in 328.In machine/reg.h ) 329pointed to by 330.Fa addr . 331The 332.Fa data 333argument contains the LWP ID of the thread whose registers are to 334be read. 335If zero is supplied, the first thread of the process is read. 336.It Dv PT_SETREGS 337This request is the converse of 338.Dv PT_GETREGS ; 339it loads the traced process' machine registers from the 340.Dq Li "struct reg" 341(defined in 342.In machine/reg.h ) 343pointed to by 344.Fa addr . 345The 346.Fa data 347argument contains the LWP ID of the thread whose registers are to 348be written. 349If zero is supplied, the first thread of the process is written. 350.It Dv PT_GETFPREGS 351This request reads the traced process' floating-point registers into 352the 353.Dq Li "struct fpreg" 354(defined in 355.In machine/reg.h ) 356pointed to by 357.Fa addr . 358The 359.Fa data 360argument contains the LWP ID of the thread whose registers are to 361be read. 362If zero is supplied, the first thread of the process is read. 363.It Dv PT_SETFPREGS 364This request is the converse of 365.Dv PT_GETFPREGS ; 366it loads the traced process' floating-point registers from the 367.Dq Li "struct fpreg" 368(defined in 369.In machine/reg.h ) 370pointed to by 371.Fa addr . 372The 373.Fa data 374argument contains the LWP ID of the thread whose registers are to 375be written. 376If zero is supplied, the first thread of the process is written. 377.\" .It Dv PT_SYSCALL 378.\" This request is like 379.\" .Dv PT_CONTINUE 380.\" except that the process will stop next time it executes any system 381.\" call. 382.\" Information about the system call can be examined with 383.\" .Dv PT_READ_U 384.\" and potentially modified with 385.\" .Dv PT_WRITE_U 386.\" through the 387.\" .Li u_kproc.kp_proc.p_md 388.\" element of the user structure (see below). 389.\" If the process is continued 390.\" with another 391.\" .Dv PT_SYSCALL 392.\" request, it will stop again on exit from the syscall, at which point 393.\" the return values can be examined and potentially changed. 394.\" The 395.\" .Li u_kproc.kp_proc.p_md 396.\" element is of type 397.\" .Dq Li "struct mdproc" , 398.\" which should be declared by including 399.\" .In sys/param.h , 400.\" .In sys/user.h , 401.\" and 402.\" .In machine/proc.h , 403.\" and contains the following fields (among others): 404.\" .Bl -item -compact -offset indent 405.\" .It 406.\" .Li syscall_num 407.\" .It 408.\" .Li syscall_nargs 409.\" .It 410.\" .Li syscall_args[8] 411.\" .It 412.\" .Li syscall_err 413.\" .It 414.\" .Li syscall_rv[2] 415.\" .El 416.\" When a process stops on entry to a syscall, 417.\" .Li syscall_num 418.\" holds the number of the syscall, 419.\" .Li syscall_nargs 420.\" holds the number of arguments it expects, and 421.\" .Li syscall_args 422.\" holds the arguments themselves. 423.\" (Only the first 424.\" .Li syscall_nargs 425.\" elements of 426.\" .Li syscall_args 427.\" are guaranteed to be useful.) 428.\" When a process stops on exit from a syscall, 429.\" .Li syscall_num 430.\" is 431.\" .Eo \& 432.\" .Li \-1 433.\" .Ec , 434.\" .Li syscall_err 435.\" holds the error number 436.\" .Po 437.\" see 438.\" .Xr errno 2 439.\" .Pc , 440.\" or 0 if no error occurred, and 441.\" .Li syscall_rv 442.\" holds the return values. 443.\" (If the syscall returns only one value, only 444.\" .Li syscall_rv[0] 445.\" is useful.) 446.\" The tracing process can modify any of these with 447.\" .Dv PT_WRITE_U ; 448.\" only some modifications are useful. 449.\" .Pp 450.\" On entry to a syscall, 451.\" .Li syscall_num 452.\" can be changed, and the syscall actually performed will correspond to 453.\" the new number (it is the responsibility of the tracing process to fill 454.\" in 455.\" .Li syscall_args 456.\" appropriately for the new call, but there is no need to modify 457.\" .Eo \& 458.\" .Li syscall_nargs 459.\" .Ec ). 460.\" If the new syscall number is 0, no syscall is actually performed; 461.\" instead, 462.\" .Li syscall_err 463.\" and 464.\" .Li syscall_rv 465.\" are passed back to the traced process directly (and therefore should be 466.\" filled in). 467.\" If the syscall number is otherwise out of range, a dummy 468.\" syscall which simply produces an 469.\" .Er ENOSYS 470.\" error is effectively performed. 471.\" .Pp 472.\" On exit from a syscall, only 473.\" .Li syscall_err 474.\" and 475.\" .Li syscall_rv 476.\" can usefully be changed; they are set to the values returned by the 477.\" syscall and will be passed back to the traced process by the normal 478.\" syscall return mechanism. 479.It Dv PT_DUMPCORE 480Cause the traced process to dump core. 481If the 482.Fa addr 483argument is not 484.Dv NULL 485it is taken to be the pathname of the core file to be generated and the 486.Fa data 487argument should contain the length of the pathname. 488The pathname may contain 489.Dv % 490patterns that are expanded as described in 491.Xr sysctl 8 . 492If the 493.Fa data 494argument is 495.Dv NULL , 496the default core file path generation rules are followed. 497.El 498.Sh ERRORS 499Some requests can cause 500.Fn ptrace 501to return 502.Li \-1 503as a non-error value; to disambiguate, 504.Va errno 505can be set to 0 before the call and checked afterwards. 506The possible errors are: 507.Bl -tag -width "[EINVAL]" 508.It Bq Er EAGAIN 509Process is currently exec'ing and cannot be traced. 510.It Bq Er EBUSY 511.Bl -bullet -compact 512.It 513.Dv PT_ATTACH 514was attempted on a process that was already being traced. 515.It 516A request attempted to manipulate a process that was being traced by 517some process other than the one making the request. 518.It 519A request (other than 520.Dv PT_ATTACH ) 521specified a process that wasn't stopped. 522.El 523.It Bq Er EINVAL 524.Bl -bullet -compact 525.It 526A process attempted to use 527.Dv PT_ATTACH 528on itself. 529.It 530The 531.Fa request 532was not a legal request on this machine architecture. 533.\" .It 534.\" The 535.\" .Fa addr 536.\" to 537.\" .Dv PT_READ_U 538.\" or 539.\" .Dv PT_WRITE_U 540.\" was not 541.\" .Li int Ns \&-aligned. 542.It 543The signal number (in 544.Fa data ) 545to 546.Dv PT_CONTINUE 547.\" or 548.\" .Dv PT_SYSCALL 549was neither 0 nor a legal signal number. 550.It 551.Dv PT_GETREGS , 552.Dv PT_SETREGS , 553.Dv PT_GETFPREGS , 554or 555.Dv PT_SETFPREGS 556was attempted on a process with no valid register set. 557(This is normally true only of system processes.) 558.El 559.It Bq Er EPERM 560.Bl -bullet -compact 561.It 562A request (other than 563.Dv PT_ATTACH ) 564attempted to manipulate a process that wasn't being traced at all. 565.It 566An attempt was made to use 567.Dv PT_ATTACH 568on a process in violation of the requirements listed under 569.Dv PT_ATTACH 570above. 571.El 572.It Bq Er ESRCH 573No process having the specified process ID exists. 574.El 575.Sh SEE ALSO 576.Xr sigaction 2 , 577.Xr signal 7 578.Sh BUGS 579On the SPARC, the PC is set to the provided PC value for 580.Dv PT_CONTINUE 581and similar calls, 582but the NPC is set willy-nilly to 4 greater than the PC value. 583Using 584.Dv PT_GETREGS 585and 586.Dv PT_SETREGS 587to modify the PC, passing 588.Li (caddr_t)1 589to 590.Eo \& 591.Fn ptrace 592.Ec , 593should be able to sidestep this. 594.\" .Pp 595.\" When using 596.\" .Dv PT_SYSCALL , 597.\" there is no easy way to tell whether the traced process stopped because 598.\" it made a syscall or because a signal was sent at a moment that it just 599.\" happened to have valid-looking garbage in its 600.\" .Dq Li "struct mdproc" . 601