unw_init_local(3)

1UNW_INIT_LOCAL(3)            Programming Library             UNW_INIT_LOCAL(3)
2
3
4

NAME

6       unw_init_local -- initialize cursor for local unwinding
7

SYNOPSIS

9       #include <libunwind.h>
10
11       int unw_init_local(unw_cursor_t *c, unw_context_t *ctxt);
12

DESCRIPTION

14       The  unw_init_local()  routine initializes the unwind cursor pointed to
15       by c with the machine-state in the  context  structure  pointed  to  by
16       ctxt.   As  such,  the  machine-state pointed to by ctxt identifies the
17       initial stack frame at which unwinding starts. The  machine-state  must
18       remain valid for the duration for which the cursor c is in use.
19
20       The  unw_init_local()  routine  can  be  used only for unwinding in the
21       address space of the current process (i.e., for local unwinding).   For
22       all other cases, unw_init_remote() must be used instead.  From a behav‐
23       ioral point of view, the call:
24
25           ret = unw_init_local(&cursor, &ucontext);
26
27       is equivalent to:
28
29           ret = unw_init_remote(&cursor, unw_local_addr_space,
30                                 &ucontext);
31
32       However, unwind performance may be better when using  unw_init_local().
33       Also,  unw_init_local()  is available even when UNW_LOCAL_ONLY has been
34       defined before including <libunwind.h>,  whereas  unw_init_remote()  is
35       not.
36

RETURN VALUE

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

THREAD AND SIGNAL SAFETY

42       unw_init_local() is thread-safe as well as safe to use  from  a  signal
43       handler.
44

ERRORS

46       UNW_EINVAL
47               unw_init_local()  was  called  in  a version of libunwind which
48              supports remote unwinding only (this normally happens when call‐
49              ing unw_init_local() for a cross-platform version of libunwind).
50
51       UNW_EUNSPEC
52               An unspecified error occurred.
53
54       UNW_EBADREG
55               A register needed by unw_init_local() wasn't accessible.
56

AUTHOR

61       David Mosberger-Tang
62       Hewlett-Packard Labs
63       Palo-Alto, CA 94304
64       Email: davidm@hpl.hp.com
65       WWW: http://www.hpl.hp.com/research/linux/libunwind/.
66
67
68
69Programming Library             05 August 2004               UNW_INIT_LOCAL(3)