Unix/Linux Go Back    


BSD 2.11 - man page for ptrace (bsd section 2)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


PTRACE(2)										PTRACE(2)

NAME
       ptrace - process trace

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

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

DESCRIPTION
       Ptrace  provides  a  means  by which a parent process may control the execution of a child
       process, and examine and change its core image.	Its primary use is for the implementation
       of  breakpoint  debugging.   There  are	four  arguments whose interpretation depends on a
       request argument.  Generally, pid is the process ID of the traced process, which must be a
       child (no more distant descendant) of the tracing process.  A process being traced behaves
       normally until it encounters  some  signal  whether  internally	generated  like  "illegal
       instruction"  or externally generated like "interrupt".	See sigvec(2) for the list.  Then
       the traced process enters a stopped state and its parent is notified  via  wait(2).   When
       the  child  is  in  the	stopped  state, its core image can be examined and modified using
       ptrace.	If desired, another ptrace request can then cause the child either  to	terminate
       or to continue, possibly ignoring the signal.

       The value of the request argument determines the precise action of the call:

       PT_TRACE_ME
	   This  request  is the only one used by the child process; it declares that the process
	   is to be traced by its parent.  All the other arguments are ignored.  Peculiar results
	   will ensue if the parent does not expect to trace the child.

       PT_READ_I, PT_READ_D
	   The	word  in the child process's address space at addr is returned.  If I and D space
	   are separated (e.g. historically on a pdp-11), request PT_READ_I  indicates	I  space,
	   PT_READ_D  D  space.   Addr must be even on some machines.  The child must be stopped.
	   The input data is ignored.

       PT_READ_U
	   The word of the system's per-process data area  corresponding  to  addr  is	returned.
	   Addr  must be even on some machines and less than 512.  This space contains the regis-
	   ters and other information about the process;  its  layout  corresponds  to	the  user
	   structure in the system.

       PT_WRITE_I, PT_WRITE_D
	   The	given data is written at the word in the process's address space corresponding to
	   addr, which must be even on some machines.  No useful value is returned.  If I  and	D
	   space  are  separated,  request  PT_WRITE_I	indicates  I  space,  PT_WRITE_D D space.
	   Attempts to write in pure procedure fail if another	process  is  executing	the  same
	   file.

       PT_WRITE_U
	   The	process's  system  data is written, as it is read with request PT_READ_U.  Only a
	   few locations can be written in this way: the general registers,  the  floating  point
	   status and registers, and certain bits of the processor status word.

       PT_CONTINUE
	   The	data  argument is taken as a signal number and the child's execution continues at
	   location addr as if it had incurred that signal.  Normally the signal number  will  be
	   either  0  to indicate that the signal that caused the stop should be ignored, or that
	   value fetched out of the process's image indicating which signal caused the stop.   If
	   addr is (int *)1 then execution continues from where it stopped.

       PT_KILL
	   The traced process terminates.

       PT_STEP
	   Execution continues as in request PT_CONTINUE; however, as soon as possible after exe-
	   cution of at least one instruction, execution stops again.  The signal number from the
	   stop  is  SIGTRAP.	(On the VAX-11 the T-bit is used and just one instruction is exe-
	   cuted.)  This is part of the mechanism for implementing breakpoints.

       As indicated, these calls (except for request PT_TRACE_ME) can be used only when the  sub-
       ject  process  has  stopped.   The wait call is used to determine when a process stops; in
       such a case the "termination" status returned by wait has the value 0177 to indicate stop-
       page rather than genuine termination.

       To  forestall  possible fraud, ptrace inhibits the set-user-id and set-group-id facilities
       on subsequent execve(2) calls.  If a traced process calls execve, it will stop before exe-
       cuting the first instruction of the new image showing signal SIGTRAP.

       On  a  VAX-11,  "word"  also  means  a 32-bit integer, but the "even" restriction does not
       apply.

RETURN VALUE
       A 0 value is returned if the call succeeds.  If the call fails then a -1 is  returned  and
       the global variable errno is set to indicate the error.

ERRORS
       [EIO]	      The request code is invalid.

       [ESRCH]	      The specified process does not exist.

       [EIO]	      The given signal number is invalid.

       [EIO]	      The specified address is out of bounds.

       [EPERM]	      The specified process cannot be traced.

SEE ALSO
       wait(2), sigvec(2), adb(1)

NOTES  (PDP-11)
       On  the	PDP-11	the PT_WRITE_U request may also write the child process's current overlay
       number in the system data area; the T-bit is used to single step the  processor	and  just
       one  instruction is executed for the PT_STEP request; a "word" means a 16-bit integer, and
       the "even" restriction does apply.

BUGS
       Ptrace is unique and arcane; it should be replaced with a special file that can be  opened
       and read and written.  The control functions could then be implemented with ioctl(2) calls
       on this file.  This would be simpler to understand and have much higher performance.

       The request PT_TRACE_ME call should be able to specify signals that are to be treated nor-
       mally  and  not	cause a stop.  In this way, for example, programs with simulated floating
       point (which use "illegal instruction" signals at a very high rate) could  be  efficiently
       debugged.

       The  error  indication,	-1, is a legitimate function value; errno, (see intro(2)), can be
       used to disambiguate.

       It should be possible to stop a process on occurrence of a system call; in this way a com-
       pletely controlled environment could be provided.

4th Berkeley Distribution		   May 23, 1986 				PTRACE(2)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 08:08 AM.