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
	  request
	       Determines the action to	be taken by the	ptrace() func-
	       tion.

	  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 util-
	  ity programs to enable breakpoint debugging.

	  The child process behaves normally until it receives a sig-
	  nal. 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	param-
	       eter 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	pro-
	       cess 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	infor-
	       mation 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 pro-
	       cess errno is set to indicate the error.

	  PT_CONTINUE
	       This request permits the	child process to resume	execu-
	       tion.  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_KILL
	       This request terminates a child process as if the child
	       process called the exit() function.

	  PT_STEP
	       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,	execu-
	       tion stops again	as if the child	process	had received
	       the SIGTRAP signal.

     ERRORS

	  If the 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.

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