| mostang.com!davidm | 9787d38 | 2003-03-13 02:15:01 +0000 | [diff] [blame^] | 1 | '\" t |
| 2 | .\" Manual page created with latex2man on Wed Mar 12 14:07:43 PST 2003 |
| 3 | .\" NOTE: This file is generated, DO NOT EDIT. |
| 4 | .de Vb |
| 5 | .ft CW |
| 6 | .nf |
| 7 | .. |
| 8 | .de Ve |
| 9 | .ft R |
| 10 | |
| 11 | .fi |
| 12 | .. |
| 13 | .TH "UNW\\_INIT\\_REMOTE" "3" "12 March 2003" "Programming Library " "Programming Library " |
| 14 | .SH NAME |
| 15 | |
| 16 | .PP |
| 17 | unw_init_remote \-\- initialize cursor for remote unwinding |
| 18 | .PP |
| 19 | .SH SYNOPSIS |
| 20 | |
| 21 | .PP |
| 22 | #include <libunwind.h> |
| 23 | .br |
| 24 | .PP |
| 25 | int |
| 26 | unw_init_remote(unw_cursor_t *c, |
| 27 | unw_addr_space_t as, |
| 28 | void *arg); |
| 29 | .br |
| 30 | .PP |
| 31 | .SH DESCRIPTION |
| 32 | |
| 33 | .PP |
| 34 | The unw_init_remote() |
| 35 | routine initializes the unwind cursor |
| 36 | pointed to by c |
| 37 | for unwinding in the address space identified by |
| 38 | as\&. |
| 39 | The as |
| 40 | argument can either be set to |
| 41 | unw_local_addr_space |
| 42 | (local address space) or to an arbitrary |
| 43 | address space created with unw_create_addr_space(). |
| 44 | .PP |
| 45 | The arg |
| 46 | void\-pointer tells the address space exactly what entity |
| 47 | should be unwound. For example, if unw_local_addr_space |
| 48 | is |
| 49 | passed in as, |
| 50 | then arg |
| 51 | needs to be a pointer to a context |
| 52 | structure containing the machine\-state of the initial stack frame. |
| 53 | However, other address\-spaces may instead expect a process\-id, a |
| 54 | thread\-id, or a pointer to an arbitrary structure which identifies the |
| 55 | stack\-frame chain to be unwound. In other words, the interpretation |
| 56 | of arg |
| 57 | is entirely dependent on the address\-space in use; |
| 58 | libunwind |
| 59 | never interprets the argument in any way on its own. |
| 60 | .PP |
| 61 | Note that unw_init_remote() |
| 62 | can be used to initiate unwinding |
| 63 | in \fIany\fP |
| 64 | process, including the local process in which the |
| 65 | unwinder itself is running. However, for local unwinding, it is |
| 66 | generally preferable to use unw_init_local() |
| 67 | instead, because |
| 68 | it is easier to use and because it may perform better. |
| 69 | .PP |
| 70 | .SH RETURN VALUE |
| 71 | |
| 72 | .PP |
| 73 | On successful completion, unw_init_remote() |
| 74 | returns 0. |
| 75 | Otherwise the negative value of one of the error\-codes below is |
| 76 | returned. |
| 77 | .PP |
| 78 | .SH THREAD AND SIGNAL SAFETY |
| 79 | |
| 80 | .PP |
| 81 | unw_init_remote() |
| 82 | is thread\-safe as well as safe to use from a |
| 83 | signal handler. |
| 84 | .PP |
| 85 | .SH ERRORS |
| 86 | |
| 87 | .PP |
| 88 | .TP |
| 89 | UNW_EINVAL |
| 90 | unw_init_remote() |
| 91 | was called in a |
| 92 | version of libunwind |
| 93 | which supports local unwinding only |
| 94 | (this normally happens when defining UNW_LOCAL_ONLY |
| 95 | before |
| 96 | including <libunwind.h> |
| 97 | and then calling |
| 98 | unw_init_remote()). |
| 99 | .TP |
| 100 | UNW_EUNSPEC |
| 101 | An unspecified error occurred. |
| 102 | .TP |
| 103 | UNW_EBADREG |
| 104 | A register needed by unw_init_remote() |
| 105 | wasn\&'t accessible. |
| 106 | .PP |
| 107 | .SH SEE ALSO |
| 108 | |
| 109 | .PP |
| 110 | libunwind(3), |
| 111 | unw_create_addr_space(3), |
| 112 | unw_init_local(3) |
| 113 | .PP |
| 114 | .SH AUTHOR |
| 115 | |
| 116 | .PP |
| 117 | David Mosberger\-Tang |
| 118 | .br |
| 119 | Hewlett\-Packard Labs |
| 120 | .br |
| 121 | Palo\-Alto, CA 94304 |
| 122 | .br |
| 123 | Email: \fBdavidm@hpl.hp.com\fP |
| 124 | .br |
| 125 | WWW: \fBhttp://www.hpl.hp.com/research/linux/libunwind/\fP\&. |
| 126 | .\" NOTE: This file is generated, DO NOT EDIT. |