OSF  —  Environment_Note_Added

NAME

ptrace −  Traces the execution of a child process

SYNOPSIS

#include <sys/signal.h> #include <sys/ptrace.h> int  ptrace(
int request,
int process,
int ∗address,
int data );

PARAMETERS

requestDetermines the action to be taken by the ptrace() function. 

processSpecifies the process ID. 

addressDetermined by the value of the request parameter. 

dataDetermined by the value of the request parameter. 

DESCRIPTION

The ptrace() function permits a parent process to control execution of a child process.  It is primarily used by utility programs to enable breakpoint debugging. 

The child process behaves normally until it receives a signal.  When a signal is delivered, the child process is stopped, and a SIGCHLD signal is sent to its parent.  The parent process can wait for the child process to stop using the wait() function. 

When the child process is stopped, its parent process may use the ptrace() function to examine and modify the image memory of the child process, to either terminate the child process or permit it to continue. 

As a security measure, the ptrace() function inhibits the set-user ID facility when any subsequent exec function is issued by the child process.  When a traced process calls one of the exec functions, it stops before executing the first instruction of the new image as if it had received the SIGTRAP signal. 

The request parameter is set to one of the following values.  Only the PT_TRACE_ME request may be issued by child processes; the remaining requests can only be used by the parent process.  For each request, the process parameter is the process ID of the child process. The child process must be in a stopped state before these requests are made. 

PT_TRACE_ME
This request sets the child process trace flag. It must be issued by the child process that is to be traced by its parent process. When the trace flag is set, the child process is left in a stopped state on receipt of a signal, and the action specified by the sigaction() function is ignored. The process, address, and data parameters are ignored, and the return value is not defined for this request. Do not issue this request when the parent process does not expect to trace the child process. 

PT_READ_I or PT_READ_D
These requests return the address space data of the child process at the location pointed to by the address parameter.  The PT_READ_I and PT_READ_D requests can be used with equal results.  The data parameter is ignored.  These requests fail when the value of the address parameter is not in the address space of the child process or on some machines, when the address parameter is not properly aligned.  These errors return a value of -1, and the parent process errno is set to [EIO]. 

PT_READ_U
This request returns the variable of the system’s per-process data area for the child, specified by the address parameter.  This area contains the register values and other information about the process.  On some machines, the address parameter is subject to alignment constraints.  The data parameter is ignored.  This request fails when the value of the address parameter is outside of the system’s per-process data area for the child.  On failure, a value of -1 is returned and the parent process errno is set to [EIO]. 

PT_WRITE_I, PT_WRITE_D
These requests write the value of the data parameter into the address space variable of the child process at the location pointed to by the address parameter.  On some machines, where necessary, the PT_WRITE_I request synchronizes any hardware caches, if present.  In all other respects, the PT_WRITE_I and PT_WRITE_D requests can be used with equal results.  On some machines, these requests return the previous contents of the address space variable of the child process, while on other machines no useful value is returned.  These requests fail when the address parameter points to a location in a pure procedure space and a copy cannot be made.  These requests also fail when the value of the address parameter is out of range and on some machines, when the address parameter is not properly aligned.  On failure a value of -1 is returned and the parent process errno is set to [EIO]. 

PT_WRITE_U
This request writes the value of the data parameter into the variable of the system’s per-process data area for the child, specified by the address parameter.  This area contains the register values and other information about the process.  On some machines, the address parameter is subject to alignment constraints.  Not all locations within the system’s per-process data area for the child may be written.  This request fails when the value of the address parameter is outside of the systems’s per-process data area for the child.  On failure, a value of -1 is returned and the parent process errno is set to indicate the error. 

PT_CONTINUE
This request permits the child process to resume execution.  When the data parameter is 0 (zero), the signal that caused the child process to stop is canceled before the child process resumes execution. 

When the data parameter has a valid signal value, the child process resumes execution as though that signal had been received.  When the address parameter is equal to 1, execution continues from where it stopped.  When the address parameter is not 1, it is assumed to be the address at which the process should resume execution. 

This request fails when the data parameter is not 0 (zero) or a valid signal value.  On failure, a value of -1 is returned to the parent process and the parent process errno is set to [EIO]. 

PT_KILLThis request terminates a child process as if the child process called the exit() function. 

PT_STEPThis request permits execution to continue in the same manner as PT_CONTINUE; however, as soon as possible after the execution of at least one instruction, execution stops again as if the child process had received the SIGTRAP signal. 

ERRORS

ptrace() function fails, errno may be set to one of the following values:

[EIO]The request parameter does not have one of the listed values, or is not valid for the machine type on which the process is executing. 

[EIO]The given signal number is invalid. 

[EIO]The specified address is either out of bounds or improperly aligned. 

[ESRCH]The process parameter identifies a child process that does not exist or that has not executed this function with the request parameter PT_TRACE_ME. 

[EPERM]The specified process cannot be traced. 

[EINVAL]An invalid location was specified for the system’s per-process data area. 

[EACCES]The location within the system’s per-process data area could not be modified. 

ENVIRONMENT NOTES

This section describes system features that are not generic to OSF/1 but that are provided in this OSF/1 implementation. 

System V Compatibility

To accurately reflect System V behavior, the following changes should be made to the descriptions of the request parameters:

       •The following statement in the description of the PT_WRITE, PT_WRITE_D paramenters does not apply to System V:

On some machines, these requests return the previous contents of the address space variable of the child process, while on other machines, no useful value is returned. 

To reflect System V behavior, the statement should read as follows:

On success, the value written into the address space of the child process is returned. 

       •To correctly describe System V behavior, the following statement should be added to the end of the third paragraph in the description of the PT_CONTINUE parameter:

On success, the signal value to be received by the child process is returned. 
 

RELATED INFORMATION

Functions: exec(2), sigaction(2), wait(2)