libdw/libdw.h

   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.  */
  75 typedef enum
  76   {
  77     DWARF_C_READ,               /* Read .. */
  78     DWARF_C_RDWR,               /* Read and write .. */
  79     DWARF_C_WRITE,              /* Write .. */
  80   }
  81 Dwarf_Cmd;
  82
  83
  84 /* Callback results.  */
  85 enum
  86 {
  87   DWARF_CB_OK = 0,
  88   DWARF_CB_ABORT
  89 };
  90
  91
  92 /* Error values.  */
  93 enum
  94   {
  95     DW_TAG_invalid = 0
  96 #define DW_TAG_invalid  DW_TAG_invalid
  97   };
  98
  99
 100 /* Type for offset in DWARF file.  */
 101 typedef GElf_Off Dwarf_Off;
 102
 103 /* Type for address in DWARF file.  */
 104 typedef GElf_Addr Dwarf_Addr;
 105
 106 /* Integer types.  Big enough to hold any numeric value.  */
 107 typedef GElf_Xword Dwarf_Word;
 108 typedef GElf_Sxword Dwarf_Sword;
 109 /* For the times we know we do not need that much.  */
 110 typedef GElf_Half Dwarf_Half;
 111
 112
 113 /* DWARF abbreviation record.  */
 114 typedef 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.  */
 120 typedef struct Dwarf_Lines_s Dwarf_Lines;
 121
 122 /* One source code line information.  */
 123 typedef struct Dwarf_Line_s Dwarf_Line;
 124
 125 /* Source file information.  */
 126 typedef struct Dwarf_Files_s Dwarf_Files;
 127
 128 /* One address range record.  */
 129 typedef struct Dwarf_Arange_s Dwarf_Arange;
 130
 131 /* Address ranges of a file.  */
 132 typedef struct Dwarf_Aranges_s Dwarf_Aranges;
 133
 134 /* CU representation.  */
 135 struct Dwarf_CU;
 136
 137 /* Macro information.  */
 138 typedef struct Dwarf_Macro_s Dwarf_Macro;
 139
 140 /* Attribute representation.  */
 141 typedef 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.  */
 151 typedef struct
 152 {
 153   Dwarf_Word length;
 154   unsigned char *data;
 155 } Dwarf_Block;
 156
 157
 158 /* DIE information.  */
 159 typedef 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.  */
 174 typedef 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.  */
 184 typedef 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.  */
 195 typedef 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.  */
 221 typedef 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.  */
 243 typedef 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.  */
 253 typedef struct Dwarf_Frame_s Dwarf_Frame;
 254
 255 /* Opaque type representing a CFI section found in a DWARF or ELF file.  */
 256 typedef struct Dwarf_CFI_s Dwarf_CFI;
 257
 258
 259 /* Handle for debug sessions.  */
 260 typedef struct Dwarf Dwarf;
 261
 262
 263 /* Out-Of-Memory handler.  */
 264 #if __GNUC__ < 4
 265 typedef void (*Dwarf_OOM) (void);
 266 #else
 267 typedef void (*__attribute__ ((noreturn)) Dwarf_OOM) (void);
 268 #endif
 269
 270
 271 #ifdef __cplusplus
 272 extern "C" {
 273 #endif
 274
 275 /* Create a handle for a new debug session.  */
 276 extern Dwarf *dwarf_begin (int fildes, Dwarf_Cmd cmd);
 277
 278 /* Create a handle for a new debug session for an ELF file.  */
 279 extern Dwarf *dwarf_begin_elf (Elf *elf, Dwarf_Cmd cmd, Elf_Scn *scngrp);
 280
 281 /* Retrieve ELF descriptor used for DWARF access.  */
 282 extern Elf *dwarf_getelf (Dwarf *dwarf);
 283
 284 /* Release debugging handling context.  */
 285 extern int dwarf_end (Dwarf *dwarf);
 286
 287
 288 /* Get the data block for the .debug_info section.  */
 289 extern Elf_Data *dwarf_getscn_info (Dwarf *dwarf);
 290
 291 /* Read the header for the DWARF CU.  */
 292 extern 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.  */
 300 extern 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.  */
 325 extern 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.  */
 336 extern 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.  */
 343 extern Dwarf_CFI *dwarf_getcfi_elf (Elf *elf);
 344
 345 /* Release resources allocated by dwarf_getcfi_elf.  */
 346 extern int dwarf_cfi_end (Dwarf_CFI *cache);
 347
 348
 349 /* Return DIE at given offset in .debug_info section.  */
 350 extern 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.  */
 354 extern Dwarf_Die *dwarf_offdie_types (Dwarf *dbg, Dwarf_Off offset,
 355                                       Dwarf_Die *result)
 356      __nonnull_attribute__ (3);
 357
 358 /* Return offset of DIE.  */
 359 extern Dwarf_Off dwarf_dieoffset (Dwarf_Die *die);
 360
 361 /* Return offset of DIE in CU.  */
 362 extern Dwarf_Off dwarf_cuoffset (Dwarf_Die *die);
 363
 364 /* Return CU DIE containing given DIE.  */
 365 extern 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.  */
 370 extern Dwarf_Die *dwarf_addrdie (Dwarf *dbg, Dwarf_Addr addr,
 371                                  Dwarf_Die *result) __nonnull_attribute__ (3);
 372
 373 /* Return child of current DIE.  */
 374 extern 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.  */
 383 extern int dwarf_siblingof (Dwarf_Die *die, Dwarf_Die *result)
 384      __nonnull_attribute__ (2);
 385
 386 /* Check whether the DIE has children.  */
 387 extern 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.  */
 395 extern 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.  */
 401 extern int dwarf_tag (Dwarf_Die *die) __nonnull_attribute__ (1);
 402
 403
 404 /* Return specific attribute of DIE.  */
 405 extern 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.  */
 410 extern 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.  */
 414 extern Dwarf_Attribute *dwarf_attr_integrate (Dwarf_Die *die,
 415                                               unsigned int search_name,
 416                                               Dwarf_Attribute *result)
 417      __nonnull_attribute__ (3);
 418 extern int dwarf_hasattr_integrate (Dwarf_Die *die, unsigned int search_name);
 419
 420
 421
 422
 423 /* Check whether given attribute has specific form.  */
 424 extern int dwarf_hasform (Dwarf_Attribute *attr, unsigned int search_form);
 425
 426 /* Return attribute code of given attribute.  */
 427 extern unsigned int dwarf_whatattr (Dwarf_Attribute *attr);
 428
 429 /* Return form code of given attribute.  */
 430 extern unsigned int dwarf_whatform (Dwarf_Attribute *attr);
 431
 432
 433 /* Return string associated with given attribute.  */
 434 extern const char *dwarf_formstring (Dwarf_Attribute *attrp);
 435
 436 /* Return unsigned constant represented by attribute.  */
 437 extern int dwarf_formudata (Dwarf_Attribute *attr, Dwarf_Word *return_uval)
 438      __nonnull_attribute__ (2);
 439
 440 /* Return signed constant represented by attribute.  */
 441 extern int dwarf_formsdata (Dwarf_Attribute *attr, Dwarf_Sword *return_uval)
 442      __nonnull_attribute__ (2);
 443
 444 /* Return address represented by attribute.  */
 445 extern 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.  */
 450 extern 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.  */
 454 extern Dwarf_Die *dwarf_formref_die (Dwarf_Attribute *attr, Dwarf_Die *die_mem)
 455      __nonnull_attribute__ (2);
 456
 457 /* Return block represented by attribute.  */
 458 extern int dwarf_formblock (Dwarf_Attribute *attr, Dwarf_Block *return_block)
 459      __nonnull_attribute__ (2);
 460
 461 /* Return flag represented by attribute.  */
 462 extern 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.  */
 469 extern const char *dwarf_diename (Dwarf_Die *die);
 470
 471 /* Return high PC attribute of DIE.  */
 472 extern int dwarf_highpc (Dwarf_Die *die, Dwarf_Addr *return_addr)
 473      __nonnull_attribute__ (2);
 474
 475 /* Return low PC attribute of DIE.  */
 476 extern 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.  */
 480 extern 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.  */
 485 extern 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.  */
 494 extern 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.  */
 500 extern int dwarf_bytesize (Dwarf_Die *die);
 501
 502 /* Return bit size attribute of DIE.  */
 503 extern int dwarf_bitsize (Dwarf_Die *die);
 504
 505 /* Return bit offset attribute of DIE.  */
 506 extern int dwarf_bitoffset (Dwarf_Die *die);
 507
 508 /* Return array order attribute of DIE.  */
 509 extern int dwarf_arrayorder (Dwarf_Die *die);
 510
 511 /* Return source language attribute of DIE.  */
 512 extern int dwarf_srclang (Dwarf_Die *die);
 513
 514
 515 /* Get abbreviation at given offset for given DIE.  */
 516 extern 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.  */
 520 extern int dwarf_offabbrev (Dwarf *dbg, Dwarf_Off offset, size_t *lengthp,
 521                             Dwarf_Abbrev *abbrevp)
 522      __nonnull_attribute__ (4);
 523
 524 /* Get abbreviation code.  */
 525 extern unsigned int dwarf_getabbrevcode (Dwarf_Abbrev *abbrev);
 526
 527 /* Get abbreviation tag.  */
 528 extern unsigned int dwarf_getabbrevtag (Dwarf_Abbrev *abbrev);
 529
 530 /* Return true if abbreviation is children flag set.  */
 531 extern int dwarf_abbrevhaschildren (Dwarf_Abbrev *abbrev);
 532
 533 /* Get number of attributes of abbreviation.  */
 534 extern int dwarf_getattrcnt (Dwarf_Abbrev *abbrev, size_t *attrcntp)
 535      __nonnull_attribute__ (2);
 536
 537 /* Get specific attribute of abbreviation.  */
 538 extern 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.  */
 544 extern const char *dwarf_getstring (Dwarf *dbg, Dwarf_Off offset,
 545                                     size_t *lenp);
 546
 547
 548 /* Get public symbol information.  */
 549 extern 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.  */
 557 extern 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.  */
 561 extern Dwarf_Line *dwarf_onesrcline (Dwarf_Lines *lines, size_t idx);
 562
 563 /* Get the file source files used in the CU.  */
 564 extern 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.  */
 570 extern Dwarf_Line *dwarf_getsrc_die (Dwarf_Die *cudie, Dwarf_Addr addr);
 571
 572 /* Get source for file and line number.  */
 573 extern 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.  */
 579 extern int dwarf_lineaddr (Dwarf_Line *line, Dwarf_Addr *addrp);
 580
 581 /* Return line VLIW operation index.  */
 582 extern int dwarf_lineop_index (Dwarf_Line *line, unsigned int *op_indexp);
 583
 584 /* Return line number.  */
 585 extern int dwarf_lineno (Dwarf_Line *line, int *linep)
 586      __nonnull_attribute__ (2);
 587
 588 /* Return column in line.  */
 589 extern int dwarf_linecol (Dwarf_Line *line, int *colp)
 590      __nonnull_attribute__ (2);
 591
 592 /* Return true if record is for beginning of a statement.  */
 593 extern int dwarf_linebeginstatement (Dwarf_Line *line, bool *flagp)
 594      __nonnull_attribute__ (2);
 595
 596 /* Return true if record is for end of sequence.  */
 597 extern 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.  */
 601 extern int dwarf_lineblock (Dwarf_Line *line, bool *flagp)
 602      __nonnull_attribute__ (2);
 603
 604 /* Return true if record is for end of prologue.  */
 605 extern int dwarf_lineprologueend (Dwarf_Line *line, bool *flagp)
 606      __nonnull_attribute__ (2);
 607
 608 /* Return true if record is for beginning of epilogue.  */
 609 extern int dwarf_lineepiloguebegin (Dwarf_Line *line, bool *flagp)
 610      __nonnull_attribute__ (2);
 611
 612 /* Return instruction-set architecture in this record.  */
 613 extern int dwarf_lineisa (Dwarf_Line *line, unsigned int *isap)
 614      __nonnull_attribute__ (2);
 615
 616 /* Return code path discriminator in this record.  */
 617 extern int dwarf_linediscriminator (Dwarf_Line *line, unsigned int *discp)
 618      __nonnull_attribute__ (2);
 619
 620
 621 /* Find line information for address.  */
 622 extern const char *dwarf_linesrc (Dwarf_Line *line,
 623                                   Dwarf_Word *mtime, Dwarf_Word *length);
 624
 625 /* Return file information.  */
 626 extern 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.  */
 633 extern 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.  */
 639 extern 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.  */
 650 extern 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.  */
 657 extern 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.  */
 667 extern 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.  */
 676 extern 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.  */
 685 extern 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.  */
 694 extern 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.  */
 706 extern 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.  */
 715 extern 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.  */
 720 extern Dwarf_Arange *dwarf_onearange (Dwarf_Aranges *aranges, size_t idx);
 721
 722 /* Return information in address range record.  */
 723 extern 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.  */
 727 extern Dwarf_Arange *dwarf_getarange_addr (Dwarf_Aranges *aranges,
 728                                            Dwarf_Addr addr);
 729
 730
 731
 732 /* Get functions in CUDIE.  */
 733 extern 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.  */
 739 extern const char *dwarf_decl_file (Dwarf_Die *decl);
 740
 741 /* Get line number of beginning of given declaration.  */
 742 extern int dwarf_decl_line (Dwarf_Die *decl, int *linep)
 743      __nonnull_attribute__ (2);
 744
 745 /* Get column number of beginning of given declaration.  */
 746 extern 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.  */
 751 extern int dwarf_func_inline (Dwarf_Die *func);
 752
 753 /* Find each concrete inlined instance of the abstract inline definition.  */
 754 extern 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.  */
 763 extern 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.  */
 768 extern 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.  */
 774 extern int dwarf_macro_opcode (Dwarf_Macro *macro, unsigned int *opcodep)
 775      __nonnull_attribute__ (2);
 776
 777 /* Return first macro parameter.  */
 778 extern int dwarf_macro_param1 (Dwarf_Macro *macro, Dwarf_Word *paramp)
 779      __nonnull_attribute__ (2);
 780
 781 /* Return second macro parameter.  */
 782 extern 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.  */
 789 extern 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.  */
 802 extern 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.  */
 812 extern 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.  */
 833 extern 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.  */
 841 extern 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.  */
 847 extern const char *dwarf_errmsg (int err);
 848
 849
 850 /* Register new Out-Of-Memory handler.  The old handler is returned.  */
 851 extern 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
 858 dwarf_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
 865 dwarf_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 */