libunwind-ptrace.tex revision d10a5225e02c9f26ae9dddf578dc65a016a91888 
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
41The \Func{ptrace}(2) system-call makes it possible for a process to
42gain access to the machine-state and virtual memory of \emph{another}
43process.  With the right set of call-back routines, it is therefore
44possible 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
47ready-to-use callbacks for this purpose.  The routines and variables
48implementing this facility use a name-prefix of \Func{\_UPT}, which is
49stands for ``unwind-via-ptrace''.
50
51An application that wants to use the \Func{\_UPT}-facility first needs
52to create a new \Prog{libunwind} address-space that represents the
53target process.  This is done by calling
54\Func{unw\_create\_addr\_space}().  In many cases, the application
55will simply want to pass the address of \Var{\_UPT\_accessors} as the
56first argument to this routine.  Doing so will ensure that
57\Prog{libunwind} will be able to properly unwind the target process.
58However, in special circumstances, an application may prefer to use
59only portions of the \Prog{\_UPT}-facility.  For this reason, the
60individual callback routines (\Func{\_UPT\_find\_proc\_info}(),
61\Func{\_UPT\_put\_unwind\_info}(), etc.)  are also available for direct
62use.  Of course, the addresses of these routines could also be picked
63up from \Var{\_UPT\_accessors}, but doing so would prevent static
64initialization.  Also, when using \Var{\_UPT\_accessors}, \emph{all}
65the callback routines will be linked into the application, even if
66they are never actually called.
67
68Next, the application can turn on ptrace-mode on the target process,
69either by forking a new process, invoking \Const{PTRACE\_TRACEME}, and
70then starting the target program (via \Func{execve}(2)), or by
71directly attaching to an already running process (via
72\Const{PTRACE\_ATTACH}).  Either way, once the process-ID (pid) of the
73target process is known, a \Prog{\_UPT}-info-structure can be created
74by calling \Func{\_UPT\_create}(), passing the pid of the target process
75as the only argument.  The returned void-pointer then needs to be
76passed as the ``argument'' pointer (third argument) to
77\Func{unw\_init\_remote}().
78
79The \Func{\_UPT\_resume}() routine can be used to resume execution of
80the target process.  It simply invokes \Func{ptrace}(2) with a command
81value of \Const{PTRACE\_CONT}.
82
83When the application is done using \Prog{libunwind} on the target
84process, \Func{\_UPT\_destroy}() needs to be called, passing it the
85void-pointer that was returned by the corresponding call to
86\Func{\_UPT\_create}().  This ensures that all memory and other
87resources are freed up.
88
89\section{Availability}
90
91Since \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
97The \Prog{\_UPT}-facility assumes that a single \Prog{\_UPT}-info
98structure is never shared between threads.  Because of this, no
99explicit locking is used.  As long as only one thread uses
100a \Prog{\_UPT}-info structure at any given time, this facility
101is thread-safe.
102
103\section{Return Value}
104
105\Func{\_UPT\_create}() may return a \Const{NULL} pointer if it fails
106to create the \Prog{\_UPT}-info-structure for any reason.  For the
107current implementation, the only reason this call may fail is when the
108system 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
122execve(2),
123\SeeAlso{libunwind(3)},
124ptrace(2)
125
126\section{Author}
127
128\noindent
129David Mosberger-Tang\\
130Hewlett-Packard Labs\\
131Palo-Alto, CA 94304\\
132Email: \Email{davidm@hpl.hp.com}\\
133WWW: \URL{http://www.hpl.hp.com/research/linux/libunwind/}.
134\LatexManEnd
135
136\end{document}
137