doc/unw_init_remote.man

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