2 .\" Manual page created with latex2man on Thu Aug 16 09:44:45 MDT 2007
3 .\" NOTE: This file is generated, DO NOT EDIT.
13 .TH "UNW\\_CREATE\\_ADDR\\_SPACE" "3" "16 August 2007" "Programming Library " "Programming Library "
16 \-\- create address space for remote unwinding
21 #include <libunwind.h>
25 unw_create_addr_space(unw_accessors_t *ap,
33 The unw_create_addr_space()
34 routine creates a new unwind
35 address\-space and initializes it based on the call\-back routines
37 pointer and the specified byteorder\&.
38 The call\-back routines are described in detail below. The
40 can be set to 0 to request the default byte\-order of
41 the unwind target. To request a particular byte\-order,
43 can be set to any constant defined by
45 In particular, __LITTLE_ENDIAN
47 request little\-endian byte\-order and __BIG_ENDIAN
49 request big\-endian byte\-order. Whether or not a particular byte\-order
50 is supported depends on the target platform.
52 .SH CALL\-BACK ROUTINES
56 uses a set of call\-back routines to access the
57 information it needs to unwind a chain of stack\-frames. These
58 routines are specified via the ap
59 argument, which points to a
60 variable of type unw_accessors_t\&.
62 variable is copied into the newly\-created address space, so the
63 variable must remain valid only for the duration of the call to
64 unw_create_addr_space().
66 The first argument to every call\-back routine is an address\-space
68 and the last argument is an arbitrary,
69 application\-specified void\-pointer (arg).
71 call\-back routine, libunwind
74 address\-space on whose behalf the invocation is made and the arg
75 argument to the value that was specified when
79 The synopsis and a detailed description of every call\-back routine
82 .SS CALL\-BACK ROUTINE SYNOPSIS
85 find_proc_info(unw_addr_space_t
88 \fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fPunw_word_t
92 \fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fPint
97 put_unwind_info(unw_addr_space_t
100 \fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fPunw_proc_info_t *pip,
104 get_dyn_info_list_addr(unw_addr_space_t
107 \fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fPunw_word_t *dilap,
111 access_mem(unw_addr_space_t
114 \fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fPunw_word_t
118 \fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fPint
123 access_reg(unw_addr_space_t
126 \fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fPunw_regnum_t
130 \fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fPint
135 access_fpreg(unw_addr_space_t
138 \fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fPunw_regnum_t
142 \fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fPint
147 resume(unw_addr_space_t
150 \fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fPunw_cursor_t *cp,
154 get_proc_name(unw_addr_space_t
157 \fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fPunw_word_t
161 \fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fPsize_t
165 \fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fPvoid *arg);
171 invokes the find_proc_info()
173 locate the information need to unwind a particular procedure. The
175 argument is an instruction\-address inside the procedure whose
176 information is needed. The pip
177 argument is a pointer to the
178 variable used to return the desired information. The type of this
179 variable is unw_proc_info_t\&.
182 for details. Argument
184 is zero if the call\-back does not need to
185 provide values for the following members in the
192 is non\-zero, valid values need to be returned
193 in these members. Furthermore, the contents of the memory addressed
195 member must remain valid until the info is
196 released via the put_unwind_info
197 call\-back (see below).
199 On successful completion, the find_proc_info()
201 return zero. Otherwise, the negative value of one of the
203 error\-codes may be returned. In particular, this
204 call\-back may return \-UNW_ESTOPUNWIND
211 invokes the put_unwind_info()
213 release the resources (such as memory) allocated by a previous call to
215 with the need_unwind_info
217 set to a non\-zero value. The pip
218 argument has the same value as
219 the argument of the same name in the previous matching call to
223 invoke put_unwind_info
224 for calls to find_proc_info()
225 with a zero need_unwind_info
228 .SS GET_DYN_INFO_LIST_ADDR
231 invokes the get_dyn_info_list_addr()
232 call\-back to obtain the address of the head of the dynamic unwind\-info
233 registration list. The variable stored at the returned address must
234 have a type of unw_dyn_info_list_t
238 argument is a pointer
239 to a variable of type unw_word_t
240 which is used to return the
241 address of the dynamic unwind\-info registration list. If no dynamic
242 unwind\-info registration list exist, the value pointed to by
244 must be cleared to zero. Libunwind
246 value returned by get_dyn_info_list_addr()
248 enabled for the given address\-space. The cache can be cleared with a
249 call to unw_flush_cache().
251 On successful completion, the get_dyn_info_list_addr()
252 call\-back must return zero. Otherwise, the negative value of one of
254 error\-codes may be returned.
259 invokes the access_mem()
261 from or write to a word of memory in the target address\-space. The
262 address of the word to be accessed is passed in argument addr\&.
263 To read memory, libunwind
267 to point to the word that receives the read value. To
268 write memory, libunwind
272 to point to the word that contains the value to
273 be written. The word that valp
274 points to is always in the
275 byte\-order of the host\-platform, regardless of the byte\-order of the
276 target. In other words, it is the responsibility of the call\-back
277 routine to convert between the target\&'s and the host\&'s byte\-order, if
280 On successful completion, the access_mem()
281 call\-back must return zero. Otherwise, the negative value of one of
283 error\-codes may be returned.
288 invokes the access_reg()
290 from or write to a scalar (non\-floating\-point) CPU register. The
291 index of the register to be accessed is passed in argument
293 To read a register, libunwind
297 to point to the word that receives
298 the read value. To write a register, libunwind
301 to a non\-zero value and valp
303 that contains the value to be written. The word that valp
304 points to is always in the byte\-order of the host\-platform, regardless
305 of the byte\-order of the target. In other words, it is the
306 responsibility of the call\-back routine to convert between the
307 target\&'s and the host\&'s byte\-order, if necessary.
309 On successful completion, the access_reg()
311 return zero. Otherwise, the negative value of one of the
313 error\-codes may be returned.
318 invokes the access_fpreg()
320 from or write to a floating\-point CPU register. The index of the
321 register to be accessed is passed in argument regnum\&.
327 to point to a variable of type unw_fpreg_t
329 receives the read value. To write a register, libunwind
332 to a non\-zero value and fpvalp
334 the variable of type unw_fpreg_t
335 that contains the value to
336 be written. The word that fpvalp
337 points to is always in the
338 byte\-order of the host\-platform, regardless of the byte\-order of the
339 target. In other words, it is the responsibility of the call\-back
340 routine to convert between the target\&'s and the host\&'s byte\-order, if
343 On successful completion, the access_fpreg()
345 return zero. Otherwise, the negative value of one of the
347 error\-codes may be returned.
354 execution in the target address space. Argument cp
356 unwind\-cursor that identifies the stack\-frame in which execution
357 should resume. By the time libunwind
359 call\-back, it has already established the desired machine\- and
360 memory\-state via calls to the access_reg(),
363 call\-backs. Thus, all
364 the call\-back needs to do is perform whatever action is needed to
365 actually resume execution.
368 call\-back is invoked only in response to a call to
370 so applications which never invoke
372 need not define the resume
375 On successful completion, the resume()
376 call\-back must return
377 zero. Otherwise, the negative value of one of the
379 error\-codes may be returned. As a special case,
380 when resuming execution in the local address space, the call\-back will
381 not return on success.
386 invokes the get_proc_name()
388 obtain the procedure\-name of a static (not dynamically generated)
389 procedure. Argument addr
390 is an instruction\-address within the
391 procedure whose name is to be obtained. The bufp
393 pointer to a character\-buffer used to return the procedure name. The
394 size of this buffer is specified in argument buf_len\&.
396 returned name must be terminated by a NUL character. If the
397 procedure\&'s name is longer than buf_len
399 truncated to buf_len\-1
400 bytes, with the last byte in the
401 buffer set to the NUL character and \-UNW_ENOMEM
403 returned. Argument offp
404 is a pointer to a word which is used to
405 return the byte\-offset relative to the start of the procedure whose
406 name is being returned. For example, if procedure foo()
408 at address 0x40003000, then invoking get_proc_name()
411 set to 0x40003080 should return a value of 0x80 in the word
413 (assuming the procedure is at least 0x80
416 On successful completion, the get_proc_name()
418 return zero. Otherwise, the negative value of one of the
420 error\-codes may be returned.
425 On successful completion, unw_create_addr_space()
428 value that represents the newly created
429 address\-space. Otherwise, NULL
432 .SH THREAD AND SIGNAL SAFETY
435 unw_create_addr_space()
436 is thread\-safe but \fInot\fP
437 safe to use from a signal handler.
444 unw_destroy_addr_space(3),
445 unw_get_proc_info(3),
452 David Mosberger\-Tang
454 Email: \fBdmosberger@gmail.com\fP
456 WWW: \fBhttp://www.nongnu.org/libunwind/\fP\&.
457 .\" NOTE: This file is generated, DO NOT EDIT.