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 17\section{Description} 18 19The \Func{unw\_init\_local}() routine initializes the unwind cursor 20pointed to by \Var{c} with the machine-state in the context structure 21pointed to by \Var{ctxt}. As such, the machine-state pointed to by 22\Var{ctxt} identifies the initial stack frame at which unwinding 23starts. The machine-state must remain valid for the duration for 24which the cursor \Var{c} is in use. 25 26The \Func{unw\_init\_local}() routine can be used only for unwinding in 27the address space of the current process (i.e., for local unwinding). 28For all other cases, \Func{unw\_init\_remote}() must be used instead. 29From a behavioral point of view, the call: 30 31\begin{verbatim} 32 ret = unw_init_local(&cursor, &ucontext); 33\end{verbatim} 34is equivalent to: 35 36\begin{verbatim} 37 ret = unw_init_remote(&cursor, unw_local_addr_space, 38 &ucontext); 39\end{verbatim} 40However, unwind performance may be better when using 41\Func{unw\_init\_local}(). Also, \Func{unw\_init\_local}() is 42available even when \Const{UNW\_LOCAL\_ONLY} has been defined before 43including \File{$<$libunwind.h$>$}, whereas \Func{unw\_init\_remote}() 44is not. 45 46\section{Return Value} 47 48On successful completion, \Func{unw\_init\_local}() returns 0. 49Otherwise the negative value of one of the error-codes below is 50returned. 51 52\section{Thread and Signal Safety} 53 54\Func{unw\_init\_local}() is thread-safe as well as safe to use from a 55signal handler. 56 57\section{Errors} 58 59\begin{Description} 60\item[\Const{UNW\_EINVAL}] \Func{unw\_init\_local}() was called in a 61 version of \Prog{libunwind} which supports remote unwinding only 62 (this normally happens when calling \Func{unw\_init\_local}() for a 63 cross-platform version of \Prog{libunwind}). 64\item[\Const{UNW\_EUNSPEC}] An unspecified error occurred. 65\item[\Const{UNW\_EBADREG}] A register needed by \Func{unw\_init\_local}() 66 wasn't accessible. 67\end{Description} 68 69\section{See Also} 70 71\SeeAlso{libunwind(3)}, \SeeAlso{unw\_init\_remote(3)} 72 73\section{Author} 74 75\noindent 76David Mosberger-Tang\\ 77Email: \Email{dmosberger@gmail.com}\\ 78WWW: \URL{http://www.nongnu.org/libunwind/}. 79\LatexManEnd 80 81\end{document} 82