1UNW_CREATE_ADDR_SPACE(3) Programming Library UNW_CREATE_ADDR_SPACE(3)
2
6 unw_create_addr_space -- create address space for remote unwinding
7
9 #include <libunwind.h>
10 unw_addr_space_t unw_create_addr_space(unw_accessors_t *ap, int byte‐
12 order);
13
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
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 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 The synopsis and a detailed description of every call-back routine fol‐
41 lows below.
42 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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
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
212 unw_create_addr_space() is thread-safe but not safe to use from a sig‐
213 nal handler.
214
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
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/.
225Programming Library 20 April 2005 UNW_CREATE_ADDR_SPACE(3)