NAME

       unw_init_remote -- initialize cursor for remote unwinding

SYNOPSIS

       #include <libunwind.h>

       int unw_init_remote(unw_cursor_t *c, unw_addr_space_t as, void *arg);

DESCRIPTION

       The  unw_init_remote() routine initializes the unwind cursor pointed to by c for unwinding
       in  the  address  space  identified  by  as.   The  as  argument  can  either  be  set  to
       unw_local_addr_space  (local  address space) or to an arbitrary address space created with
       unw_create_addr_space().

       The arg void-pointer tells the address space exactly what entity should  be  unwound.  For
       example,  if  unw_local_addr_space  is  passed  in as, then arg needs to be a pointer to a
       context structure containing the machine-state of the initial stack frame.  However, other
       address-spaces  may instead expect a process-id, a thread-id, or a pointer to an arbitrary
       structure which identifies the stack-frame chain  to  be  unwound.  In  other  words,  the
       interpretation  of  arg is entirely dependent on the address-space in use; libunwind never
       interprets the argument in any way on its own.

       Note that unw_init_remote() can be used to initiate unwinding in  any  process,  including
       the  local  process in which the unwinder itself is running. However, for local unwinding,
       it is generally preferable to use unw_init_local() instead, because it is  easier  to  use
       and because it may perform better.

RETURN VALUE

       On  successful  completion,  unw_init_remote() returns 0.  Otherwise the negative value of
       one of the error-codes below is returned.

THREAD AND SIGNAL SAFETY

       unw_init_remote() is thread-safe. If the local address-space is  passed  in  argument  as,
       this routine is also safe to use from a signal handler.

ERRORS

       UNW_EINVAL
               unw_init_remote()  was  called  in  a  version  of  libunwind which supports local
              unwinding only (this normally happens when defining UNW_LOCAL_ONLY before including
              <libunwind.h> and then calling unw_init_remote()).

       UNW_EUNSPEC
               An unspecified error occurred.

       UNW_EBADREG
               A register needed by unw_init_remote() wasn't accessible.

SEE ALSO

       libunwind(3), unw_create_addr_space(3), unw_init_local(3)

AUTHOR

       David Mosberger-Tang
       Email: dmosberger@gmail.com
       WWW: http://www.nongnu.org/libunwind/.