[ Previous | Next | Contents | Glossary | Home | Search ]
AIX Version 4.3 Base Operating System and Extensions Technical Reference, Volume 1

ptrace Subroutine

Purpose

Traces the execution of another process.

Library

Standard C Library (libc.a)

Syntax

#include <sys/reg.h>
#include <sys/ptrace.h>
#include <sys/ldr.h>
int ptrace (Request,  Identifier,  Address, Data, Buffer)
int Request;
int Identifier;
int *Address;
int Data;
int *Buffer;

Description

The ptrace subroutine allows a process to trace the execution of another process. The ptrace subroutine is used to implement breakpoint debugging.

A debugged process executes normally until it encounters a signal. Then it enters a stopped state and its debugging process is notified with the wait subroutine. While the process is in the stopped state, the debugger examines and modifies its memory image by using the ptrace subroutine. For multi-threaded processes, the getthrds subroutine is used to identify each kernel thread in the debugged process. Also, the debugging process can cause the debugged process to terminate or continue, with the possibility of ignoring the signal that caused it to stop.

As a security measure, the ptrace subroutine inhibits the set-user-ID facility on subsequent exec subroutines.

When a process is executing under ptrace, its segments 1 and 13 are reconstructed when the load subroutine is called. Code modification will not work in this case. If the running code has been modified dynamically (in segment 1), when load is called it will be changed back to its original value.

If a traced process initiates an exec subroutine, the process stops before executing the first instruction of the new image and returns the SIGTRAP signal.

Note: ptrace is not supported in 64-bit mode.

Parameters

Request Determines the action to be taken by the ptrace subroutine and has one of the following values:
PT_ATTACH
This request allows a debugging process to attach a current process and place it into trace mode for debugging. This request cannot be used if the target process is already being traced. The Identifier parameter is interpreted as the process ID of the traced process. The Address, Data, and Buffer parameters are ignored.

If this request is unsuccessful, -1 is returned and the errno global variable is set to one the following codes:

ESRCH
Process ID is not valid; the traced process is a kernel process; the process is currently being traced; or, the debugger or traced process already exists.
EPERM
Real or effective user ID of the debugger does not match that of the traced process, or the debugger does not have root authority.
EINVAL
The debugger and the traced process are the same.
PT_CONTINUE
This request allows the process to resume execution. If the Data parameter is 0, all pending signals, including the one that caused the process to stop, are concealed before the process resumes execution. If the data parameter is a valid signal number, the process resumes execution as if it had received that signal. If the Address parameter equals 1, the execution continues from where it stopped. If the Address parameter is not 1, it is assumed to be the address at which the process should resume execution. Upon successful completion, the value of the Data parameter is returned to the debugging process. The Identifier parameter is interpreted as the process ID of the traced process. The Buffer parameter is ignored.

If this request is unsuccessful, -1 is returned and the errno global variable is set to the following code:

EIO
The signal to be sent to the traced process is not a valid signal number.
PTT_CONTINUE
This request asks the scheduler to resume execution of the kernel thread specified by Identifier. This kernel thread must be the one that caused the exception. The Data parameter specifies how to handle signals:   
  • If the Data parameter is zero, the kernel thread which caused the exception will be resumed as if the signal never occurred.
  • If the Data parameter is a valid signal number, the kernel thread which caused the exception will be resumed as if it had received that signal.

    The Address parameter specifies where to resume execution:

  • If the Address parameter is one, execution resumes from the address where it stopped.
  • If the Address parameter contains an address value other than one, execution resumes from that address.

    The Buffer parameter should point to a PTTHREADS structure, which contains a list of kernel thread identifiers to be started. This list should be NULL terminated if it is smaller than the maxiumum allowed.

    On successful completion, the value of the Data parameter is returned to the debugging process. On unsuccessful completion, the value -1 is returned, and the errno global variable is set as follows:

    EINVAL
    The Identifier parameter names the wrong kernel thread.
    EIO
    The signal to be sent to the traced kernel thread is not a valid signal number.
    ESRCH
    The Buffer parameter names an invalid kernel thread. Each kernel thread in the list must be stopped and belong to the same process as the kernel thread named by the Identifier parameter.
PT_DETACH
This request allows a debugged process, specified by the Identifier parameter, to exit trace mode. The process then continues running, as if it had received the signal whose number is contained in the data parameter. The process is no longer traced and does not process any further ptrace calls. The Address and Buffer parameters are ignored.

If this request is unsuccessful, -1 is returned and the errno global variable is set to the following code:

EIO
Signal to be sent to the traced process is not a valid signal number.
PT_KILL
This request allows the process to terminate the same way it would with an exit subroutine.
PT_LDINFO
This request retrieves a description of the object modules that were loaded by the debugged process. The Identifier parameter is interpreted as the process ID of the traced process. The Buffer parameter is ignored. The Address parameter specifies the location where the loader information is copied. The Data parameter specifies the size of this area. The loader information is retrieved as a linked list of ld_info structures. The ld_info structures are defined in the /usr/include/sys/ldr.h file. The linked list is implemented so that the ldinfo_nxt field of each element gives the offset of the next element from this element. The ldinfo_nxt field of the last element has the value 0.

If this request is unsuccessful, -1 is returned and the errno global variable is set to the following code:

ENOMEM
Either the area is not large enough to accommodate the loader information, or there is not enough memory to allocate an equivalent buffer in the kernel.
PT_MULTI
This request turns multiprocess debugging mode on and off, to allow debugging to continue across fork and exec subroutines. A 0 value for the data parameter turns multiprocess debugging mode off, while all other values turn it on. When multiprocess debugging mode is in effect, any fork subroutine allows both the traced process and its newly created process to trap on the next instruction. If a traced process initiated an exec subroutine, the process stops before executing the first instruction of the new image and returns the SIGTRAP signal. The Identifier parameter is interpreted as the process ID of the traced process. The Address and Buffer parameters are ignored.

Also, when multiprocess debugging mode is enabled, the following values are returned from the wait subroutine:

W_SEWTED
Process stopped during execution of the exec subroutine.
W_SFWTED
Process stopped during execution of the fork subroutine.
PT_READ_BLOCK
This request reads a block of data from the debugged process address space. The Address parameter points to the block of data in the process address space, and the Data parameter gives its length in bytes. The value of the Data parameter must not be greater than 1024. The Identifier parameter is interpreted as the process ID of the traced process. The Buffer parameter points to the location in the debugging process address space where the data is copied. Upon successful completion, the ptrace subroutine returns the value of the data parameter.

If this request is unsuccessful, -1 is returned and the errno global variable is set to one of the following codes:

EIO
The Data parameter is less than 1 or greater than 1024.
EIO
The Address parameter is not a valid pointer into the debugged process address space.
EFAULT
The Buffer parameter does not point to a writable location in the debugging process address space.
PT_READ_FPR
This request stores the value of a floating-point register into the location pointed to by the Address parameter. The Data parameter specifies the floating-point register, defined in the sys/reg.h file for the machine type on which the process is executed. The Identifier parameter is interpreted as the process ID of the traced process. The Buffer parameter is ignored.

If this request is unsuccessful, -1 is returned and the errno global variable is set to the following code:

EIO
The Data parameter is not a valid floating-point register. The Data parameter must be in the range 256-287.
PTT_READ_FPRS
This request writes the contents of the 32 floating point registers to the area specified by the Address parameter. This area must be at least 256 bytes long. The Identifier parameter specifies the traced kernel thread. The Data and Buffer parameters are ignored.
PT_READ_GPR
This request returns the contents of one of the general-purpose or special-purpose registers of the debugged process. The Address parameter specifies register returns. The value of the Address parameter is defined in the sys/reg.h file for the machine type on which the process is executed. The Identifier parameter is interpreted as the process ID of the traced process. The Data and Buffer parameters are ignored.

If this request is unsuccessful, -1 is returned and the errno global variable is set to the following code:

EIO
The Address is not a valid general-purpose or special-purpose register. The Address parameter must be in the range 0-31 or 128-136.
PTT_READ_GPRS
This request writes the contents of the 32 general purpose registers to the area specified by the Address parameter. This area must be at least 128 bytes long. The Identifier parameter specifies the traced kernel thread. The Data and Buffer parameters are ignored.
PT_READ_I
or PT_READ_D
These requests return the word-aligned address in the debugged process address space specified by the Address parameter. On all machines currently supported by the Version 4 operating system, the PT_READ_I and PT_READ_D instruction and data requests can be used with equal results. The Identifier parameter is interpreted as the process ID of the traced process. The Data parameter is ignored.

If this request is unsuccessful, -1 is returned and the errno global variable is set to the following code:

EIO
The Address is not word-aligned, or the Address is not valid. User blocks, kernel segments, and kernel extension segments are not considered as valid addresses.
PTT_READ_SPRS
This request writes the contents of the special purpose registers to the area specified by the Address parameter, which points to a ptsprs structure. The Identifier parameter specifies the traced kernel thread. The Data and Buffer parameters are ignored.
PT_REATT
This request allows a new debugger, with the proper permissions, to trace a process that was already traced by another debugger. The Identifier parameter is interpreted as the process ID of the traced process. The Address, Data, and Buffer parameters are ignored.

If this request is unsuccessful, -1 is returned and the errno global variable is set to one the following codes:

ESRCH
The Identifier is not valid; or the traced process is a kernel process.
EPERM
Real or effective user ID of the debugger does not match that of the traced process, or the debugger does not have root authority.
EINVAL
The debugger and the traced process are the same.
PT_REGSET
This request writes the contents of all 32 general purpose registers to the area specified by the Address parameter. This area must be at least 128 bytes. The Identifier parameter is interpreted as the process ID of the traced process. The Data and Buffer parameters are ignored.

If this request is unsuccessful, -1 is returned and the errno global variable is set to the following code:

EIO
The Address parameter points to a location outside of the allocated address space of the process.
PT_TRACE_ME
This request must be issued by the debugged process to be traced. Upon receipt of a signal, this request sets the process trace flag, placing the process in a stopped state, rather than the action specified by the sigaction subroutine. The Identifier, Address, Data, and Buffer parameters are ignored. Do not issue this request if the parent process does not expect to trace the debugged process.

As a security measure, the ptrace subroutine inhibits the set-user-ID facility on subsequent exec subroutines, as shown in the following example:


if((childpid = fork()) == 0)
{ /* child process */
 ptrace(PT_TRACE_ME,0,0,0,0);
   execlp(          )/* your favorite exec*/
   }
else
{    /* parent                          */
     /* wait for child to stop          */
        rc = wait(status)
Note: This is the only request that should be performed by the child. The parent should perform all other requests when the child is in a stopped state.

If this request is unsuccessful, -1 is returned and the errno global variable is set to the following code:

ESRCH
Process is debugged by a process that is not its parent.
PT_WRITE_BLOCK
This request writes a block of data into the debugged process address space. The Address parameter points to the location in the process address space to be written into. The Data parameter gives the length of the block in bytes, and must not be greater than 1024. The Identifier parameter is interpreted as the process ID of the traced process. The Buffer parameter points to the location in the debugging process address space where the data is copied. Upon successful completion, the value of the Data parameter is returned to the debugging process.

If this request is unsuccessful, -1 is returned and the errno global variable is set to one of the following codes:

EIO
The Data parameter is less than 1 or greater than 1024.
EIO
The Address parameter is not a valid pointer into the debugged process address space.
EFAULT
The Buffer parameter does not point to a readable location in the debugging process address space.
PT_WRITE_FPR
This request sets the floating-point register specified by the Data parameter to the value specified by the Address parameter. The Identifier parameter is interpreted as the process ID of the traced process. The Buffer parameter is ignored.

If this request is unsuccessful, -1 is returned and the errno global variable is set to the following code:

EIO
The Data parameter is not a valid floating-point register. The Data parameter must be in the range 256-287.
PTT_WRITE_FPRS
This request updates the contents of the 32 floating point registers with the values specified in the area designated by the Address parameter. This area must be at least 256 bytes long. The Identifier parameter specifies the traced kernel thread. The Data and Buffer parameters are ignored.
PT_WRITE_GPR
This request stores the value of the Data parameter in one of the process general-purpose or special-purpose registers. The Address parameter specifies the register to be modified. Upon successful completion, the value of the Data parameter is returned to the debugging process. The Identifier parameter is interpreted as the process ID of the traced process. The Buffer parameter is ignored.

If this request is unsuccessful, -1 is returned and the errno global variable is set to the following code:

EIO
The Address is not a valid general-purpose or special-special purpose register. The Address parameter must be in the range 0-31 or 128-136.
PTT_WRITE_GPRS
This request updates the contents of the 32 general purpose registers with the values specified in the area designated by the Address parameter. This area must be at least 128 bytes long. The Identifier parameter specifies the traced kernel thread. The Data and Buffer parameters are ignored.
PT_WRITE_I
or PT_WRITE_D
These requests write the value of the data parameter into the address space of the debugged process at the word-aligned address specified by the Address parameter. On all machines currently supported by the Version 4 operating system, instruction and data address spaces are not separated. The PT_WRITE_I and PT_WRITE_D instruction and data requests can be used with equal results. Upon successful completion, the value written into the address space of the debugged process is returned to the debugging process. The Identifier parameter is interpreted as the process ID of the traced process. The Buffer parameter is ignored.

If this request is unsuccessful, -1 is returned and the errno global variable is set to the following code:

EIO
The Address parameter points to a location in a pure procedure space and a copy cannot be made; the Address is not word-aligned; or, the Address is not valid. User blocks, kernel segments, and kernel extension segments are not considered valid addresses.
PTT_WRITE_SPRS
This request updates the special purpose registers with the values in the area specified by the Address parameter, which points to a ptsprs structure. The Identifier parameter specifies the traced kernel thread. The Data and Buffer parameters are ignored.
Identifier Determined by the value of the Request parameter.
Address Determined by the value of the Request parameter.
Data Determined by the value of the Request parameter.
Buffer Determined by the value of the Request parameter.

Error Codes

The ptrace subroutine is unsuccessful when one of the following is true:

EFAULT The Buffer parameter points to a location outside the debugging process address space.
EINVAL The debugger and the traced process are the same; or the Identifier parameter does not identify the thread that caused the exception.
EIO The Request parameter is not one of the values listed, or the Request parameter is not valid for the machine type on which the process is executed.
ENOMEM Either the area is not large enough to accommodate the loader information, or there is not enough memory to allocate an equivalent buffer in the kernel.
EPERM The Identifier parameter corresponds to a kernel thread which is stopped in kernel mode and whose computational state cannot be read or written.
ESRCH The Identifier parameter identifies a process or thread that does not exist, that has not executed a ptrace call with the PT_TRACE_ME request, or that is not stopped.

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Related Information

The exec subroutines, load subroutine, sigaction subroutine, unload subroutine, wait, waitpid, or wait3 subroutine.

The getprocs subroutine, getthrds subroutine.

The dbx command.

[ Previous | Next | Contents | Glossary | Home | Search ]