---
name: "unw_init_remote"
section: "3"
platform: "linux"
package: "libunwind"
version: "1.8.3-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/unw_init_remote"
---

# unw\_init\_remote(3)

## 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 opaque 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(3libunwind), unw\_create\_addr\_space(3libunwind), unw\_init\_local(3libunwind)

## AUTHOR

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