Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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	break-
       point 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 modify its "core im-
       age" 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  stipulates  that	the  child should be left in a stopped
		state on receipt of a signal rather than the  state  specified
		by  func  (see	signal(3C)). The pid, addr, and	data arguments
		are ignored, and a return value	is not defined	for  this  re-
		quest. 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 in-
		struction 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 re-
		turned 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	 sepa-
		rated,	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	execu-
		tion. 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 con-
		sequences 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 li-
       brary.

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

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.10			  22 Mar 2004			    ptrace(3C)

NAME | SYNOPSIS | DESCRIPTION | ERRORS | USAGE | ATTRIBUTES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ptrace&sektion=3c&manpath=SunOS+5.10>

home | help