libdwfl/libdwfl.h

   1 /* Interfaces for libdwfl.
   2    Copyright (C) 2005-2010, 2013 Red Hat, Inc.
   3    This file is part of elfutils.
   4
   5    This file is free software; you can redistribute it and/or modify
   6    it under the terms of either
   7
   8      * the GNU Lesser General Public License as published by the Free
   9        Software Foundation; either version 3 of the License, or (at
  10        your option) any later version
  11
  12    or
  13
  14      * the GNU General Public License as published by the Free
  15        Software Foundation; either version 2 of the License, or (at
  16        your option) any later version
  17
  18    or both in parallel, as here.
  19
  20    elfutils is distributed in the hope that it will be useful, but
  21    WITHOUT ANY WARRANTY; without even the implied warranty of
  22    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  23    General Public License for more details.
  24
  25    You should have received copies of the GNU General Public License and
  26    the GNU Lesser General Public License along with this program.  If
  27    not, see <http://www.gnu.org/licenses/>.  */
  28
  29 #ifndef _LIBDWFL_H
  30 #define _LIBDWFL_H      1
  31
  32 #include "libdw.h"
  33 #include <stdio.h>
  34
  35 /* Handle for a session using the library.  */
  36 typedef struct Dwfl Dwfl;
  37
  38 /* Handle for a module.  */
  39 typedef struct Dwfl_Module Dwfl_Module;
  40
  41 /* Handle describing a line record.  */
  42 typedef struct Dwfl_Line Dwfl_Line;
  43
  44 /* This holds information common for all the frames of one backtrace for
  45    a partical thread/task/TID.  Several threads belong to one Dwfl.  */
  46 typedef struct Dwfl_Thread Dwfl_Thread;
  47
  48 /* This holds everything we know about the state of the frame at a particular
  49    PC location described by an FDE belonging to Dwfl_Thread.  */
  50 typedef struct Dwfl_Frame Dwfl_Frame;
  51
  52 /* Callbacks.  */
  53 typedef struct
  54 {
  55   int (*find_elf) (Dwfl_Module *mod, void **userdata,
  56                    const char *modname, Dwarf_Addr base,
  57                    char **file_name, Elf **elfp);
  58
  59   int (*find_debuginfo) (Dwfl_Module *mod, void **userdata,
  60                          const char *modname, Dwarf_Addr base,
  61                          const char *file_name,
  62                          const char *debuglink_file, GElf_Word debuglink_crc,
  63                          char **debuginfo_file_name);
  64
  65   /* Fill *ADDR with the loaded address of the section called SECNAME in
  66      the given module.  Use (Dwarf_Addr) -1 if this section is omitted from
  67      accessible memory.  This is called exactly once for each SHF_ALLOC
  68      section that relocations affecting DWARF data refer to, so it can
  69      easily be used to collect state about the sections referenced.  */
  70   int (*section_address) (Dwfl_Module *mod, void **userdata,
  71                           const char *modname, Dwarf_Addr base,
  72                           const char *secname,
  73                           GElf_Word shndx, const GElf_Shdr *shdr,
  74                           Dwarf_Addr *addr);
  75
  76   char **debuginfo_path;        /* See dwfl_standard_find_debuginfo.  */
  77 } Dwfl_Callbacks;
  78
  79
  80 #ifdef __cplusplus
  81 extern "C" {
  82 #endif
  83
  84 /* Start a new session with the library.  */
  85 extern Dwfl *dwfl_begin (const Dwfl_Callbacks *callbacks)
  86   __nonnull_attribute__ (1);
  87
  88
  89 /* End a session.  */
  90 extern void dwfl_end (Dwfl *);
  91
  92 /* Return implementation's version string suitable for printing.  */
  93 extern const char *dwfl_version (Dwfl *);
  94
  95 /* Return error code of last failing function call.  This value is kept
  96    separately for each thread.  */
  97 extern int dwfl_errno (void);
  98
  99 /* Return error string for ERROR.  If ERROR is zero, return error string
 100    for most recent error or NULL if none occurred.  If ERROR is -1 the
 101    behaviour is similar to the last case except that not NULL but a legal
 102    string is returned.  */
 103 extern const char *dwfl_errmsg (int err);
 104
 105
 106 /* Start reporting the current set of segments and modules to the library.
 107    All existing segments are wiped.  Existing modules are marked to be
 108    deleted, and will not be found via dwfl_addrmodule et al if they are not
 109    re-reported before dwfl_report_end is called.  */
 110 extern void dwfl_report_begin (Dwfl *dwfl);
 111
 112 /* Report that segment NDX begins at PHDR->p_vaddr + BIAS.
 113    If NDX is < 0, the value succeeding the last call's NDX
 114    is used instead (zero on the first call).
 115
 116    If nonzero, the smallest PHDR->p_align value seen sets the
 117    effective page size for the address space DWFL describes.
 118    This is the granularity at which reported module boundary
 119    addresses will be considered to fall in or out of a segment.
 120
 121    Returns -1 for errors, or NDX (or its assigned replacement) on success.
 122
 123    When NDX is the value succeeding the last call's NDX (or is implicitly
 124    so as above), IDENT is nonnull and matches the value in the last call,
 125    and the PHDR and BIAS values reflect a segment that would be contiguous,
 126    in both memory and file, with the last segment reported, then this
 127    segment may be coalesced internally with preceding segments.  When given
 128    an address inside this segment, dwfl_addrsegment may return the NDX of a
 129    preceding contiguous segment.  To prevent coalesced segments, always
 130    pass a null pointer for IDENT.
 131
 132    The values passed are not stored (except to track coalescence).
 133    The only information that can be extracted from DWFL later is the
 134    mapping of an address to a segment index that starts at or below
 135    it.  Reporting segments at all is optional.  Its only benefit to
 136    the caller is to offer this quick lookup via dwfl_addrsegment,
 137    or use other segment-based calls.  */
 138 extern int dwfl_report_segment (Dwfl *dwfl, int ndx,
 139                                 const GElf_Phdr *phdr, GElf_Addr bias,
 140                                 const void *ident);
 141
 142 /* Report that a module called NAME spans addresses [START, END).
 143    Returns the module handle, either existing or newly allocated,
 144    or returns a null pointer for an allocation error.  */
 145 extern Dwfl_Module *dwfl_report_module (Dwfl *dwfl, const char *name,
 146                                         Dwarf_Addr start, Dwarf_Addr end);
 147
 148 /* Report a module to address BASE with start and end addresses computed
 149    from the ELF program headers in the given file - see the table below.
 150    FD may be -1 to open FILE_NAME.  On success, FD is consumed by the
 151    library, and the `find_elf' callback will not be used for this module.
 152             ADD_P_VADDR  BASE
 153    ET_EXEC  ignored      ignored
 154    ET_DYN   false        absolute address where to place the file
 155             true         start address relative to ELF's phdr p_vaddr
 156    ET_REL   ignored      absolute address where to place the file
 157    ET_CORE  ignored      ignored
 158    ET_DYN ELF phdr p_vaddr address can be non-zero if the shared library
 159    has been prelinked by tool prelink(8).  */
 160 extern Dwfl_Module *dwfl_report_elf (Dwfl *dwfl, const char *name,
 161                                      const char *file_name, int fd,
 162                                      GElf_Addr base, bool add_p_vaddr);
 163
 164 /* Similar, but report the module for offline use.  All ET_EXEC files
 165    being reported must be reported before any relocatable objects.
 166    If this is used, dwfl_report_module and dwfl_report_elf may not be
 167    used in the same reporting session.  */
 168 extern Dwfl_Module *dwfl_report_offline (Dwfl *dwfl, const char *name,
 169                                          const char *file_name, int fd);
 170
 171
 172 /* Finish reporting the current set of modules to the library.
 173    If REMOVED is not null, it's called for each module that
 174    existed before but was not included in the current report.
 175    Returns a nonzero return value from the callback.
 176    The callback may call dwfl_report_module; doing so with the
 177    details of the module being removed prevents its removal.
 178    DWFL cannot be used until this function has returned zero.  */
 179 extern int dwfl_report_end (Dwfl *dwfl,
 180                             int (*removed) (Dwfl_Module *, void *,
 181                                             const char *, Dwarf_Addr,
 182                                             void *arg),
 183                             void *arg);
 184
 185 /* Start reporting additional modules to the library.  No calls but
 186    dwfl_report_* can be made on DWFL until dwfl_report_end is called.
 187    This is like dwfl_report_begin, but all the old modules are kept on.
 188    More dwfl_report_* calls can follow to add more modules.
 189    When dwfl_report_end is called, no old modules will be removed.  */
 190 extern void dwfl_report_begin_add (Dwfl *dwfl);
 191
 192
 193 /* Return the name of the module, and for each non-null argument store
 194    interesting details: *USERDATA is a location for storing your own
 195    pointer, **USERDATA is initially null; *START and *END give the address
 196    range covered by the module; *DWBIAS is the address bias for debugging
 197    information, and *SYMBIAS for symbol table entries (either is -1 if not
 198    yet accessed); *MAINFILE is the name of the ELF file, and *DEBUGFILE the
 199    name of the debuginfo file (might be equal to *MAINFILE; either is null
 200    if not yet accessed).  */
 201 extern const char *dwfl_module_info (Dwfl_Module *mod, void ***userdata,
 202                                      Dwarf_Addr *start, Dwarf_Addr *end,
 203                                      Dwarf_Addr *dwbias, Dwarf_Addr *symbias,
 204                                      const char **mainfile,
 205                                      const char **debugfile);
 206
 207 /* Iterate through the modules, starting the walk with OFFSET == 0.
 208    Calls *CALLBACK for each module as long as it returns DWARF_CB_OK.
 209    When *CALLBACK returns another value, the walk stops and the
 210    return value can be passed as OFFSET to resume it.  Returns 0 when
 211    there are no more modules, or -1 for errors.  */
 212 extern ptrdiff_t dwfl_getmodules (Dwfl *dwfl,
 213                                   int (*callback) (Dwfl_Module *, void **,
 214                                                    const char *, Dwarf_Addr,
 215                                                    void *arg),
 216                                   void *arg,
 217                                   ptrdiff_t offset);
 218
 219 /* Find the module containing the given address.  */
 220 extern Dwfl_Module *dwfl_addrmodule (Dwfl *dwfl, Dwarf_Addr address);
 221
 222 /* Find the segment, if any, and module, if any, containing ADDRESS.
 223    Returns a segment index returned by dwfl_report_segment, or -1
 224    if no segment matches the address.  Regardless of the return value,
 225    *MOD is always set to the module containing ADDRESS, or to null.  */
 226 extern int dwfl_addrsegment (Dwfl *dwfl, Dwarf_Addr address, Dwfl_Module **mod);
 227
 228
 229
 230 /* Report the known build ID bits associated with a module.
 231    If VADDR is nonzero, it gives the absolute address where those
 232    bits are found within the module.  This can be called at any
 233    time, but is usually used immediately after dwfl_report_module.
 234    Once the module's main ELF file is opened, the ID note found
 235    there takes precedence and cannot be changed.  */
 236 extern int dwfl_module_report_build_id (Dwfl_Module *mod,
 237                                         const unsigned char *bits, size_t len,
 238                                         GElf_Addr vaddr)
 239   __nonnull_attribute__ (2);
 240
 241 /* Extract the build ID bits associated with a module.
 242    Returns -1 for errors, 0 if no ID is known, or the number of ID bytes.
 243    When an ID is found, *BITS points to it; *VADDR is the absolute address
 244    at which the ID bits are found within the module, or 0 if unknown.
 245
 246    This returns 0 when the module's main ELF file has not yet been loaded
 247    and its build ID bits were not reported.  To ensure the ID is always
 248    returned when determinable, call dwfl_module_getelf first.  */
 249 extern int dwfl_module_build_id (Dwfl_Module *mod,
 250                                  const unsigned char **bits, GElf_Addr *vaddr)
 251   __nonnull_attribute__ (2, 3);
 252
 253
 254 /*** Standard callbacks ***/
 255
 256 /* These standard find_elf and find_debuginfo callbacks are
 257    controlled by a string specifying directories to look in.
 258    If `debuginfo_path' is set in the Dwfl_Callbacks structure
 259    and the char * it points to is not null, that supplies the
 260    string.  Otherwise a default path is used.
 261
 262    If the first character of the string is + or - that enables or
 263    disables CRC32 checksum validation when it's necessary.  The
 264    remainder of the string is composed of elements separated by
 265    colons.  Each element can start with + or - to override the
 266    global checksum behavior.  This flag is never relevant when
 267    working with build IDs, but it's always parsed in the path
 268    string.  The remainder of the element indicates a directory.
 269
 270    Searches by build ID consult only the elements naming absolute
 271    directory paths.  They look under those directories for a link
 272    named ".build-id/xx/yy" or ".build-id/xx/yy.debug", where "xxyy"
 273    is the lower-case hexadecimal representation of the ID bytes.
 274
 275    In searches for debuginfo by name, if the remainder of the
 276    element is empty, the directory containing the main file is
 277    tried; if it's an absolute path name, the absolute directory path
 278    (and any subdirectory of that path) containing the main file is
 279    taken as a subdirectory of this path; a relative path name is taken
 280    as a subdirectory of the directory containing the main file.
 281    Hence for /usr/bin/ls, the default string ":.debug:/usr/lib/debug"
 282    says to look in /usr/bin, then /usr/bin/.debug, then the path subdirs
 283    under /usr/lib/debug, in the order /usr/lib/debug/usr/bin, then
 284    /usr/lib/debug/bin, and finally /usr/lib/debug, for the file name in
 285    the .gnu_debuglink section (or "ls.debug" if none was found).  */
 286
 287 /* Standard find_elf callback function working solely on build ID.
 288    This can be tried first by any find_elf callback, to use the
 289    bits passed to dwfl_module_report_build_id, if any.  */
 290 extern int dwfl_build_id_find_elf (Dwfl_Module *, void **,
 291                                    const char *, Dwarf_Addr,
 292                                    char **, Elf **);
 293
 294 /* Standard find_debuginfo callback function working solely on build ID.
 295    This can be tried first by any find_debuginfo callback,
 296    to use the build ID bits from the main file when present.  */
 297 extern int dwfl_build_id_find_debuginfo (Dwfl_Module *, void **,
 298                                          const char *, Dwarf_Addr,
 299                                          const char *, const char *,
 300                                          GElf_Word, char **);
 301
 302 /* Standard find_debuginfo callback function.
 303    If a build ID is available, this tries first to use that.
 304    If there is no build ID or no valid debuginfo found by ID,
 305    it searches the debuginfo path by name, as described above.
 306    Any file found in the path is validated by build ID if possible,
 307    or else by CRC32 checksum if enabled, and skipped if it does not match.  */
 308 extern int dwfl_standard_find_debuginfo (Dwfl_Module *, void **,
 309                                          const char *, Dwarf_Addr,
 310                                          const char *, const char *,
 311                                          GElf_Word, char **);
 312
 313
 314 /* This callback must be used when using dwfl_offline_* to report modules,
 315    if ET_REL is to be supported.  */
 316 extern int dwfl_offline_section_address (Dwfl_Module *, void **,
 317                                          const char *, Dwarf_Addr,
 318                                          const char *, GElf_Word,
 319                                          const GElf_Shdr *,
 320                                          Dwarf_Addr *addr);
 321
 322
 323 /* Callbacks for working with kernel modules in the running Linux kernel.  */
 324 extern int dwfl_linux_kernel_find_elf (Dwfl_Module *, void **,
 325                                        const char *, Dwarf_Addr,
 326                                        char **, Elf **);
 327 extern int dwfl_linux_kernel_module_section_address (Dwfl_Module *, void **,
 328                                                      const char *, Dwarf_Addr,
 329                                                      const char *, GElf_Word,
 330                                                      const GElf_Shdr *,
 331                                                      Dwarf_Addr *addr);
 332
 333 /* Call dwfl_report_elf for the running Linux kernel.
 334    Returns zero on success, -1 if dwfl_report_module failed,
 335    or an errno code if opening the kernel binary failed.  */
 336 extern int dwfl_linux_kernel_report_kernel (Dwfl *dwfl);
 337
 338 /* Call dwfl_report_module for each kernel module in the running Linux kernel.
 339    Returns zero on success, -1 if dwfl_report_module failed,
 340    or an errno code if reading the list of modules failed.  */
 341 extern int dwfl_linux_kernel_report_modules (Dwfl *dwfl);
 342
 343 /* Report a kernel and its modules found on disk, for offline use.
 344    If RELEASE starts with '/', it names a directory to look in;
 345    if not, it names a directory to find under /lib/modules/;
 346    if null, /lib/modules/`uname -r` is used.
 347    Returns zero on success, -1 if dwfl_report_module failed,
 348    or an errno code if finding the files on disk failed.
 349
 350    If PREDICATE is not null, it is called with each module to be reported;
 351    its arguments are the module name, and the ELF file name or null if unknown,
 352    and its return value should be zero to skip the module, one to report it,
 353    or -1 to cause the call to fail and return errno.  */
 354 extern int dwfl_linux_kernel_report_offline (Dwfl *dwfl, const char *release,
 355                                              int (*predicate) (const char *,
 356                                                                const char *));
 357
 358 /* Examine an ET_CORE file and report modules based on its contents.
 359    This can follow a dwfl_report_offline call to bootstrap the
 360    DT_DEBUG method of following the dynamic linker link_map chain, in
 361    case the core file does not contain enough of the executable's text
 362    segment to locate its PT_DYNAMIC in the dump.  In such case you need to
 363    supply non-NULL EXECUTABLE, otherwise dynamic libraries will not be loaded
 364    into the DWFL map.  This might call dwfl_report_elf on file names found in
 365    the dump if reading some link_map files is the only way to ascertain those
 366    modules' addresses.  Returns the number of modules reported, or -1 for
 367    errors.  */
 368 extern int dwfl_core_file_report (Dwfl *dwfl, Elf *elf, const char *executable);
 369
 370 /* Call dwfl_report_module for each file mapped into the address space of PID.
 371    Returns zero on success, -1 if dwfl_report_module failed,
 372    or an errno code if opening the proc files failed.  */
 373 extern int dwfl_linux_proc_report (Dwfl *dwfl, pid_t pid);
 374
 375 /* Similar, but reads an input stream in the format of Linux /proc/PID/maps
 376    files giving module layout, not the file for a live process.  */
 377 extern int dwfl_linux_proc_maps_report (Dwfl *dwfl, FILE *);
 378
 379 /* Trivial find_elf callback for use with dwfl_linux_proc_report.
 380    This uses the module name as a file name directly and tries to open it
 381    if it begin with a slash, or handles the magic string "[vdso]".  */
 382 extern int dwfl_linux_proc_find_elf (Dwfl_Module *mod, void **userdata,
 383                                      const char *module_name, Dwarf_Addr base,
 384                                      char **file_name, Elf **);
 385
 386 /* Standard argument parsing for using a standard callback set.  */
 387 struct argp;
 388 extern const struct argp *dwfl_standard_argp (void) __attribute__ ((const));
 389
 390
 391 /*** Relocation of addresses from Dwfl ***/
 392
 393 /* Return the number of relocatable bases associated with the module,
 394    which is zero for ET_EXEC and one for ET_DYN.  Returns -1 for errors.  */
 395 extern int dwfl_module_relocations (Dwfl_Module *mod);
 396
 397 /* Return the relocation base index associated with the *ADDRESS location,
 398    and adjust *ADDRESS to be an offset relative to that base.
 399    Returns -1 for errors.  */
 400 extern int dwfl_module_relocate_address (Dwfl_Module *mod,
 401                                          Dwarf_Addr *address);
 402
 403 /* Return the ELF section name for the given relocation base index;
 404    if SHNDXP is not null, set *SHNDXP to the ELF section index.
 405    For ET_DYN, returns "" and sets *SHNDXP to SHN_ABS; the relocation
 406    base is the runtime start address reported for the module.
 407    Returns null for errors.  */
 408 extern const char *dwfl_module_relocation_info (Dwfl_Module *mod,
 409                                                 unsigned int idx,
 410                                                 GElf_Word *shndxp);
 411
 412 /* Validate that ADDRESS and ADDRESS+OFFSET lie in a known module
 413    and both within the same contiguous region for relocation purposes.
 414    Returns zero for success and -1 for errors.  */
 415 extern int dwfl_validate_address (Dwfl *dwfl,
 416                                   Dwarf_Addr address, Dwarf_Sword offset);
 417
 418
 419 /*** ELF access functions ***/
 420
 421 /* Fetch the module main ELF file (where the allocated sections
 422    are found) for use with libelf.  If successful, fills in *BIAS
 423    with the difference between addresses within the loaded module
 424    and those in symbol tables or Dwarf information referring to it.  */
 425 extern Elf *dwfl_module_getelf (Dwfl_Module *, GElf_Addr *bias)
 426   __nonnull_attribute__ (2);
 427
 428 /* Return the number of symbols in the module's symbol table,
 429    or -1 for errors.  */
 430 extern int dwfl_module_getsymtab (Dwfl_Module *mod);
 431
 432 /* Return the index of the first global symbol in the module's symbol
 433    table, or -1 for errors.  In each symbol table, all symbols with
 434    STB_LOCAL binding precede the weak and global symbols.  This
 435    function returns the symbol table index one greater than the last
 436    local symbol.  */
 437 extern int dwfl_module_getsymtab_first_global (Dwfl_Module *mod);
 438
 439 /* Fetch one entry from the module's symbol table.  On errors, returns
 440    NULL.  If successful, fills in *SYM and returns the string for st_name.
 441    This works like gelf_getsym except that st_value is always adjusted to
 442    an absolute value based on the module's location, when the symbol is in
 443    an SHF_ALLOC section.  If SHNDXP is non-null, it's set with the section
 444    index (whether from st_shndx or extended index table); in case of a
 445    symbol in a non-allocated section, *SHNDXP is instead set to -1.
 446    Note that since symbols can come from either the main, debug or auxiliary
 447    ELF symbol file (either dynsym or symtab) the section index can only
 448    be reliably used to compare against special section constants like
 449    SHN_UNDEF or SHN_ABS.  It is recommended to use dwfl_module_getsym_info
 450    which doesn't have these deficiencies.  */
 451 extern const char *dwfl_module_getsym (Dwfl_Module *mod, int ndx,
 452                                        GElf_Sym *sym, GElf_Word *shndxp)
 453   __nonnull_attribute__ (3);
 454
 455 /* Fetch one entry from the module's symbol table and the associated
 456    address value.  On errors, returns NULL.  If successful, fills in
 457    *SYM, *ADDR and returns the string for st_name.  This works like
 458    gelf_getsym.  *ADDR is set to the st_value adjusted to an absolute
 459    value based on the module's location, when the symbol is in an
 460    SHF_ALLOC section.  For non-ET_REL files, if the arch uses function
 461    descriptors, and the st_value points to one, *ADDR will be resolved
 462    to the actual function entry address.  The SYM->ST_VALUE itself
 463    isn't adjusted in any way.  Fills in ELFP, if not NULL, with the
 464    ELF file the symbol originally came from.  Note that symbols can
 465    come from either the main, debug or auxiliary ELF symbol file
 466    (either dynsym or symtab).  If SHNDXP is non-null, it's set with
 467    the section index (whether from st_shndx or extended index table);
 468    in case of a symbol in a non-allocated section, *SHNDXP is instead
 469    set to -1.  Fills in BIAS, if not NULL, with the difference between
 470    addresses within the loaded module and those in symbol table of the
 471    ELF file.  Note that the address associated with the symbol might
 472    be in a different section than the returned symbol.  The section in
 473    the main elf file in which returned ADDR falls can be found with
 474    dwfl_module_address_section.  */
 475 extern const char *dwfl_module_getsym_info (Dwfl_Module *mod, int ndx,
 476                                             GElf_Sym *sym, GElf_Addr *addr,
 477                                             GElf_Word *shndxp,
 478                                             Elf **elfp, Dwarf_Addr *bias)
 479   __nonnull_attribute__ (3, 4);
 480
 481 /* Find the symbol that ADDRESS lies inside, and return its name.  */
 482 extern const char *dwfl_module_addrname (Dwfl_Module *mod, GElf_Addr address);
 483
 484 /* Find the symbol associated with ADDRESS.  Return its name or NULL
 485    when nothing was found.  If the architecture uses function
 486    descriptors, and symbol st_value points to one, ADDRESS wil be
 487    matched against either the adjusted st_value or the associated
 488    function entry value as described in dwfl_module_getsym_info.  If
 489    OFFSET is not NULL it will be filled in with the difference from
 490    the start of the symbol (or function entry).  If SYM is not NULL it
 491    is filled in with the symbol associated with the matched ADDRESS.
 492    The SYM->ST_VALUE itself isn't adjusted in any way.  Fills in ELFP,
 493    if not NULL, with the ELF file the symbol originally came from.
 494    Note that symbols can come from either the main, debug or auxiliary
 495    ELF symbol file (either dynsym or symtab).  If SHNDXP is non-null,
 496    it's set with the section index (whether from st_shndx or extended
 497    index table).  Fills in BIAS, if not NULL, with the difference
 498    between addresses within the loaded module and those in symbol
 499    table of the ELF file.  Note that the address matched against the
 500    symbol might be in a different section than the returned symbol.
 501    The section in the main elf file in ADDRESS falls can be found with
 502    dwfl_module_address_section.  */
 503 extern const char *dwfl_module_addrinfo (Dwfl_Module *mod, GElf_Addr address,
 504                                          GElf_Off *offset, GElf_Sym *sym,
 505                                          GElf_Word *shndxp, Elf **elfp,
 506                                          Dwarf_Addr *bias)
 507   __nonnull_attribute__ (3);
 508
 509 /* Find the symbol that ADDRESS lies inside, and return detailed
 510    information as for dwfl_module_getsym (above).  Note that like
 511    dwfl_module_getsym this function also adjusts SYM->ST_VALUE to an
 512    absolute value based on the module's location.  ADDRESS is only
 513    matched against this adjusted SYM->ST_VALUE.  This means that
 514    depending on architecture this might only match symbols that
 515    represent function descriptor addresses (and not function entry
 516    addresses).  For these reasons it is recommended to use
 517    dwfl_module_addrinfo instead.  */
 518 extern const char *dwfl_module_addrsym (Dwfl_Module *mod, GElf_Addr address,
 519                                         GElf_Sym *sym, GElf_Word *shndxp)
 520   __nonnull_attribute__ (3);
 521
 522 /* Find the ELF section that *ADDRESS lies inside and return it.
 523    On success, adjusts *ADDRESS to be relative to the section,
 524    and sets *BIAS to the difference between addresses used in
 525    the returned section's headers and run-time addresses.  */
 526 extern Elf_Scn *dwfl_module_address_section (Dwfl_Module *mod,
 527                                              Dwarf_Addr *address,
 528                                              Dwarf_Addr *bias)
 529   __nonnull_attribute__ (2, 3);
 530
 531
 532 /*** Dwarf access functions ***/
 533
 534 /* Fetch the module's debug information for use with libdw.
 535    If successful, fills in *BIAS with the difference between
 536    addresses within the loaded module and those  to use with libdw.  */
 537 extern Dwarf *dwfl_module_getdwarf (Dwfl_Module *, Dwarf_Addr *bias)
 538      __nonnull_attribute__ (2);
 539
 540 /* Get the libdw handle for each module.  */
 541 extern ptrdiff_t dwfl_getdwarf (Dwfl *,
 542                                 int (*callback) (Dwfl_Module *, void **,
 543                                                  const char *, Dwarf_Addr,
 544                                                  Dwarf *, Dwarf_Addr, void *),
 545                                 void *arg, ptrdiff_t offset);
 546
 547 /* Look up the module containing ADDR and return its debugging information,
 548    loading it if necessary.  */
 549 extern Dwarf *dwfl_addrdwarf (Dwfl *dwfl, Dwarf_Addr addr, Dwarf_Addr *bias)
 550      __nonnull_attribute__ (3);
 551
 552
 553 /* Find the CU containing ADDR and return its DIE.  */
 554 extern Dwarf_Die *dwfl_addrdie (Dwfl *dwfl, Dwarf_Addr addr, Dwarf_Addr *bias)
 555      __nonnull_attribute__ (3);
 556 extern Dwarf_Die *dwfl_module_addrdie (Dwfl_Module *mod,
 557                                        Dwarf_Addr addr, Dwarf_Addr *bias)
 558      __nonnull_attribute__ (3);
 559
 560 /* Iterate through the CUs, start with null for LASTCU.  */
 561 extern Dwarf_Die *dwfl_nextcu (Dwfl *dwfl, Dwarf_Die *lastcu, Dwarf_Addr *bias)
 562      __nonnull_attribute__ (3);
 563 extern Dwarf_Die *dwfl_module_nextcu (Dwfl_Module *mod,
 564                                       Dwarf_Die *lastcu, Dwarf_Addr *bias)
 565      __nonnull_attribute__ (3);
 566
 567 /* Return the module containing the CU DIE.  */
 568 extern Dwfl_Module *dwfl_cumodule (Dwarf_Die *cudie);
 569
 570
 571 /* Cache the source line information fo the CU and return the
 572    number of Dwfl_Line entries it has.  */
 573 extern int dwfl_getsrclines (Dwarf_Die *cudie, size_t *nlines);
 574
 575 /* Access one line number entry within the CU.  */
 576 extern Dwfl_Line *dwfl_onesrcline (Dwarf_Die *cudie, size_t idx);
 577
 578 /* Get source for address.  */
 579 extern Dwfl_Line *dwfl_module_getsrc (Dwfl_Module *mod, Dwarf_Addr addr);
 580 extern Dwfl_Line *dwfl_getsrc (Dwfl *dwfl, Dwarf_Addr addr);
 581
 582 /* Get address for source.  */
 583 extern int dwfl_module_getsrc_file (Dwfl_Module *mod,
 584                                     const char *fname, int lineno, int column,
 585                                     Dwfl_Line ***srcsp, size_t *nsrcs);
 586
 587 /* Return the module containing this line record.  */
 588 extern Dwfl_Module *dwfl_linemodule (Dwfl_Line *line);
 589
 590 /* Return the CU containing this line record.  */
 591 extern Dwarf_Die *dwfl_linecu (Dwfl_Line *line);
 592
 593 /* Return the source file name and fill in other information.
 594    Arguments may be null for unneeded fields.  */
 595 extern const char *dwfl_lineinfo (Dwfl_Line *line, Dwarf_Addr *addr,
 596                                   int *linep, int *colp,
 597                                   Dwarf_Word *mtime, Dwarf_Word *length);
 598
 599   /* Return the equivalent Dwarf_Line and the bias to apply to its address.  */
 600 extern Dwarf_Line *dwfl_dwarf_line (Dwfl_Line *line, Dwarf_Addr *bias);
 601
 602 /* Return the compilation directory (AT_comp_dir) from this line's CU.  */
 603 extern const char *dwfl_line_comp_dir (Dwfl_Line *line);
 604
 605
 606 /*** Machine backend access functions ***/
 607
 608 /* Return location expression to find return value given a
 609    DW_TAG_subprogram, DW_TAG_subroutine_type, or similar DIE describing
 610    function itself (whose DW_AT_type attribute describes its return type).
 611    The given DIE must come from the given module.  Returns -1 for errors.
 612    Returns zero if the function has no return value (e.g. "void" in C).
 613    Otherwise, *LOCOPS gets a location expression to find the return value,
 614    and returns the number of operations in the expression.  The pointer is
 615    permanently allocated at least as long as the module is live.  */
 616 extern int dwfl_module_return_value_location (Dwfl_Module *mod,
 617                                               Dwarf_Die *functypedie,
 618                                               const Dwarf_Op **locops);
 619
 620 /* Enumerate the DWARF register numbers and their names.
 621    For each register, CALLBACK gets its DWARF number, a string describing
 622    the register set (such as "integer" or "FPU"), a prefix used in
 623    assembler syntax (such as "%" or "$", may be ""), and the name for the
 624    register (contains identifier characters only, possibly all digits).
 625    The REGNAME string is valid only during the callback. */
 626 extern int dwfl_module_register_names (Dwfl_Module *mod,
 627                                        int (*callback) (void *arg,
 628                                                         int regno,
 629                                                         const char *setname,
 630                                                         const char *prefix,
 631                                                         const char *regname,
 632                                                         int bits, int type),
 633                                        void *arg);
 634
 635
 636 /* Find the CFI for this module.  Returns NULL if there is no CFI.
 637    On success, fills in *BIAS with the difference between addresses
 638    within the loaded module and those in the CFI referring to it.
 639    The pointer returned can be used until the module is cleaned up.
 640    Calling these more than once returns the same pointers.
 641
 642    dwfl_module_dwarf_cfi gets the '.debug_frame' information found with the
 643    rest of the DWARF information.  dwfl_module_eh_cfi gets the '.eh_frame'
 644    information found linked into the text.  A module might have either or
 645    both.  */
 646 extern Dwarf_CFI *dwfl_module_dwarf_cfi (Dwfl_Module *mod, Dwarf_Addr *bias);
 647 extern Dwarf_CFI *dwfl_module_eh_cfi (Dwfl_Module *mod, Dwarf_Addr *bias);
 648
 649
 650 typedef struct
 651 {
 652   /* Called to iterate through threads.  Returns next TID (thread ID) on
 653      success, a negative number on failure and zero if there are no more
 654      threads.  dwfl_errno () should be set if negative number has been
 655      returned.  *THREAD_ARGP is NULL on first call, and may be optionally
 656      set by the implementation. The value set by the implementation will
 657      be passed in on the next call to NEXT_THREAD.  THREAD_ARGP is never
 658      NULL.  *THREAD_ARGP will be passed to set_initial_registers or
 659      thread_detach callbacks together with Dwfl_Thread *thread.  This
 660      method must not be NULL.  */
 661   pid_t (*next_thread) (Dwfl *dwfl, void *dwfl_arg, void **thread_argp)
 662     __nonnull_attribute__ (1);
 663
 664   /* Called to get a specific thread.  Returns true if there is a
 665      thread with the given thread id number, returns false if no such
 666      thread exists and will set dwfl_errno in that case.  THREAD_ARGP
 667      is never NULL.  *THREAD_ARGP will be passed to
 668      set_initial_registers or thread_detach callbacks together with
 669      Dwfl_Thread *thread.  This method may be NULL and will then be
 670      emulated using the next_thread callback. */
 671   bool (*get_thread) (Dwfl *dwfl, pid_t tid, void *dwfl_arg,
 672                       void **thread_argp)
 673     __nonnull_attribute__ (1);
 674
 675   /* Called during unwinding to access memory (stack) state.  Returns true for
 676      successfully read *RESULT or false and sets dwfl_errno () on failure.
 677      This method may be NULL - in such case dwfl_thread_getframes will return
 678      only the initial frame.  */
 679   bool (*memory_read) (Dwfl *dwfl, Dwarf_Addr addr, Dwarf_Word *result,
 680                        void *dwfl_arg)
 681     __nonnull_attribute__ (1, 3);
 682
 683   /* Called on initial unwind to get the initial register state of the first
 684      frame.  Should call dwfl_thread_state_registers, possibly multiple times
 685      for different ranges and possibly also dwfl_thread_state_register_pc, to
 686      fill in initial (DWARF) register values.  After this call, till at least
 687      thread_detach is called, the thread is assumed to be frozen, so that it is
 688      safe to unwind.  Returns true on success or false and sets dwfl_errno ()
 689      on failure.  In the case of a failure thread_detach will not be called.
 690      This method must not be NULL.  */
 691   bool (*set_initial_registers) (Dwfl_Thread *thread, void *thread_arg)
 692     __nonnull_attribute__ (1);
 693
 694   /* Called by dwfl_end.  All thread_detach method calls have been already
 695      done.  This method may be NULL.  */
 696   void (*detach) (Dwfl *dwfl, void *dwfl_arg)
 697     __nonnull_attribute__ (1);
 698
 699   /* Called when unwinding is done.  No callback will be called after
 700      this method has been called.  Iff set_initial_registers was called for
 701      a TID and it returned success thread_detach will be called before the
 702      detach method above.  This method may be NULL.  */
 703   void (*thread_detach) (Dwfl_Thread *thread, void *thread_arg)
 704     __nonnull_attribute__ (1);
 705 } Dwfl_Thread_Callbacks;
 706
 707 /* PID is the process id associated with the DWFL state.  Architecture of DWFL
 708    modules is specified by ELF, ELF must remain valid during DWFL lifetime.
 709    Use NULL ELF to detect architecture from DWFL, the function will then detect
 710    it from arbitrary Dwfl_Module of DWFL.  DWFL_ARG is the callback backend
 711    state.  DWFL_ARG will be provided to the callbacks.  *THREAD_CALLBACKS
 712    function pointers must remain valid during lifetime of DWFL.  Function
 713    returns true on success, false otherwise.  */
 714 bool dwfl_attach_state (Dwfl *dwfl, Elf *elf, pid_t pid,
 715                         const Dwfl_Thread_Callbacks *thread_callbacks,
 716                         void *dwfl_arg)
 717   __nonnull_attribute__ (1, 4);
 718
 719 /* Calls dwfl_attach_state with Dwfl_Thread_Callbacks setup for extracting
 720    thread state from the ELF core file.  Returns the pid number extracted
 721    from the core file, or -1 for errors.  */
 722 extern int dwfl_core_file_attach (Dwfl *dwfl, Elf *elf);
 723
 724 /* Calls dwfl_attach_state with Dwfl_Thread_Callbacks setup for extracting
 725    thread state from the proc file system.  Uses ptrace to attach and stop
 726    the thread under inspection and detaches when thread_detach is called
 727    and unwinding for the thread is done, unless ASSUME_PTRACE_STOPPED is
 728    true.  If ASSUME_PTRACE_STOPPED is true the caller should make sure that
 729    the thread is ptrace attached and stopped before unwinding by calling
 730    either dwfl_thread_getframes or dwfl_getthread_frames.  Returns zero on
 731    success, -1 if dwfl_attach_state failed, or an errno code if opening the
 732    proc files failed.  */
 733 extern int dwfl_linux_proc_attach (Dwfl *dwfl, pid_t pid,
 734                                    bool assume_ptrace_stopped);
 735
 736 /* Return PID for the process associated with DWFL.  Function returns -1 if
 737    dwfl_attach_state was not called for DWFL.  */
 738 pid_t dwfl_pid (Dwfl *dwfl)
 739   __nonnull_attribute__ (1);
 740
 741 /* Return DWFL from which THREAD was created using dwfl_getthreads.  */
 742 Dwfl *dwfl_thread_dwfl (Dwfl_Thread *thread)
 743   __nonnull_attribute__ (1);
 744
 745 /* Return positive TID (thread ID) for THREAD.  This function never fails.  */
 746 pid_t dwfl_thread_tid (Dwfl_Thread *thread)
 747   __nonnull_attribute__ (1);
 748
 749 /* Return thread for frame STATE.  This function never fails.  */
 750 Dwfl_Thread *dwfl_frame_thread (Dwfl_Frame *state)
 751   __nonnull_attribute__ (1);
 752
 753 /* Called by Dwfl_Thread_Callbacks.set_initial_registers implementation.
 754    For every known continuous block of registers <FIRSTREG..FIRSTREG+NREGS)
 755    (inclusive..exclusive) set their content to REGS (array of NREGS items).
 756    Function returns false if any of the registers has invalid number.  */
 757 bool dwfl_thread_state_registers (Dwfl_Thread *thread, int firstreg,
 758                                   unsigned nregs, const Dwarf_Word *regs)
 759   __nonnull_attribute__ (1, 4);
 760
 761 /* Called by Dwfl_Thread_Callbacks.set_initial_registers implementation.
 762    If PC is not contained among DWARF registers passed by
 763    dwfl_thread_state_registers on the target architecture pass the PC value
 764    here.  */
 765 void dwfl_thread_state_register_pc (Dwfl_Thread *thread, Dwarf_Word pc)
 766   __nonnull_attribute__ (1);
 767
 768 /* Iterate through the threads for a process.  Returns zero if all threads have
 769    been processed by the callback, returns -1 on error, or the value of the
 770    callback when not DWARF_CB_OK.  -1 returned on error will set dwfl_errno ().
 771    Keeps calling the callback with the next thread while the callback returns
 772    DWARF_CB_OK, till there are no more threads.  */
 773 int dwfl_getthreads (Dwfl *dwfl,
 774                      int (*callback) (Dwfl_Thread *thread, void *arg),
 775                      void *arg)
 776   __nonnull_attribute__ (1, 2);
 777
 778 /* Iterate through the frames for a thread.  Returns zero if all frames
 779    have been processed by the callback, returns -1 on error, or the value of
 780    the callback when not DWARF_CB_OK.  -1 returned on error will
 781    set dwfl_errno ().  Some systems return error instead of zero on end of the
 782    backtrace, for cross-platform compatibility callers should consider error as
 783    a zero.  Keeps calling the callback with the next frame while the callback
 784    returns DWARF_CB_OK, till there are no more frames.  On start will call the
 785    set_initial_registers callback and on return will call the detach_thread
 786    callback of the Dwfl_Thread.  */
 787 int dwfl_thread_getframes (Dwfl_Thread *thread,
 788                            int (*callback) (Dwfl_Frame *state, void *arg),
 789                            void *arg)
 790   __nonnull_attribute__ (1, 2);
 791
 792 /* Like dwfl_thread_getframes, but specifying the thread by its unique
 793    identifier number.  Returns zero if all frames have been processed
 794    by the callback, returns -1 on error (and when no thread with
 795    the given thread id number exists), or the value of the callback
 796    when not DWARF_CB_OK.  -1 returned on error will set dwfl_errno ().  */
 797 int dwfl_getthread_frames (Dwfl *dwfl, pid_t tid,
 798                            int (*callback) (Dwfl_Frame *thread, void *arg),
 799                            void *arg)
 800   __nonnull_attribute__ (1, 3);
 801
 802 /* Return *PC (program counter) for thread-specific frame STATE.
 803    Set *ISACTIVATION according to DWARF frame "activation" definition.
 804    Typically you need to substract 1 from *PC if *ACTIVATION is false to safely
 805    find function of the caller.  ACTIVATION may be NULL.  PC must not be NULL.
 806    Function returns false if it failed to find *PC.  */
 807 bool dwfl_frame_pc (Dwfl_Frame *state, Dwarf_Addr *pc, bool *isactivation)
 808   __nonnull_attribute__ (1, 2);
 809
 810 #ifdef __cplusplus
 811 }
 812 #endif
 813
 814 #endif  /* libdwfl.h */