ptrace(3C)						   Standard C Library Functions 						ptrace(3C)

NAME

       ptrace - allows a parent process to control the execution of a child process

SYNOPSIS

       #include <unistd.h>
       #include <sys/types.h>

       int ptrace(int request, pid_t pid, int addr, int data);

DESCRIPTION

       The  ptrace()  function	allows	a parent process to control the execution of a child process. Its primary use is for the implementation of
       breakpoint debugging. The child process behaves normally until it encounters a signal (see signal.h(3HEAD)), at	which  time  it  enters  a
       stopped	state and its parent is notified by the wait(3C) function. When the child is in the stopped state, its parent can examine and mod-
       ify its "core image" using ptrace(). Also, the parent can cause the child either to terminate or continue, with the possibility of ignoring
       the signal that caused it to stop.

       The request argument determines the action to be taken by ptrace() and is one of the following:

       0    This  request  must be issued by the child process if it is to be traced by its parent. It turns on the child's trace flag that stipu-
	    lates that the child should be left in a stopped state on receipt of a signal rather than  the  state  specified  by  func	(see  sig-
	    nal(3C)). The pid, addr, and data arguments are ignored, and a return value is not defined for this request. Peculiar results ensue if
	    the parent does not expect to trace the child.

       The remainder of the requests can only be used by the parent process. For each, pid is the process ID of the child. The child must be in  a
       stopped state before these requests are made.

       1, 2    With  these requests, the word at location addr in the address space of the child is returned to the parent process. If instruction
	       and data space are separated, request 1 returns a word from instruction space, and request 2 returns a word  from  data	space.	If
	       instruction  and  data  space are not separated, either request 1 or request 2 may be used with equal results. The data argument is
	       ignored. These two requests fail if addr is not the start address of a word, in which case -1 is returned to the parent process and
	       the parent's errno is set to EIO.

       3       With  this request, the word at location addr in the child's user area in the system's address space (see <sys/user.h>) is returned
	       to the parent process. The data argument is ignored. This request fails if addr is not the start address of a word  or  is  outside
	       the user area, in which case -1 is returned to the parent process and the parent's errno is set to EIO.

       4, 5    With  these  requests,  the  value  given  by the data argument is written into the address space of the child at location addr. If
	       instruction and data space are separated, request 4 writes a word into instruction space, and request 5 writes  a  word	into  data
	       space.  If  instruction and data space are not separated, either request 4 or request 5 may be used with equal results. On success,
	       the value written into the address space of the child is returned to the parent. These two requests fail if addr is not	the  start
	       address of a word. On failure -1 is returned to the parent process and the parent's errno is set to EIO.

       6       With  this  request,  a few entries in the child's user area can be written. data gives the value that is to be written and addr is
	       the location of the entry. The few entries that can be written are the general registers and the condition codes of  the  Processor
	       Status Word.

       7       This request causes the child to resume execution. If the data argument is 0, all pending signals including the one that caused the
	       child to stop are canceled before it resumes execution. If the data argument is a valid signal number, the child resumes  execution
	       as  if  it  had	incurred  that	signal,  and any other pending signals are canceled. The addr argument must be equal to 1 for this
	       request. On success, the  value of data is returned to the parent. This request fails if data is not 0 or a valid signal number, in
	       which case -1 is returned to the parent process and the parent's errno is set to EIO.

       8       This request causes the child to terminate with the same consequences as exit(2).

       9       This  request  sets  the  trace	bit in the Processor Status Word of the child and then executes the same steps as listed above for
	       request 7. The trace bit causes an interrupt on completion of one machine instruction. This effectively allows single  stepping	of
	       the child.

       To  forestall  possible	fraud,	ptrace() inhibits the set-user-ID facility on subsequent calls to one of the exec family of functions (see
       exec(2)). If a traced process calls one of these functions, it stops before executing the first instruction of the new image showing signal
       SIGTRAP.

ERRORS

       The ptrace() function will fail if:

       EIO	The request argument is an illegal number.

       EPERM	The calling process does not have appropriate privileges to control the calling process. See proc(4).

       ESRCH	The pid argument identifies a child that does not exist or has not executed a ptrace() call with request 0.

USAGE

       The ptrace() function is available only with the 32-bit version of libc(3LIB). It is not available with the 64-bit version of this library.

       The  /proc debugging interfaces should be used instead of ptrace(), which provides quite limited debugger support and is itself implemented
       using the /proc interfaces. There is no actual ptrace() system call in the kernel. See proc(4) for  descriptions  of  the  /proc  debugging
       interfaces.

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Standard			   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Safe			   |
       +-----------------------------+-----------------------------+

SEE ALSO

       exec(2), exit(2), libc(3LIB), signal(3C), signal.h(3HEAD), wait(3C), proc(4), attributes(5)

SunOS 5.11							    22 Mar 2004 							ptrace(3C)