unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



ptrace(2)							    ptrace(2)



NAME
  ptrace - Traces the execution	of a child process

SYNOPSIS

  #include <&lt;sys/signal.h>&gt;
  #include <&lt;sys/ptrace.h>&gt;

  int  ptrace (
	  long 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 break-
  point	debugging.

  The child process behaves normally until it receives a signal.  When a sig-
  nal 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 facil-
  ity 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 remain-
  ing 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 pro-
      cess.

  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 running on Alpha proces-
      sors, 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:

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

  [EIO]
      Specifies	that the given signal number is	invalid.

  [EIO]
      Specifies	that the addressed used	is either out of bounds	or improperly
      aligned.

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

  [EPERM]
      Specifies	that the specified process cannot be traced.

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

  [EACCES]
      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)