1.\" $NetBSD: ptrace.2,v 1.2 1995/02/27 12:35:37 cgd Exp $ 2.\" 3.\" This file is in the public domain. 4.Dd November 7, 1994 5.Dt PTRACE 2 6.Os NetBSD 1.0BETA 7.Sh NAME 8.Nm ptrace 9.Nd process tracing and debugging 10.Sh SYNOPSIS 11.Fd #include <sys/types.h> 12.Fd #include <sys/ptrace.h> 13.Ft int 14.Fn ptrace "int request" "pid_t pid" "caddr_t addr" "int data" 15.Sh DESCRIPTION 16.Fn ptrace 17provides tracing and debugging facilities. It allows one process (the 18.Em tracing 19process) to control another (the 20.Em traced 21process). Most of the time, the traced process runs normally, but when 22it receives a signal 23.Po 24see 25.Xr sigaction 2 26.Pc , 27it stops. The tracing process is expected to notice this via 28.Xr wait 2 29or the delivery of a 30.Dv SIGCHLD 31signal, examine the state of the stopped process, and cause it to 32terminate or continue as appropriate. 33.Fn ptrace 34is the mechanism by which all this happens. 35.Pp 36The 37.Fa request 38argument specifies what operation is being performed; the meaning of 39the rest of the arguments depends on the operation, but except for one 40special case noted below, all 41.Fn ptrace 42calls are made by the tracing process, and the 43.Fa pid 44argument specifies the process ID of the traced process. 45.Fa request 46can be: 47.Bl -tag -width 12n 48.It Dv PT_TRACE_ME 49This request is the only one used by the traced process; it declares 50that the process expects to be traced by its parent. All the other 51arguments are ignored. (If the parent process does not expect to trace 52the child, it will probably be rather confused by the results; once the 53traced process stops, it cannot be made to continue except via 54.Eo \& 55.Fn ptrace 56.Ec \&.) 57When a process has used this request and calls 58.Xr execve 2 59or any of the routines built on it 60.Po 61such as 62.Xr execv 3 63.Pc , 64it will stop before executing the first instruction of the new image. 65Also, any setuid or setgid bits on the executable being executed will 66be ignored. 67.It Dv PT_READ_I , Dv PT_READ_D 68These requests read a single 69.Li int 70of data from the traced process' address space. Traditionally, 71.Fn ptrace 72has allowed for machines with distinct address spaces for instruction 73and data, which is why there are two requests: conceptually, 74.Dv PT_READ_I 75reads from the instruction space and 76.Dv PT_READ_D 77reads from the data space. In the current NetBSD implementation, these 78two requests are completely identical. The 79.Fa addr 80argument specifies the address (in the traced process' virtual address 81space) at which the read is to be done. This address does not have to 82meet any alignment constraints. The value read is returned as the 83return value from 84.Eo \& 85.Fn ptrace 86.Ec . 87.It Dv PT_WRITE_I , Dv PT_WRITE_D 88These requests parallel 89.Dv PT_READ_I 90and 91.Dv PT_READ_D , 92except that they write rather than read. The 93.Fa data 94argument supplies the value to be written. 95.It Dv PT_READ_U 96This request reads an 97.Li int 98from the traced process' user structure. The 99.Fa addr 100argument specifies the location of the int relative to the base of the 101user structure; it will usually be an integer value cast to 102.Li caddr_t 103either explicitly or via the presence of a prototype for 104.Eo \& 105.Fn ptrace 106.Ec . 107Unlike 108.Dv PT_READ_I 109and 110.Dv PT_READ_D , 111.Fa addr 112must be aligned on an 113.Li int 114boundary. The value read is returned as the return value from 115.Eo \& 116.Fn ptrace 117.Ec . 118.It Dv PT_WRITE_U 119This request writes an 120.Li int 121into the traced process' user structure. 122.Fa addr 123specifies the offset, just as for 124.Dv PT_READ_U , 125and 126.Fa data 127specifies the value to be written, just as for 128.Dv PT_WRITE_I 129and 130.Dv PT_WRITE_D . 131.It Dv PT_CONTINUE 132The traced process continues execution. 133.Fa addr 134is an address specifying the place where execution is to be resumed (a 135new value for the program counter), or 136.Li (caddr_t)1 137to indicate that execution is to pick up where it left off. 138.Fa data 139provides a signal number to be delivered to the traced process as it 140resumes execution, or 0 if no signal is to be sent. 141.It Dv PT_KILL 142The traced process terminates, as if 143.Dv PT_CONTINUE 144had been used with 145.Dv SIGKILL 146given as the signal to be delivered. 147.It Dv PT_ATTACH 148This request allows a process to gain control of an otherwise unrelated 149process and begin tracing it. It does not need any cooperation from 150the to-be-traced process. In this case, 151.Fa pid 152specifies the process ID of the to-be-traced process, and the other two 153arguments are ignored. This request requires that the target process 154must have the same real UID as the tracing process, and that it must 155not be executing a setuid or setgid executable. (If the tracing 156process is running as root, these restrictions do not apply.) The 157tracing process will see the newly-traced process stop and may then 158control it as if it had been traced all along. 159.It Dv PT_DETACH 160This request is like PT_CONTINUE, except that it does not allow 161specifying an alternate place to continue execution, and after it 162succeeds, the traced process is no longer traced and continues 163execution normally. 164.El 165.Pp 166Additionally, machine-specific requests can exist. On the SPARC, these 167are: 168.Bl -tag -width 12n 169.It Dv PT_GETREGS 170This request reads the traced process' machine registers into the 171.Dq Li "struct reg" 172(defined in 173.Aq Pa machine/reg.h ) 174pointed to by 175.Fa addr . 176.It Dv PT_SETREGS 177This request is the converse of 178.Dv PT_GETREGS ; 179it loads the traced process' machine registers from the 180.Dq Li "struct reg" 181(defined in 182.Aq Pa machine/reg.h ) 183pointed to by 184.Fa addr . 185.It Dv PT_GETFPREGS 186This request reads the traced process' floating-point registers into 187the 188.Dq Li "struct fpreg" 189(defined in 190.Aq Pa machine/reg.h ) 191pointed to by 192.Fa addr . 193.It Dv PT_SETFPREGS 194This request is the converse of 195.Dv PT_GETFPREGS ; 196it loads the traced process' floating-point registers from the 197.Dq Li "struct fpreg" 198(defined in 199.Aq Pa machine/reg.h ) 200pointed to by 201.Fa addr . 202.It Dv PT_SYSCALL 203This request is like 204.Dv PT_CONTINUE 205except that the process will stop next time it executes any system 206call. Information about the system call can be examined with 207.Dv PT_READ_U 208and potentially modified with 209.Dv PT_WRITE_U 210through the 211.Li u_kproc.kp_proc.p_md 212element of the user structure (see below). If the process is continued 213with another 214.Dv PT_SYSCALL 215request, it will stop again on exit from the syscall, at which point 216the return values can be examined and potentially changed. The 217.Li u_kproc.kp_proc.p_md 218element is of type 219.Dq Li "struct mdproc" , 220which should be declared by including 221.Aq Pa sys/param.h , 222.Aq Pa sys/user.h , 223and 224.Aq Pa machine/proc.h , 225and contains the following fields (among others): 226.Bl -item -compact -offset indent 227.It 228.Li syscall_num 229.It 230.Li syscall_nargs 231.It 232.Li syscall_args[8] 233.It 234.Li syscall_err 235.It 236.Li syscall_rv[2] 237.El 238When a process stops on entry to a syscall, 239.Li syscall_num 240holds the number of the syscall, 241.Li syscall_nargs 242holds the number of arguments it expects, and 243.Li syscall_args 244holds the arguments themselves. (Only the first 245.Li syscall_nargs 246elements of 247.Li syscall_args 248are guaranteed to be useful.) When a process stops on exit from a 249syscall, 250.Li syscall_num 251is 252.Eo \& 253.Li -1 254.Ec , 255.Li syscall_err 256holds the error number 257.Po 258see 259.Xr errno 2 260.Pc , 261or 0 if no error occurred, and 262.Li syscall_rv 263holds the return values. (If the syscall returns only one value, only 264.Li syscall_rv[0] 265is useful.) The tracing process can modify any of these with 266.Dv PT_WRITE_U ; 267only some modifications are useful. 268.Pp 269On entry to a syscall, 270.Li syscall_num 271can be changed, and the syscall actually performed will correspond to 272the new number (it is the responsibility of the tracing process to fill 273in 274.Li syscall_args 275appropriately for the new call, but there is no need to modify 276.Eo \& 277.Li syscall_nargs 278.Ec ). 279If the new syscall number is 0, no syscall is actually performed; 280instead, 281.Li syscall_err 282and 283.Li syscall_rv 284are passed back to the traced process directly (and therefore should be 285filled in). If the syscall number is otherwise out of range, a dummy 286syscall which simply produces an 287.Er ENOSYS 288error is effectively performed. 289.Pp 290On exit from a syscall, only 291.Li syscall_err 292and 293.Li syscall_rv 294can usefully be changed; they are set to the values returned by the 295syscall and will be passed back to the traced process by the normal 296syscall return mechanism. 297.El 298.Sh ERRORS 299Some requests can cause 300.Fn ptrace 301to return 302.Li -1 303as a non-error value; to disambiguate, 304.Va errno 305can be set to 0 before the call and checked afterwards. The possible 306errors are: 307.Bl -tag -width 4n 308.It Bq Er ESRCH 309No process having the specified process ID exists. 310.It Bq Er EINVAL 311.Bl -bullet -compact 312.It 313A process attempted to use 314.Dv PT_ATTACH 315on itself. 316.It 317The 318.Fa request 319was not one of the legal requests. 320.It 321The 322.Fa addr 323to 324.Dv PT_READ_U 325or 326.Dv PT_WRITE_U 327was not 328.Li int Ns \&-aligned. 329.It 330The signal number (in 331.Fa data ) 332to 333.Dv PT_CONTINUE 334or 335.Dv PT_SYSCALL 336was neither 0 nor a legal signal number. 337.It 338.Dv PT_GETREGS , 339.Dv PT_SETREGS , 340.Dv PT_GETFPREGS , 341or 342.Dv PT_SETFPREGS 343was attempted on a process with no valid register set. (This is 344normally true only of system processes.) 345.El 346.It Bq Er EBUSY 347.Bl -bullet -compact 348.It 349.Dv PT_ATTACH 350was attempted on a process that was already being traced. 351.It 352A request attempted to manipulate a process that was being traced by 353some process other than the one making the request. 354.It 355A request (other than 356.Dv PT_ATTACH ) 357specified a process that wasn't stopped. 358.El 359.It Bq Er EPERM 360.Bl -bullet -compact 361.It 362A request (other than 363.Dv PT_ATTACH ) 364attempted to manipulate a process that wasn't being traced at all. 365.It 366An attempt was made to use 367.Dv PT_ATTACH 368on a process in violation of the requirements listed under 369.Dv PT_ATTACH 370above. 371.El 372.Sh BUGS 373On the SPARC, the PC is set to the provided PC value for 374.Dv PT_CONTINUE 375and similar calls, but the NPC is set willy-nilly to 4 greater than the 376PC value. Using 377.Dv PT_GETREGS 378and 379.Dv PT_SETREGS 380to modify the PC, passing 381.Li (caddr_t)1 382to 383.Eo \& 384.Fn ptrace 385.Ec , 386should be able to sidestep this. 387.Pp 388Single-stepping is not available. 389.Pp 390When using 391.Dv PT_SYSCALL , 392there is no easy way to tell whether the traced process stopped because 393it made a syscall or because a signal was sent at a moment that it just 394happened to have valid-looking garbage in its 395.Dq Li "struct mdproc" . 396