ptrace man page on OSF1

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

ptrace(2)							     ptrace(2)

NAME
       ptrace - Trace the execution of a child process

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

       int ptrace(
	       long int request,
	       long int process,
	       ulong_t *address,
	       ulong_t data );

PARAMETERS
       Determines  the action to be taken by the ptrace() function.  Specifies
       the process ID.	Determined by the  value  of  the  request  parameter.
       Determined by the value of the request parameter.

DESCRIPTION
       The  ptrace() function permits a parent process to control execution of
       a child process. It is primarily used by	 utility  programs  to	enable
       breakpoint debugging.

       The  child  process behaves normally until it receives a signal. When a
       signal is delivered, the child process is stopped, and a SIGCHLD signal
       is  sent	 to  its  parent.  The	parent	process can wait for the child
       process to stop using the wait() function.

       When the child process is stopped,  its	parent	process	 can  use  the
       ptrace()	 function  to examine and modify the image memory of the child
       process, to either terminate the child process or  permit  it  to  con‐
       tinue.

       As  a  security measure, the ptrace() function inhibits the set-user ID
       facility when any subsequent exec  function  is	issued	by  the	 child
       process.	 When  a  traced  process  calls one of the exec functions, it
       stops before executing the first instruction of the new image as if  it
       had received the SIGTRAP signal.

       The  request  parameter	is  set	 to one of the values in the following
       list. Only the PT_TRACE_ME request can be issued	 by  child  processes;
       the remaining requests can only be used by the parent process. For each
       request, the process parameter is the process ID of the child  process.
       The  child  process  must  be  in  a stopped state before the following
       requests are made.  This request sets the child process trace flag.  It
       must  be issued by the child process that is to be traced by its parent
       process. When the trace flag is set, the child process  is  left	 in  a
       stopped	state  on receipt of a signal, and the action specified by the
       sigaction() function is ignored. The process, address, and data parame‐
       ters are ignored, and the return value is not defined for this request.
       Do not issue this request when the parent process does  not  expect  to
       trace  the child process.  These requests return the address space data
       of the child process at the location pointed to by the address  parame‐
       ter.  The  PT_READ_I  and PT_READ_D requests produce equal results. The
       data parameter is ignored. These requests fail when the	value  of  the
       address	parameter is not in the address space of the child process or,
       on some machines, when the address parameter is not  properly  aligned.
       These  errors return a value of -1, and the parent process errno is set
       to [EIO].  This request returns	the  variable  of  the	system's  per-
       process	data  area  for the child, specified by the address parameter.
       This area contains the register values and other information about  the
       process.	 On  some machines, the address parameter is subject to align‐
       ment constraints.  The data parameter is ignored.  This	request	 fails
       when the value of the address parameter is outside of the system's per-
       process data area for the child. On failure, a value of -1 is  returned
       and the parent process errno is set to [EIO].  These requests write the
       value of the data parameter into the  address  space  variable  of  the
       child  process  at the location pointed to by the address parameter. On
       some machines, where necessary, the PT_WRITE_I request synchronizes any
       hardware	 caches, if present. In all other respects, the PT_WRITE_I and
       PT_WRITE_D requests can be used with equal results. On  some  machines,
       these  requests return the previous contents of the address space vari‐
       able of the child process, while on other machines no useful  value  is
       returned with the exception of System V behavior. System V behavior for
       libsys5 returns the value written, and for  libc	 behavior  it  returns
       zero (0) for success.

	      These requests fail when the address parameter points to a loca‐
	      tion in a pure procedure space and a copy cannot be made.	 These
	      requests	also  fail  when the value of the address parameter is
	      out of range and on some machines, when the address parameter is
	      not  properly  aligned. On failure a value of -1 is returned and
	      the parent process errno is set to [EIO].	 This  request	writes
	      the  value  of  the data parameter into the variable of the sys‐
	      tem's per-process data area for  the  child,  specified  by  the
	      address  parameter.  This	 area contains the register values and
	      other information about  the  process.  On  some	machines,  the
	      address  parameter  is subject to alignment constraints. Not all
	      locations within the system's  per-process  data	area  for  the
	      child  may  be written. This request fails when the value of the
	      address parameter is outside of the  system's  per-process  data
	      area  for	 the  child. On failure, a value of -1 is returned and
	      the parent process errno is set to  indicate  the	 error.	  This
	      request  permits the child process to resume execution. When the
	      data parameter is zero (0), the signal  that  caused  the	 child
	      process  to  stop	 is  canceled before the child process resumes
	      execution.

	      When the data parameter has a  valid  signal  value,  the	 child
	      process  resumes	execution  as  though  that  signal  had  been
	      received.	 When the address parameter is equal to	 1,  execution
	      continues	 from  where it stopped. When the address parameter is
	      not 1, it is assumed to be the  address  at  which  the  process
	      should resume execution.

	      System V behavior for libsys5 returns the value written, and for
	      libc behavior it returns zero (0)	 for  success.	 This  request
	      fails  when the data parameter is not zero (0) or a valid signal
	      value. On failure, a value of  -1	 is  returned  to  the	parent
	      process  and  the	 parent	 process  errno is set to [EIO].  This
	      request terminates a child  process  as  if  the	child  process
	      called  the  exit() function.  This request permits execution to
	      continue in the same manner as PT_CONTINUE.  However, as soon as
	      possible after the execution of at least one instruction, execu‐
	      tion stops again as if the child process had received  the  SIG‐
	      TRAP signal.

	      Note  that  for  the  Tru64  UNIX	 operating system, the PT_STEP
	      request parameter may cause the traced  program  to  execute  an
	      indefinite  number of instructions if the current instruction is
	      a branch instruction.

ERRORS
       If the ptrace() function fails, errno is set to one  of	the  following
       values:	The  location  within the system's per-process data area could
       not be modified.	 An invalid location was used for  the	system's  per-
       process data area or the process parameter is out of range.  One of the
       following conditions applies: The request parameter does not  have  one
       of the listed values, or is not valid for the machine type on which the
       process is  executing.	The  given  signal  number  is	invalid.   The
       addressed  used	is  either  out	 of bounds or improperly aligned.  The
       specified process cannot be traced.  The process parameter identifies a
       child  process  that does not exist or that has not executed this func‐
       tion with the request parameter PT_TRACE_ME.

SEE ALSO
       Functions: exec(2), sigaction(2), wait(2)

								     ptrace(2)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server OSF1

List of man pages available for OSF1

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