1\documentclass{article} 2\usepackage[fancyhdr,pdf]{latex2man} 3 4\input{common.tex} 5 6\begin{document} 7 8\begin{Name}{3}{unw\_init\_local}{David Mosberger-Tang}{Programming Library}{unw\_init\_local}unw\_init\_local -- initialize cursor for local unwinding 9\end{Name} 10 11\section{Synopsis} 12 13\File{\#include $<$libunwind.h$>$}\\ 14 15\Type{int} \Func{unw\_init\_local}(\Type{unw\_cursor\_t~*}\Var{c}, \Type{unw\_context\_t~*}\Var{ctxt});\\ 16\Type{int} \Func{unw\_init\_local2}(\Type{unw\_cursor\_t~*}\Var{c}, \Type{unw\_context\_t~*}\Var{ctxt}, \Type{int} \Var{flag});\\ 17 18\section{Description} 19 20The \Func{unw\_init\_local}() routine initializes the unwind cursor 21pointed to by \Var{c} with the machine-state in the context structure 22pointed to by \Var{ctxt}. As such, the machine-state pointed to by 23\Var{ctxt} identifies the initial stack frame at which unwinding 24starts. The machine-state is expected to be one provided by a call to 25unw_getcontext; as such, the instruction pointer may point to the 26instruction after the last instruction of a function, and libunwind 27will back-up the instruction pointer before beginning a walk up the 28call stack. The machine-state must remain valid for the duration for 29which the cursor \Var{c} is in use. 30 31The \Func{unw\_init\_local}() routine can be used only for unwinding in 32the address space of the current process (i.e., for local unwinding). 33For all other cases, \Func{unw\_init\_remote}() must be used instead. 34However, unwind performance may be better when using 35\Func{unw\_init\_local}(). Also, \Func{unw\_init\_local}() is 36available even when \Const{UNW\_LOCAL\_ONLY} has been defined before 37including \File{$<$libunwind.h$>$}, whereas \Func{unw\_init\_remote}() 38is not. 39 40If the unw_context_t is known to be a signal frame (i.e., from the 41third argument in a sigaction handler on linux), 42\Func{unw\_init\_local2}() should be used for correct initialization 43on some platforms, passing the UNW_INIT_SIGNAL_FRAME flag. 44 45\section{Return Value} 46 47On successful completion, \Func{unw\_init\_local}() returns 0. 48Otherwise the negative value of one of the error-codes below is 49returned. 50 51\section{Thread and Signal Safety} 52 53\Func{unw\_init\_local}() is thread-safe as well as safe to use from a 54signal handler. 55 56\section{Errors} 57 58\begin{Description} 59\item[\Const{UNW\_EINVAL}] \Func{unw\_init\_local}() was called in a 60 version of \Prog{libunwind} which supports remote unwinding only 61 (this normally happens when calling \Func{unw\_init\_local}() for a 62 cross-platform version of \Prog{libunwind}). 63\item[\Const{UNW\_EUNSPEC}] An unspecified error occurred. 64\item[\Const{UNW\_EBADREG}] A register needed by \Func{unw\_init\_local}() 65 wasn't accessible. 66\end{Description} 67 68\section{See Also} 69 70\SeeAlso{libunwind(3)}, \SeeAlso{unw\_init\_remote(3)} 71 72\section{Author} 73 74\noindent 75David Mosberger-Tang\\ 76Email: \Email{dmosberger@gmail.com}\\ 77WWW: \URL{http://www.nongnu.org/libunwind/}. 78\LatexManEnd 79 80\end{document} 81