doc/unw_create_addr_space.man

   1 '\" t
   2 .\" Manual page created with latex2man on Thu Aug 16 09:44:45 MDT 2007
   3 .\" NOTE: This file is generated, DO NOT EDIT.
   4 .de Vb
   5 .ft CW
   6 .nf
   7 ..
   8 .de Ve
   9 .ft R
  10
  11 .fi
  12 ..
  13 .TH "UNW\\_CREATE\\_ADDR\\_SPACE" "3" "16 August 2007" "Programming Library " "Programming Library "
  14 .SH NAME
  15 unw_create_addr_space
  16 \-\- create address space for remote unwinding
  17 .PP
  18 .SH SYNOPSIS
  19
  20 .PP
  21 #include <libunwind.h>
  22 .br
  23 .PP
  24 unw_addr_space_t
  25 unw_create_addr_space(unw_accessors_t *ap,
  26 int
  27 byteorder);
  28 .br
  29 .PP
  30 .SH DESCRIPTION
  31
  32 .PP
  33 The unw_create_addr_space()
  34 routine creates a new unwind
  35 address\-space and initializes it based on the call\-back routines
  36 passed via the ap
  37 pointer and the specified byteorder\&.
  38 The call\-back routines are described in detail below. The
  39 byteorder
  40 can be set to 0 to request the default byte\-order of
  41 the unwind target. To request a particular byte\-order,
  42 byteorder
  43 can be set to any constant defined by
  44 <endian.h>\&.
  45 In particular, __LITTLE_ENDIAN
  46 would
  47 request little\-endian byte\-order and __BIG_ENDIAN
  48 would
  49 request big\-endian byte\-order. Whether or not a particular byte\-order
  50 is supported depends on the target platform.
  51 .PP
  52 .SH CALL\-BACK ROUTINES
  53
  54 .PP
  55 Libunwind
  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\&.
  61 The contents of this
  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().
  65 .PP
  66 The first argument to every call\-back routine is an address\-space
  67 identifier (as)
  68 and the last argument is an arbitrary,
  69 application\-specified void\-pointer (arg).
  70 When invoking a
  71 call\-back routine, libunwind
  72 sets the as
  73 argument to the
  74 address\-space on whose behalf the invocation is made and the arg
  75 argument to the value that was specified when
  76 unw_init_remote(3)
  77 was called.
  78 .PP
  79 The synopsis and a detailed description of every call\-back routine
  80 follows below.
  81 .PP
  82 .SS CALL\-BACK ROUTINE SYNOPSIS
  83 .PP
  84 int
  85 find_proc_info(unw_addr_space_t
  86 as,
  87 .br
  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
  89 ip,
  90 unw_proc_info_t *pip,
  91 .br
  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
  93 need_unwind_info,
  94 void *arg);
  95 .br
  96 void
  97 put_unwind_info(unw_addr_space_t
  98 as,
  99 .br
 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,
 101 void *arg);
 102 .br
 103 int
 104 get_dyn_info_list_addr(unw_addr_space_t
 105 as,
 106 .br
 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,
 108 void *arg);
 109 .br
 110 int
 111 access_mem(unw_addr_space_t
 112 as,
 113 .br
 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
 115 addr,
 116 unw_word_t *valp,
 117 .br
 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
 119 write,
 120 void *arg);
 121 .br
 122 int
 123 access_reg(unw_addr_space_t
 124 as,
 125 .br
 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
 127 regnum,
 128 unw_word_t *valp,
 129 .br
 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
 131 write,
 132 void *arg);
 133 .br
 134 int
 135 access_fpreg(unw_addr_space_t
 136 as,
 137 .br
 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
 139 regnum,
 140 unw_fpreg_t *fpvalp,
 141 .br
 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
 143 write,
 144 void *arg);
 145 .br
 146 int
 147 resume(unw_addr_space_t
 148 as,
 149 .br
 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,
 151 void *arg);
 152 .br
 153 int
 154 get_proc_name(unw_addr_space_t
 155 as,
 156 .br
 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
 158 addr,
 159 char *bufp,
 160 .br
 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
 162 buf_len,
 163 unw_word_t *offp,
 164 .br
 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);
 166 .br
 167 .PP
 168 .SS FIND_PROC_INFO
 169 .PP
 170 Libunwind
 171 invokes the find_proc_info()
 172 call\-back to
 173 locate the information need to unwind a particular procedure. The
 174 ip
 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\&.
 180 See
 181 unw_get_proc_info(3)
 182 for details. Argument
 183 need_unwind_info
 184 is zero if the call\-back does not need to
 185 provide values for the following members in the
 186 unw_proc_info_t
 187 structure: format,
 188 unwind_info_size,
 189 and unwind_info\&.
 190 If
 191 need_unwind_info
 192 is non\-zero, valid values need to be returned
 193 in these members. Furthermore, the contents of the memory addressed
 194 by the unwind_info
 195 member must remain valid until the info is
 196 released via the put_unwind_info
 197 call\-back (see below).
 198 .PP
 199 On successful completion, the find_proc_info()
 200 call\-back must
 201 return zero. Otherwise, the negative value of one of the
 202 unw_error_t
 203 error\-codes may be returned. In particular, this
 204 call\-back may return \-UNW_ESTOPUNWIND
 205 to signal the end of
 206 the frame\-chain.
 207 .PP
 208 .SS PUT_UNWIND_INFO
 209 .PP
 210 Libunwind
 211 invokes the put_unwind_info()
 212 call\-back to
 213 release the resources (such as memory) allocated by a previous call to
 214 find_proc_info()
 215 with the need_unwind_info
 216 argument
 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
 220 find_proc_info().
 221 Note that libunwind
 222 does \fInot\fP
 223 invoke put_unwind_info
 224 for calls to find_proc_info()
 225 with a zero need_unwind_info
 226 argument.
 227 .PP
 228 .SS GET_DYN_INFO_LIST_ADDR
 229 .PP
 230 Libunwind
 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
 235 (see
 236 _U_dyn_register(3)).
 237 The dliap
 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
 243 dliap
 244 must be cleared to zero. Libunwind
 245 will cache the
 246 value returned by get_dyn_info_list_addr()
 247 if caching is
 248 enabled for the given address\-space. The cache can be cleared with a
 249 call to unw_flush_cache().
 250 .PP
 251 On successful completion, the get_dyn_info_list_addr()
 252 call\-back must return zero. Otherwise, the negative value of one of
 253 the unw_error_t
 254 error\-codes may be returned.
 255 .PP
 256 .SS ACCESS_MEM
 257 .PP
 258 Libunwind
 259 invokes the access_mem()
 260 call\-back to read
 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
 264 sets argument write
 265 to zero and
 266 valp
 267 to point to the word that receives the read value. To
 268 write memory, libunwind
 269 sets argument write
 270 to a non\-zero
 271 value and valp
 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
 278 necessary.
 279 .PP
 280 On successful completion, the access_mem()
 281 call\-back must return zero. Otherwise, the negative value of one of
 282 the unw_error_t
 283 error\-codes may be returned.
 284 .PP
 285 .SS ACCESS_REG
 286 .PP
 287 Libunwind
 288 invokes the access_reg()
 289 call\-back to read
 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
 292 regnum\&.
 293 To read a register, libunwind
 294 sets argument
 295 write
 296 to zero and valp
 297 to point to the word that receives
 298 the read value. To write a register, libunwind
 299 sets argument
 300 write
 301 to a non\-zero value and valp
 302 to point to the word
 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.
 308 .PP
 309 On successful completion, the access_reg()
 310 call\-back must
 311 return zero. Otherwise, the negative value of one of the
 312 unw_error_t
 313 error\-codes may be returned.
 314 .PP
 315 .SS ACCESS_FPREG
 316 .PP
 317 Libunwind
 318 invokes the access_fpreg()
 319 call\-back to read
 320 from or write to a floating\-point CPU register. The index of the
 321 register to be accessed is passed in argument regnum\&.
 322 To read a
 323 register, libunwind
 324 sets argument write
 325 to zero and
 326 fpvalp
 327 to point to a variable of type unw_fpreg_t
 328 that
 329 receives the read value. To write a register, libunwind
 330 sets
 331 argument write
 332 to a non\-zero value and fpvalp
 333 to point to
 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
 341 necessary.
 342 .PP
 343 On successful completion, the access_fpreg()
 344 call\-back must
 345 return zero. Otherwise, the negative value of one of the
 346 unw_error_t
 347 error\-codes may be returned.
 348 .PP
 349 .SS RESUME
 350 .PP
 351 Libunwind
 352 invokes the resume()
 353 call\-back to resume
 354 execution in the target address space. Argument cp
 355 is the
 356 unwind\-cursor that identifies the stack\-frame in which execution
 357 should resume. By the time libunwind
 358 invokes the resume
 359 call\-back, it has already established the desired machine\- and
 360 memory\-state via calls to the access_reg(),
 361 access_fpreg,
 362 and access_mem()
 363 call\-backs. Thus, all
 364 the call\-back needs to do is perform whatever action is needed to
 365 actually resume execution.
 366 .PP
 367 The resume
 368 call\-back is invoked only in response to a call to
 369 unw_resume(3),
 370 so applications which never invoke
 371 unw_resume(3)
 372 need not define the resume
 373 callback.
 374 .PP
 375 On successful completion, the resume()
 376 call\-back must return
 377 zero. Otherwise, the negative value of one of the
 378 unw_error_t
 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.
 382 .PP
 383 .SS GET_PROC_NAME
 384 .PP
 385 Libunwind
 386 invokes the get_proc_name()
 387 call\-back to
 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
 392 argument is a
 393 pointer to a character\-buffer used to return the procedure name. The
 394 size of this buffer is specified in argument buf_len\&.
 395 The
 396 returned name must be terminated by a NUL character. If the
 397 procedure\&'s name is longer than buf_len
 398 bytes, it must be
 399 truncated to buf_len\-1
 400 bytes, with the last byte in the
 401 buffer set to the NUL character and \-UNW_ENOMEM
 402 must be
 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()
 407 starts
 408 at address 0x40003000, then invoking get_proc_name()
 409 with
 410 addr
 411 set to 0x40003080 should return a value of 0x80 in the word
 412 pointed to by offp
 413 (assuming the procedure is at least 0x80
 414 bytes long).
 415 .PP
 416 On successful completion, the get_proc_name()
 417 call\-back must
 418 return zero. Otherwise, the negative value of one of the
 419 unw_error_t
 420 error\-codes may be returned.
 421 .PP
 422 .SH RETURN VALUE
 423
 424 .PP
 425 On successful completion, unw_create_addr_space()
 426 returns a
 427 non\-NULL
 428 value that represents the newly created
 429 address\-space. Otherwise, NULL
 430 is returned.
 431 .PP
 432 .SH THREAD AND SIGNAL SAFETY
 433
 434 .PP
 435 unw_create_addr_space()
 436 is thread\-safe but \fInot\fP
 437 safe to use from a signal handler.
 438 .PP
 439 .SH SEE ALSO
 440
 441 .PP
 442 _U_dyn_register(3),
 443 libunwind(3),
 444 unw_destroy_addr_space(3),
 445 unw_get_proc_info(3),
 446 unw_init_remote(3),
 447 unw_resume(3)
 448 .PP
 449 .SH AUTHOR
 450
 451 .PP
 452 David Mosberger\-Tang
 453 .br
 454 Email: \fBdmosberger@gmail.com\fP
 455 .br
 456 WWW: \fBhttp://www.nongnu.org/libunwind/\fP\&.
 457 .\" NOTE: This file is generated, DO NOT EDIT.