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 19 The \Func{unw\_init\_local}() routine initializes the unwind cursor 20 pointed to by \Var{c} with the machine-state in the context structure 21 pointed to by \Var{ctxt}. As such, the machine-state pointed to by 22 \Var{ctxt} identifies the initial stack frame at which unwinding 23 starts. The machine-state must remain valid for the duration for 24 which the cursor \Var{c} is in use. 25 26 The \Func{unw\_init\_local}() routine can be used only for unwinding in 27 the address space of the current process (i.e., for local unwinding). 28 For all other cases, \Func{unw\_init\_remote}() must be used instead. 29 From a behavioral point of view, the call: 30 31 \begin{verbatim} 32 ret = unw_init_local(&cursor, &ucontext); 33 \end{verbatim} 34 is equivalent to: 35 36 \begin{verbatim} 37 ret = unw_init_remote(&cursor, unw_local_addr_space, 38 &ucontext); 39 \end{verbatim} 40 However, unwind performance may be better when using 41 \Func{unw\_init\_local}(). Also, \Func{unw\_init\_local}() is 42 available even when \Const{UNW\_LOCAL\_ONLY} has been defined before 43 including \File{$<$libunwind.h$>$}, whereas \Func{unw\_init\_remote}() 44 is not. 45 46 \section{Return Value} 47 48 On successful completion, \Func{unw\_init\_local}() returns 0. 49 Otherwise the negative value of one of the error-codes below is 50 returned. 51 52 \section{Thread and Signal Safety} 53 54 \Func{unw\_init\_local}() is thread-safe as well as safe to use from a 55 signal 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 76 David Mosberger-Tang\\ 77 Email: \Email{dmosberger (a] gmail.com}\\ 78 WWW: \URL{http://www.nongnu.org/libunwind/}. 79 \LatexManEnd 80 81 \end{document} 82