home | help 
PTRACE(2)		       System Calls Manual		       PTRACE(2)

NAME
     ptrace -- process tracing and debugging

LIBRARY
     Standard C Library (libc, -lc)

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

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

DESCRIPTION
     The ptrace() system call provides tracing and debugging facilities.  It al-
     lows  one	process  (the  tracing	process)  to control another (the traced
     process).	The tracing process must first attach to the traced process, and
     then issue a series of ptrace() system calls to control  the  execution  of
     the  process, as well as access process memory and register state.  For the
     duration of the tracing session, the traced process will be  "re-parented",
     with  its parent process ID (and resulting behavior) changed to the tracing
     process.  It is permissible for a tracing process to attach  to  more  than
     one  other  process  at a time.  When the tracing process has completed its
     work, it must detach the traced process; if a tracing process exits without
     first detaching all processes it has  attached,  those  processes	will  be
     killed.

     Most  of the time, the traced process runs normally, but when it receives a
     signal (see sigaction(2)), it stops.  The tracing process	is  expected  to
     notice  this  via	wait(2) or the delivery of a SIGCHLD signal, examine the
     state of the stopped process, and cause it to terminate or continue as  ap-
     propriate.   The  signal may be a normal process signal, generated as a re-
     sult of traced process behavior, or use of the kill(2) system call;  alter-
     natively,	it  may  be generated by the tracing facility as a result of at-
     taching, system calls, or stepping by the	tracing  process.   The  tracing
     process may choose to intercept the signal, using it to observe process be-
     havior (such as SIGTRAP), or forward the signal to the process if appropri-
     ate.  The ptrace() system call is the mechanism by which all this happens.

     The request argument specifies what operation is being performed; the mean-
     ing  of  the rest of the arguments depends on the operation, but except for
     one special case noted below, all ptrace() calls are made	by  the  tracing
     process,  and  the  pid  argument	specifies  the	process ID of the traced
     process.  The request argument can be:

     PT_TRACE_ME   This request is the only one used by the traced  process;  it
		   declares that the process expects to be traced by its parent.
		   All	the other arguments are ignored.  (If the parent process
		   does not expect to trace  the  child,  it  will  probably  be
		   rather  confused  by  the  results;	once  the traced process
		   stops, it cannot be made to continue  except  via  ptrace().)
		   When  a  process has used this request and calls execve(2) or
		   any of the routines built on it (such as execv(3)),	it  will
		   stop before executing the first instruction of the new image.
		   Also,  any setuid or setgid bits on the executable being exe-
		   cuted will be ignored.

     PT_READ_I, PT_READ_D
		   These requests read a single int  of  data  from  the  traced
		   process's address space.  Traditionally, ptrace() has allowed
		   for machines with distinct address spaces for instruction and
		   data,  which  is  why  there  are two requests: conceptually,
		   PT_READ_I reads from  the  instruction  space  and  PT_READ_D
		   reads  from the data space.	In the current FreeBSD implemen-
		   tation, these two requests  are  completely	identical.   The
		   addr  argument specifies the address (in the traced process's
		   virtual address space) at which the read is to be done.  This
		   address does not have to meet any alignment constraints.  The
		   value read is returned as the return value from ptrace().

     PT_WRITE_I, PT_WRITE_D
		   These requests parallel PT_READ_I and PT_READ_D, except  that
		   they  write rather than read.  The data argument supplies the
		   value to be written.

     PT_IO	   This request allows reading and writing arbitrary amounts  of
		   data  in  the traced process's address space.  The addr argu-
		   ment specifies a pointer to a struct ptrace_io_desc, which is
		   defined as follows:

		   struct ptrace_io_desc {
			   int	   piod_op;	   /* I/O operation */
			   void    *piod_offs;	   /* child offset */
			   void    *piod_addr;	   /* parent offset */
			   size_t  piod_len;	   /* request length */
		   };

		   /*
		    * Operations in piod_op.
		    */
		   #define PIOD_READ_D	   1	   /* Read from D space */
		   #define PIOD_WRITE_D    2	   /* Write to D space */
		   #define PIOD_READ_I	   3	   /* Read from I space */
		   #define PIOD_WRITE_I    4	   /* Write to I space */

		   The data argument is ignored.  The  actual  number  of  bytes
		   read or written is stored in piod_len upon return.

     PT_CONTINUE   The traced process continues execution.  The addr argument is
		   an  address specifying the place where execution is to be re-
		   sumed (a new value for the program counter), or (caddr_t)1 to
		   indicate that execution is to pick up where it left off.  The
		   data argument provides a signal number to be delivered to the
		   traced process as it resumes execution, or 0 if no signal  is
		   to be sent.

     PT_STEP	   The	traced	process  is single stepped one instruction.  The
		   addr argument should be passed (caddr_t)1.  The data argument
		   provides a signal  number  to  be  delivered  to  the  traced
		   process  as	it resumes execution, or 0 if no signal is to be
		   sent.

     PT_KILL	   The traced process terminates, as  if  PT_CONTINUE  had  been
		   used with SIGKILL given as the signal to be delivered.

     PT_ATTACH	   This request allows a process to gain control of an otherwise
		   unrelated process and begin tracing it.  It does not need any
		   cooperation from the to-be-traced process.  In this case, pid
		   specifies the process ID of the to-be-traced process, and the
		   other  two arguments are ignored.  This request requires that
		   the target process must have the same real UID as the tracing
		   process, and that it must not be executing a setuid or setgid
		   executable.	(If the tracing  process  is  running  as  root,
		   these  restrictions	do not apply.)	The tracing process will
		   see the newly-traced process stop and may then control it  as
		   if it had been traced all along.

     PT_DETACH	   This request is like PT_CONTINUE, except that it does not al-
		   low	specifying an alternate place to continue execution, and
		   after it succeeds, the traced process is no longer traced and
		   continues execution normally.

     PT_GETREGS    This request reads the  traced  process's  machine  registers
		   into the "struct reg" (defined in <machine/reg.h>) pointed to
		   by addr.

     PT_SETREGS    This  request  is  the  converse  of PT_GETREGS; it loads the
		   traced process's machine registers from the "struct reg" (de-
		   fined in <machine/reg.h>) pointed to by addr.

     PT_GETFPREGS  This request reads the traced process's floating-point regis-
		   ters into the "struct  fpreg"  (defined  in	<machine/reg.h>)
		   pointed to by addr.

     PT_SETFPREGS  This  request  is  the converse of PT_GETFPREGS; it loads the
		   traced process's floating-point registers  from  the  "struct
		   fpreg" (defined in <machine/reg.h>) pointed to by addr.

     PT_GETDBREGS  This  request reads the traced process's debug registers into
		   the "struct dbreg" (defined in <machine/reg.h>) pointed to by
		   addr.

     PT_SETDBREGS  This request is the converse of PT_GETDBREGS;  it  loads  the
		   traced process's debug registers from the "struct dbreg" (de-
		   fined in <machine/reg.h>) pointed to by addr.

     PT_LWPINFO    This request can be used to obtain information about the ker-
		   nel	thread,  also known as light-weight process, that caused
		   the traced process to stop.	The addr  argument  specifies  a
		   pointer  to a struct ptrace_lwpinfo, which is defined as fol-
		   lows:

		   struct ptrace_lwpinfo {
			   lwpid_t pl_lwpid;	   /* LWP described. */
			   int	   pl_event;	   /* Event received. */
		   };

		   The data argument is to be set to the size of  the  structure
		   known to the caller.  This allows the structure to grow with-
		   out affecting older programs.

     PT_GETNUMLWPS
		   This  request returns the number of kernel threads associated
		   with the traced process.

     PT_GETLWPLIST
		   This request can be used to get the current thread  list.   A
		   pointer to an array of type lwpid_t should be passed in addr,
		   with the array size specified by data.  The return value from
		   ptrace() is the count of array entries filled in.

     Additionally, machine-specific requests can exist.

RETURN VALUES
     Some requests can cause ptrace() to return -1 as a non-error value; to dis-
     ambiguate, errno can be set to 0 before the call and checked afterwards.

ERRORS
     The ptrace() system call may fail if:

     [ESRCH]
			*   No process having the specified process ID exists.

     [EINVAL]
			*   A process attempted to use PT_ATTACH on itself.
			*   The  request  argument  was not one of the legal re-
			    quests.
			*   The signal number (in data) to PT_CONTINUE was  nei-
			    ther 0 nor a legal signal number.
			*   PT_GETREGS,  PT_SETREGS, PT_GETFPREGS, PT_SETFPREGS,
			    PT_GETDBREGS, or PT_SETDBREGS  was	attempted  on  a
			    process  with  no valid register set.  (This is nor-
			    mally true only of system processes.)

     [EBUSY]
			*   PT_ATTACH was attempted on a process  that	was  al-
			    ready being traced.
			*   A request attempted to manipulate a process that was
			    being traced by some process other than the one mak-
			    ing the request.
			*   A request (other than PT_ATTACH) specified a process
			    that was not stopped.

     [EPERM]
			*   A request (other than PT_ATTACH) attempted to manip-
			    ulate a process that was not being traced at all.
			*   An attempt was made to use PT_ATTACH on a process in
			    violation of the requirements listed under PT_ATTACH
			    above.

SEE ALSO
     execve(2),     sigaction(2),    wait(2),	 execv(3),    i386_clr_watch(3),
     i386_set_watch(3)

HISTORY
     The ptrace() function appeared in Version 7 AT&T UNIX.

FreeBSD 7.0			  April 9, 2007 		       PTRACE(2)
home | help