Home Man
Today's Posts

Linux & Unix Commands - Search Man Pages

Unix Version 7 - man page for ptrace (v7 section 2)

PTRACE(2)			       System Calls Manual				PTRACE(2)

       ptrace  -  process trace

       #include <signal.h>

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

       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 signal(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:

       0   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.

       1,2 The	word  in the child process's address space at addr is returned.  If I and D space
	   are separated, request 1 indicates I space, 2 D space.  Addr must be even.  The  child
	   must be stopped.  The input data is ignored.

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

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

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

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

       8   The traced process terminates.

       9   Execution  continues  as in request 7; however, as soon as possible after execution of
	   at least one instruction, execution stops again.  The signal number from the  stop  is
	   SIGTRAP.   (On  the	PDP-11 the T-bit is used and just one instruction is executed; on
	   the Interdata the stop does not take place until a  store  instruction  is  executed.)
	   This is part of the mechanism for implementing breakpoints.

       As indicated, these calls (except for request 0) can be used only when the subject 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 stoppage rather than
       genuine termination.

       To forestall possible fraud,  ptrace  inhibits  the  set-user-id  facility  on  subsequent
       exec(2)	calls.	 If  a traced process calls exec, it will stop before executing the first
       instruction of the new image showing signal SIGTRAP.

       On the Interdata 8/32, `word' means a 32-bit word and `even' means 0 mod 4.

       wait(2), signal(2), adb(1)

       The value -1 is returned if request is invalid, pid is not a traceable  process,  addr  is
       out of bounds, or data specifies an illegal signal number.

       On  the	Interdata  8/32,  `as  soon  as  possible'  (request 7) means `as soon as a store
       instruction has been executed.'

       The request 0 call should be able to specify signals which are to be treated normally  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.

       (ptrace = 26.)
       (data in r0)
       sys ptrace; pid; addr; request
       (value in r0)


All times are GMT -4. The time now is 06:00 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
Show Password