PTRACE(2) — HP-UX

Series 300, 800 Only

NAME

ptrace − process trace

SYNOPSIS

#include <sys/ptrace.h> int ptrace(request, pid, addr, data, addr2);
int request, pid, addr, data, addr2;

REMARKS

Much of the functionality of this capability is highly dependent on the underlying hardware. An application that uses this system call should not be expected to be portable across architectures or implementations.

DESCRIPTION

Ptrace provides a means by which a process may control the execution of another process. Its primary use is for the implementation of breakpoint debugging; see adb(1). The traced process behaves normally until it encounters a signal (see signal(2) for the list), at which time it enters a stopped state and the tracing process is notified via wait(2). When the traced process is in the stopped state, the tracing process can examine and modify the "core image" using ptrace. Also, the tracing process can cause the traced process either to terminate or continue, with the possibility of ignoring the signal that caused it to stop.

The request argument determines the precise action to be taken by ptrace and is one of the following:

PT_SETTRC This request must be issued by a 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(2). The pid, addr, data, and addr2 arguments are ignored, and a return value is not defined for this request. Peculiar results will ensue if the parent does not expect to trace the child.

The remainder of the requests can only be used by the tracing process. For each, pid is the process ID of the process being traced, which must be in a stopped state before these requests are made.

PT_RIUSER, PT_RDUSER
With these requests, the word at location addr in the address space of the traced process is returned to the tracing process. If instruction (I) and data (D) space are separated, request PT_RIUSER returns a word from I space, and request PT_RDUSER returns a word from D space. If I and D space are not separated, either request PT_RIUSER or request PT_RDUSER may be used with equal results. The data and addr2 arguments are ignored. These two requests will fail if addr is not the start address of a word, in which case a value of −1 is returned to the tracing process and its errno is set to EIO.

PT_RUAREA
With this request, the word at location addr in the USER area of the traced process in the system’s address space (see <sys/user.h>) is returned to the tracing process. Addresses in this area are system dependent, but start at zero. The limit can be derived from <sys/user.h>. The data and addr2 arguments are ignored. This request will fail if addr is not the start address of a word or is outside the area, in which case a value of −1 is returned to the tracing process and its errno is set to EIO.

PT_WIUSER, PT_WDUSER
With these requests, the value given by the data argument is written into the address space of the traced process at location addr. Request PT_WIUSER writes a word into I space, and request PT_WDUSER writes a word in D space. Upon successful completion, the value written into the address space of the traced process is returned to the tracing process. The addr2 argument is ignored. These two requests will fail if addr is not the start address of a word, or if addr is a location in a pure procedure space and either another process is executing in that space or the tracing process does not have write access for the executable file corresponding to that space. Upon failure a value of −1 is returned to the tracing process and its errno is set to EIO.

PT_WUAREA
With this request, a few entries in the traced process’ USER area can be written. Data gives the value that is to be written and addr is the location of the entry. The addr2 argument is ignored. The few entries that can be written are dependent on the architecture of the system, but include the user data registers, auxiliary data registers, and status register (the set of registers, or bits in registers, which the user’s program could modify).

PT_CONTIN This request causes the traced process to resume execution. If the data argument is 0, all pending signals including the one that caused the traced process to stop are canceled before it resumes execution. If the data argument is a valid signal number, the traced process resumes execution as if it had incurred that signal, and any other pending signals are canceled. The addr argument must be equal to 1 for this request. The addr2 argument is ignored. Upon successful completion, the value of data is returned to the tracing process. This request will fail if data is not 0 or a valid signal number, in which case a value of −1 is returned to the tracing process and its errno is set to EIO.

PT_EXIT This request causes the traced process to terminate with the same consequences as exit(2). The addr, data, and addr2 arguments are ignored.

PT_SINGLE This request causes a flag to be set so that an interrupt will occur upon the completion of one machine instruction, and then executes the same steps as listed above for request PT_CONTIN. If the processor does not provide a trace bit, this request returns an error. This effectively allows single stepping of the traced process. Whether or not the trace bit remains set after this interrupt is a function of the hardware.

To forestall possible fraud, ptrace inhibits the set-user-ID facility on subsequent exec(2) calls. If a traced process calls exec, it will stop before executing the first instruction of the new image showing signal SIGTRAP.

ERRORS

In general, ptrace will fail if one or more of the following are true:

[EIO] Request is an illegal number.

[EPERM] The specified process cannot be attached for tracing.

[ESRCH] Pid identifies a process to be traced that does not exist or has not executed a ptrace with request PT_SETTRC.

DEPENDENCIES

Series 300
The following additional request is available:

PT_RFPREGS
With this request, the child’s floating point accelerator register set is returned to the parent process in addr. Addr must be the address of a buffer of at least 136 bytes. The first 128 bytes will contain the 16 double precision floating point registers and the next 8 bytes will contain the status and control registers. The data argument is ignored. This request will fail if the child process is not using the floating point accelerator, in which case a value of −1 is returned to the parent process and the parent’s errno is set to EIO. This request will also fail if addr is a bad address, in which case a value of −1 is returned to the parent process and the parent’s errno is set to EFAULT.

Series 800
The request PT_WUAREA is not supported. Therefore, it returns −1, sets errno to EIO and does not affect the USER area of the traced process.

If the addr argument to a PT_CONTIN or PT_SINGLE request is not 1, the Instruction Address Offset Queue (program counter) is loaded with the values addr and addr+4 before execution resumes. Otherwise, execution resumes from the point where it was interrupted.

Additional requests are available:

PT_RUREGS With this request, the word at location addr in the save_state structure at the base of the per-process kernel stack is returned to the tracing process. Addr must be word-aligned and less than STACKSIZE*NBPG (see <sys/param.h> and <machine/param.h>). The save_state structure contains the registers and other information about the process. The data and addr2 arguments are ignored.

PT_WUREGS
The save_state structure at the base of the per-process kernel stack is written, as it is read with request PT_RUREGS. Only a few locations can be written in this way: the general registers, most floating point registers, a few control registers, and certain bits of the interruption processor status word. The addr2 argument is ignored.

PT_ATTACH This request stops the process identified by pid and allows the calling process to trace it. Process pid does not have to be a child of the calling process, but the effective user IDs of the two processes must match (unless the effective user ID of the tracing process is superuser). The calling process can use the wait(2) system call to wait for process pid to stop. The addr, data, and addr2 arguments are ignored.

PT_DETACH This request detaches the traced process pid and allows it to continue its execution in the manner of PT_CONTIN with the exception that if the value of addr is not 1, the Instruction Address Offset Queue is loaded with the values addr and addr2.

PT_RDTEXT, PT_RDDATA
These requests are identical to PT_RIUSER and PT_RDUSER except that the data argument specifies the number of bytes to read and the addr2 argument specifies where to store that data in the tracing process.

PT_WRTEXT, PT_WRDATA
These requests are identical to PT_WIUSER and PT_WDUSER except that the data argument specifies the number of bytes to write and the addr2 argument specifies where to read that data in the tracing process.

Museum

Related Articles