libdw/libdw.h

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