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