Man Linux: Main Page and Category List

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/.