Home | History | Annotate | Download | only in doc 
      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