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

FreeBSD Manual Pages

  
 
  

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

NAME
       ptrace()	- process trace

SYNOPSIS
   Remarks
       is  not available on IPF	systems.  Its use is discouraged because it is
       targeted	for removal from HP-UX.	 Use ttrace(2) instead.

       Much of the functionality of is	highly	dependent  on  the  underlying
       hardware.   An application that uses this system	call should not	be ex-
       pected to be portable across architectures or implementations.

DESCRIPTION
       The system call provides	a means	by which a process can control the ex-
       ecution	of another process.  Its primary use is	for the	implementation
       of breakpoint debugging (see adb(1)).  The traced process behaves  nor-
       mally  until  it	 encounters  a signal (see signal(2) for the list), at
       which time it enters a stopped state and	the tracing process  is	 noti-
       fied via	(see wait(2)).

       A  traced process may also enter	the stopped state without encountering
       a signal.  This can happen if the traced	process	stops in  response  to
       specific	 events	that it	encounters during the course of	its execution.
       To make this happen, the	tracing	process	 has  to  set  specific	 event
       flags in	the context of the traced process.  This mechanism will	be de-
       scribed later in	greater	detail.

       When the	traced process is in the stopped state,	 the  tracing  process
       can  use	 to  examine  and  modify the "core image".  Also, the tracing
       process can cause the traced process to either terminate	 or  continue,
       with the	possibility of ignoring	the signal that	caused it to stop.

       To  forestall possible fraud, inhibits the set-user-ID facility on sub-
       sequent calls.  If a traced process calls it stops before executing the
       first instruction of the	new image, showing signal

       The request argument determines the precise action to be	taken by It is
       one of the values described in the rest of this section.

       The following request is	used by	the child process that will be traced.

	      This request must	be issued by a child process
			     if	it is to be traced by its parent.  It turns on
			     the child's trace flag, which stipulates that the
			     child should be left in a stopped state upon  re-
			     ceipt of a	signal rather than the state specified
			     by	func (see signal(2)).  The  pid,  addr,	 data,
			     and  addr2	 arguments  are	 ignored, and a	return
			     value is not defined for this request.   Peculiar
			     results  occur  if	 the parent does not expect to
			     trace the child.

       The remainder of	the requests can only be used by the tracing  process.
       For each, pid is	the process ID of the process being traced, which must
       be in a stopped state before these requests are made.  The responsibil-
       ity  of ensuring	that the traced	process	is in a	stopped	state before a
       request is issued, lies with the	tracing	process.

	      With these requests, the word at location
			     addr in the address space of the  traced  process
			     is	 returned to the tracing process.  If instruc-
			     tion (I) and data (D) space  are  separated,  re-
			     quest  returns  a	word from I space, and request
			     returns a word from D space.  If I	 and  D	 space
			     are not separated,	either request produces	equiv-
			     alent results.  The data and addr2	arguments  are
			     ignored.

			     These  two	requests fail if addr is not the start
			     address of	a word,	in which case a	value of -1 is
			     returned to the tracing process and its is	set to
			     [EIO].

	      With this	request, the word at location
			     addr in the user area of the  traced  process  in
			     the  system's  address  space (see	is returned to
			     the tracing process.  Addresses in	this area  are
			     system  dependent,	 but start at zero.  The limit
			     can be derived from The data and addr2  arguments
			     are ignored.

			     This  request  fails if addr is not the start ad-
			     dress of a	word or	is outside the user  area,  in
			     which case	a value	of -1 is returned to the trac-
			     ing process and its is set	to [EIO].

	      With these requests, the value given by the
			     data argument is written into the	address	 space
			     of	the traced process at location addr.  writes a
			     word into I space,	and writes a word in D	space.
			     Upon  successful  completion,  the	 value written
			     into the address space of the traced  process  is
			     returned to the tracing process.  The addr2 argu-
			     ment is ignored.

			     These two requests	fail if	addr is	not the	 start
			     address  of a word, or if addr is a location in a
			     pure procedure space and either  another  process
			     is	executing in that space	or the tracing process
			     does not have write  access  for  the  executable
			     file  corresponding to that space.	 Upon failure,
			     a value of	-1 is returned to the tracing  process
			     and its is	set to [EIO].

	      This request is not supported.
			     Therefore,	 it returns -1,	sets to	[EIO] and does
			     not affect	the user area of the traced process.

	      With this	request, the word at location
			     addr in the structure at the  base	 of  the  per-
			     process  kernel  stack is returned	to the tracing
			     process.  addr must be word-aligned and less than
			     (see and The structure contains the registers and
			     other information about the  process.   The  data
			     and addr2 arguments are ignored.

	      The	     structure	at  the	base of	the per-process	kernel
			     stack is written as it is read with request  Only
			     a	few  locations can be written in this way: the
			     general registers,	most floating-point registers,
			     a	few control registers, and certain bits	of the
			     interruption processor status  word.   The	 addr2
			     argument is ignored.

	      These requests are identical to
			     and  except  that the data	argument specifies the
			     number of bytes to	read and  the  addr2  argument
			     specifies where to	store that data	in the tracing
			     process.

	      These requests are identical to
			     and except	that the data argument	specifies  the
			     number  of	 bytes to write	and the	addr2 argument
			     specifies where to	read that data in the  tracing
			     process.

	      This request causes the traced process to	resume execution.
			     If	 the  data argument is 0, all pending signals,
			     including the one that caused the traced  process
			     to	 stop,	are  canceled before it	resumes	execu-
			     tion.  If the data	argument  is  a	 valid	signal
			     number,  the  traced process resumes execution as
			     if	it had incurred	that  signal,  and  any	 other
			     pending signals are canceled.  The	addr2 argument
			     is	ignored.

			     If	the addr argument is not  1,  the  Instruction
			     Address  Offset Queue (program counter) is	loaded
			     with the values addr  and	before	execution  re-
			     sumes.   Otherwise,  execution  resumes  from the
			     point where it was	interrupted.

			     Upon successful completion, the value of data  is
			     returned to the tracing process.

			     This  request  fails  if data is not 0 or a valid
			     signal number, in which case a value of -1	is re-
			     turned  to	 the tracing process and its is	set to
			     [EIO].

	      This request causes the traced process to	terminate
			     with the same consequences	as The addr, data, and
			     addr2 arguments are ignored.

	      This request causes a flag to be set so that an interrupt	occurs
			     upon  the	completion of one machine instruction.
			     It	then executes the same steps as	 listed	 above
			     for  request  If the processor does not provide a
			     trace bit,	this request returns an	 error.	  This
			     effectively  allows single-stepping of the	traced
			     process.

			     Whether or	not the	trace bit  remains  set	 after
			     this interrupt is a function of the hardware.

	      This request stops the process identified	by
			     pid  and  allows the calling process to trace it.
			     Process pid does not have to be a	child  of  the
			     calling process, but the effective	user ID	of the
			     calling process must match	 the  real  and	 saved
			     user  ID of process pid unless the	effective user
			     ID	of the	tracing	 process  is  superuser.   The
			     calling  process  can use the system call to wait
			     for process pid to	stop.	The  addr,  data,  and
			     addr2 arguments are ignored.

	      This request detaches the	traced process
			     pid  and  allows  it to continue its execution in
			     the manner	of

			     If	the addr argument is not  1,  the  Instruction
			     Address  Offset Queue (program counter) is	loaded
			     with the values addr and addr2.

	      This request causes the traced process to	resume execution
			     with all its pending signals intact.  If the data
			     argument  is 0, the signal	that caused the	traced
			     process to	stop is	 canceled  before  the	traced
			     process  resumes execution.  If the data argument
			     is	a valid	signal number, the traced process  re-
			     sumes  execution  as if it	had received that sig-
			     nal.  The addr argument must be equal  to	1  for
			     this  request.   The  addr2  argument is ignored.
			     Upon successful completion, the value of data  is
			     returned to the tracing process.

			     This  request  fails  if data is not 0 or a valid
			     signal number, in which case a value of -1	is re-
			     turned  to	 the tracing process and its is	set to
			     [EIO].

	      This request causes a flag to be set so that an interrupt	occurs
			     upon the completion of one	 machine  instruction.
			     It	 then  executes	the same steps as listed above
			     for request If the	processor does not  provide  a
			     trace  bit,  this request returns an error.  This
			     effectively allows	single stepping	of the	traced
			     process.

			     Whether  or  not  the trace bit remains set after
			     this interrupt is a function of the hardware.

       As noted	earlier, a tracing process can set event flags in the  context
       of the traced process to	make it	respond	to specific events, during its
       execution.  These events	are:

	      This event flag indicates	that,
			     when processing signals, the traced process needs
			     to	examine	signal mask bits set in	its context by
			     the tracing process.  See the ptrace_event	struc-
			     ture description under for	further	details.

			     If	the signal being processed has its signal mask
			     bit set, signal processing	 continues  as	though
			     the  process were not traced.  The	traced process
			     is	not stopped and	the tracing process is not no-
			     tified  of	the signal.  If	the signal mask	bit is
			     not set  for  the	signal	being  processed,  the
			     traced process is stopped and the tracing process
			     is	notified via (see wait(2)).

			     Note that the signal is an	exception to this rule
			     in	that it	can never be unmasked; that is,	it be-
			     haves as though its mask bit were always set, re-
			     gardless  of  whether  or	not its	mask bit is in
			     fact set.	Consequently, a	signal cannot be  used
			     to	stop a traced process.

			     In	this respect, a	signal is also special in that
			     it	is specifically	used to	stop traced processes.
			     A	signal should therefore	never be masked.  Set-
			     ting a mask bit for  will	result	in  unexpected
			     system behavior.

	      This event flag indicates	that the traced	process
			     needs to take special action when it invokes When
			     set, both the parent  and	child  processes  stop
			     (the  child  after	 marking  itself  as  a	traced
			     process  and  adopting  its  parent's  debugger).
			     Both  processes log the fact that they stopped in
			     response to a event.  Further, the	child's	pid is
			     logged  in	the parent's context, and the parent's
			     pid is logged in the child's context.  The	 child
			     does  not	inherit	its parent's event flags.  See
			     the ptrace_state structure	description under  for
			     further details.

	      This event flag indicates	that the traced	process
			     needs to take special action when it invokes When
			     set, the child process stops after	marking	itself
			     as	a traced process and adopting its parent's de-
			     bugger.  The fact that a event was	 responded  to
			     is	 logged	 in the	context	of both	the parent and
			     child processes.  Further,	 the  child's  pid  is
			     logged  in	the parent's context, and the parent's
			     pid is logged in the child's context.  The	 child
			     does  not	inherit	its parent's event flags.  See
			     the ptrace_state structure	description under  for
			     further  details.	 It  is	important to note that
			     the warnings with respect to (see vfork(2)), con-
			     tinue  to apply here.  In particular, it needs to
			     be	remembered that, when the child	process	stops,
			     its  parent  process  is  suspended, and that the
			     child borrows the parent's	memory and  thread  of
			     control  until  a call to or an exit (either by a
			     call to or	abnormally (see	exec(2)	and exit(2))).

	      This event flag indicates	that the traced	process
			     needs to take special action when it invokes When
			     set,  the	traced process stops after logging the
			     fact that it stopped in response to a event.   It
			     also  logs	 information pertaining	to the path or
			     file argument of This includes a pointer  to  the
			     path  name	string and the length of the path name
			     string.  See the ptrace_state structure  descrip-
			     tion under	for further details.

	      This event flag indicates	that the traced	process
			     needs to take special action when it invokes When
			     set, the traced process stops after  logging  the
			     fact that it stopped in response to a event.

	      This  request  is	 used  by the calling process to specify event
	      flags
			     and signal	mask values that it wants  the	traced
			     process to	respond	to.  It	does so	by writing the
			     contents of the ptrace_event  data	 structure  in
			     the  user	space pointed to by addr into the con-
			     text of the traced	process.   The	data  argument
			     specifies	the number of bytes to be transferred.
			     The addr2 argument	is ignored.

			     The request fails if the number of	 bytes	speci-
			     fied  is  less than zero or greater than the size
			     of	the ptrace_event structure, and	its is set  to
			     [EIO].

			     Event flags are set in the	pe_set_event member of
			     the ptrace_event data structure.  An  event  flag
			     is	 set when the tracing process wants the	traced
			     process to	respond	to a particular	event.	As de-
			     tailed  earlier,  the event flags defined are and
			     See the definition	of events_t in	for  more  de-
			     tails.

			     Signal mask values	are set	in the pe_signals mem-
			     ber of the	ptrace_event structure.	 This field is
			     qualified	by  a  event  flag  being  set	in the
			     pe_set_event member.   Mask  values  set  in  the
			     pe_signals	member correspond to signals that need
			     to	be masked from the tracing  process  when  re-
			     ceived  by	the traced process; that is, these are
			     signals received by the traced process  that  the
			     tracing  process  does  not  want	to be informed
			     about.  The pe_signals member is described	by the
			     type definition sigset_t, which is	defined	in

	      This request is used by the calling process
			     to	determine the event flags and signal mask val-
			     ues that have been	set in	the  traced  process's
			     context  by  the last request.  The data argument
			     specifies the number bytes	to be  read  from  the
			     context   of   the	  traced   process   into  the
			     ptrace_event data structure in user space pointed
			     to	by addr	.  The addr2 argument is ignored.

			     The  request  fails  if  the  number of bytes re-
			     quested is	less than zero	or  greater  than  the
			     size  of  the  ptrace_event structure, and	its is
			     set to [EIO].

	      This request is used by the calling process to access
			     state information logged by  the  traced  process
			     after it (the traced process) has responded to an
			     event.  The request reads data bytes of data from
			     the    traced    process's	  context   into   the
			     ptrace_state data structure in user space pointed
			     to	by addr	.  The addr2 argument is ignored.

			     The  ptrace_state	data structure is described in
			     and has the following members:

			     The event that the	traced	process	 responded  to
			     and stopped is logged in the pe_report_event mem-
			     ber.  One of or is	logged here.  See the  defini-
			     tion of events_t in for more details.

			     If	the event that the traced process responded to
			     was then  the  pe_path_len	 member	 provides  the
			     length of the path	name string (which is the path
			     name of the executable file)  not	including  the
			     null terminating character.

			     If	the event that the traced process responded to
			     was or then the pe_other_pid member provides  the
			     parent's  pid when	accessed from the child's con-
			     text, and the child's pid when accessed from  the
			     parent's context.

			     The  request  fails  if  the  number of bytes re-
			     quested is	less than zero	or  greater  than  the
			     size of the ptrace_event structure	and its	is set
			     to	[EIO].

	      If the event that	the traced process responded  to  and  stopped
	      was
			     then  this	request	is used	by the calling process
			     to	access the path	name of	 the  executable  file
			     provided  as  a  path or file argument to The re-
			     quest reads data bytes of data of the  path  name
			     string from the traced process's context into the
			     data buffer in user space pointed to  by  addr  .
			     The  addr2	 argument  is ignored.	In the typical
			     case,  data  is  equal  to	 the  value   of   the
			     pe_path_len  member of the	ptrace_state structure
			     returned via the request.

			     If	the number of bytes requested is greater  than
			     zero  but	less  than the length of the path name
			     string, then the number of	bytes requested	is re-
			     turned.   If  the	number	of  bytes requested is
			     greater than the length of	the path name  string,
			     then  the	full  path  name string	(including the
			     null terminating character) is returned.

			     The request fails if  the	number	of  bytes  re-
			     quested  is  less	than  zero,  and its is	set to
			     [EIO].

EXAMPLES
       The following example illustrates the use of some of the	requests by  a
       tracing process.

ERRORS
       If fails, is set	to one of the following	values.

	      [EACCES]	     The  executable  image  of	 the process being at-
			     tached resides across an interruptible NFS	mount.

	      [EIO]	     request is	an illegal number.

	      [EIO]	     The request is used with a	data argument that  is
			     less than zero or not a multiple of four, or data
			     is	not word-aligned.

	      [EIO]	     Attempting	to write to a memory  segment  of  the
			     traced  process that is not writable, or attempt-
			     ing to write to page 0, or	the  request  argument
			     is	out of range.

	      [EIO]	     The  request  is  being used with an invalid data
			     argument (signal number).

	      [EIO]	     Attempting	to write to the	user area via the  re-
			     quest.

	      [EPERM]	     The  specified  process  cannot  be  attached for
			     tracing.

	      [EPERM]	     The process pid is	already	being  traced  or  pid
			     refers to the calling process itself.

	      [ESRCH]	     pid  identifies  a	process	to be traced that does
			     not exist or has not executed a with request

SEE ALSO
       adb(1), exec(2),	exit(2), signal(2), ttrace(2), wait(2).

STANDARDS CONFORMANCE
			   PA only; TO BE OBSOLETED		     ptrace(2)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLES | ERRORS | SEE ALSO | STANDARDS CONFORMANCE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ptrace&sektion=2&manpath=HP-UX+11.22>

home | help