1 \documentclass{article} 2 \usepackage[fancyhdr,pdf]{latex2man} 3 4 \input{common.tex} 5 6 \begin{document} 7 8 \begin{Name}{3}{unw\_create\_addr\_space}{David Mosberger-Tang}{Programming Library}{unw\_create\_addr\_space}unw\_create\_addr\_space -- create address space for remote unwinding 9 \end{Name} 10 11 \section{Synopsis} 12 13 \File{\#include $<$libunwind.h$>$}\\ 14 15 \Type{unw\_addr\_space\_t} \Func{unw\_create\_addr\_space}(\Type{unw\_accessors\_t~*}\Var{ap}, \Type{int} \Var{byteorder});\\ 16 17 \section{Description} 18 19 The \Func{unw\_create\_addr\_space}() routine creates a new unwind 20 address-space and initializes it based on the call-back routines 21 passed via the \Var{ap} pointer and the specified \Var{byteorder}. 22 The call-back routines are described in detail below. The 23 \Var{byteorder} can be set to 0 to request the default byte-order of 24 the unwind target. To request a particular byte-order, 25 \Var{byteorder} can be set to any constant defined by 26 \File{$<$endian.h$>$}. In particular, \Const{\_\_LITTLE\_ENDIAN} would 27 request little-endian byte-order and \Const{\_\_BIG\_ENDIAN} would 28 request big-endian byte-order. Whether or not a particular byte-order 29 is supported depends on the target platform. 30 31 \section{Call-back Routines} 32 33 \Prog{Libunwind} uses a set of call-back routines to access the 34 information it needs to unwind a chain of stack-frames. These 35 routines are specified via the \Var{ap} argument, which points to a 36 variable of type \Type{unw\_accessors\_t}. The contents of this 37 variable is copied into the newly-created address space, so the 38 variable must remain valid only for the duration of the call to 39 \Func{unw\_create\_addr\_space}(). 40 41 The first argument to every call-back routine is an address-space 42 identifier (\Var{as}) and the last argument is an arbitrary, 43 application-specified void-pointer (\Var{arg}). When invoking a 44 call-back routine, \Prog{libunwind} sets the \Var{as} argument to the 45 address-space on whose behalf the invocation is made and the \Var{arg} 46 argument to the value that was specified when 47 \Func{unw\_init\_remote}(3) was called. 48 49 The synopsis and a detailed description of every call-back routine 50 follows below. 51 52 \subsection{Call-back Routine Synopsis} 53 54 \Type{int} \Func{find\_proc\_info}(\Type{unw\_addr\_space\_t} \Var{as},\\ 55 \SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\Type{unw\_word\_t} \Var{ip}, \Type{unw\_proc\_info\_t~*}\Var{pip},\\ 56 \SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\Type{int} \Var{need\_unwind\_info}, \Type{void~*}arg);\\ 57 \Type{void} \Func{put\_unwind\_info}(\Type{unw\_addr\_space\_t} \Var{as},\\ 58 \SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\Type{unw\_proc\_info\_t~*}pip, \Type{void~*}\Var{arg});\\ 59 \Type{int} \Func{get\_dyn\_info\_list\_addr}(\Type{unw\_addr\_space\_t} \Var{as},\\ 60 \SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\Type{unw\_word\_t~*}\Var{dilap}, \Type{void~*}\Var{arg});\\ 61 \Type{int} \Func{access\_mem}(\Var{unw\_addr\_space\_t} \Var{as},\\ 62 \SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\Type{unw\_word\_t} \Var{addr}, \Type{unw\_word\_t~*}\Var{valp},\\ 63 \SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\Type{int} \Var{write}, \Type{void~*}\Var{arg});\\ 64 \Type{int} \Func{access\_reg}(\Var{unw\_addr\_space\_t} \Var{as},\\ 65 \SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\Type{unw\_regnum\_t} \Var{regnum}, \Type{unw\_word\_t~*}\Var{valp},\\ 66 \SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\Type{int} \Var{write}, \Type{void~*}\Var{arg});\\ 67 \Type{int} \Func{access\_fpreg}(\Var{unw\_addr\_space\_t} \Var{as},\\ 68 \SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\Type{unw\_regnum\_t} \Var{regnum}, \Type{unw\_fpreg\_t~*}\Var{fpvalp},\\ 69 \SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\Type{int} \Var{write}, \Type{void~*}\Var{arg});\\ 70 \Type{int} \Func{resume}(\Var{unw\_addr\_space\_t} \Var{as},\\ 71 \SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\Type{unw\_cursor\_t~*}\Var{cp}, \Type{void~*}\Var{arg});\\ 72 \Type{int} \Func{get\_proc\_name}(\Type{unw\_addr\_space\_t} \Var{as},\\ 73 \SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\Type{unw\_word\_t} \Var{addr}, \Type{char~*}\Var{bufp},\\ 74 \SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\Type{size\_t} \Var{buf\_len}, \Type{unw\_word\_t~*}\Var{offp},\\ 75 \SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\Type{void~*}\Var{arg});\\ 76 77 \subsection{find\_proc\_info} 78 79 \Prog{Libunwind} invokes the \Func{find\_proc\_info}() call-back to 80 locate the information need to unwind a particular procedure. The 81 \Var{ip} argument is an instruction-address inside the procedure whose 82 information is needed. The \Var{pip} argument is a pointer to the 83 variable used to return the desired information. The type of this 84 variable is \Type{unw\_proc\_info\_t}. See 85 \Func{unw\_get\_proc\_info(3)} for details. Argument 86 \Var{need\_unwind\_info} is zero if the call-back does not need to 87 provide values for the following members in the 88 \Type{unw\_proc\_info\_t} structure: \Var{format}, 89 \Var{unwind\_info\_size}, and \Var{unwind\_info}. If 90 \Var{need\_unwind\_info} is non-zero, valid values need to be returned 91 in these members. Furthermore, the contents of the memory addressed 92 by the \Var{unwind\_info} member must remain valid until the info is 93 released via the \Func{put\_unwind\_info} call-back (see below). 94 95 On successful completion, the \Func{find\_proc\_info}() call-back must 96 return zero. Otherwise, the negative value of one of the 97 \Type{unw\_error\_t} error-codes may be returned. In particular, this 98 call-back may return -\Const{UNW\_ESTOPUNWIND} to signal the end of 99 the frame-chain. 100 101 \subsection{put\_unwind\_info} 102 103 \Prog{Libunwind} invokes the \Func{put\_unwind\_info}() call-back to 104 release the resources (such as memory) allocated by a previous call to 105 \Func{find\_proc\_info}() with the \Var{need\_unwind\_info} argument 106 set to a non-zero value. The \Var{pip} argument has the same value as 107 the argument of the same name in the previous matching call to 108 \Func{find\_proc\_info}(). Note that \Prog{libunwind} does \emph{not} 109 invoke \Func{put\_unwind\_info} for calls to \Func{find\_proc\_info}() 110 with a zero \Var{need\_unwind\_info} argument. 111 112 113 \subsection{get\_dyn\_info\_list\_addr} 114 115 \Prog{Libunwind} invokes the \Func{get\_dyn\_info\_list\_addr}() 116 call-back to obtain the address of the head of the dynamic unwind-info 117 registration list. The variable stored at the returned address must 118 have a type of \Type{unw\_dyn\_info\_list\_t} (see 119 \Func{\_U\_dyn\_register}(3)). The \Var{dliap} argument is a pointer 120 to a variable of type \Type{unw\_word\_t} which is used to return the 121 address of the dynamic unwind-info registration list. If no dynamic 122 unwind-info registration list exist, the value pointed to by 123 \Var{dliap} must be cleared to zero. \Prog{Libunwind} will cache the 124 value returned by \Func{get\_dyn\_info\_list\_addr}() if caching is 125 enabled for the given address-space. The cache can be cleared with a 126 call to \Func{unw\_flush\_cache}(). 127 128 On successful completion, the \Func{get\_dyn\_info\_list\_addr}() 129 call-back must return zero. Otherwise, the negative value of one of 130 the \Type{unw\_error\_t} error-codes may be returned. 131 132 \subsection{access\_mem} 133 134 \Prog{Libunwind} invokes the \Func{access\_mem}() call-back to read 135 from or write to a word of memory in the target address-space. The 136 address of the word to be accessed is passed in argument \Var{addr}. 137 To read memory, \Prog{libunwind} sets argument \Var{write} to zero and 138 \Var{valp} to point to the word that receives the read value. To 139 write memory, \Prog{libunwind} sets argument \Var{write} to a non-zero 140 value and \Var{valp} to point to the word that contains the value to 141 be written. The word that \Var{valp} points to is always in the 142 byte-order of the host-platform, regardless of the byte-order of the 143 target. In other words, it is the responsibility of the call-back 144 routine to convert between the target's and the host's byte-order, if 145 necessary. 146 147 On successful completion, the \Func{access\_mem}() 148 call-back must return zero. Otherwise, the negative value of one of 149 the \Type{unw\_error\_t} error-codes may be returned. 150 151 \subsection{access\_reg} 152 153 \Prog{Libunwind} invokes the \Func{access\_reg}() call-back to read 154 from or write to a scalar (non-floating-point) CPU register. The 155 index of the register to be accessed is passed in argument 156 \Var{regnum}. To read a register, \Prog{libunwind} sets argument 157 \Var{write} to zero and \Var{valp} to point to the word that receives 158 the read value. To write a register, \Prog{libunwind} sets argument 159 \Var{write} to a non-zero value and \Var{valp} to point to the word 160 that contains the value to be written. The word that \Var{valp} 161 points to is always in the byte-order of the host-platform, regardless 162 of the byte-order of the target. In other words, it is the 163 responsibility of the call-back routine to convert between the 164 target's and the host's byte-order, if necessary. 165 166 On successful completion, the \Func{access\_reg}() call-back must 167 return zero. Otherwise, the negative value of one of the 168 \Type{unw\_error\_t} error-codes may be returned. 169 170 \subsection{access\_fpreg} 171 172 \Prog{Libunwind} invokes the \Func{access\_fpreg}() call-back to read 173 from or write to a floating-point CPU register. The index of the 174 register to be accessed is passed in argument \Var{regnum}. To read a 175 register, \Prog{libunwind} sets argument \Var{write} to zero and 176 \Var{fpvalp} to point to a variable of type \Type{unw\_fpreg\_t} that 177 receives the read value. To write a register, \Prog{libunwind} sets 178 argument \Var{write} to a non-zero value and \Var{fpvalp} to point to 179 the variable of type \Type{unw\_fpreg\_t} that contains the value to 180 be written. The word that \Var{fpvalp} points to is always in the 181 byte-order of the host-platform, regardless of the byte-order of the 182 target. In other words, it is the responsibility of the call-back 183 routine to convert between the target's and the host's byte-order, if 184 necessary. 185 186 On successful completion, the \Func{access\_fpreg}() call-back must 187 return zero. Otherwise, the negative value of one of the 188 \Type{unw\_error\_t} error-codes may be returned. 189 190 \subsection{resume} 191 192 \Prog{Libunwind} invokes the \Func{resume}() call-back to resume 193 execution in the target address space. Argument \Var{cp} is the 194 unwind-cursor that identifies the stack-frame in which execution 195 should resume. By the time \Prog{libunwind} invokes the \Func{resume} 196 call-back, it has already established the desired machine- and 197 memory-state via calls to the \Func{access\_reg}(), 198 \Func{access\_fpreg}, and \Func{access\_mem}() call-backs. Thus, all 199 the call-back needs to do is perform whatever action is needed to 200 actually resume execution. 201 202 The \Func{resume} call-back is invoked only in response to a call to 203 \Func{unw\_resume}(3), so applications which never invoke 204 \Func{unw\_resume}(3) need not define the \Func{resume} callback. 205 206 On successful completion, the \Func{resume}() call-back must return 207 zero. Otherwise, the negative value of one of the 208 \Type{unw\_error\_t} error-codes may be returned. As a special case, 209 when resuming execution in the local address space, the call-back will 210 not return on success. 211 212 \subsection{get\_proc\_name} 213 214 \Prog{Libunwind} invokes the \Func{get\_proc\_name}() call-back to 215 obtain the procedure-name of a static (not dynamically generated) 216 procedure. Argument \Var{addr} is an instruction-address within the 217 procedure whose name is to be obtained. The \Var{bufp} argument is a 218 pointer to a character-buffer used to return the procedure name. The 219 size of this buffer is specified in argument \Var{buf\_len}. The 220 returned name must be terminated by a NUL character. If the 221 procedure's name is longer than \Var{buf\_len} bytes, it must be 222 truncated to \Var{buf\_len}\Prog{-1} bytes, with the last byte in the 223 buffer set to the NUL character and -\Const{UNW\_ENOMEM} must be 224 returned. Argument \Var{offp} is a pointer to a word which is used to 225 return the byte-offset relative to the start of the procedure whose 226 name is being returned. For example, if procedure \Func{foo}() starts 227 at address 0x40003000, then invoking \Func{get\_proc\_name}() with 228 \Var{addr} set to 0x40003080 should return a value of 0x80 in the word 229 pointed to by \Var{offp} (assuming the procedure is at least 0x80 230 bytes long). 231 232 On successful completion, the \Func{get\_proc\_name}() call-back must 233 return zero. Otherwise, the negative value of one of the 234 \Type{unw\_error\_t} error-codes may be returned. 235 236 237 \section{Return Value} 238 239 On successful completion, \Func{unw\_create\_addr\_space}() returns a 240 non-\Const{NULL} value that represents the newly created 241 address-space. Otherwise, \Const{NULL} is returned. 242 243 \section{Thread and Signal Safety} 244 245 \Func{unw\_create\_addr\_space}() is thread-safe but \emph{not} 246 safe to use from a signal handler. 247 248 \section{See Also} 249 250 \SeeAlso{\_U\_dyn\_register(3)}, 251 \SeeAlso{libunwind(3)}, 252 \SeeAlso{unw\_destroy\_addr\_space(3)}, 253 \SeeAlso{unw\_get\_proc\_info(3)}, 254 \SeeAlso{unw\_init\_remote(3)}, 255 \SeeAlso{unw\_resume(3)} 256 257 \section{Author} 258 259 \noindent 260 David Mosberger-Tang\\ 261 Email: \Email{dmosberger (a] gmail.com}\\ 262 WWW: \URL{http://www.nongnu.org/libunwind/}. 263 \LatexManEnd 264 265 \end{document} 266
