blob: fe074d8619174a23e82c72916cd00b5811ab7c85 [file] [log] [blame]
 \documentclass{article} \usepackage[fancyhdr,pdf]{latex2man} \input{common.tex} \begin{document} \begin{Name}{3}{libunwind-ptrace}{David Mosberger-Tang}{Programming Library}{ptrace() support in libunwind}libunwind-ptrace -- ptrace() support in libunwind \end{Name} \section{Synopsis} \File{\#include $<$libunwind-ptrace.h$>$}\\ \noindent \Type{unw\_accessors\_t} \Var{\_UPT\_accessors};\\ \Type{void~*}\Func{\_UPT\_create}(\Type{pid\_t});\\ \noindent \Type{void} \Func{\_UPT\_destroy}(\Type{void~*});\\ \noindent \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~*});\\ \noindent \Type{void} \Func{\_UPT\_put\_unwind\_info}(\Type{unw\_addr\_space\_t}, \Type{unw\_proc\_info\_t~*}, \Type{void~*});\\ \noindent \Type{int} \Func{\_UPT\_get\_dyn\_info\_list\_addr}(\Type{unw\_addr\_space\_t}, \Type{unw\_word\_t~*}, \Type{void~*});\\ \noindent \Type{int} \Func{\_UPT\_access\_mem}(\Type{unw\_addr\_space\_t}, \Type{unw\_word\_t}, \Type{unw\_word\_t~*}, \Type{int}, \Type{void~*});\\ \noindent \Type{int} \Func{\_UPT\_access\_reg}(\Type{unw\_addr\_space\_t}, \Type{unw\_regnum\_t}, \Type{unw\_word\_t~*}, \Type{int}, \Type{void~*});\\ \noindent \Type{int} \Func{\_UPT\_access\_fpreg}(\Type{unw\_addr\_space\_t}, \Type{unw\_regnum\_t}, \Type{unw\_fpreg\_t~*}, \Type{int}, \Type{void~*});\\ \noindent \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~*});\\ \noindent \Type{int} \Func{\_UPT\_resume}(\Type{unw\_addr\_space\_t}, \Type{unw\_cursor\_t~*}, \Type{void~*});\\ \section{Description} The \Func{ptrace}(2) system-call makes it possible for a process to gain access to the machine-state and virtual memory of \emph{another} process. With the right set of call-back routines, it is therefore possible to hook up \Prog{libunwind} to another process via \Func{ptrace}(2). While it's not very difficult to do so directly, \Prog{libunwind} further facilitates this task by providing ready-to-use callbacks for this purpose. The routines and variables implementing this facility use a name-prefix of \Func{\_UPT}, which is stands for unwind-via-ptrace''. An application that wants to use the \Func{\_UPT}-facility first needs to create a new \Prog{libunwind} address-space that represents the target process. This is done by calling \Func{unw\_create\_addr\_space}(). In many cases, the application will simply want to pass the address of \Var{\_UPT\_accessors} as the first argument to this routine. Doing so will ensure that \Prog{libunwind} will be able to properly unwind the target process. However, in special circumstances, an application may prefer to use only portions of the \Prog{\_UPT}-facility. For this reason, the individual callback routines (\Func{\_UPT\_find\_proc\_info}(), \Func{\_UPT\_put\_unwind\_info}(), etc.) are also available for direct use. Of course, the addresses of these routines could also be picked up from \Var{\_UPT\_accessors}, but doing so would prevent static initialization. Also, when using \Var{\_UPT\_accessors}, \emph{all} the callback routines will be linked into the application, even if they are never actually called. Next, the application can turn on ptrace-mode on the target process, either by forking a new process, invoking \Const{PTRACE\_TRACEME}, and then starting the target program (via \Func{execve}(2)), or by directly attaching to an already running process (via \Const{PTRACE\_ATTACH}). Either way, once the process-ID (pid) of the target process is known, a \Prog{\_UPT}-info-structure can be created by calling \Func{\_UPT\_create}(), passing the pid of the target process as the only argument. The returned void-pointer then needs to be passed as the argument'' pointer (third argument) to \Func{unw\_init\_remote}(). The \Func{\_UPT\_resume}() routine can be used to resume execution of the target process. It simply invokes \Func{ptrace}(2) with a command value of \Const{PTRACE\_CONT}. When the application is done using \Prog{libunwind} on the target process, \Func{\_UPT\_destroy}() needs to be called, passing it the void-pointer that was returned by the corresponding call to \Func{\_UPT\_create}(). This ensures that all memory and other resources are freed up. \section{Availability} Since \Func{ptrace}(2) works within a single machine only, the \Prog{\_UPT}-facility by definition is not available in \Prog{libunwind}-versions configured for cross-unwinding. \section{Thread Safety} The \Prog{\_UPT}-facility assumes that a single \Prog{\_UPT}-info structure is never shared between threads. Because of this, no explicit locking is used. As long as only one thread uses a \Prog{\_UPT}-info structure at any given time, this facility is thread-safe. \section{Return Value} \Func{\_UPT\_create}() may return a \Const{NULL} pointer if it fails to create the \Prog{\_UPT}-info-structure for any reason. For the current implementation, the only reason this call may fail is when the system is out of memory. \section{Files} \begin{Description} \item[\File{libunwind-ptrace.h}] Headerfile to include when using the interface defined by this library. \item[\Opt{-l}\File{unwind-ptrace} \Opt{-l}\File{unwind-generic}] Linker-switches to add when building a program that uses the functions defined by this library. \end{Description} \section{See Also} execve(2), \SeeAlso{libunwind(3)}, ptrace(2) \section{Author} \noindent David Mosberger-Tang\\ Email: \Email{dmosberger@gmail.com}\\ WWW: \URL{http://www.nongnu.org/libunwind/}. \LatexManEnd \end{document}