PTRACE(2) — HP-UX

Series 200, 300, 800 Only

NAME

ptrace − process trace

SYNOPSIS

int ptrace (request, pid, addr, data);
int request, pid, addr, data;

REMARKS

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

DESCRIPTION

Ptrace 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 adb(1). The child process behaves normally until it encounters a signal (see signal(2) for the list), at which time it enters a stopped state and its parent is notified via wait(2). 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 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(2). The pid, addr, and data 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 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 instruction (I) and data (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. 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 parent process and the parent’s errno is set to EIO.

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. Addresses in this area are system dependent, but start at zero. The limit can be derived from <sys/user.h>. The data argument is ignored. This request will fail if addr is not the start address of a word or 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. Request 4 writes a word into I space, and request 5 writes a word in D space. Upon successful completion, the value written into the address space of the child is returned to the parent. 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 parent process does not have write access for the executable file corresponding to 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 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).

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 pending 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 will fail 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 consequences as exit(2).

9 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 7. If the processor does not provide a trace bit, this request returns an error. This effectively allows single stepping of the child.
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

Ptrace will in general fail if one or more of the following are true:

[EIO] Request is an illegal number.

[ESRCH] Pid identifies a child that does not exist or has not executed a ptrace with request 0.

HARDWARE DEPENDENCIES

Series 800
Request 6 is not supported and will return −1 with errno set to EIO.

Two other requests are available:

10 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 parent 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.

11 The save_state structure at the base of the per-process kernel stack is written, as it is read with request 10. 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.

Museum

Related Articles