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 19 The \Func{unw\_init\_remote}() routine initializes the unwind cursor 20 pointed 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 23 address space created with \Func{unw\_create\_addr\_space}(). 24 25 The \Var{arg} void-pointer tells the address space exactly what entity 26 should be unwound. For example, if \Var{unw\_local\_addr\_space} is 27 passed in \Var{as}, then \Var{arg} needs to be a pointer to a context 28 structure containing the machine-state of the initial stack frame. 29 However, other address-spaces may instead expect a process-id, a 30 thread-id, or a pointer to an arbitrary structure which identifies the 31 stack-frame chain to be unwound. In other words, the interpretation 32 of \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 35 Note that \Func{unw\_init\_remote}() can be used to initiate unwinding 36 in \emph{any} process, including the local process in which the 37 unwinder itself is running. However, for local unwinding, it is 38 generally preferable to use \Func{unw\_init\_local}() instead, because 39 it is easier to use and because it may perform better. 40 41 \section{Return Value} 42 43 On successful completion, \Func{unw\_init\_remote}() returns 0. 44 Otherwise the negative value of one of the error-codes below is 45 returned. 46 47 \section{Thread and Signal Safety} 48 49 \Func{unw\_init\_remote}() is thread-safe. If the local address-space 50 is passed in argument \Var{as}, this routine is also safe to use from 51 a 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 74 David Mosberger-Tang\\ 75 Email: \Email{dmosberger (a] gmail.com}\\ 76 WWW: \URL{http://www.nongnu.org/libunwind/}. 77 \LatexManEnd 78 79 \end{document} 80
