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