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 19The \Func{unw\_create\_addr\_space}() routine creates a new unwind 20address-space and initializes it based on the call-back routines 21passed via the \Var{ap} pointer and the specified \Var{byteorder}. 22The call-back routines are described in detail below. The 23\Var{byteorder} can be set to 0 to request the default byte-order of 24the 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 27request little-endian byte-order and \Const{\_\_BIG\_ENDIAN} would 28request big-endian byte-order. Whether or not a particular byte-order 29is 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 34information it needs to unwind a chain of stack-frames. These 35routines are specified via the \Var{ap} argument, which points to a 36variable of type \Type{unw\_accessors\_t}. The contents of this 37variable is copied into the newly-created address space, so the 38variable must remain valid only for the duration of the call to 39\Func{unw\_create\_addr\_space}(). 40 41The first argument to every call-back routine is an address-space 42identifier (\Var{as}) and the last argument is an arbitrary, 43application-specified void-pointer (\Var{arg}). When invoking a 44call-back routine, \Prog{libunwind} sets the \Var{as} argument to the 45address-space on whose behalf the invocation is made and the \Var{arg} 46argument to the value that was specified when 47\Func{unw\_init\_remote}(3) was called. 48 49The synopsis and a detailed description of every call-back routine 50follows 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 80locate the information need to unwind a particular procedure. The 81\Var{ip} argument is an instruction-address inside the procedure whose 82information is needed. The \Var{pip} argument is a pointer to the 83variable used to return the desired information. The type of this 84variable 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 87provide 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 91in these members. Furthermore, the contents of the memory addressed 92by the \Var{unwind\_info} member must remain valid until the info is 93released via the \Func{put\_unwind\_info} call-back (see below). 94 95On successful completion, the \Func{find\_proc\_info}() call-back must 96return zero. Otherwise, the negative value of one of the 97\Type{unw\_error\_t} error-codes may be returned. In particular, this 98call-back may return -\Const{UNW\_ESTOPUNWIND} to signal the end of 99the frame-chain. 100 101\subsection{put\_unwind\_info} 102 103\Prog{Libunwind} invokes the \Func{put\_unwind\_info}() call-back to 104release the resources (such as memory) allocated by a previous call to 105\Func{find\_proc\_info}() with the \Var{need\_unwind\_info} argument 106set to a non-zero value. The \Var{pip} argument has the same value as 107the argument of the same name in the previous matching call to 108\Func{find\_proc\_info}(). Note that \Prog{libunwind} does \emph{not} 109invoke \Func{put\_unwind\_info} for calls to \Func{find\_proc\_info}() 110with 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}() 116call-back to obtain the address of the head of the dynamic unwind-info 117registration list. The variable stored at the returned address must 118have a type of \Type{unw\_dyn\_info\_list\_t} (see 119\Func{\_U\_dyn\_register}(3)). The \Var{dliap} argument is a pointer 120to a variable of type \Type{unw\_word\_t} which is used to return the 121address of the dynamic unwind-info registration list. If no dynamic 122unwind-info registration list exist, the value pointed to by 123\Var{dliap} must be cleared to zero. \Prog{Libunwind} will cache the 124value returned by \Func{get\_dyn\_info\_list\_addr}() if caching is 125enabled for the given address-space. The cache can be cleared with a 126call to \Func{unw\_flush\_cache}(). 127 128On successful completion, the \Func{get\_dyn\_info\_list\_addr}() 129call-back must return zero. Otherwise, the negative value of one of 130the \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 135from or write to a word of memory in the target address-space. The 136address of the word to be accessed is passed in argument \Var{addr}. 137To 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 139write memory, \Prog{libunwind} sets argument \Var{write} to a non-zero 140value and \Var{valp} to point to the word that contains the value to 141be written. The word that \Var{valp} points to is always in the 142byte-order of the host-platform, regardless of the byte-order of the 143target. In other words, it is the responsibility of the call-back 144routine to convert between the target's and the host's byte-order, if 145necessary. 146 147On successful completion, the \Func{access\_mem}() 148call-back must return zero. Otherwise, the negative value of one of 149the \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 154from or write to a scalar (non-floating-point) CPU register. The 155index 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 158the 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 160that contains the value to be written. The word that \Var{valp} 161points to is always in the byte-order of the host-platform, regardless 162of the byte-order of the target. In other words, it is the 163responsibility of the call-back routine to convert between the 164target's and the host's byte-order, if necessary. 165 166On successful completion, the \Func{access\_reg}() call-back must 167return 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 173from or write to a floating-point CPU register. The index of the 174register to be accessed is passed in argument \Var{regnum}. To read a 175register, \Prog{libunwind} sets argument \Var{write} to zero and 176\Var{fpvalp} to point to a variable of type \Type{unw\_fpreg\_t} that 177receives the read value. To write a register, \Prog{libunwind} sets 178argument \Var{write} to a non-zero value and \Var{fpvalp} to point to 179the variable of type \Type{unw\_fpreg\_t} that contains the value to 180be written. The word that \Var{fpvalp} points to is always in the 181byte-order of the host-platform, regardless of the byte-order of the 182target. In other words, it is the responsibility of the call-back 183routine to convert between the target's and the host's byte-order, if 184necessary. 185 186On successful completion, the \Func{access\_fpreg}() call-back must 187return 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 193execution in the target address space. Argument \Var{cp} is the 194unwind-cursor that identifies the stack-frame in which execution 195should resume. By the time \Prog{libunwind} invokes the \Func{resume} 196call-back, it has already established the desired machine- and 197memory-state via calls to the \Func{access\_reg}(), 198\Func{access\_fpreg}, and \Func{access\_mem}() call-backs. Thus, all 199the call-back needs to do is perform whatever action is needed to 200actually resume execution. 201 202The \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 206On successful completion, the \Func{resume}() call-back must return 207zero. Otherwise, the negative value of one of the 208\Type{unw\_error\_t} error-codes may be returned. As a special case, 209when resuming execution in the local address space, the call-back will 210not return on success. 211 212\subsection{get\_proc\_name} 213 214\Prog{Libunwind} invokes the \Func{get\_proc\_name}() call-back to 215obtain the procedure-name of a static (not dynamically generated) 216procedure. Argument \Var{addr} is an instruction-address within the 217procedure whose name is to be obtained. The \Var{bufp} argument is a 218pointer to a character-buffer used to return the procedure name. The 219size of this buffer is specified in argument \Var{buf\_len}. The 220returned name must be terminated by a NUL character. If the 221procedure's name is longer than \Var{buf\_len} bytes, it must be 222truncated to \Var{buf\_len}\Prog{-1} bytes, with the last byte in the 223buffer set to the NUL character and -\Const{UNW\_ENOMEM} must be 224returned. Argument \Var{offp} is a pointer to a word which is used to 225return the byte-offset relative to the start of the procedure whose 226name is being returned. For example, if procedure \Func{foo}() starts 227at address 0x40003000, then invoking \Func{get\_proc\_name}() with 228\Var{addr} set to 0x40003080 should return a value of 0x80 in the word 229pointed to by \Var{offp} (assuming the procedure is at least 0x80 230bytes long). 231 232On successful completion, the \Func{get\_proc\_name}() call-back must 233return 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 239On successful completion, \Func{unw\_create\_addr\_space}() returns a 240non-\Const{NULL} value that represents the newly created 241address-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} 246safe 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 260David Mosberger-Tang\\ 261Email: \Email{dmosberger@gmail.com}\\ 262WWW: \URL{http://www.nongnu.org/libunwind/}. 263\LatexManEnd 264 265\end{document} 266