doc/unw_init_remote.tex

   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@gmail.com}\\
  76 WWW: \URL{http://www.nongnu.org/libunwind/}.
  77 \LatexManEnd
  78
  79 \end{document}