libdw/libdw.h

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