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