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

NAME

6       unw_create_addr_space -- create address space for remote unwinding
7

SYNOPSIS

9       #include <libunwind.h>
10
11       unw_addr_space_t  unw_create_addr_space(unw_accessors_t  *ap, int byte‐
12       order);
13

DESCRIPTION

15       The unw_create_addr_space() routine creates a new unwind  address-space
16       and  initializes  it  based on the call-back routines passed via the ap
17       pointer and  the  specified  byteorder.   The  call-back  routines  are
18       described in detail below. The byteorder can be set to 0 to request the
19       default byte-order of  the  unwind  target.  To  request  a  particular
20       byte-order, byteorder can be set to any constant defined by <endian.h>.
21       In particular, __LITTLE_ENDIAN would request  little-endian  byte-order
22       and  __BIG_ENDIAN would request big-endian byte-order. Whether or not a
23       particular byte-order is supported depends on the target platform.
24

CALL-BACK ROUTINES

26       Libunwind uses a set of call-back routines to access the information it
27       needs  to  unwind a chain of stack-frames. These routines are specified
28       via the ap argument, which points to  a  variable  of  type  unw_acces‐
29       sors_t.  The contents of this variable is copied into the newly-created
30       address space, so the variable must remain valid only for the  duration
31       of the call to unw_create_addr_space().
32
33       The first argument to every call-back routine is an address-space iden‐
34       tifier (as) and the last argument is an  arbitrary,  application-speci‐
35       fied  void-pointer (arg).  When invoking a call-back routine, libunwind
36       sets the as argument to the address-space on whose behalf  the  invoca‐
37       tion  is made and the arg argument to the value that was specified when
38       unw_init_remote(3) was called.
39
40       The synopsis and a detailed description of every call-back routine fol‐
41       lows below.
42
43   CALL-BACK ROUTINE SYNOPSIS
44       int find_proc_info(unw_addr_space_t as,
45                       unw_word_t ip, unw_proc_info_t *pip,
46                       int need_unwind_info, void *arg);
47       void put_unwind_info(unw_addr_space_t as,
48                       unw_proc_info_t *pip, void *arg);
49       int get_dyn_info_list_addr(unw_addr_space_t as,
50                       unw_word_t *dilap, void *arg);
51       int access_mem(unw_addr_space_t as,
52                       unw_word_t addr, unw_word_t *valp,
53                       int write, void *arg);
54       int access_reg(unw_addr_space_t as,
55                       unw_regnum_t regnum, unw_word_t *valp,
56                       int write, void *arg);
57       int access_fpreg(unw_addr_space_t as,
58                       unw_regnum_t regnum, unw_fpreg_t *fpvalp,
59                       int write, void *arg);
60       int resume(unw_addr_space_t as,
61                       unw_cursor_t *cp, void *arg);
62       int get_proc_name(unw_addr_space_t as,
63                       unw_word_t addr, char *bufp,
64                       size_t buf_len, unw_word_t *offp,
65                       void *arg);
66
67   FIND_PROC_INFO
68       Libunwind invokes the find_proc_info() call-back to locate the informa‐
69       tion need to unwind a particular  procedure.  The  ip  argument  is  an
70       instruction-address  inside  the procedure whose information is needed.
71       The pip argument is a pointer  to  the  variable  used  to  return  the
72       desired information. The type of this variable is unw_proc_info_t.  See
73       unw_get_proc_info(3) for details. Argument need_unwind_info is zero  if
74       the call-back does not need to provide values for the following members
75       in  the  unw_proc_info_t  structure:  format,   unwind_info_size,   and
76       unwind_info.   If need_unwind_info is non-zero, valid values need to be
77       returned in these members. Furthermore,  the  contents  of  the  memory
78       addressed by the unwind_info member must remain valid until the info is
79       released via the put_unwind_info call-back (see below).
80
81       On successful completion, the find_proc_info()  call-back  must  return
82       zero.   Otherwise,  the  negative  value  of  one  of  the  unw_error_t
83       error-codes may be returned. In particular, this call-back  may  return
84       -UNW_ESTOPUNWIND to signal the end of the frame-chain.
85
86   PUT_UNWIND_INFO
87       Libunwind  invokes  the  put_unwind_info()  call-back  to  release  the
88       resources  (such  as  memory)  allocated  by   a   previous   call   to
89       find_proc_info()  with  the need_unwind_info argument set to a non-zero
90       value. The pip argument has the same value as the argument of the  same
91       name  in  the  previous  matching  call to find_proc_info().  Note that
92       libunwind does not invoke put_unwind_info for calls to find_proc_info()
93       with a zero need_unwind_info argument.
94
95   GET_DYN_INFO_LIST_ADDR
96       Libunwind  invokes the get_dyn_info_list_addr() call-back to obtain the
97       address of the head of the dynamic unwind-info registration  list.  The
98       variable   stored   at  the  returned  address  must  have  a  type  of
99       unw_dyn_info_list_t (see _U_dyn_register(3)).  The dliap argument is  a
100       pointer  to  a  variable of type unw_word_t which is used to return the
101       address of the dynamic unwind-info registration  list.  If  no  dynamic
102       unwind-info registration list exist, the value pointed to by dliap must
103       be cleared  to  zero.  Libunwind  will  cache  the  value  returned  by
104       get_dyn_info_list_addr()   if   caching   is   enabled  for  the  given
105       address-space.  The   cache   can   be   cleared   with   a   call   to
106       unw_flush_cache().
107
108       On  successful  completion, the get_dyn_info_list_addr() call-back must
109       return zero. Otherwise, the negative value of one  of  the  unw_error_t
110       error-codes may be returned.
111
112   ACCESS_MEM
113       Libunwind invokes the access_mem() call-back to read from or write to a
114       word of memory in the target address-space. The address of the word  to
115       be accessed is passed in argument addr.  To read memory, libunwind sets
116       argument write to zero and valp to point to the word that receives  the
117       read  value.  To  write  memory,  libunwind  sets  argument  write to a
118       non-zero value and valp to point to the word that contains the value to
119       be written. The word that valp points to is always in the byte-order of
120       the host-platform, regardless of the byte-order of the target. In other
121       words,  it  is  the  responsibility of the call-back routine to convert
122       between the target's and the host's byte-order, if necessary.
123
124       On successful completion, the access_mem() call-back must return  zero.
125       Otherwise, the negative value of one of the unw_error_t error-codes may
126       be returned.
127
128   ACCESS_REG
129       Libunwind invokes the access_reg() call-back to read from or write to a
130       scalar  (non-floating-point) CPU register. The index of the register to
131       be accessed is passed in argument regnum.  To read a  register,  libun‐
132       wind  sets  argument  write  to zero and valp to point to the word that
133       receives the read value. To write a register, libunwind  sets  argument
134       write  to  a non-zero value and valp to point to the word that contains
135       the value to be written. The word that valp points to is always in  the
136       byte-order  of  the  host-platform, regardless of the byte-order of the
137       target. In other words, it is the responsibility of the call-back  rou‐
138       tine to convert between the target's and the host's byte-order, if nec‐
139       essary.
140
141       On successful completion, the access_reg() call-back must return  zero.
142       Otherwise, the negative value of one of the unw_error_t error-codes may
143       be returned.
144
145   ACCESS_FPREG
146       Libunwind invokes the access_fpreg() call-back to read from or write to
147       a floating-point CPU register. The index of the register to be accessed
148       is passed in argument regnum.  To read a register, libunwind sets argu‐
149       ment  write  to  zero  and  fpvalp  to  point  to  a  variable  of type
150       unw_fpreg_t that receives the read value. To write a  register,  libun‐
151       wind sets argument write to a non-zero value and fpvalp to point to the
152       variable of type unw_fpreg_t that contains the value to be written. The
153       word  that  fpvalp  points  to  is  always  in  the  byte-order  of the
154       host-platform, regardless of the byte-order of  the  target.  In  other
155       words,  it  is  the  responsibility of the call-back routine to convert
156       between the target's and the host's byte-order, if necessary.
157
158       On successful completion,  the  access_fpreg()  call-back  must  return
159       zero.   Otherwise,  the  negative  value  of  one  of  the  unw_error_t
160       error-codes may be returned.
161
162   RESUME
163       Libunwind invokes the resume() call-back to  resume  execution  in  the
164       target  address space. Argument cp is the unwind-cursor that identifies
165       the stack-frame in which execution should resume. By the time libunwind
166       invokes  the  resume  call-back, it has already established the desired
167       machine- and memory-state via calls to the access_reg(),  access_fpreg,
168       and  access_mem()  call-backs.  Thus,  all the call-back needs to do is
169       perform whatever action is needed to actually resume execution.
170
171       The resume  call-back  is  invoked  only  in  response  to  a  call  to
172       unw_resume(3),  so  applications  which never invoke unw_resume(3) need
173       not define the resume callback.
174
175       On successful completion, the resume() call-back must return zero. Oth‐
176       erwise, the negative value of one of the unw_error_t error-codes may be
177       returned. As a special case,  when  resuming  execution  in  the  local
178       address space, the call-back will not return on success.
179
180   GET_PROC_NAME
181       Libunwind  invokes  the  get_proc_name() call-back to obtain the proce‐
182       dure-name of a static (not dynamically generated)  procedure.  Argument
183       addr is an instruction-address within the procedure whose name is to be
184       obtained. The bufp argument is a pointer to a character-buffer used  to
185       return  the  procedure  name.  The  size of this buffer is specified in
186       argument buf_len.  The returned name must be terminated by a NUL  char‐
187       acter. If the procedure's name is longer than buf_len bytes, it must be
188       truncated to buf_len-1 bytes, with the last byte in the buffer  set  to
189       the  NUL character and -UNW_ENOMEM must be returned. Argument offp is a
190       pointer to a word which is used to return the byte-offset  relative  to
191       the  start  of the procedure whose name is being returned. For example,
192       if  procedure  foo()  starts  at  address  0x40003000,  then   invoking
193       get_proc_name()  with  addr  set to 0x40003080 should return a value of
194       0x80 in the word pointed to by offp (assuming the procedure is at least
195       0x80 bytes long).
196
197       If  bufp  is  NULL  , buf_len is still verified to fit and offp is set.
198       Passing buf_len as zero to indicate no limits on the buffer  length  is
199       only  safe  if  buf  is  NULL  , otherwise the callback is entitled and
200       likely to scribble anywhere in the entire address space.
201
202       On successful completion, the  get_proc_name()  call-back  must  return
203       zero.   Otherwise,  the  negative  value  of  one  of  the  unw_error_t
204       error-codes may be returned.
205

RETURN VALUE

207       On successful completion, unw_create_addr_space()  returns  a  non-NULL
208       value  that represents the newly created address-space. Otherwise, NULL
209       is returned.
210

THREAD AND SIGNAL SAFETY

212       unw_create_addr_space() is thread-safe but not safe to use from a  sig‐
213       nal handler.
214

SEE ALSO

216       _U_dyn_register(3),       libunwind(3),      unw_destroy_addr_space(3),
217       unw_get_proc_info(3), unw_init_remote(3), unw_resume(3)
218

AUTHOR

220       David Mosberger-Tang
221       Hewlett-Packard Labs
222       Palo-Alto, CA 94304
223       Email: davidm@hpl.hp.com
224       WWW: http://www.hpl.hp.com/research/linux/libunwind/.
225
226
227
228Programming Library              20 April 2005        UNW_CREATE_ADDR_SPACE(3)
Impressum