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\\ 130Email: \Email{dmosberger@gmail.com}\\ 131WWW: \URL{http://www.nongnu.org/libunwind/}. 132\LatexManEnd 133 134\end{document} 135