ptrace(2)							System Calls Manual							 ptrace(2)

NAME

       ptrace - Traces the execution of a child process

SYNOPSIS

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

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

PARAMETERS

       Determines  the	action	to  be taken by the ptrace function.  Specifies the process ID.  Determined by the value of the request parameter.
       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.  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.  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].  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].  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].  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.  This request permits the child process to resume  exe-
	      cution.	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].  This request terminates a child process as if the child process called the exit function.
	      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 running on Alpha processors, the PT_STEP request parameter may cause the  traced  pro-
	      gram 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: Specifies that 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.  Specifies that the given signal number is  invalid.
       Specifies  that	the addressed used is either out of bounds or improperly aligned.  Specifies that 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.  Specifies  that  the  specified
       process cannot be traced.  Specifies that an invalid location was used for the system's per-process data area or that the process parameter
       is out of range.  Specifies that the location within the system's per-process data area could not be modified.

RELATED INFORMATION

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

																	 ptrace(2)