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