Index for Section 2

Alphabetical listing for P

Bottom of page

ptrace(2)
NAME
  ptrace - Trace the execution of a child process

SYNOPSIS
  #include <sys/signal.h>
  #include <sys/ptrace.h>

  int ptrace(
	  long int request,
	  long int process,
	  ulong_t *address,
	  ulong_t data );

PARAMETERS
  request Determines the action to be taken by the ptrace() function.

  process Specifies the process ID.

  address Determined by the value of the request parameter.

  data	  Determined 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 can 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 values in the following list.
  Only the PT_TRACE_ME request can 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 the following requests are
  made.

  PT_TRACE_ME (0)
      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 (1, 2)
      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 produce 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 (3)
      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 (4,5)
      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 with the exception of System V
      behavior. System V behavior for libsys5 returns the value written, and
      for libc behavior it returns zero (0) for success.

      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 (6)
      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
      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 indicate the error.

  PT_CONTINUE (7)
      This request permits the child process to resume execution. When the
      data parameter is zero (0), 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.

      System V behavior for libsys5 returns the value written, and for libc
      behavior it returns zero (0) for success.	 This request fails when the
      data parameter is not zero (0) 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_KILL (8)
      This request terminates a child process as if the child process called
      the exit() function.

  PT_STEP (9)
      This 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.

      Note that for the Tru64 UNIX operating system, the PT_STEP request
      parameter may cause the traced program to execute an indefinite number
      of instructions if the current instruction is a branch instruction.

ERRORS
  If the ptrace() function fails, errno is set to one of the following
  values:

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

  [EINVAL]
	  An invalid location was used for the system's per-process data area
	  or the process parameter is out of range.

  [EIO]	  One of the following conditions applies:

	    ·  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.

	    ·  The given signal number is invalid.

	    ·  The addressed used is either out of bounds or improperly
	       aligned.

  [EPERM] The specified process cannot be traced.

  [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.

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

Index for Section 2

Alphabetical listing for P

Top of page