doc/libunwind-ptrace.tex

   1 \documentclass{article}
   2 \usepackage[fancyhdr,pdf]{latex2man}
   3
   4 \input{common.tex}
   5
   6 \begin{document}
   7
   8 \begin{Name}{3}{libunwind-ptrace}{David Mosberger-Tang}{Programming Library}{ptrace() support in libunwind}libunwind-ptrace -- ptrace() support in libunwind
   9 \end{Name}
  10
  11 \section{Synopsis}
  12
  13 \File{\#include $<$libunwind-ptrace.h$>$}\\
  14
  15 \noindent
  16 \Type{unw\_accessors\_t} \Var{\_UPT\_accessors};\\
  17
  18 \Type{void~*}\Func{\_UPT\_create}(\Type{pid\_t});\\
  19 \noindent
  20 \Type{void} \Func{\_UPT\_destroy}(\Type{void~*});\\
  21
  22 \noindent
  23 \Type{int} \Func{\_UPT\_find\_proc\_info}(\Type{unw\_addr\_space\_t}, \Type{unw\_word\_t}, \Type{unw\_proc\_info\_t~*}, \Type{int}, \Type{void~*});\\
  24 \noindent
  25 \Type{void} \Func{\_UPT\_put\_unwind\_info}(\Type{unw\_addr\_space\_t}, \Type{unw\_proc\_info\_t~*}, \Type{void~*});\\
  26 \noindent
  27 \Type{int} \Func{\_UPT\_get\_dyn\_info\_list\_addr}(\Type{unw\_addr\_space\_t}, \Type{unw\_word\_t~*}, \Type{void~*});\\
  28 \noindent
  29 \Type{int} \Func{\_UPT\_access\_mem}(\Type{unw\_addr\_space\_t}, \Type{unw\_word\_t}, \Type{unw\_word\_t~*}, \Type{int}, \Type{void~*});\\
  30 \noindent
  31 \Type{int} \Func{\_UPT\_access\_reg}(\Type{unw\_addr\_space\_t}, \Type{unw\_regnum\_t}, \Type{unw\_word\_t~*}, \Type{int}, \Type{void~*});\\
  32 \noindent
  33 \Type{int} \Func{\_UPT\_access\_fpreg}(\Type{unw\_addr\_space\_t}, \Type{unw\_regnum\_t}, \Type{unw\_fpreg\_t~*}, \Type{int}, \Type{void~*});\\
  34 \noindent
  35 \Type{int} \Func{\_UPT\_get\_proc\_name}(\Type{unw\_addr\_space\_t}, \Type{unw\_word\_t}, \Type{char~*}, \Type{size\_t}, \Type{unw\_word\_t~*}, \Type{void~*});\\
  36 \noindent
  37 \Type{int} \Func{\_UPT\_resume}(\Type{unw\_addr\_space\_t}, \Type{unw\_cursor\_t~*}, \Type{void~*});\\
  38
  39 \section{Description}
  40
  41 The \Func{ptrace}(2) system-call makes it possible for a process to
  42 gain access to the machine-state and virtual memory of \emph{another}
  43 process.  With the right set of call-back routines, it is therefore
  44 possible to hook up \Prog{libunwind} to another process via
  45 \Func{ptrace}(2).  While it's not very difficult to do so directly,
  46 \Prog{libunwind} further facilitates this task by providing
  47 ready-to-use callbacks for this purpose.  The routines and variables
  48 implementing this facility use a name-prefix of \Func{\_UPT}, which is
  49 stands for ``unwind-via-ptrace''.
  50
  51 An application that wants to use the \Func{\_UPT}-facility first needs
  52 to create a new \Prog{libunwind} address-space that represents the
  53 target process.  This is done by calling
  54 \Func{unw\_create\_addr\_space}().  In many cases, the application
  55 will simply want to pass the address of \Var{\_UPT\_accessors} as the
  56 first argument to this routine.  Doing so will ensure that
  57 \Prog{libunwind} will be able to properly unwind the target process.
  58 However, in special circumstances, an application may prefer to use
  59 only portions of the \Prog{\_UPT}-facility.  For this reason, the
  60 individual callback routines (\Func{\_UPT\_find\_proc\_info}(),
  61 \Func{\_UPT\_put\_unwind\_info}(), etc.)  are also available for direct
  62 use.  Of course, the addresses of these routines could also be picked
  63 up from \Var{\_UPT\_accessors}, but doing so would prevent static
  64 initialization.  Also, when using \Var{\_UPT\_accessors}, \emph{all}
  65 the callback routines will be linked into the application, even if
  66 they are never actually called.
  67
  68 Next, the application can turn on ptrace-mode on the target process,
  69 either by forking a new process, invoking \Const{PTRACE\_TRACEME}, and
  70 then starting the target program (via \Func{execve}(2)), or by
  71 directly attaching to an already running process (via
  72 \Const{PTRACE\_ATTACH}).  Either way, once the process-ID (pid) of the
  73 target process is known, a \Prog{\_UPT}-info-structure can be created
  74 by calling \Func{\_UPT\_create}(), passing the pid of the target process
  75 as the only argument.  The returned void-pointer then needs to be
  76 passed as the ``argument'' pointer (third argument) to
  77 \Func{unw\_init\_remote}().
  78
  79 The \Func{\_UPT\_resume}() routine can be used to resume execution of
  80 the target process.  It simply invokes \Func{ptrace}(2) with a command
  81 value of \Const{PTRACE\_CONT}.
  82
  83 When the application is done using \Prog{libunwind} on the target
  84 process, \Func{\_UPT\_destroy}() needs to be called, passing it the
  85 void-pointer that was returned by the corresponding call to
  86 \Func{\_UPT\_create}().  This ensures that all memory and other
  87 resources are freed up.
  88
  89 \section{Availability}
  90
  91 Since \Func{ptrace}(2) works within a single machine only, the
  92 \Prog{\_UPT}-facility by definition is not available in
  93 \Prog{libunwind}-versions configured for cross-unwinding.
  94
  95 \section{Thread Safety}
  96
  97 The \Prog{\_UPT}-facility assumes that a single \Prog{\_UPT}-info
  98 structure is never shared between threads.  Because of this, no
  99 explicit locking is used.  As long as only one thread uses
 100 a \Prog{\_UPT}-info structure at any given time, this facility
 101 is thread-safe.
 102
 103 \section{Return Value}
 104
 105 \Func{\_UPT\_create}() may return a \Const{NULL} pointer if it fails
 106 to create the \Prog{\_UPT}-info-structure for any reason.  For the
 107 current implementation, the only reason this call may fail is when the
 108 system is out of memory.
 109
 110 \section{Files}
 111
 112 \begin{Description}
 113 \item[\File{libunwind-ptrace.h}] Headerfile to include when using the
 114   interface defined by this library.
 115 \item[\Opt{-l}\File{unwind-ptrace} \Opt{-l}\File{unwind-generic}]
 116     Linker-switches to add when building a program that uses the
 117     functions defined by this library.
 118 \end{Description}
 119
 120 \section{See Also}
 121
 122 execve(2),
 123 \SeeAlso{libunwind(3)},
 124 ptrace(2)
 125
 126 \section{Author}
 127
 128 \noindent
 129 David Mosberger-Tang\\
 130 Email: \Email{dmosberger@gmail.com}\\
 131 WWW: \URL{http://www.nongnu.org/libunwind/}.
 132 \LatexManEnd
 133
 134 \end{document}