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    containing the main file is taken as a subdirectory of this path;
 279    a relative path name is taken as a subdirectory of the directory
 280    containing the main file.  Hence for /bin/ls, the default string
 281    ":.debug:/usr/lib/debug" says to look in /bin, then /bin/.debug,
 282    then /usr/lib/debug/bin, for the file name in the .gnu_debuglink
 283    section (or "ls.debug" if none was found).  */
 284
 285 /* Standard find_elf callback function working solely on build ID.
 286    This can be tried first by any find_elf callback, to use the
 287    bits passed to dwfl_module_report_build_id, if any.  */
 288 extern int dwfl_build_id_find_elf (Dwfl_Module *, void **,
 289                                    const char *, Dwarf_Addr,
 290                                    char **, Elf **);
 291
 292 /* Standard find_debuginfo callback function working solely on build ID.
 293    This can be tried first by any find_debuginfo callback,
 294    to use the build ID bits from the main file when present.  */
 295 extern int dwfl_build_id_find_debuginfo (Dwfl_Module *, void **,
 296                                          const char *, Dwarf_Addr,
 297                                          const char *, const char *,
 298                                          GElf_Word, char **);
 299
 300 /* Standard find_debuginfo callback function.
 301    If a build ID is available, this tries first to use that.
 302    If there is no build ID or no valid debuginfo found by ID,
 303    it searches the debuginfo path by name, as described above.
 304    Any file found in the path is validated by build ID if possible,
 305    or else by CRC32 checksum if enabled, and skipped if it does not match.  */
 306 extern int dwfl_standard_find_debuginfo (Dwfl_Module *, void **,
 307                                          const char *, Dwarf_Addr,
 308                                          const char *, const char *,
 309                                          GElf_Word, char **);
 310
 311
 312 /* This callback must be used when using dwfl_offline_* to report modules,
 313    if ET_REL is to be supported.  */
 314 extern int dwfl_offline_section_address (Dwfl_Module *, void **,
 315                                          const char *, Dwarf_Addr,
 316                                          const char *, GElf_Word,
 317                                          const GElf_Shdr *,
 318                                          Dwarf_Addr *addr);
 319
 320
 321 /* Callbacks for working with kernel modules in the running Linux kernel.  */
 322 extern int dwfl_linux_kernel_find_elf (Dwfl_Module *, void **,
 323                                        const char *, Dwarf_Addr,
 324                                        char **, Elf **);
 325 extern int dwfl_linux_kernel_module_section_address (Dwfl_Module *, void **,
 326                                                      const char *, Dwarf_Addr,
 327                                                      const char *, GElf_Word,
 328                                                      const GElf_Shdr *,
 329                                                      Dwarf_Addr *addr);
 330
 331 /* Call dwfl_report_elf for the running Linux kernel.
 332    Returns zero on success, -1 if dwfl_report_module failed,
 333    or an errno code if opening the kernel binary failed.  */
 334 extern int dwfl_linux_kernel_report_kernel (Dwfl *dwfl);
 335
 336 /* Call dwfl_report_module for each kernel module in the running Linux kernel.
 337    Returns zero on success, -1 if dwfl_report_module failed,
 338    or an errno code if reading the list of modules failed.  */
 339 extern int dwfl_linux_kernel_report_modules (Dwfl *dwfl);
 340
 341 /* Report a kernel and its modules found on disk, for offline use.
 342    If RELEASE starts with '/', it names a directory to look in;
 343    if not, it names a directory to find under /lib/modules/;
 344    if null, /lib/modules/`uname -r` is used.
 345    Returns zero on success, -1 if dwfl_report_module failed,
 346    or an errno code if finding the files on disk failed.
 347
 348    If PREDICATE is not null, it is called with each module to be reported;
 349    its arguments are the module name, and the ELF file name or null if unknown,
 350    and its return value should be zero to skip the module, one to report it,
 351    or -1 to cause the call to fail and return errno.  */
 352 extern int dwfl_linux_kernel_report_offline (Dwfl *dwfl, const char *release,
 353                                              int (*predicate) (const char *,
 354                                                                const char *));
 355
 356 /* Examine an ET_CORE file and report modules based on its contents.
 357    This can follow a dwfl_report_offline call to bootstrap the
 358    DT_DEBUG method of following the dynamic linker link_map chain, in
 359    case the core file does not contain enough of the executable's text
 360    segment to locate its PT_DYNAMIC in the dump.  In such case you need to
 361    supply non-NULL EXECUTABLE, otherwise dynamic libraries will not be loaded
 362    into the DWFL map.  This might call dwfl_report_elf on file names found in
 363    the dump if reading some link_map files is the only way to ascertain those
 364    modules' addresses.  dwfl_attach_state is also called for DWFL,
 365    dwfl_core_file_report does not fail if the dwfl_attach_state call has failed.
 366    Returns the number of modules reported, or -1 for errors.  */
 367 extern int dwfl_core_file_report (Dwfl *dwfl, Elf *elf, const char *executable);
 368
 369 /* Call dwfl_report_module for each file mapped into the address space of PID.
 370    dwfl_attach_state is also called for DWFL, dwfl_linux_proc_report does
 371    not fail if the dwfl_attach_state call has failed.
 372    Returns zero on success, -1 if dwfl_report_module failed,
 373    or an errno code if opening the kernel binary failed.  */
 374 extern int dwfl_linux_proc_report (Dwfl *dwfl, pid_t pid);
 375
 376 /* Similar, but reads an input stream in the format of Linux /proc/PID/maps
 377    files giving module layout, not the file for a live process.  */
 378 extern int dwfl_linux_proc_maps_report (Dwfl *dwfl, FILE *);
 379
 380 /* Trivial find_elf callback for use with dwfl_linux_proc_report.
 381    This uses the module name as a file name directly and tries to open it
 382    if it begin with a slash, or handles the magic string "[vdso]".  */
 383 extern int dwfl_linux_proc_find_elf (Dwfl_Module *mod, void **userdata,
 384                                      const char *module_name, Dwarf_Addr base,
 385                                      char **file_name, Elf **);
 386
 387 /* Standard argument parsing for using a standard callback set.  */
 388 struct argp;
 389 extern const struct argp *dwfl_standard_argp (void) __attribute__ ((const));
 390
 391
 392 /*** Relocation of addresses from Dwfl ***/
 393
 394 /* Return the number of relocatable bases associated with the module,
 395    which is zero for ET_EXEC and one for ET_DYN.  Returns -1 for errors.  */
 396 extern int dwfl_module_relocations (Dwfl_Module *mod);
 397
 398 /* Return the relocation base index associated with the *ADDRESS location,
 399    and adjust *ADDRESS to be an offset relative to that base.
 400    Returns -1 for errors.  */
 401 extern int dwfl_module_relocate_address (Dwfl_Module *mod,
 402                                          Dwarf_Addr *address);
 403
 404 /* Return the ELF section name for the given relocation base index;
 405    if SHNDXP is not null, set *SHNDXP to the ELF section index.
 406    For ET_DYN, returns "" and sets *SHNDXP to SHN_ABS; the relocation
 407    base is the runtime start address reported for the module.
 408    Returns null for errors.  */
 409 extern const char *dwfl_module_relocation_info (Dwfl_Module *mod,
 410                                                 unsigned int idx,
 411                                                 GElf_Word *shndxp);
 412
 413 /* Validate that ADDRESS and ADDRESS+OFFSET lie in a known module
 414    and both within the same contiguous region for relocation purposes.
 415    Returns zero for success and -1 for errors.  */
 416 extern int dwfl_validate_address (Dwfl *dwfl,
 417                                   Dwarf_Addr address, Dwarf_Sword offset);
 418
 419
 420 /*** ELF access functions ***/
 421
 422 /* Fetch the module main ELF file (where the allocated sections
 423    are found) for use with libelf.  If successful, fills in *BIAS
 424    with the difference between addresses within the loaded module
 425    and those in symbol tables or Dwarf information referring to it.  */
 426 extern Elf *dwfl_module_getelf (Dwfl_Module *, GElf_Addr *bias)
 427   __nonnull_attribute__ (1, 2);
 428
 429 /* Return the number of symbols in the module's symbol table,
 430    or -1 for errors.  */
 431 extern int dwfl_module_getsymtab (Dwfl_Module *mod);
 432
 433 /* Return the index of the first global symbol in the module's symbol
 434    table, or -1 for errors.  In each symbol table, all symbols with
 435    STB_LOCAL binding precede the weak and global symbols.  This
 436    function returns the symbol table index one greater than the last
 437    local symbol.  */
 438 extern int dwfl_module_getsymtab_first_global (Dwfl_Module *mod);
 439
 440 /* Fetch one entry from the module's symbol table.  On errors, returns
 441    NULL.  If successful, fills in *SYM and returns the string for st_name.
 442    This works like gelf_getsym except that st_value is always adjusted to
 443    an absolute value based on the module's location, when the symbol is in
 444    an SHF_ALLOC section.  If SHNDXP is non-null, it's set with the section
 445    index (whether from st_shndx or extended index table); in case of a
 446    symbol in a non-allocated section, *SHNDXP is instead set to -1.
 447    Note that since symbols can come from either the main, debug or auxiliary
 448    ELF symbol file (either dynsym or symtab) the section index can only
 449    be reliably used to compare against special section constants like
 450    SHN_UNDEF or SHN_ABS.  It is recommended to use dwfl_module_getsym_info
 451    which doesn't have these deficiencies.  */
 452 extern const char *dwfl_module_getsym (Dwfl_Module *mod, int ndx,
 453                                        GElf_Sym *sym, GElf_Word *shndxp)
 454   __nonnull_attribute__ (3);
 455
 456 /* Fetch one entry from the module's symbol table and the associated
 457    address value.  On errors, returns NULL.  If successful, fills in
 458    *SYM, *ADDR and returns the string for st_name.  This works like
 459    gelf_getsym.  *ADDR is set to the st_value adjusted to an absolute
 460    value based on the module's location, when the symbol is in an
 461    SHF_ALLOC section.  For non-ET_REL files, if the arch uses function
 462    descriptors, and the st_value points to one, *ADDR will be resolved
 463    to the actual function entry address.  The SYM->ST_VALUE itself
 464    isn't adjusted in any way.  Fills in ELFP, if not NULL, with the
 465    ELF file the symbol originally came from.  Note that symbols can
 466    come from either the main, debug or auxiliary ELF symbol file
 467    (either dynsym or symtab).  If SHNDXP is non-null, it's set with
 468    the section index (whether from st_shndx or extended index table);
 469    in case of a symbol in a non-allocated section, *SHNDXP is instead
 470    set to -1.  Fills in BIAS, if not NULL, with the difference between
 471    addresses within the loaded module and those in symbol table of the
 472    ELF file.  Note that the address associated with the symbol might
 473    be in a different section than the returned symbol.  The section in
 474    the main elf file in which returned ADDR falls can be found with
 475    dwfl_module_address_section.  */
 476 extern const char *dwfl_module_getsym_info (Dwfl_Module *mod, int ndx,
 477                                             GElf_Sym *sym, GElf_Addr *addr,
 478                                             GElf_Word *shndxp,
 479                                             Elf **elfp, Dwarf_Addr *bias)
 480   __nonnull_attribute__ (3, 4);
 481
 482 /* Find the symbol that ADDRESS lies inside, and return its name.  */
 483 extern const char *dwfl_module_addrname (Dwfl_Module *mod, GElf_Addr address);
 484
 485 /* Find the symbol associated with ADDRESS.  Return its name or NULL
 486    when nothing was found.  If the architecture uses function
 487    descriptors, and symbol st_value points to one, ADDRESS wil be
 488    matched against either the adjusted st_value or the associated
 489    function entry value as described in dwfl_module_getsym_info.  If
 490    OFFSET is not NULL it will be filled in with the difference from
 491    the start of the symbol (or function entry).  If SYM is not NULL it
 492    is filled in with the symbol associated with the matched ADDRESS.
 493    The SYM->ST_VALUE itself isn't adjusted in any way.  Fills in ELFP,
 494    if not NULL, with the ELF file the symbol originally came from.
 495    Note that symbols can come from either the main, debug or auxiliary
 496    ELF symbol file (either dynsym or symtab).  If SHNDXP is non-null,
 497    it's set with the section index (whether from st_shndx or extended
 498    index table).  Fills in BIAS, if not NULL, with the difference
 499    between addresses within the loaded module and those in symbol
 500    table of the ELF file.  Note that the address matched against the
 501    symbol might be in a different section than the returned symbol.
 502    The section in the main elf file in ADDRESS falls can be found with
 503    dwfl_module_address_section.  */
 504 extern const char *dwfl_module_addrinfo (Dwfl_Module *mod, GElf_Addr address,
 505                                          GElf_Off *offset, GElf_Sym *sym,
 506                                          GElf_Word *shndxp, Elf **elfp,
 507                                          Dwarf_Addr *bias)
 508   __nonnull_attribute__ (3);
 509
 510 /* Find the symbol that ADDRESS lies inside, and return detailed
 511    information as for dwfl_module_getsym (above).  Note that like
 512    dwfl_module_getsym this function also adjusts SYM->ST_VALUE to an
 513    absolute value based on the module's location.  ADDRESS is only
 514    matched against this adjusted SYM->ST_VALUE.  This means that
 515    depending on architecture this might only match symbols that
 516    represent function descriptor addresses (and not function entry
 517    addresses).  For these reasons it is recommended to use
 518    dwfl_module_addrinfo instead.  */
 519 extern const char *dwfl_module_addrsym (Dwfl_Module *mod, GElf_Addr address,
 520                                         GElf_Sym *sym, GElf_Word *shndxp)
 521   __nonnull_attribute__ (3);
 522
 523 /* Find the ELF section that *ADDRESS lies inside and return it.
 524    On success, adjusts *ADDRESS to be relative to the section,
 525    and sets *BIAS to the difference between addresses used in
 526    the returned section's headers and run-time addresses.  */
 527 extern Elf_Scn *dwfl_module_address_section (Dwfl_Module *mod,
 528                                              Dwarf_Addr *address,
 529                                              Dwarf_Addr *bias)
 530   __nonnull_attribute__ (2, 3);
 531
 532
 533 /*** Dwarf access functions ***/
 534
 535 /* Fetch the module's debug information for use with libdw.
 536    If successful, fills in *BIAS with the difference between
 537    addresses within the loaded module and those  to use with libdw.  */
 538 extern Dwarf *dwfl_module_getdwarf (Dwfl_Module *, Dwarf_Addr *bias)
 539      __nonnull_attribute__ (2);
 540
 541 /* Get the libdw handle for each module.  */
 542 extern ptrdiff_t dwfl_getdwarf (Dwfl *,
 543                                 int (*callback) (Dwfl_Module *, void **,
 544                                                  const char *, Dwarf_Addr,
 545                                                  Dwarf *, Dwarf_Addr, void *),
 546                                 void *arg, ptrdiff_t offset);
 547
 548 /* Look up the module containing ADDR and return its debugging information,
 549    loading it if necessary.  */
 550 extern Dwarf *dwfl_addrdwarf (Dwfl *dwfl, Dwarf_Addr addr, Dwarf_Addr *bias)
 551      __nonnull_attribute__ (3);
 552
 553
 554 /* Find the CU containing ADDR and return its DIE.  */
 555 extern Dwarf_Die *dwfl_addrdie (Dwfl *dwfl, Dwarf_Addr addr, Dwarf_Addr *bias)
 556      __nonnull_attribute__ (3);
 557 extern Dwarf_Die *dwfl_module_addrdie (Dwfl_Module *mod,
 558                                        Dwarf_Addr addr, Dwarf_Addr *bias)
 559      __nonnull_attribute__ (3);
 560
 561 /* Iterate through the CUs, start with null for LASTCU.  */
 562 extern Dwarf_Die *dwfl_nextcu (Dwfl *dwfl, Dwarf_Die *lastcu, Dwarf_Addr *bias)
 563      __nonnull_attribute__ (3);
 564 extern Dwarf_Die *dwfl_module_nextcu (Dwfl_Module *mod,
 565                                       Dwarf_Die *lastcu, Dwarf_Addr *bias)
 566      __nonnull_attribute__ (3);
 567
 568 /* Return the module containing the CU DIE.  */
 569 extern Dwfl_Module *dwfl_cumodule (Dwarf_Die *cudie);
 570
 571
 572 /* Cache the source line information fo the CU and return the
 573    number of Dwfl_Line entries it has.  */
 574 extern int dwfl_getsrclines (Dwarf_Die *cudie, size_t *nlines);
 575
 576 /* Access one line number entry within the CU.  */
 577 extern Dwfl_Line *dwfl_onesrcline (Dwarf_Die *cudie, size_t idx);
 578
 579 /* Get source for address.  */
 580 extern Dwfl_Line *dwfl_module_getsrc (Dwfl_Module *mod, Dwarf_Addr addr);
 581 extern Dwfl_Line *dwfl_getsrc (Dwfl *dwfl, Dwarf_Addr addr);
 582
 583 /* Get address for source.  */
 584 extern int dwfl_module_getsrc_file (Dwfl_Module *mod,
 585                                     const char *fname, int lineno, int column,
 586                                     Dwfl_Line ***srcsp, size_t *nsrcs);
 587
 588 /* Return the module containing this line record.  */
 589 extern Dwfl_Module *dwfl_linemodule (Dwfl_Line *line);
 590
 591 /* Return the CU containing this line record.  */
 592 extern Dwarf_Die *dwfl_linecu (Dwfl_Line *line);
 593
 594 /* Return the source file name and fill in other information.
 595    Arguments may be null for unneeded fields.  */
 596 extern const char *dwfl_lineinfo (Dwfl_Line *line, Dwarf_Addr *addr,
 597                                   int *linep, int *colp,
 598                                   Dwarf_Word *mtime, Dwarf_Word *length);
 599
 600   /* Return the equivalent Dwarf_Line and the bias to apply to its address.  */
 601 extern Dwarf_Line *dwfl_dwarf_line (Dwfl_Line *line, Dwarf_Addr *bias);
 602
 603 /* Return the compilation directory (AT_comp_dir) from this line's CU.  */
 604 extern const char *dwfl_line_comp_dir (Dwfl_Line *line);
 605
 606
 607 /*** Machine backend access functions ***/
 608
 609 /* Return location expression to find return value given a
 610    DW_TAG_subprogram, DW_TAG_subroutine_type, or similar DIE describing
 611    function itself (whose DW_AT_type attribute describes its return type).
 612    The given DIE must come from the given module.  Returns -1 for errors.
 613    Returns zero if the function has no return value (e.g. "void" in C).
 614    Otherwise, *LOCOPS gets a location expression to find the return value,
 615    and returns the number of operations in the expression.  The pointer is
 616    permanently allocated at least as long as the module is live.  */
 617 extern int dwfl_module_return_value_location (Dwfl_Module *mod,
 618                                               Dwarf_Die *functypedie,
 619                                               const Dwarf_Op **locops);
 620
 621 /* Enumerate the DWARF register numbers and their names.
 622    For each register, CALLBACK gets its DWARF number, a string describing
 623    the register set (such as "integer" or "FPU"), a prefix used in
 624    assembler syntax (such as "%" or "$", may be ""), and the name for the
 625    register (contains identifier characters only, possibly all digits).
 626    The REGNAME string is valid only during the callback. */
 627 extern int dwfl_module_register_names (Dwfl_Module *mod,
 628                                        int (*callback) (void *arg,
 629                                                         int regno,
 630                                                         const char *setname,
 631                                                         const char *prefix,
 632                                                         const char *regname,
 633                                                         int bits, int type),
 634                                        void *arg);
 635
 636
 637 /* Find the CFI for this module.  Returns NULL if there is no CFI.
 638    On success, fills in *BIAS with the difference between addresses
 639    within the loaded module and those in the CFI referring to it.
 640    The pointer returned can be used until the module is cleaned up.
 641    Calling these more than once returns the same pointers.
 642
 643    dwfl_module_dwarf_cfi gets the '.debug_frame' information found with the
 644    rest of the DWARF information.  dwfl_module_eh_cfi gets the '.eh_frame'
 645    information found linked into the text.  A module might have either or
 646    both.  */
 647 extern Dwarf_CFI *dwfl_module_dwarf_cfi (Dwfl_Module *mod, Dwarf_Addr *bias);
 648 extern Dwarf_CFI *dwfl_module_eh_cfi (Dwfl_Module *mod, Dwarf_Addr *bias);
 649
 650
 651 typedef struct
 652 {
 653   /* Called to iterate through threads.  Returns next TID (thread ID) on
 654      success, a negative number on failure and zero if there are no more
 655      threads.  dwfl_errno () should be set if negative number has been
 656      returned.  *THREAD_ARGP is NULL on first call, and may be optionally
 657      set by the implementation. The value set by the implementation will
 658      be passed in on the next call to NEXT_THREAD.  THREAD_ARGP is never
 659      NULL.  *THREAD_ARGP will be passed to set_initial_registers or
 660      thread_detach callbacks together with Dwfl_Thread *thread.  This
 661      method must not be NULL.  */
 662   pid_t (*next_thread) (Dwfl *dwfl, void *dwfl_arg, void **thread_argp)
 663     __nonnull_attribute__ (1);
 664
 665   /* Called to get a specific thread.  Returns true if there is a
 666      thread with the given thread id number, returns false if no such
 667      thread exists and will set dwfl_errno in that case.  THREAD_ARGP
 668      is never NULL.  *THREAD_ARGP will be passed to
 669      set_initial_registers or thread_detach callbacks together with
 670      Dwfl_Thread *thread.  This method may be NULL and will then be
 671      emulated using the next_thread callback. */
 672   bool (*get_thread) (Dwfl *dwfl, pid_t tid, void *dwfl_arg,
 673                       void **thread_argp)
 674     __nonnull_attribute__ (1);
 675
 676   /* Called during unwinding to access memory (stack) state.  Returns true for
 677      successfully read *RESULT or false and sets dwfl_errno () on failure.
 678      This method may be NULL - in such case dwfl_thread_getframes will return
 679      only the initial frame.  */
 680   bool (*memory_read) (Dwfl *dwfl, Dwarf_Addr addr, Dwarf_Word *result,
 681                        void *dwfl_arg)
 682     __nonnull_attribute__ (1, 3);
 683
 684   /* Called on initial unwind to get the initial register state of the first
 685      frame.  Should call dwfl_thread_state_registers, possibly multiple times
 686      for different ranges and possibly also dwfl_thread_state_register_pc, to
 687      fill in initial (DWARF) register values.  After this call, till at least
 688      thread_detach is called, the thread is assumed to be frozen, so that it is
 689      safe to unwind.  Returns true on success or false and sets dwfl_errno ()
 690      on failure.  In the case of a failure thread_detach will not be called.
 691      This method must not be NULL.  */
 692   bool (*set_initial_registers) (Dwfl_Thread *thread, void *thread_arg)
 693     __nonnull_attribute__ (1);
 694
 695   /* Called by dwfl_end.  All thread_detach method calls have been already
 696      done.  This method may be NULL.  */
 697   void (*detach) (Dwfl *dwfl, void *dwfl_arg)
 698     __nonnull_attribute__ (1);
 699
 700   /* Called when unwinding is done.  No callback will be called after
 701      this method has been called.  Iff set_initial_registers was called for
 702      a TID and it returned success thread_detach will be called before the
 703      detach method above.  This method may be NULL.  */
 704   void (*thread_detach) (Dwfl_Thread *thread, void *thread_arg)
 705     __nonnull_attribute__ (1);
 706 } Dwfl_Thread_Callbacks;
 707
 708 /* PID is the process id associated with the DWFL state.  Architecture of DWFL
 709    modules is specified by ELF, ELF must remain valid during DWFL lifetime.
 710    Use NULL ELF to detect architecture from DWFL, the function will then detect
 711    it from arbitrary Dwfl_Module of DWFL.  DWFL_ARG is the callback backend
 712    state.  DWFL_ARG will be provided to the callbacks.  *THREAD_CALLBACKS
 713    function pointers must remain valid during lifetime of DWFL.  Function
 714    returns true on success, false otherwise.  */
 715 bool dwfl_attach_state (Dwfl *dwfl, Elf *elf, pid_t pid,
 716                         const Dwfl_Thread_Callbacks *thread_callbacks,
 717                         void *dwfl_arg)
 718   __nonnull_attribute__ (1, 4);
 719
 720 /* Return PID for the process associated with DWFL.  Function returns -1 if
 721    dwfl_attach_state was not called for DWFL.  */
 722 pid_t dwfl_pid (Dwfl *dwfl)
 723   __nonnull_attribute__ (1);
 724
 725 /* Return DWFL from which THREAD was created using dwfl_getthreads.  */
 726 Dwfl *dwfl_thread_dwfl (Dwfl_Thread *thread)
 727   __nonnull_attribute__ (1);
 728
 729 /* Return positive TID (thread ID) for THREAD.  This function never fails.  */
 730 pid_t dwfl_thread_tid (Dwfl_Thread *thread)
 731   __nonnull_attribute__ (1);
 732
 733 /* Return thread for frame STATE.  This function never fails.  */
 734 Dwfl_Thread *dwfl_frame_thread (Dwfl_Frame *state)
 735   __nonnull_attribute__ (1);
 736
 737 /* Called by Dwfl_Thread_Callbacks.set_initial_registers implementation.
 738    For every known continuous block of registers <FIRSTREG..FIRSTREG+NREGS)
 739    (inclusive..exclusive) set their content to REGS (array of NREGS items).
 740    Function returns false if any of the registers has invalid number.  */
 741 bool dwfl_thread_state_registers (Dwfl_Thread *thread, int firstreg,
 742                                   unsigned nregs, const Dwarf_Word *regs)
 743   __nonnull_attribute__ (1, 4);
 744
 745 /* Called by Dwfl_Thread_Callbacks.set_initial_registers implementation.
 746    If PC is not contained among DWARF registers passed by
 747    dwfl_thread_state_registers on the target architecture pass the PC value
 748    here.  */
 749 void dwfl_thread_state_register_pc (Dwfl_Thread *thread, Dwarf_Word pc)
 750   __nonnull_attribute__ (1);
 751
 752 /* Iterate through the threads for a process.  Returns zero if all threads have
 753    been processed by the callback, returns -1 on error, or the value of the
 754    callback when not DWARF_CB_OK.  -1 returned on error will set dwfl_errno ().
 755    Keeps calling the callback with the next thread while the callback returns
 756    DWARF_CB_OK, till there are no more threads.  */
 757 int dwfl_getthreads (Dwfl *dwfl,
 758                      int (*callback) (Dwfl_Thread *thread, void *arg),
 759                      void *arg)
 760   __nonnull_attribute__ (1, 2);
 761
 762 /* Iterate through the frames for a thread.  Returns zero if all frames
 763    have been processed by the callback, returns -1 on error, or the value of
 764    the callback when not DWARF_CB_OK.  -1 returned on error will
 765    set dwfl_errno ().  Some systems return error instead of zero on end of the
 766    backtrace, for cross-platform compatibility callers should consider error as
 767    a zero.  Keeps calling the callback with the next frame while the callback
 768    returns DWARF_CB_OK, till there are no more frames.  On start will call the
 769    set_initial_registers callback and on return will call the detach_thread
 770    callback of the Dwfl_Thread.  */
 771 int dwfl_thread_getframes (Dwfl_Thread *thread,
 772                            int (*callback) (Dwfl_Frame *state, void *arg),
 773                            void *arg)
 774   __nonnull_attribute__ (1, 2);
 775
 776 /* Like dwfl_thread_getframes, but specifying the thread by its unique
 777    identifier number.  Returns zero if all frames have been processed
 778    by the callback, returns -1 on error (and when no thread with
 779    the given thread id number exists), or the value of the callback
 780    when not DWARF_CB_OK.  -1 returned on error will set dwfl_errno ().  */
 781 int dwfl_getthread_frames (Dwfl *dwfl, pid_t tid,
 782                            int (*callback) (Dwfl_Frame *thread, void *arg),
 783                            void *arg)
 784   __nonnull_attribute__ (1, 3);
 785
 786 /* Return *PC (program counter) for thread-specific frame STATE.
 787    Set *ISACTIVATION according to DWARF frame "activation" definition.
 788    Typically you need to substract 1 from *PC if *ACTIVATION is false to safely
 789    find function of the caller.  ACTIVATION may be NULL.  PC must not be NULL.
 790    Function returns false if it failed to find *PC.  */
 791 bool dwfl_frame_pc (Dwfl_Frame *state, Dwarf_Addr *pc, bool *isactivation)
 792   __nonnull_attribute__ (1, 2);
 793
 794 #ifdef __cplusplus
 795 }
 796 #endif
 797
 798 #endif  /* libdwfl.h */