Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

RedHat 9 (Linux i386) - man page for ptrace (redhat section 2)

PTRACE(2)			    Linux Programmer's Manual				PTRACE(2)

NAME
       ptrace - process trace

SYNOPSIS
       #include <sys/ptrace.h>

       long ptrace(enum __ptrace_request request, pid_t pid, void *addr, void *data);

DESCRIPTION
       The  ptrace system call provides a means by which a parent process may observe and control
       the execution of another process, and examine and change its core image and registers.  It
       is primarily used to implement breakpoint debugging and system call tracing.

       The  parent  can  initiate  a trace by calling fork(2) and having the resulting child do a
       PTRACE_TRACEME, followed (typically) by an exec(3).  Alternatively, the	parent	may  com-
       mence trace of an existing process using PTRACE_ATTACH.

       While  being traced, the child will stop each time a signal is delivered, even if the sig-
       nal is being ignored.  (The exception is SIGKILL, which has its usual effect.)  The parent
       will be notified at its next wait(2) and may inspect and modify the child process while it
       is stopped.  The parent then causes the child to continue, optionally ignoring the  deliv-
       ered signal (or even delivering a different signal instead).

       When  the parent is finished tracing, it can terminate the child with PTRACE_KILL or cause
       it to continue executing in a normal, untraced mode via PTRACE_DETACH.

       The value of request determines the action to be performed:

       PTRACE_TRACEME
	      Indicates that this process is to be traced by  its  parent.   Any  signal  (except
	      SIGKILL) delivered to this process will cause it to stop and its parent to be noti-
	      fied via wait.  Also, all subsequent calls to exec by this  process  will  cause	a
	      SIGTRAP to be sent to it, giving the parent a chance to gain control before the new
	      program begins execution.  A process probably shouldn't make this  request  if  its
	      parent isn't expecting to trace it.  (pid, addr, and data are ignored.)

       The above request is used only by the child process; the rest are used only by the parent.
       In the following requests, pid specifies the child process to be acted on.   For  requests
       other than PTRACE_KILL, the child process must be stopped.

       PTRACE_PEEKTEXT, PTRACE_PEEKDATA
	      Reads  a word at the location addr in the child's memory, returning the word as the
	      result of the ptrace call.  Linux does not have separate text and data address spa-
	      ces, so the two requests are currently equivalent.  (The argument data is ignored.)

       PTRACE_PEEKUSR
	      Reads a word at offset addr in the child's USER area, which holds the registers and
	      other information about the process (see	<linux/user.h>	and  <sys/user.h>).   The
	      word  is	returned  as the result of the ptrace call.  Typically the offset must be
	      word-aligned, though this might vary by architecture.  (data is ignored.)

       PTRACE_POKETEXT, PTRACE_POKEDATA
	      Copies the word data to location addr in the child's memory.   As  above,  the  two
	      requests are currently equivalent.

       PTRACE_POKEUSR
	      Copies the word data to offset addr in the child's USER area.  As above, the offset
	      must typically be word-aligned.  In order to maintain the integrity of the  kernel,
	      some modifications to the USER area are disallowed.

       PTRACE_GETREGS, PTRACE_GETFPREGS
	      Copies  the  child's  general purpose or floating-point registers, respectively, to
	      location data in the parent.  See <linux/user.h> for information on the  format  of
	      this data.  (addr is ignored.)

       PTRACE_SETREGS, PTRACE_SETFPREGS
	      Copies  the child's general purpose or floating-point registers, respectively, from
	      location data in the parent.  As for PTRACE_POKEUSER, some general purpose register
	      modifications may be disallowed.	(addr is ignored.)

       PTRACE_CONT
	      Restarts	the  stopped  child  process.  If data is non-zero and not SIGSTOP, it is
	      interpreted as a signal to be delivered to  the  child;  otherwise,  no  signal  is
	      delivered.   Thus, for example, the parent can control whether a signal sent to the
	      child is delivered or not.  (addr is ignored.)

       PTRACE_SYSCALL, PTRACE_SINGLESTEP
	      Restarts the stopped child as for PTRACE_CONT, but arranges for  the  child  to  be
	      stopped  at  the	next entry to or exit from a system call, or after execution of a
	      single instruction, respectively.  (The child will also, as usual, be stopped  upon
	      receipt of a signal.)  From the parent's perspective, the child will appear to have
	      been stopped by receipt of a SIGTRAP.  So, for  PTRACE_SYSCALL,  for  example,  the
	      idea  is	to  inspect  the  arguments to the system call at the first stop, then do
	      another PTRACE_SYSCALL and inspect the return value of the system call at the  sec-
	      ond stop.  (addr is ignored.)

       PTRACE_KILL
	      Sends the child a SIGKILL to terminate it.  (addr and data are ignored.)

       PTRACE_ATTACH
	      Attaches to the process specified in pid, making it a traced "child" of the current
	      process; the behavior of the child is as if it had done a PTRACE_TRACEME.  The cur-
	      rent  process  actually  becomes	the parent of the child process for most purposes
	      (e.g., it will receive notification of child events and appears in ps(1) output  as
	      the child's parent), but a getppid(2) by the child will still return the pid of the
	      original parent.	The child is sent  a  SIGSTOP,	but  will  not	necessarily  have
	      stopped  by  the	completion  of this call; use wait to wait for the child to stop.
	      (addr and data are ignored.)

       PTRACE_DETACH
	      Restarts the stopped child as for PTRACE_CONT, but first detaches from the process,
	      undoing the reparenting effect of PTRACE_ATTACH, and the effects of PTRACE_TRACEME.
	      Although perhaps not intended, under Linux a traced child can be detached  in  this
	      way regardless of which method was used to initiate tracing.  (addr is ignored.)

NOTES
       Although  arguments  to	ptrace are interpreted according to the prototype given, GNU libc
       currently declares ptrace as a variadic function with only  the	request  argument  fixed.
       This  means  that unneeded trailing arguments may be omitted, though doing so makes use of
       undocumented gcc(1) behavior.

       init(8), the process with pid 1, may not be traced.

       The layout of the contents of memory and the USER area are quite OS- and architecture-spe-
       cific.

       The size of a "word" is determined by the OS variant (e.g., for 32-bit Linux it's 32 bits,
       etc.).

       Tracing causes a few subtle differences in the semantics of traced processes.   For  exam-
       ple,  if  a  process  is attached to with PTRACE_ATTACH, its original parent can no longer
       receive notification via wait when it stops, and there is no way for  the  new  parent  to
       effectively simulate this notification.

       This  page  documents the way the ptrace call works currently in Linux.	Its behavior dif-
       fers noticeably on other flavors of Unix.  In any case, use of ptrace is  highly  OS-  and
       architecture-specific.

       The  SunOS  man page describes ptrace as "unique and arcane", which it is.  The proc-based
       debugging interface present in Solaris 2 implements a superset of ptrace functionality  in
       a more powerful and uniform way.

RETURN VALUE
       On  success,  PTRACE_PEEK* requests return the requested data, while other requests return
       zero.  On error, all requests return -1, and errno(3) is  set  appropriately.   Since  the
       value returned by a successful PTRACE_PEEK* request may be -1, the caller must check errno
       after such requests to determine whether or not an error occurred.

ERRORS
       EPERM  The specified process cannot be traced.  This  could  be	because  the  parent  has
	      insufficient privileges; non-root processes cannot trace processes that they cannot
	      send signals to or those	running  setuid/setgid	programs,  for	obvious  reasons.
	      Alternatively, the process may already be being traced, or be init (pid 1).

       ESRCH  The specified process does not exist, or is not currently being traced by the call-
	      er, or is not stopped (for requests that require that).

       EIO    request is invalid, or an attempt was made to read from or write to an invalid area
	      in  the  parent's or child's memory, or there was a word-alignment violation, or an
	      invalid signal was specified during a restart request.

       EFAULT There was an attempt to read from or write to an invalid area in	the  parent's  or
	      child's  memory,	probably  because the area wasn't mapped or accessible.  Unfortu-
	      nately, under Linux, different variations of this fault will return EIO  or  EFAULT
	      more or less arbitrarily.

CONFORMING TO
       SVr4, SVID EXT, AT&T, X/OPEN, BSD 4.3

SEE ALSO
       gdb(1), strace(1), execve(2), fork(2), signal(2), wait(2), exec(3)

Linux 2.2.10				    1999-11-07					PTRACE(2)


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

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
UNIX.COM Login
Username:
Password:  
Show Password