ptrace man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]

PTRACE(3C)							    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
       image" 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  request.  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
	       instruction  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
	       returned 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 separated,
	       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 par‐
	       ent process and the parent's errno is set to EIO.

       8
	       This request causes the child to terminate with the same conse‐
	       quences 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	 step‐
	       ping 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
       library.

       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)

				 Mar 22, 2004			    PTRACE(3C)
[top]

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net