ptrace(S) 6 January 1993 ptrace(S) Name ptrace - process trace Syntax cc ... -lc int ptrace (request, pid, addr, data); int request, pid, data; Description The ptrace system call provides a means by which a parent process may control the execution of a child process. Its primary use is for the implementation of breakpoint debugging (see sdb(CP)). The child process behaves normally until it encounters a signal (see signal(S) for the list), at which time it enters a stopped state and its parent is notified via wait(S). When the child is in the stopped state, its parent can examine and modify its ``core image'' using ptrace. Also, the parent can cause the child either to terminate or continue, with the possibility of ignoring the signal that caused it to stop. The data type of the argu- ment addr depends upon the particular request given to ptrace. The request argument determines the precise action to be taken by ptrace and is one of the following: 0 This request must be issued by the child process if it is to be traced by its parent. It turns on the child's trace flag that stipulates that the child should be left in a stopped state upon receipt of a signal rather than the state specified by func (see signal(S)). The pid, addr, and data arguments are ignored, and a return value is not defined for this request. Peculiar results ensue if the parent does not expect to trace the child. The remainder of the requests can only be used by the parent process. For each, pid is the process ID of the child. The child must be in a stopped state before these requests are made. 1, 2 With these requests, the word at location addr in the address space of the child is returned to the parent process. If I and D space are separated, request 1 returns a word from I space, and request 2 returns a word from D space. If I and D space are not separated, either request 1 or request 2 may be used with equal results. The data argument is ignored. 3 With this request, the word at location addr in the child's USER area in the system's address space (see <sys/user.h>) is returned to the parent process. The data argument is ignored. This request fails if addr is outside the USER area, in which case a value of -1 is returned to the parent process and the parent's errno is set to EIO. 4, 5 With these requests, the value given by the data argument is written into the address space of the child at location addr. If I and D space are separated, request 4 writes a word into I space, and request 5 writes a word into D space. If I and D space are not separated, either request 4 or request 5 may be used with equal results. Upon successful completion, the value written into the address space of the child is returned to the parent. These two requests fail if addr is a location in a pure procedure space and another process is executing in that space. Upon failure a value of -1 is returned to the parent process and the parent's errno is set to EIO. 6 With this request, a few entries in the child's USER area can be written. Data gives the value that is to be written and addr is the location of the entry. The few entries that can be written are all registers. On the 80386, the ptrace system call can be used to modify the debug registers. The 80386 debug registers are used to specify an address to moni- tor in a user process. Any access to this location by the user process delivers a SIGTRAP (see signal(S)) to the user process and possibly restart the parent process. The 80386 debug registers can be accessed by using the 3 or 6 options of the ptrace system call to read or write a traced-pro- cess's u-area. The file <sys/debugreg.h> should be included in the parent process that wants to control the debug registers. This header file defines bit masks that describe the debug- registers in the udebugreg[] array in the u-area. The debug registers numbered u.udebugreg [DRFIRSTADDR] (%dr0) to u.udebugreg[DRLASTADDR] (%dr3) contain process addresses which are monitored according to the instructions provided in u.udebugreg[DRCONTROL] (%dr7). Only the DRLOCALENABLEMASK and the various read/write and length bits in u.udebugreg[DRCONTROL] can be set. Setting DRLOCALSLOWDOWN to slow down processing is also highly recommended. The setting of all other bits is undefined and should be set to zero to ensure compatibility with future Intel processors. In the process being debugged, these registers are automatically loaded before entering user-mode (privilege level 3) and cleared before entering the system for any reason. In System V Release 3.2, if the location specified by a debug-register is accessed during a system call, core-dump, or interrupt service, no trap ensues. 7 This request causes the child to resume execution. If the data argument is 0, all pending signals including the one that caused the child to stop are canceled before it resumes execution. If the data argument is a valid signal number, the child resumes execution as if it had incurred that signal, and any other pend- ing signals are canceled. The addr argument must be equal to 1 for this request. Upon successful completion, the value of data is returned to the parent. This request fails if data is not 0 or a valid signal number, in which case a value of -1 is returned to the parent process and the parent's errno is set to EIO. 8 This request causes the child to terminate with the same conse- quences as exit(S). 9 This request sets the trace bit in the Processor Status Word of the child and then executes the same steps as listed above for request 7. The trace bit causes an interrupt upon completion of one machine instruction. This effectively allows single stepping of the child. 10 Attach to the process PID, and begin tracing it. Process PID must have the same uid as the current process, and it must not have executed a suid or sgid program, nor may it be executing a file for which the current process' UID did not have read permis- sion at the time of the exec. Process PID need not be a child of the current process. Root may attach to any process. 11 Detach the process being traced. Process PID is no longer traced, and continues executing. The same steps as listed above for request 7 are performed. 12 The STRCFRK flag for the process PID is set. This causes any child processes resulting from a fork(S) by the process PID to be controlled by the current process. The child processes stops before executing the return from the fork call. On a multipro- cessor it is possible for another process to successfully ATTACH before the child is set up to be traced by the parent's control- ler. In this case, the other process remains the child's con- troller, and the STRCFRK bit is ignored. 13 The process with process ID equal to DATA is given control of the process PID. The process with a process ID equal to DATA must have the same UID as the current process. The current process no longer controls the process PID. The process with process ID equal to DATA is sent a SIGCLD signal. To forestall possible fraud, ptrace inhibits the set-user-ID facility on subsequent exec(S) calls. If a traced process calls exec, it stops before executing the first instruction of the new image showing signal SIGTRAP. General errors The ptrace system call generally fails if the child process is running under i286emul(CP) or one or more of the following is true: [EIO] request is an illegal number. [EINVAL] For request 10, the process is already being traced. For request 0, the parent of the current process has a process ID of 1, or the process is already traced, or, on a multiprocessor, the parent process is exiting. [EPERM] For request 10, the process has a different UID, the pro- cess's GID is not in the group list of the current pro- cess, the process is executing a setuid/setgid program, or the process is executing a file for which it does not have read permission. For request 13, the process data has a different UID than the current process. [ESRCH] pid identifies a process that does not exist or is not controlled by the current process, or is in the process of terminating (on a multiprocessor). See also exec(S), sdb(CP), signal(S), wait(S) Standards conformance ptrace is conformant with: AT&T SVID Issue 2, but has been withdrawn from XPG3.