PTRACE(2) UNIX Programmer's Manual PTRACE(2) NAME ptrace - process trace SYNOPSIS #include #include ptrace(request, pid, addr, data) int request, pid, *addr, data; DESCRIPTION _P_t_r_a_c_e provides a means by which a parent process may con- trol the execution of a child process, and examine and change its core image. Its primary use is for the implemen- tation of breakpoint debugging. There are four arguments whose interpretation depends on a _r_e_q_u_e_s_t argument. Gen- erally, _p_i_d is the process ID of the traced process, which must be a child (no more distant descendant) of the tracing process. A process being traced behaves normally until it encounters some signal whether internally generated like "illegal instruction" or externally generated like "inter- rupt". See _s_i_g_v_e_c(2) for the list. Then the traced process enters a stopped state and its parent is notified via _w_a_i_t(2). When the child is in the stopped state, its core image can be examined and modified using _p_t_r_a_c_e. If desired, another _p_t_r_a_c_e request can then cause the child either to terminate or to continue, possibly ignoring the signal. The value of the _r_e_q_u_e_s_t argument determines the precise action of the call: PT_TRACE_ME This request is the only one used by the child process; it declares that the process is to be traced by its parent. All the other arguments are ignored. Peculiar results will ensue if the parent does not expect to trace the child. PT_READ_I, PT_READ_D The word in the child process's address space at _a_d_d_r is returned. If I and D space are separated (e.g. histori- cally on a pdp-11), request PT_READ_I indicates I space, PT_READ_D D space. _A_d_d_r must be even on some machines. The child must be stopped. The input _d_a_t_a is ignored. PT_READ_U The word of the system's per-process data area corresponding to _a_d_d_r is returned. _A_d_d_r must be even on some machines and less than 512. This space contains the registers and other information about the process; its layout corresponds to the _u_s_e_r structure in the Printed 11/26/99 May 23, 1986 1 PTRACE(2) UNIX Programmer's Manual PTRACE(2) system. PT_WRITE_I, PT_WRITE_D The given _d_a_t_a is written at the word in the process's address space corresponding to _a_d_d_r, which must be even on some machines. No useful value is returned. If I and D space are separated, request PT_WRITE_I indicates I space, PT_WRITE_D D space. Attempts to write in pure procedure fail if another process is executing the same file. PT_WRITE_U The process's system data is written, as it is read with request PT_READ_U. Only a few locations can be written in this way: the general registers, the floating point status and registers, and certain bits of the processor status word. PT_CONTINUE The _d_a_t_a argument is taken as a signal number and the child's execution continues at location _a_d_d_r as if it had incurred that signal. Normally the signal number will be either 0 to indicate that the signal that caused the stop should be ignored, or that value fetched out of the process's image indicating which signal caused the stop. If _a_d_d_r is (int *)1 then execution continues from where it stopped. PT_KILL The traced process terminates. PT_STEP Execution continues as in request PT_CONTINUE; however, as soon as possible after execution of at least one instruction, execution stops again. The signal number from the stop is SIGTRAP. (On the VAX-11 the T-bit is used and just one instruction is executed.) This is part of the mechanism for implementing breakpoints. As indicated, these calls (except for request PT_TRACE_ME) can be used only when the subject process has stopped. The _w_a_i_t call is used to determine when a process stops; in such a case the "termination" status returned by _w_a_i_t has the value 0177 to indicate stoppage rather than genuine termina- tion. To forestall possible fraud, _p_t_r_a_c_e inhibits the set-user-id and set-group-id facilities on subsequent _e_x_e_c_v_e(2) calls. If a traced process calls _e_x_e_c_v_e, it will stop before exe- cuting the first instruction of the new image showing signal SIGTRAP. Printed 11/26/99 May 23, 1986 2 PTRACE(2) UNIX Programmer's Manual PTRACE(2) On a VAX-11, "word" also means a 32-bit integer, but the "even" restriction does not apply. RETURN VALUE A 0 value is returned if the call succeeds. If the call fails then a -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. ERRORS [EIO] The request code is invalid. [ESRCH] The specified process does not exist. [EIO] The given signal number is invalid. [EIO] The specified address is out of bounds. [EPERM] The specified process cannot be traced. SEE ALSO wait(2), sigvec(2), adb(1) NOTES (PDP-11) On the PDP-11 the PT_WRITE_U request may also write the child process's current overlay number in the system data area; the T-bit is used to single step the processor and just one instruction is executed for the PT_STEP request; a "word" means a 16-bit integer, and the "even" restriction _d_o_e_s apply. BUGS _P_t_r_a_c_e is unique and arcane; it should be replaced with a special file that can be opened and read and written. The control functions could then be implemented with _i_o_c_t_l(2) calls on this file. This would be simpler to understand and have much higher performance. The request PT_TRACE_ME call should be able to specify sig- nals that are to be treated normally and not cause a stop. In this way, for example, programs with simulated floating point (which use "illegal instruction" signals at a very high rate) could be efficiently debugged. The error indication, -1, is a legitimate function value; _e_r_r_n_o, (see _i_n_t_r_o(2)), can be used to disambiguate. It should be possible to stop a process on occurrence of a system call; in this way a completely controlled environment could be provided. Printed 11/26/99 May 23, 1986 3