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