1.\" $FreeBSD: src/lib/libc/sys/ptrace.2,v 1.12.2.12 2001/12/14 18:34:01 ru Exp $ 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 June 22, 2015 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 19.Fn ptrace 20provides tracing and debugging facilities. It allows one process (the 21.Em tracing 22process) to control another (the 23.Em traced 24process). Most of the time, the traced process runs normally, but when 25it receives a signal 26(see 27.Xr sigaction 2 ) , 28it stops. The tracing process is expected to notice this via 29.Xr wait 2 30or the delivery of a 31.Dv SIGCHLD 32signal, examine the state of the stopped process, and cause it to 33terminate or continue as appropriate. 34.Fn ptrace 35is the mechanism by which all this happens. 36.Pp 37The 38.Fa request 39argument specifies what operation is being performed; the meaning of 40the rest of the arguments depends on the operation, but except for one 41special case noted below, all 42.Fn ptrace 43calls are made by the tracing process, and the 44.Fa pid 45argument specifies the process ID of the traced process. 46.Fa request 47can be: 48.Bl -tag -width 12n 49.It Dv PT_TRACE_ME 50This request is the only one used by the traced process; it declares 51that the process expects to be traced by its parent. All the other 52arguments are ignored. (If the parent process does not expect to trace 53the child, it will probably be rather confused by the results; once the 54traced process stops, it cannot be made to continue except via 55.Fn ptrace . ) 56When a process has used this request and calls 57.Xr execve 2 58or any of the routines built on it 59(such as 60.Xr execv 3 ) , 61it will stop before executing the first instruction of the new image. 62Also, any setuid or setgid bits on the executable being executed will 63be ignored. 64.It Dv PT_READ_I , Dv PT_READ_D 65These requests read a single 66.Vt int 67of data from the traced process' address space. Traditionally, 68.Fn ptrace 69has allowed for machines with distinct address spaces for instruction 70and data, which is why there are two requests: conceptually, 71.Dv PT_READ_I 72reads from the instruction space and 73.Dv PT_READ_D 74reads from the data space. In the current 75.Dx 76implementation, these 77two requests are completely identical. The 78.Fa addr 79argument specifies the address (in the traced process' virtual address 80space) at which the read is to be done. This address does not have to 81meet any alignment constraints. The value read is returned as the 82return value from 83.Eo \& 84.Fn ptrace 85.Ec . 86.It Dv PT_WRITE_I , Dv PT_WRITE_D 87These requests parallel 88.Dv PT_READ_I 89and 90.Dv PT_READ_D , 91except that they write rather than read. The 92.Fa data 93argument supplies the value to be written. 94.It Dv PT_IO 95This request allows reading and writing arbitrary amounts of data in 96the traced process's address space. 97The 98.Fa addr 99argument specifies a pointer to a 100.Vt "struct ptrace_io_desc" , 101which is defined as follows: 102.Bd -literal 103struct ptrace_io_desc { 104 int piod_op; /* I/O operation */ 105 void *piod_offs; /* child offset */ 106 void *piod_addr; /* parent offset */ 107 size_t piod_len; /* request length */ 108}; 109 110/* 111 * Operations in piod_op. 112 */ 113#define PIOD_READ_D 1 /* Read from D space */ 114#define PIOD_WRITE_D 2 /* Write to D space */ 115#define PIOD_READ_I 3 /* Read from I space */ 116#define PIOD_WRITE_I 4 /* Write to I space */ 117.Ed 118.Pp 119The 120.Fa data 121argument is ignored. 122The actual number of bytes read or written is stored in 123.Va piod_len 124upon return. 125.It Dv PT_CONTINUE 126The traced process continues execution. 127.Fa addr 128is an address specifying the place where execution is to be resumed (a 129new value for the program counter), or 130.Po Vt caddr_t Pc Ns 1 131to indicate that execution is to pick up where it left off. 132.Fa data 133provides a signal number to be delivered to the traced process as it 134resumes execution, or 0 if no signal is to be sent. 135.It Dv PT_STEP 136The traced process is single stepped one instruction. 137.Fa addr 138should be passed 139.Po Vt caddr_t Pc Ns 1 . 140.Fa data 141is not used. 142.It Dv PT_KILL 143The traced process terminates, as if 144.Dv PT_CONTINUE 145had been used with 146.Dv SIGKILL 147given as the signal to be delivered. 148.It Dv PT_ATTACH 149This request allows a process to gain control of an otherwise unrelated 150process and begin tracing it. It does not need any cooperation from 151the to-be-traced process. In this case, 152.Fa pid 153specifies the process ID of the to-be-traced process, and the other two 154arguments are ignored. This request requires that the target process 155must have the same real UID as the tracing process, and that it must 156not be executing a setuid or setgid executable. (If the tracing 157process is running as root, these restrictions do not apply.) The 158tracing process will see the newly-traced process stop and may then 159control it as if it had been traced all along. 160.It Dv PT_DETACH 161This request is like PT_CONTINUE, except that it does not allow 162specifying an alternate place to continue execution, and after it 163succeeds, the traced process is no longer traced and continues 164execution normally. 165.El 166.Pp 167Additionally, machine-specific requests can exist. 168On x86_64, these are: 169.Bl -tag -width 12n 170.It Dv PT_GETREGS 171This request reads the traced process' machine registers into the 172.Do 173.Vt "struct reg" 174.Dc 175(defined in 176.In machine/reg.h ) 177pointed to by 178.Fa addr . 179.It Dv PT_SETREGS 180This request is the converse of 181.Dv PT_GETREGS ; 182it loads the traced process' machine registers from the 183.Do 184.Vt "struct reg" 185.Dc 186(defined in 187.In machine/reg.h ) 188pointed to by 189.Fa addr . 190.It Dv PT_GETFPREGS 191This request reads the traced process' floating-point registers into 192the 193.Do 194.Vt "struct fpreg" 195.Dc 196(defined in 197.In machine/reg.h ) 198pointed to by 199.Fa addr . 200.It Dv PT_SETFPREGS 201This request is the converse of 202.Dv PT_GETFPREGS ; 203it loads the traced process' floating-point registers from the 204.Do 205.Vt "struct fpreg" 206.Dc 207(defined in 208.In machine/reg.h ) 209pointed to by 210.Fa addr . 211.It Dv PT_GETDBREGS 212This request reads the traced process' debug registers into 213the 214.Do 215.Vt "struct dbreg" 216.Dc 217(defined in 218.In machine/reg.h ) 219pointed to by 220.Fa addr . 221.It Dv PT_SETDBREGS 222This request is the converse of 223.Dv PT_GETDBREGS ; 224it loads the traced process' debug registers from the 225.Do 226.Vt "struct dbreg" 227.Dc 228(defined in 229.In machine/reg.h ) 230pointed to by 231.Fa addr . 232.El 233.Sh RETURN VALUES 234Some requests can cause 235.Fn ptrace 236to return 237.Li -1 238as a non-error value; to disambiguate, 239.Va errno 240can be set to 0 before the call and checked afterwards. 241.Sh ERRORS 242The 243.Fn ptrace 244function may fail if: 245.Bl -tag -width Er 246.It Bq Er ESRCH 247.Bl -bullet -compact 248.It 249No process having the specified process ID exists. 250.El 251.It Bq Er EINVAL 252.Bl -bullet -compact 253.It 254A process attempted to use 255.Dv PT_ATTACH 256on itself. 257.It 258The 259.Fa request 260was not one of the legal requests. 261.It 262The signal number (in 263.Fa data ) 264to 265.Dv PT_CONTINUE 266was neither 0 nor a legal signal number. 267.It 268The 269.Fa pid 270represents a system process. 271.It 272.Dv PT_GETREGS , 273.Dv PT_SETREGS , 274.Dv PT_GETFPREGS , 275.Dv PT_SETFPREGS , 276.Dv PT_GETDBREGS , 277or 278.Dv PT_SETDBREGS 279was attempted on a process with no valid register set. (This is 280normally true only of system processes.) 281.El 282.It Bq Er EBUSY 283.Bl -bullet -compact 284.It 285.Dv PT_ATTACH 286was attempted on a process that was already being traced. 287.It 288A request attempted to manipulate a process that was being traced by 289some process other than the one making the request. 290.It 291A request (other than 292.Dv PT_ATTACH ) 293specified a process that wasn't stopped. 294.El 295.It Bq Er EPERM 296.Bl -bullet -compact 297.It 298A request (other than 299.Dv PT_ATTACH ) 300attempted to manipulate a process that wasn't being traced at all. 301.It 302An attempt was made to use 303.Dv PT_ATTACH 304on a process in violation of the requirements listed under 305.Dv PT_ATTACH 306above. 307.El 308.El 309.Sh SEE ALSO 310.Xr execve 2 , 311.Xr sigaction 2 , 312.Xr wait 2 , 313.Xr execv 3 314.Sh HISTORY 315A 316.Fn ptrace 317function call appeared in 318.At v7 . 319