1 /* Interfaces for libdw. 2 Copyright (C) 2002-2010, 2013, 2014, 2016, 2018 Red Hat, Inc. 3 This file is part of elfutils. 4 5 This file is free software; you can redistribute it and/or modify 6 it under the terms of either 7 8 * the GNU Lesser General Public License as published by the Free 9 Software Foundation; either version 3 of the License, or (at 10 your option) any later version 11 12 or 13 14 * the GNU General Public License as published by the Free 15 Software Foundation; either version 2 of the License, or (at 16 your option) any later version 17 18 or both in parallel, as here. 19 20 elfutils is distributed in the hope that it will be useful, but 21 WITHOUT ANY WARRANTY; without even the implied warranty of 22 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 23 General Public License for more details. 24 25 You should have received copies of the GNU General Public License and 26 the GNU Lesser General Public License along with this program. If 27 not, see <http://www.gnu.org/licenses/>. */ 28 29 #ifndef _LIBDW_H 30 #define _LIBDW_H 1 31 32 #include <gelf.h> 33 #include <stdbool.h> 34 #include <stddef.h> 35 #include <stdint.h> 36 37 /* Mode for the session. */ 38 typedef enum 39 { 40 DWARF_C_READ, /* Read .. */ 41 DWARF_C_RDWR, /* Read and write .. */ 42 DWARF_C_WRITE, /* Write .. */ 43 } 44 Dwarf_Cmd; 45 46 47 /* Callback results. */ 48 enum 49 { 50 DWARF_CB_OK = 0, 51 DWARF_CB_ABORT 52 }; 53 54 55 /* Error values. */ 56 enum 57 { 58 DW_TAG_invalid = 0 59 #define DW_TAG_invalid DW_TAG_invalid 60 }; 61 62 63 /* Type for offset in DWARF file. */ 64 typedef GElf_Off Dwarf_Off; 65 66 /* Type for address in DWARF file. */ 67 typedef GElf_Addr Dwarf_Addr; 68 69 /* Integer types. Big enough to hold any numeric value. */ 70 typedef GElf_Xword Dwarf_Word; 71 typedef GElf_Sxword Dwarf_Sword; 72 /* For the times we know we do not need that much. */ 73 typedef GElf_Half Dwarf_Half; 74 75 76 /* DWARF abbreviation record. */ 77 typedef struct Dwarf_Abbrev Dwarf_Abbrev; 78 79 /* Returned to show the last DIE has be returned. */ 80 #define DWARF_END_ABBREV ((Dwarf_Abbrev *) -1l) 81 82 /* Source code line information for CU. */ 83 typedef struct Dwarf_Lines_s Dwarf_Lines; 84 85 /* One source code line information. */ 86 typedef struct Dwarf_Line_s Dwarf_Line; 87 88 /* Source file information. */ 89 typedef struct Dwarf_Files_s Dwarf_Files; 90 91 /* One address range record. */ 92 typedef struct Dwarf_Arange_s Dwarf_Arange; 93 94 /* Address ranges of a file. */ 95 typedef struct Dwarf_Aranges_s Dwarf_Aranges; 96 97 /* CU representation. */ 98 struct Dwarf_CU; 99 typedef struct Dwarf_CU Dwarf_CU; 100 101 /* Macro information. */ 102 typedef struct Dwarf_Macro_s Dwarf_Macro; 103 104 /* Attribute representation. */ 105 typedef struct 106 { 107 unsigned int code; 108 unsigned int form; 109 unsigned char *valp; 110 struct Dwarf_CU *cu; 111 } Dwarf_Attribute; 112 113 114 /* Data block representation. */ 115 typedef struct 116 { 117 Dwarf_Word length; 118 unsigned char *data; 119 } Dwarf_Block; 120 121 122 /* DIE information. */ 123 typedef struct 124 { 125 /* The offset can be computed from the address. */ 126 void *addr; 127 struct Dwarf_CU *cu; 128 Dwarf_Abbrev *abbrev; 129 // XXX We'll see what other information will be needed. 130 long int padding__; 131 } Dwarf_Die; 132 133 /* Returned to show the last DIE has be returned. */ 134 #define DWARF_END_DIE ((Dwarf_Die *) -1l) 135 136 137 /* Global symbol information. */ 138 typedef struct 139 { 140 Dwarf_Off cu_offset; 141 Dwarf_Off die_offset; 142 const char *name; 143 } Dwarf_Global; 144 145 146 /* One operation in a DWARF location expression. 147 A location expression is an array of these. */ 148 typedef struct 149 { 150 uint8_t atom; /* Operation */ 151 Dwarf_Word number; /* Operand */ 152 Dwarf_Word number2; /* Possible second operand */ 153 Dwarf_Word offset; /* Offset in location expression */ 154 } Dwarf_Op; 155 156 157 /* This describes one Common Information Entry read from a CFI section. 158 Pointers here point into the DATA->d_buf block passed to dwarf_next_cfi. */ 159 typedef struct 160 { 161 Dwarf_Off CIE_id; /* Always DW_CIE_ID_64 in Dwarf_CIE structures. */ 162 163 /* Instruction stream describing initial state used by FDEs. If 164 we did not understand the whole augmentation string and it did 165 not use 'z', then there might be more augmentation data here 166 (and in FDEs) before the actual instructions. */ 167 const uint8_t *initial_instructions; 168 const uint8_t *initial_instructions_end; 169 170 Dwarf_Word code_alignment_factor; 171 Dwarf_Sword data_alignment_factor; 172 Dwarf_Word return_address_register; 173 174 const char *augmentation; /* Augmentation string. */ 175 176 /* Augmentation data, might be NULL. The size is correct only if 177 we understood the augmentation string sufficiently. */ 178 const uint8_t *augmentation_data; 179 size_t augmentation_data_size; 180 size_t fde_augmentation_data_size; 181 } Dwarf_CIE; 182 183 /* This describes one Frame Description Entry read from a CFI section. 184 Pointers here point into the DATA->d_buf block passed to dwarf_next_cfi. */ 185 typedef struct 186 { 187 /* Section offset of CIE this FDE refers to. This will never be 188 DW_CIE_ID_64 in an FDE. If this value is DW_CIE_ID_64, this is 189 actually a Dwarf_CIE structure. */ 190 Dwarf_Off CIE_pointer; 191 192 /* We can't really decode anything further without looking up the CIE 193 and checking its augmentation string. Here follows the encoded 194 initial_location and address_range, then any augmentation data, 195 then the instruction stream. This FDE describes PC locations in 196 the byte range [initial_location, initial_location+address_range). 197 When the CIE augmentation string uses 'z', the augmentation data is 198 a DW_FORM_block (self-sized). Otherwise, when we understand the 199 augmentation string completely, fde_augmentation_data_size gives 200 the number of bytes of augmentation data before the instructions. */ 201 const uint8_t *start; 202 const uint8_t *end; 203 } Dwarf_FDE; 204 205 /* Each entry in a CFI section is either a CIE described by Dwarf_CIE or 206 an FDE described by Dward_FDE. Check CIE_id to see which you have. */ 207 typedef union 208 { 209 Dwarf_Off CIE_id; /* Always DW_CIE_ID_64 in Dwarf_CIE structures. */ 210 Dwarf_CIE cie; 211 Dwarf_FDE fde; 212 } Dwarf_CFI_Entry; 213 214 /* Same as DW_CIE_ID_64 from dwarf.h to keep libdw.h independent. */ 215 #define LIBDW_CIE_ID 0xffffffffffffffffULL 216 #define dwarf_cfi_cie_p(entry) ((entry)->cie.CIE_id == LIBDW_CIE_ID) 217 218 /* Opaque type representing a frame state described by CFI. */ 219 typedef struct Dwarf_Frame_s Dwarf_Frame; 220 221 /* Opaque type representing a CFI section found in a DWARF or ELF file. */ 222 typedef struct Dwarf_CFI_s Dwarf_CFI; 223 224 225 /* Handle for debug sessions. */ 226 typedef struct Dwarf Dwarf; 227 228 229 /* Out-Of-Memory handler. */ 230 typedef void (*__noreturn_attribute__ Dwarf_OOM) (void); 231 232 233 #ifdef __cplusplus 234 extern "C" { 235 #endif 236 237 /* Create a handle for a new debug session. */ 238 extern Dwarf *dwarf_begin (int fildes, Dwarf_Cmd cmd); 239 240 /* Create a handle for a new debug session for an ELF file. */ 241 extern Dwarf *dwarf_begin_elf (Elf *elf, Dwarf_Cmd cmd, Elf_Scn *scngrp); 242 243 /* Retrieve ELF descriptor used for DWARF access. */ 244 extern Elf *dwarf_getelf (Dwarf *dwarf); 245 246 /* Retieve DWARF descriptor used for a Dwarf_Die or Dwarf_Attribute. 247 A Dwarf_Die or a Dwarf_Attribute is associated with a particular 248 Dwarf_CU handle. This function returns the DWARF descriptor for 249 that Dwarf_CU. */ 250 extern Dwarf *dwarf_cu_getdwarf (Dwarf_CU *cu); 251 252 /* Retrieves the DWARF descriptor for debugaltlink data. Returns NULL 253 if no alternate debug data has been supplied yet. libdw will try 254 to set the alt file on first use of an alt FORM if not yet explicitly 255 provided by dwarf_setalt. */ 256 extern Dwarf *dwarf_getalt (Dwarf *main); 257 258 /* Provides the data referenced by the .gnu_debugaltlink section. The 259 caller should check that MAIN and ALT match (i.e., they have the 260 same build ID). It is the responsibility of the caller to ensure 261 that the data referenced by ALT stays valid while it is used by 262 MAIN, until dwarf_setalt is called on MAIN with a different 263 descriptor, or dwarf_end. Must be called before inspecting DIEs 264 that might have alt FORMs. Otherwise libdw will try to set the 265 alt file itself on first use. */ 266 extern void dwarf_setalt (Dwarf *main, Dwarf *alt); 267 268 /* Release debugging handling context. */ 269 extern int dwarf_end (Dwarf *dwarf); 270 271 272 /* Read the header for the DWARF CU. */ 273 extern int dwarf_nextcu (Dwarf *dwarf, Dwarf_Off off, Dwarf_Off *next_off, 274 size_t *header_sizep, Dwarf_Off *abbrev_offsetp, 275 uint8_t *address_sizep, uint8_t *offset_sizep) 276 __nonnull_attribute__ (3); 277 278 /* Read the header of a DWARF CU or type unit. If TYPE_SIGNATUREP is not 279 null, this reads a type unit from the .debug_types section; otherwise 280 this reads a CU from the .debug_info section. */ 281 extern int dwarf_next_unit (Dwarf *dwarf, Dwarf_Off off, Dwarf_Off *next_off, 282 size_t *header_sizep, Dwarf_Half *versionp, 283 Dwarf_Off *abbrev_offsetp, 284 uint8_t *address_sizep, uint8_t *offset_sizep, 285 uint64_t *type_signaturep, Dwarf_Off *type_offsetp) 286 __nonnull_attribute__ (3); 287 288 289 /* Gets the next Dwarf_CU (unit), version, unit type and if available 290 the CU DIE and sub (type) DIE of the unit. Returns 0 on success, 291 -1 on error or 1 if there are no more units. To start iterating 292 provide NULL for CU. If version < 5 the unit type is set from the 293 CU DIE if available (DW_UT_compile for DW_TAG_compile_unit, 294 DW_UT_type for DW_TAG_type_unit or DW_UT_partial for 295 DW_TAG_partial_unit), otherwise it is set to zero. If unavailable 296 (the version or unit type is unknown) the CU DIE is cleared. 297 Likewise if the sub DIE isn't isn't available (the unit type is not 298 DW_UT_type or DW_UT_split_type) the sub DIE tag is cleared. */ 299 extern int dwarf_get_units (Dwarf *dwarf, Dwarf_CU *cu, Dwarf_CU **next_cu, 300 Dwarf_Half *version, uint8_t *unit_type, 301 Dwarf_Die *cudie, Dwarf_Die *subdie) 302 __nonnull_attribute__ (3); 303 304 /* Provides information and DIEs associated with the given Dwarf_CU 305 unit. Returns -1 on error, zero on success. Arguments not needed 306 may be NULL. If they are NULL and aren't known yet, they won't be 307 looked up. If the subdie doesn't exist for this unit_type it will 308 be cleared. If there is no unit_id for this unit type it will be 309 set to zero. */ 310 extern int dwarf_cu_info (Dwarf_CU *cu, 311 Dwarf_Half *version, uint8_t *unit_type, 312 Dwarf_Die *cudie, Dwarf_Die *subdie, 313 uint64_t *unit_id, 314 uint8_t *address_size, uint8_t *offset_size); 315 316 /* Decode one DWARF CFI entry (CIE or FDE) from the raw section data. 317 The E_IDENT from the originating ELF file indicates the address 318 size and byte order used in the CFI section contained in DATA; 319 EH_FRAME_P should be true for .eh_frame format and false for 320 .debug_frame format. OFFSET is the byte position in the section 321 to start at; on return *NEXT_OFFSET is filled in with the byte 322 position immediately after this entry. 323 324 On success, returns 0 and fills in *ENTRY; use dwarf_cfi_cie_p to 325 see whether ENTRY->cie or ENTRY->fde is valid. 326 327 On errors, returns -1. Some format errors will permit safely 328 skipping to the next CFI entry though the current one is unusable. 329 In that case, *NEXT_OFF will be updated before a -1 return. 330 331 If there are no more CFI entries left in the section, 332 returns 1 and sets *NEXT_OFFSET to (Dwarf_Off) -1. */ 333 extern int dwarf_next_cfi (const unsigned char e_ident[], 334 Elf_Data *data, bool eh_frame_p, 335 Dwarf_Off offset, Dwarf_Off *next_offset, 336 Dwarf_CFI_Entry *entry) 337 __nonnull_attribute__ (1, 2, 5, 6); 338 339 /* Use the CFI in the DWARF .debug_frame section. 340 Returns NULL if there is no such section (not an error). 341 The pointer returned can be used until dwarf_end is called on DWARF, 342 and must not be passed to dwarf_cfi_end. 343 Calling this more than once returns the same pointer. */ 344 extern Dwarf_CFI *dwarf_getcfi (Dwarf *dwarf); 345 346 /* Use the CFI in the ELF file's exception-handling data. 347 Returns NULL if there is no such data. 348 The pointer returned can be used until elf_end is called on ELF, 349 and must be passed to dwarf_cfi_end before then. 350 Calling this more than once allocates independent data structures. */ 351 extern Dwarf_CFI *dwarf_getcfi_elf (Elf *elf); 352 353 /* Release resources allocated by dwarf_getcfi_elf. */ 354 extern int dwarf_cfi_end (Dwarf_CFI *cache); 355 356 357 /* Return DIE at given offset in .debug_info section. */ 358 extern Dwarf_Die *dwarf_offdie (Dwarf *dbg, Dwarf_Off offset, 359 Dwarf_Die *result) __nonnull_attribute__ (3); 360 361 /* Return DIE at given offset in .debug_types section. */ 362 extern Dwarf_Die *dwarf_offdie_types (Dwarf *dbg, Dwarf_Off offset, 363 Dwarf_Die *result) 364 __nonnull_attribute__ (3); 365 366 /* Return offset of DIE. */ 367 extern Dwarf_Off dwarf_dieoffset (Dwarf_Die *die); 368 369 /* Return offset of DIE in CU. */ 370 extern Dwarf_Off dwarf_cuoffset (Dwarf_Die *die); 371 372 /* Return CU DIE containing given DIE. */ 373 extern Dwarf_Die *dwarf_diecu (Dwarf_Die *die, Dwarf_Die *result, 374 uint8_t *address_sizep, uint8_t *offset_sizep) 375 __nonnull_attribute__ (2); 376 377 /* Given a Dwarf_Die addr returns a (reconstructed) Dwarf_Die, or NULL 378 if the given addr didn't come from a valid Dwarf_Die. In particular 379 it will make sure that the correct Dwarf_CU pointer is set for the 380 Dwarf_Die, the Dwarf_Abbrev pointer will not be set up yet (it will 381 only be once the Dwarf_Die is used to read attributes, children or 382 siblings). This functions can be used to keep a reference to a 383 Dwarf_Die which you want to refer to later. The addr, and the result 384 of this function, is only valid while the associated Dwarf is valid. */ 385 extern Dwarf_Die *dwarf_die_addr_die (Dwarf *dbg, void *addr, 386 Dwarf_Die *result) 387 __nonnull_attribute__ (3); 388 389 /* Return the CU DIE and the header info associated with a Dwarf_Die 390 or Dwarf_Attribute. A Dwarf_Die or a Dwarf_Attribute is associated 391 with a particular Dwarf_CU handle. This function returns the CU or 392 type unit DIE and header information for that Dwarf_CU. The 393 returned DIE is either a compile_unit, partial_unit or type_unit. 394 If it is a type_unit, then the type signature and type offset are 395 also provided, otherwise type_offset will be set to zero. See also 396 dwarf_diecu and dwarf_next_unit. */ 397 extern Dwarf_Die *dwarf_cu_die (Dwarf_CU *cu, Dwarf_Die *result, 398 Dwarf_Half *versionp, 399 Dwarf_Off *abbrev_offsetp, 400 uint8_t *address_sizep, 401 uint8_t *offset_sizep, 402 uint64_t *type_signaturep, 403 Dwarf_Off *type_offsetp) 404 __nonnull_attribute__ (2); 405 406 /* Return CU DIE containing given address. */ 407 extern Dwarf_Die *dwarf_addrdie (Dwarf *dbg, Dwarf_Addr addr, 408 Dwarf_Die *result) __nonnull_attribute__ (3); 409 410 /* Return child of current DIE. */ 411 extern int dwarf_child (Dwarf_Die *die, Dwarf_Die *result) 412 __nonnull_attribute__ (2); 413 414 /* Locates the first sibling of DIE and places it in RESULT. 415 Returns 0 if a sibling was found, -1 if something went wrong. 416 Returns 1 if no sibling could be found and, if RESULT is not 417 the same as DIE, it sets RESULT->addr to the address of the 418 (non-sibling) DIE that follows this one, or NULL if this DIE 419 was the last one in the compilation unit. */ 420 extern int dwarf_siblingof (Dwarf_Die *die, Dwarf_Die *result) 421 __nonnull_attribute__ (2); 422 423 /* For type aliases and qualifier type DIEs, which don't modify or 424 change the structural layout of the underlying type, follow the 425 DW_AT_type attribute (recursively) and return the underlying type 426 Dwarf_Die. 427 428 Returns 0 when RESULT contains a Dwarf_Die (possibly equal to the 429 given DIE) that isn't a type alias or qualifier type. Returns 1 430 when RESULT contains a type alias or qualifier Dwarf_Die that 431 couldn't be peeled further (it doesn't have a DW_TAG_type 432 attribute). Returns -1 when an error occured. 433 434 The current DWARF specification defines one type alias tag 435 (DW_TAG_typedef) and seven modifier/qualifier type tags 436 (DW_TAG_const_type, DW_TAG_volatile_type, DW_TAG_restrict_type, 437 DW_TAG_atomic_type, DW_TAG_immutable_type, DW_TAG_packed_type and 438 DW_TAG_shared_type). This function won't peel modifier type 439 tags that change the way the underlying type is accessed such 440 as the pointer or reference type tags (DW_TAG_pointer_type, 441 DW_TAG_reference_type or DW_TAG_rvalue_reference_type). 442 443 A future version of this function might peel other alias or 444 qualifier type tags if a future DWARF version or GNU extension 445 defines other type aliases or qualifier type tags that don't modify, 446 change the structural layout or the way to access the underlying type. */ 447 extern int dwarf_peel_type (Dwarf_Die *die, Dwarf_Die *result) 448 __nonnull_attribute__ (2); 449 450 /* Check whether the DIE has children. */ 451 extern int dwarf_haschildren (Dwarf_Die *die) __nonnull_attribute__ (1); 452 453 /* Walks the attributes of DIE, starting at the one OFFSET bytes in, 454 calling the CALLBACK function for each one. Stops if the callback 455 function ever returns a value other than DWARF_CB_OK and returns the 456 offset of the offending attribute. If the end of the attributes 457 is reached 1 is returned. If something goes wrong -1 is returned and 458 the dwarf error number is set. */ 459 extern ptrdiff_t dwarf_getattrs (Dwarf_Die *die, 460 int (*callback) (Dwarf_Attribute *, void *), 461 void *arg, ptrdiff_t offset) 462 __nonnull_attribute__ (2); 463 464 /* Return tag of given DIE. */ 465 extern int dwarf_tag (Dwarf_Die *die) __nonnull_attribute__ (1); 466 467 468 /* Return specific attribute of DIE. */ 469 extern Dwarf_Attribute *dwarf_attr (Dwarf_Die *die, unsigned int search_name, 470 Dwarf_Attribute *result) 471 __nonnull_attribute__ (3); 472 473 /* Check whether given DIE has specific attribute. */ 474 extern int dwarf_hasattr (Dwarf_Die *die, unsigned int search_name); 475 476 /* These are the same as dwarf_attr and dwarf_hasattr, respectively, 477 but they resolve an indirect attribute through DW_AT_abstract_origin. */ 478 extern Dwarf_Attribute *dwarf_attr_integrate (Dwarf_Die *die, 479 unsigned int search_name, 480 Dwarf_Attribute *result) 481 __nonnull_attribute__ (3); 482 extern int dwarf_hasattr_integrate (Dwarf_Die *die, unsigned int search_name); 483 484 485 486 487 /* Check whether given attribute has specific form. */ 488 extern int dwarf_hasform (Dwarf_Attribute *attr, unsigned int search_form); 489 490 /* Return attribute code of given attribute. */ 491 extern unsigned int dwarf_whatattr (Dwarf_Attribute *attr); 492 493 /* Return form code of given attribute. */ 494 extern unsigned int dwarf_whatform (Dwarf_Attribute *attr); 495 496 497 /* Return string associated with given attribute. */ 498 extern const char *dwarf_formstring (Dwarf_Attribute *attrp); 499 500 /* Return unsigned constant represented by attribute. */ 501 extern int dwarf_formudata (Dwarf_Attribute *attr, Dwarf_Word *return_uval) 502 __nonnull_attribute__ (2); 503 504 /* Return signed constant represented by attribute. */ 505 extern int dwarf_formsdata (Dwarf_Attribute *attr, Dwarf_Sword *return_uval) 506 __nonnull_attribute__ (2); 507 508 /* Return address represented by attribute. */ 509 extern int dwarf_formaddr (Dwarf_Attribute *attr, Dwarf_Addr *return_addr) 510 __nonnull_attribute__ (2); 511 512 /* This function is deprecated. Always use dwarf_formref_die instead. 513 Return reference offset represented by attribute. */ 514 extern int dwarf_formref (Dwarf_Attribute *attr, Dwarf_Off *return_offset) 515 __nonnull_attribute__ (2) __deprecated_attribute__; 516 517 /* Look up the DIE in a reference-form attribute. */ 518 extern Dwarf_Die *dwarf_formref_die (Dwarf_Attribute *attr, Dwarf_Die *die_mem) 519 __nonnull_attribute__ (2); 520 521 /* Return block represented by attribute. */ 522 extern int dwarf_formblock (Dwarf_Attribute *attr, Dwarf_Block *return_block) 523 __nonnull_attribute__ (2); 524 525 /* Return flag represented by attribute. */ 526 extern int dwarf_formflag (Dwarf_Attribute *attr, bool *return_bool) 527 __nonnull_attribute__ (2); 528 529 530 /* Simplified attribute value access functions. */ 531 532 /* Return string in name attribute of DIE. */ 533 extern const char *dwarf_diename (Dwarf_Die *die); 534 535 /* Return high PC attribute of DIE. */ 536 extern int dwarf_highpc (Dwarf_Die *die, Dwarf_Addr *return_addr) 537 __nonnull_attribute__ (2); 538 539 /* Return low PC attribute of DIE. */ 540 extern int dwarf_lowpc (Dwarf_Die *die, Dwarf_Addr *return_addr) 541 __nonnull_attribute__ (2); 542 543 /* Return entry_pc or low_pc attribute of DIE. */ 544 extern int dwarf_entrypc (Dwarf_Die *die, Dwarf_Addr *return_addr) 545 __nonnull_attribute__ (2); 546 547 /* Return 1 if DIE's lowpc/highpc or ranges attributes match the PC address, 548 0 if not, or -1 for errors. */ 549 extern int dwarf_haspc (Dwarf_Die *die, Dwarf_Addr pc); 550 551 /* Enumerate the PC address ranges covered by this DIE, covering all 552 addresses where dwarf_haspc returns true. In the first call OFFSET 553 should be zero and *BASEP need not be initialized. Returns -1 for 554 errors, zero when there are no more address ranges to report, or a 555 nonzero OFFSET value to pass to the next call. Each subsequent call 556 must preserve *BASEP from the prior call. Successful calls fill in 557 *STARTP and *ENDP with a contiguous address range. */ 558 extern ptrdiff_t dwarf_ranges (Dwarf_Die *die, 559 ptrdiff_t offset, Dwarf_Addr *basep, 560 Dwarf_Addr *startp, Dwarf_Addr *endp); 561 562 563 /* Return byte size attribute of DIE. */ 564 extern int dwarf_bytesize (Dwarf_Die *die); 565 566 /* Return bit size attribute of DIE. */ 567 extern int dwarf_bitsize (Dwarf_Die *die); 568 569 /* Return bit offset attribute of DIE. */ 570 extern int dwarf_bitoffset (Dwarf_Die *die); 571 572 /* Return array order attribute of DIE. */ 573 extern int dwarf_arrayorder (Dwarf_Die *die); 574 575 /* Return source language attribute of DIE. */ 576 extern int dwarf_srclang (Dwarf_Die *die); 577 578 579 /* Get abbreviation at given offset for given DIE. */ 580 extern Dwarf_Abbrev *dwarf_getabbrev (Dwarf_Die *die, Dwarf_Off offset, 581 size_t *lengthp); 582 583 /* Get abbreviation at given offset in .debug_abbrev section. */ 584 extern int dwarf_offabbrev (Dwarf *dbg, Dwarf_Off offset, size_t *lengthp, 585 Dwarf_Abbrev *abbrevp) 586 __nonnull_attribute__ (4); 587 588 /* Get abbreviation code. */ 589 extern unsigned int dwarf_getabbrevcode (Dwarf_Abbrev *abbrev); 590 591 /* Get abbreviation tag. */ 592 extern unsigned int dwarf_getabbrevtag (Dwarf_Abbrev *abbrev); 593 594 /* Return true if abbreviation is children flag set. */ 595 extern int dwarf_abbrevhaschildren (Dwarf_Abbrev *abbrev); 596 597 /* Get number of attributes of abbreviation. */ 598 extern int dwarf_getattrcnt (Dwarf_Abbrev *abbrev, size_t *attrcntp) 599 __nonnull_attribute__ (2); 600 601 /* Get specific attribute of abbreviation. */ 602 extern int dwarf_getabbrevattr (Dwarf_Abbrev *abbrev, size_t idx, 603 unsigned int *namep, unsigned int *formp, 604 Dwarf_Off *offset); 605 606 /* Get specific attribute of abbreviation and any data encoded with it. 607 Specifically for DW_FORM_implicit_const data will be set to the 608 constant value associated. */ 609 extern int dwarf_getabbrevattr_data (Dwarf_Abbrev *abbrev, size_t idx, 610 unsigned int *namep, unsigned int *formp, 611 Dwarf_Sword *datap, Dwarf_Off *offset); 612 613 /* Get string from-debug_str section. */ 614 extern const char *dwarf_getstring (Dwarf *dbg, Dwarf_Off offset, 615 size_t *lenp); 616 617 618 /* Get public symbol information. */ 619 extern ptrdiff_t dwarf_getpubnames (Dwarf *dbg, 620 int (*callback) (Dwarf *, Dwarf_Global *, 621 void *), 622 void *arg, ptrdiff_t offset) 623 __nonnull_attribute__ (2); 624 625 626 /* Get source file information for CU. */ 627 extern int dwarf_getsrclines (Dwarf_Die *cudie, Dwarf_Lines **lines, 628 size_t *nlines) __nonnull_attribute__ (2, 3); 629 630 /* Return one of the source lines of the CU. */ 631 extern Dwarf_Line *dwarf_onesrcline (Dwarf_Lines *lines, size_t idx); 632 633 /* Get the file source files used in the CU. */ 634 extern int dwarf_getsrcfiles (Dwarf_Die *cudie, Dwarf_Files **files, 635 size_t *nfiles) 636 __nonnull_attribute__ (2); 637 638 639 /* Get source for address in CU. */ 640 extern Dwarf_Line *dwarf_getsrc_die (Dwarf_Die *cudie, Dwarf_Addr addr); 641 642 /* Get source for file and line number. */ 643 extern int dwarf_getsrc_file (Dwarf *dbg, const char *fname, int line, int col, 644 Dwarf_Line ***srcsp, size_t *nsrcs) 645 __nonnull_attribute__ (2, 5, 6); 646 647 648 /* Return line address. */ 649 extern int dwarf_lineaddr (Dwarf_Line *line, Dwarf_Addr *addrp); 650 651 /* Return line VLIW operation index. */ 652 extern int dwarf_lineop_index (Dwarf_Line *line, unsigned int *op_indexp); 653 654 /* Return line number. */ 655 extern int dwarf_lineno (Dwarf_Line *line, int *linep) 656 __nonnull_attribute__ (2); 657 658 /* Return column in line. */ 659 extern int dwarf_linecol (Dwarf_Line *line, int *colp) 660 __nonnull_attribute__ (2); 661 662 /* Return true if record is for beginning of a statement. */ 663 extern int dwarf_linebeginstatement (Dwarf_Line *line, bool *flagp) 664 __nonnull_attribute__ (2); 665 666 /* Return true if record is for end of sequence. */ 667 extern int dwarf_lineendsequence (Dwarf_Line *line, bool *flagp) 668 __nonnull_attribute__ (2); 669 670 /* Return true if record is for beginning of a basic block. */ 671 extern int dwarf_lineblock (Dwarf_Line *line, bool *flagp) 672 __nonnull_attribute__ (2); 673 674 /* Return true if record is for end of prologue. */ 675 extern int dwarf_lineprologueend (Dwarf_Line *line, bool *flagp) 676 __nonnull_attribute__ (2); 677 678 /* Return true if record is for beginning of epilogue. */ 679 extern int dwarf_lineepiloguebegin (Dwarf_Line *line, bool *flagp) 680 __nonnull_attribute__ (2); 681 682 /* Return instruction-set architecture in this record. */ 683 extern int dwarf_lineisa (Dwarf_Line *line, unsigned int *isap) 684 __nonnull_attribute__ (2); 685 686 /* Return code path discriminator in this record. */ 687 extern int dwarf_linediscriminator (Dwarf_Line *line, unsigned int *discp) 688 __nonnull_attribute__ (2); 689 690 691 /* Find line information for address. The returned string is NULL when 692 an error occured, or the file path. The file path is either absolute 693 or relative to the compilation directory. See dwarf_decl_file. */ 694 extern const char *dwarf_linesrc (Dwarf_Line *line, 695 Dwarf_Word *mtime, Dwarf_Word *length); 696 697 /* Return file information. The returned string is NULL when 698 an error occured, or the file path. The file path is either absolute 699 or relative to the compilation directory. See dwarf_decl_file. */ 700 extern const char *dwarf_filesrc (Dwarf_Files *file, size_t idx, 701 Dwarf_Word *mtime, Dwarf_Word *length); 702 703 /* Return the Dwarf_Files and index associated with the given Dwarf_Line. */ 704 extern int dwarf_line_file (Dwarf_Line *line, 705 Dwarf_Files **files, size_t *idx) 706 __nonnull_attribute__ (2, 3); 707 708 /* Return the directory list used in the file information extracted. 709 (*RESULT)[0] is the CU's DW_AT_comp_dir value, and may be null. 710 (*RESULT)[0..*NDIRS-1] are the compile-time include directory path 711 encoded by the compiler. */ 712 extern int dwarf_getsrcdirs (Dwarf_Files *files, 713 const char *const **result, size_t *ndirs) 714 __nonnull_attribute__ (2, 3); 715 716 /* Iterates through the debug line units. Returns 0 on success, -1 on 717 error or 1 if there are no more units. To start iterating use zero 718 for OFF and set *CU to NULL. On success NEXT_OFF will be set to 719 the next offset to use. The *CU will be set if this line table 720 needed a specific CU and needs to be given when calling 721 dwarf_next_lines again (to help dwarf_next_lines quickly find the 722 next CU). *CU might be set to NULL when it couldn't be found (the 723 compilation directory entry will be the empty string in that case) 724 or for DWARF 5 or later tables, which are self contained. SRCFILES 725 and SRCLINES may be NULL if the caller is not interested in the 726 actual line or file table. On success and when not NULL, NFILES 727 and NLINES will be set to the number of files in the file table and 728 number of lines in the line table. */ 729 extern int dwarf_next_lines (Dwarf *dwarf, Dwarf_Off off, 730 Dwarf_Off *next_off, Dwarf_CU **cu, 731 Dwarf_Files **srcfiles, size_t *nfiles, 732 Dwarf_Lines **srclines, size_t *nlines) 733 __nonnull_attribute__ (3,4); 734 735 /* Return location expression, decoded as a list of operations. */ 736 extern int dwarf_getlocation (Dwarf_Attribute *attr, Dwarf_Op **expr, 737 size_t *exprlen) __nonnull_attribute__ (2, 3); 738 739 /* Return location expressions. If the attribute uses a location list, 740 ADDRESS selects the relevant location expressions from the list. 741 There can be multiple matches, resulting in multiple expressions to 742 return. EXPRS and EXPRLENS are parallel arrays of NLOCS slots to 743 fill in. Returns the number of locations filled in, or -1 for 744 errors. If EXPRS is a null pointer, stores nothing and returns the 745 total number of locations. A return value of zero means that the 746 location list indicated no value is accessible. */ 747 extern int dwarf_getlocation_addr (Dwarf_Attribute *attr, Dwarf_Addr address, 748 Dwarf_Op **exprs, size_t *exprlens, 749 size_t nlocs); 750 751 /* Enumerate the locations ranges and descriptions covered by the 752 given attribute. In the first call OFFSET should be zero and 753 *BASEP need not be initialized. Returns -1 for errors, zero when 754 there are no more locations to report, or a nonzero OFFSET 755 value to pass to the next call. Each subsequent call must preserve 756 *BASEP from the prior call. Successful calls fill in *STARTP and 757 *ENDP with a contiguous address range and *EXPR with a pointer to 758 an array of operations with length *EXPRLEN. If the attribute 759 describes a single location description and not a location list the 760 first call (with OFFSET zero) will return the location description 761 in *EXPR with *STARTP set to zero and *ENDP set to minus one. */ 762 extern ptrdiff_t dwarf_getlocations (Dwarf_Attribute *attr, 763 ptrdiff_t offset, Dwarf_Addr *basep, 764 Dwarf_Addr *startp, Dwarf_Addr *endp, 765 Dwarf_Op **expr, size_t *exprlen); 766 767 /* Return the block associated with a DW_OP_implicit_value operation. 768 The OP pointer must point into an expression that dwarf_getlocation 769 or dwarf_getlocation_addr has returned given the same ATTR. */ 770 extern int dwarf_getlocation_implicit_value (Dwarf_Attribute *attr, 771 const Dwarf_Op *op, 772 Dwarf_Block *return_block) 773 __nonnull_attribute__ (2, 3); 774 775 /* Return the attribute indicated by a DW_OP_GNU_implicit_pointer operation. 776 The OP pointer must point into an expression that dwarf_getlocation 777 or dwarf_getlocation_addr has returned given the same ATTR. 778 The result is the DW_AT_location or DW_AT_const_value attribute 779 of the OP->number DIE. */ 780 extern int dwarf_getlocation_implicit_pointer (Dwarf_Attribute *attr, 781 const Dwarf_Op *op, 782 Dwarf_Attribute *result) 783 __nonnull_attribute__ (2, 3); 784 785 /* Return the DIE associated with an operation such as 786 DW_OP_GNU_implicit_pointer, DW_OP_GNU_parameter_ref, DW_OP_GNU_convert, 787 DW_OP_GNU_reinterpret, DW_OP_GNU_const_type, DW_OP_GNU_regval_type or 788 DW_OP_GNU_deref_type. The OP pointer must point into an expression that 789 dwarf_getlocation or dwarf_getlocation_addr has returned given the same 790 ATTR. The RESULT is a DIE that expresses a type or value needed by the 791 given OP. */ 792 extern int dwarf_getlocation_die (Dwarf_Attribute *attr, 793 const Dwarf_Op *op, 794 Dwarf_Die *result) 795 __nonnull_attribute__ (2, 3); 796 797 /* Return the attribute expressing a value associated with an operation such 798 as DW_OP_implicit_value, DW_OP_GNU_entry_value or DW_OP_GNU_const_type. 799 The OP pointer must point into an expression that dwarf_getlocation 800 or dwarf_getlocation_addr has returned given the same ATTR. 801 The RESULT is a value expressed by an attribute such as DW_AT_location 802 or DW_AT_const_value. */ 803 extern int dwarf_getlocation_attr (Dwarf_Attribute *attr, 804 const Dwarf_Op *op, 805 Dwarf_Attribute *result) 806 __nonnull_attribute__ (2, 3); 807 808 809 /* Compute the byte-size of a type DIE according to DWARF rules. 810 For most types, this is just DW_AT_byte_size. 811 For DW_TAG_array_type it can apply much more complex rules. */ 812 extern int dwarf_aggregate_size (Dwarf_Die *die, Dwarf_Word *size); 813 814 /* Given a language code, as returned by dwarf_srclan, get the default 815 lower bound for a subrange type without a lower bound attribute. 816 Returns zero on success or -1 on failure when the given language 817 wasn't recognized. */ 818 extern int dwarf_default_lower_bound (int lang, Dwarf_Sword *result) 819 __nonnull_attribute__ (2); 820 821 /* Return scope DIEs containing PC address. 822 Sets *SCOPES to a malloc'd array of Dwarf_Die structures, 823 and returns the number of elements in the array. 824 (*SCOPES)[0] is the DIE for the innermost scope containing PC, 825 (*SCOPES)[1] is the DIE for the scope containing that scope, and so on. 826 Returns -1 for errors or 0 if no scopes match PC. */ 827 extern int dwarf_getscopes (Dwarf_Die *cudie, Dwarf_Addr pc, 828 Dwarf_Die **scopes); 829 830 /* Return scope DIEs containing the given DIE. 831 Sets *SCOPES to a malloc'd array of Dwarf_Die structures, 832 and returns the number of elements in the array. 833 (*SCOPES)[0] is a copy of DIE. 834 (*SCOPES)[1] is the DIE for the scope containing that scope, and so on. 835 Returns -1 for errors or 0 if DIE is not found in any scope entry. */ 836 extern int dwarf_getscopes_die (Dwarf_Die *die, Dwarf_Die **scopes); 837 838 839 /* Search SCOPES[0..NSCOPES-1] for a variable called NAME. 840 Ignore the first SKIP_SHADOWS scopes that match the name. 841 If MATCH_FILE is not null, accept only declaration in that source file; 842 if MATCH_LINENO or MATCH_LINECOL are also nonzero, accept only declaration 843 at that line and column. 844 845 If successful, fill in *RESULT with the DIE of the variable found, 846 and return N where SCOPES[N] is the scope defining the variable. 847 Return -1 for errors or -2 for no matching variable found. */ 848 extern int dwarf_getscopevar (Dwarf_Die *scopes, int nscopes, 849 const char *name, int skip_shadows, 850 const char *match_file, 851 int match_lineno, int match_linecol, 852 Dwarf_Die *result); 853 854 855 856 /* Return list address ranges. */ 857 extern int dwarf_getaranges (Dwarf *dbg, Dwarf_Aranges **aranges, 858 size_t *naranges) 859 __nonnull_attribute__ (2); 860 861 /* Return one of the address range entries. */ 862 extern Dwarf_Arange *dwarf_onearange (Dwarf_Aranges *aranges, size_t idx); 863 864 /* Return information in address range record. */ 865 extern int dwarf_getarangeinfo (Dwarf_Arange *arange, Dwarf_Addr *addrp, 866 Dwarf_Word *lengthp, Dwarf_Off *offsetp); 867 868 /* Get address range which includes given address. */ 869 extern Dwarf_Arange *dwarf_getarange_addr (Dwarf_Aranges *aranges, 870 Dwarf_Addr addr); 871 872 873 874 /* Get functions in CUDIE. The given callback will be called for all 875 defining DW_TAG_subprograms in the CU DIE tree. If the callback 876 returns DWARF_CB_ABORT the return value can be used as offset argument 877 to resume the function to find all remaining functions (this is not 878 really recommended, since it needs to rewalk the CU DIE tree first till 879 that offset is found again). If the callback returns DWARF_CB_OK 880 dwarf_getfuncs will not return but keep calling the callback for each 881 function DIE it finds. Pass zero for offset on the first call to walk 882 the full CU DIE tree. If no more functions can be found and the callback 883 returned DWARF_CB_OK then the function returns zero. */ 884 extern ptrdiff_t dwarf_getfuncs (Dwarf_Die *cudie, 885 int (*callback) (Dwarf_Die *, void *), 886 void *arg, ptrdiff_t offset); 887 888 889 /* Return file name containing definition of the given declaration. 890 Of the DECL has an (indirect, see dwarf_attr_integrate) decl_file 891 attribute. The returned file path is either absolute, or relative 892 to the compilation directory. Given the decl DIE, the compilation 893 directory can be retrieved through: 894 dwarf_formstring (dwarf_attr (dwarf_diecu (decl, &cudie, NULL, NULL), 895 DW_AT_comp_dir, &attr)); 896 Returns NULL if no decl_file could be found or an error occured. */ 897 extern const char *dwarf_decl_file (Dwarf_Die *decl); 898 899 /* Get line number of beginning of given declaration. */ 900 extern int dwarf_decl_line (Dwarf_Die *decl, int *linep) 901 __nonnull_attribute__ (2); 902 903 /* Get column number of beginning of given declaration. */ 904 extern int dwarf_decl_column (Dwarf_Die *decl, int *colp) 905 __nonnull_attribute__ (2); 906 907 908 /* Return nonzero if given function is an abstract inline definition. */ 909 extern int dwarf_func_inline (Dwarf_Die *func); 910 911 /* Find each concrete inlined instance of the abstract inline definition. */ 912 extern int dwarf_func_inline_instances (Dwarf_Die *func, 913 int (*callback) (Dwarf_Die *, void *), 914 void *arg); 915 916 917 /* Find the appropriate PC location or locations for function entry 918 breakpoints for the given DW_TAG_subprogram DIE. Returns -1 for errors. 919 On success, returns the number of breakpoint locations (never zero) 920 and sets *BKPTS to a malloc'd vector of addresses. */ 921 extern int dwarf_entry_breakpoints (Dwarf_Die *die, Dwarf_Addr **bkpts); 922 923 924 /* Iterate through the macro unit referenced by CUDIE and call 925 CALLBACK for each macro information entry. To start the iteration, 926 one would pass DWARF_GETMACROS_START for TOKEN. 927 928 The iteration continues while CALLBACK returns DWARF_CB_OK. If the 929 callback returns DWARF_CB_ABORT, the iteration stops and a 930 continuation token is returned, which can be used to restart the 931 iteration at the point where it ended. Returns -1 for errors or 0 932 if there are no more macro entries. 933 934 Note that the Dwarf_Macro pointer passed to the callback is only 935 valid for the duration of the callback invocation. 936 937 For backward compatibility, a token of 0 is accepted for starting 938 the iteration as well, but in that case this interface will refuse 939 to serve opcode 0xff from .debug_macro sections. Such opcode would 940 be considered invalid and would cause dwarf_getmacros to return 941 with error. */ 942 #define DWARF_GETMACROS_START PTRDIFF_MIN 943 extern ptrdiff_t dwarf_getmacros (Dwarf_Die *cudie, 944 int (*callback) (Dwarf_Macro *, void *), 945 void *arg, ptrdiff_t token) 946 __nonnull_attribute__ (2); 947 948 /* This is similar in operation to dwarf_getmacros, but selects the 949 unit to iterate through by offset instead of by CU, and always 950 iterates .debug_macro. This can be used for handling 951 DW_MACRO_GNU_transparent_include's or similar opcodes. 952 953 TOKEN value of DWARF_GETMACROS_START can be used to start the 954 iteration. 955 956 It is not appropriate to obtain macro unit offset by hand from a CU 957 DIE and then request iteration through this interface. The reason 958 for this is that if a dwarf_macro_getsrcfiles is later called, 959 there would be no way to figure out what DW_AT_comp_dir was present 960 on the CU DIE, and file names referenced in either the macro unit 961 itself, or the .debug_line unit that it references, might be wrong. 962 Use dwarf_getmacros. */ 963 extern ptrdiff_t dwarf_getmacros_off (Dwarf *dbg, Dwarf_Off macoff, 964 int (*callback) (Dwarf_Macro *, void *), 965 void *arg, ptrdiff_t token) 966 __nonnull_attribute__ (3); 967 968 /* Get the source files used by the macro entry. You shouldn't assume 969 that Dwarf_Files references will remain valid after MACRO becomes 970 invalid. (Which is to say it's only valid within the 971 dwarf_getmacros* callback.) Returns 0 for success or a negative 972 value in case of an error. */ 973 extern int dwarf_macro_getsrcfiles (Dwarf *dbg, Dwarf_Macro *macro, 974 Dwarf_Files **files, size_t *nfiles) 975 __nonnull_attribute__ (2, 3, 4); 976 977 /* Return macro opcode. That's a constant that can be either from 978 DW_MACINFO_* domain or DW_MACRO_GNU_* domain. The two domains have 979 compatible values, so it's OK to use either of them for 980 comparisons. The only differences is 0xff, which could be either 981 DW_MACINFO_vendor_ext or a vendor-defined DW_MACRO_* constant. One 982 would need to look if the CU DIE which the iteration was requested 983 for has attribute DW_AT_macro_info, or either of DW_AT_GNU_macros 984 or DW_AT_macros to differentiate the two interpretations. */ 985 extern int dwarf_macro_opcode (Dwarf_Macro *macro, unsigned int *opcodep) 986 __nonnull_attribute__ (2); 987 988 /* Get number of parameters of MACRO and store it to *PARAMCNTP. */ 989 extern int dwarf_macro_getparamcnt (Dwarf_Macro *macro, size_t *paramcntp); 990 991 /* Get IDX-th parameter of MACRO (numbered from zero), and stores it 992 to *ATTRIBUTE. Returns 0 on success or -1 for errors. 993 994 After a successful call, you can query ATTRIBUTE by dwarf_whatform 995 to determine which of the dwarf_formX calls to make to get actual 996 value out of ATTRIBUTE. Note that calling dwarf_whatattr is not 997 meaningful for pseudo-attributes formed this way. */ 998 extern int dwarf_macro_param (Dwarf_Macro *macro, size_t idx, 999 Dwarf_Attribute *attribute); 1000 1001 /* Return macro parameter with index 0. This will return -1 if the 1002 parameter is not an integral value. Use dwarf_macro_param for more 1003 general access. */ 1004 extern int dwarf_macro_param1 (Dwarf_Macro *macro, Dwarf_Word *paramp) 1005 __nonnull_attribute__ (2); 1006 1007 /* Return macro parameter with index 1. This will return -1 if the 1008 parameter is not an integral or string value. Use 1009 dwarf_macro_param for more general access. */ 1010 extern int dwarf_macro_param2 (Dwarf_Macro *macro, Dwarf_Word *paramp, 1011 const char **strp); 1012 1013 /* Compute what's known about a call frame when the PC is at ADDRESS. 1014 Returns 0 for success or -1 for errors. 1015 On success, *FRAME is a malloc'd pointer. */ 1016 extern int dwarf_cfi_addrframe (Dwarf_CFI *cache, 1017 Dwarf_Addr address, Dwarf_Frame **frame) 1018 __nonnull_attribute__ (3); 1019 1020 /* Return the DWARF register number used in FRAME to denote 1021 the return address in FRAME's caller frame. The remaining 1022 arguments can be non-null to fill in more information. 1023 1024 Fill [*START, *END) with the PC range to which FRAME's information applies. 1025 Fill in *SIGNALP to indicate whether this is a signal-handling frame. 1026 If true, this is the implicit call frame that calls a signal handler. 1027 This frame's "caller" is actually the interrupted state, not a call; 1028 its return address is an exact PC, not a PC after a call instruction. */ 1029 extern int dwarf_frame_info (Dwarf_Frame *frame, 1030 Dwarf_Addr *start, Dwarf_Addr *end, bool *signalp); 1031 1032 /* Return a DWARF expression that yields the Canonical Frame Address at 1033 this frame state. Returns -1 for errors, or zero for success, with 1034 *NOPS set to the number of operations stored at *OPS. That pointer 1035 can be used only as long as FRAME is alive and unchanged. *NOPS is 1036 zero if the CFA cannot be determined here. Note that if nonempty, 1037 *OPS is a DWARF expression, not a location description--append 1038 DW_OP_stack_value to a get a location description for the CFA. */ 1039 extern int dwarf_frame_cfa (Dwarf_Frame *frame, Dwarf_Op **ops, size_t *nops) 1040 __nonnull_attribute__ (2); 1041 1042 /* Deliver a DWARF location description that yields the location or 1043 value of DWARF register number REGNO in the state described by FRAME. 1044 1045 Returns -1 for errors or zero for success, setting *NOPS to the 1046 number of operations in the array stored at *OPS. Note the last 1047 operation is DW_OP_stack_value if there is no mutable location but 1048 only a computable value. 1049 1050 *NOPS zero with *OPS set to OPS_MEM means CFI says the caller's 1051 REGNO is "undefined", i.e. it's call-clobbered and cannot be recovered. 1052 1053 *NOPS zero with *OPS set to a null pointer means CFI says the 1054 caller's REGNO is "same_value", i.e. this frame did not change it; 1055 ask the caller frame where to find it. 1056 1057 For common simple expressions *OPS is OPS_MEM. For arbitrary DWARF 1058 expressions in the CFI, *OPS is an internal pointer that can be used as 1059 long as the Dwarf_CFI used to create FRAME remains alive. */ 1060 extern int dwarf_frame_register (Dwarf_Frame *frame, int regno, 1061 Dwarf_Op ops_mem[3], 1062 Dwarf_Op **ops, size_t *nops) 1063 __nonnull_attribute__ (3, 4, 5); 1064 1065 1066 /* Return error code of last failing function call. This value is kept 1067 separately for each thread. */ 1068 extern int dwarf_errno (void); 1069 1070 /* Return error string for ERROR. If ERROR is zero, return error string 1071 for most recent error or NULL is none occurred. If ERROR is -1 the 1072 behaviour is similar to the last case except that not NULL but a legal 1073 string is returned. */ 1074 extern const char *dwarf_errmsg (int err); 1075 1076 1077 /* Register new Out-Of-Memory handler. The old handler is returned. */ 1078 extern Dwarf_OOM dwarf_new_oom_handler (Dwarf *dbg, Dwarf_OOM handler); 1079 1080 1081 /* Inline optimizations. */ 1082 #ifdef __OPTIMIZE__ 1083 /* Return attribute code of given attribute. */ 1084 __libdw_extern_inline unsigned int 1085 dwarf_whatattr (Dwarf_Attribute *attr) 1086 { 1087 return attr == NULL ? 0 : attr->code; 1088 } 1089 1090 /* Return attribute code of given attribute. */ 1091 __libdw_extern_inline unsigned int 1092 dwarf_whatform (Dwarf_Attribute *attr) 1093 { 1094 return attr == NULL ? 0 : attr->form; 1095 } 1096 #endif /* Optimize. */ 1097 1098 #ifdef __cplusplus 1099 } 1100 #endif 1101 1102 #endif /* libdw.h */ 1103