1\documentclass{article} 2\usepackage[fancyhdr,pdf]{latex2man} 3 4\input{common.tex} 5 6\begin{document} 7 8\begin{Name}{3}{unw\_init\_remote}{David Mosberger-Tang}{Programming Library}{unw\_init\_remote}unw\_init\_remote -- initialize cursor for remote unwinding 9\end{Name} 10 11\section{Synopsis} 12 13\File{\#include $<$libunwind.h$>$}\\ 14 15\Type{int} \Func{unw\_init\_remote}(\Type{unw\_cursor\_t~*}\Var{c}, \Type{unw\_addr\_space\_t~}\Var{as}, \Type{void~*}\Var{arg});\\ 16 17\section{Description} 18 19The \Func{unw\_init\_remote}() routine initializes the unwind cursor 20pointed to by \Var{c} for unwinding in the address space identified by 21\Var{as}. The \Var{as} argument can either be set to 22\Var{unw\_local\_addr\_space} (local address space) or to an arbitrary 23address space created with \Func{unw\_create\_addr\_space}(). 24 25The \Var{arg} void-pointer tells the address space exactly what entity 26should be unwound. For example, if \Var{unw\_local\_addr\_space} is 27passed in \Var{as}, then \Var{arg} needs to be a pointer to a context 28structure containing the machine-state of the initial stack frame. 29However, other address-spaces may instead expect a process-id, a 30thread-id, or a pointer to an arbitrary structure which identifies the 31stack-frame chain to be unwound. In other words, the interpretation 32of \Var{arg} is entirely dependent on the address-space in use; 33\Prog{libunwind} never interprets the argument in any way on its own. 34 35Note that \Func{unw\_init\_remote}() can be used to initiate unwinding 36in \emph{any} process, including the local process in which the 37unwinder itself is running. However, for local unwinding, it is 38generally preferable to use \Func{unw\_init\_local}() instead, because 39it is easier to use and because it may perform better. 40 41\section{Return Value} 42 43On successful completion, \Func{unw\_init\_remote}() returns 0. 44Otherwise the negative value of one of the error-codes below is 45returned. 46 47\section{Thread and Signal Safety} 48 49\Func{unw\_init\_remote}() is thread-safe. If the local address-space 50is passed in argument \Var{as}, this routine is also safe to use from 51a signal handler. 52 53\section{Errors} 54 55\begin{Description} 56\item[\Const{UNW\_EINVAL}] \Func{unw\_init\_remote}() was called in a 57 version of \Prog{libunwind} which supports local unwinding only 58 (this normally happens when defining \Const{UNW\_LOCAL\_ONLY} before 59 including \File{$<$libunwind.h$>$} and then calling 60 \Func{unw\_init\_remote}()). 61\item[\Const{UNW\_EUNSPEC}] An unspecified error occurred. 62\item[\Const{UNW\_EBADREG}] A register needed by \Func{unw\_init\_remote}() 63 wasn't accessible. 64\end{Description} 65 66\section{See Also} 67 68\SeeAlso{libunwind(3)}, \SeeAlso{unw\_create\_addr\_space(3)}, 69\SeeAlso{unw\_init\_local(3)} 70 71\section{Author} 72 73\noindent 74David Mosberger-Tang\\ 75Email: \Email{dmosberger@gmail.com}\\ 76WWW: \URL{http://www.nongnu.org/libunwind/}. 77\LatexManEnd 78 79\end{document} 80