2003-03-31 21:57:09 +02:00
\documentclass { article}
\usepackage [fancyhdr,pdf] { latex2man}
\input { common.tex}
\begin { document}
\begin { Name} { 3} { unw\_ init\_ local} { David Mosberger-Tang} { Programming Library} { unw\_ init\_ local} unw\_ init\_ local -- initialize cursor for local unwinding
\end { Name}
\section { Synopsis}
\File { \# include $ < $ libunwind.h$ > $ } \\
\Type { int} \Func { unw\_ init\_ local} (\Type { unw\_ cursor\_ t~*} \Var { c} , \Type { unw\_ context\_ t~*} \Var { ctxt} );\\
\section { Description}
The \Func { unw\_ init\_ local} () routine initializes the unwind cursor
pointed to by \Var { c} with the machine-state in the context structure
pointed to by \Var { ctxt} . As such, the machine-state pointed to by
\Var { ctxt} identifies the initial stack frame at which unwinding
starts. The machine-state must remain valid for the duration for
which the cursor \Var { c} is in use.
The \Func { unw\_ init\_ local} () routine can be used only for unwinding in
the address space of the current process (i.e., for local unwinding).
For all other cases, \Func { unw\_ init\_ remote} () must be used instead.
From a behavioral point of view, the call:
\begin { verbatim}
ret = unw_ init_ local(& cursor, & ucontext);
\end { verbatim}
is equivalent to:
\begin { verbatim}
ret = unw_ init_ remote(& cursor, unw_ local_ addr_ space,
& ucontext);
\end { verbatim}
However, unwind performance may be better when using
\Func { unw\_ init\_ local} (). Also, \Func { unw\_ init\_ local} () is
available even when \Const { UNW\_ LOCAL\_ ONLY} has been defined before
including \File { $ < $ libunwind.h$ > $ } , whereas \Func { unw\_ init\_ remote} ()
is not.
\section { Return Value}
On successful completion, \Func { unw\_ init\_ local} () returns 0.
Otherwise the negative value of one of the error-codes below is
returned.
\section { Thread and Signal Safety}
\Func { unw\_ init\_ local} () is thread-safe as well as safe to use from a
signal handler.
\section { Errors}
\begin { Description}
\item [\Const{UNW\_EINVAL}] \Func { unw\_ init\_ local} () was called in a
version of \Prog { libunwind} which supports remote unwinding only
(this normally happens when calling \Func { unw\_ init\_ local} () for a
cross-platform version of \Prog { libunwind} ).
\item [\Const{UNW\_EUNSPEC}] An unspecified error occurred.
\item [\Const{UNW\_EBADREG}] A register needed by \Func { unw\_ init\_ local} ()
wasn't accessible.
\end { Description}
\section { See Also}
\SeeAlso { libunwind(3)} , \SeeAlso { unw\_ init\_ remote(3)}
\section { Author}
\noindent
David Mosberger-Tang\\
Hewlett-Packard Labs\\
Palo-Alto, CA 94304\\
Email: \Email { davidm@hpl.hp.com} \\
WWW: \URL { http://www.hpl.hp.com/research/linux/libunwind/} .
\LatexManEnd
\end { document}
