libdwfl/libdwfl.h

   1 /* Interfaces for libdwfl.
   2    Copyright (C) 2005-2010 Red Hat, Inc.
   3    This file is part of Red Hat elfutils.
   4
   5    Red Hat elfutils is free software; you can redistribute it and/or modify
   6    it under the terms of the GNU General Public License as published by the
   7    Free Software Foundation; version 2 of the License.
   8
   9    Red Hat elfutils is distributed in the hope that it will be useful, but
  10    WITHOUT ANY WARRANTY; without even the implied warranty of
  11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12    General Public License for more details.
  13
  14    You should have received a copy of the GNU General Public License along
  15    with Red Hat elfutils; if not, write to the Free Software Foundation,
  16    Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301 USA.
  17
  18    In addition, as a special exception, Red Hat, Inc. gives You the
  19    additional right to link the code of Red Hat elfutils with code licensed
  20    under any Open Source Initiative certified open source license
  21    (http://www.opensource.org/licenses/index.php) which requires the
  22    distribution of source code with any binary distribution and to
  23    distribute linked combinations of the two.  Non-GPL Code permitted under
  24    this exception must only link to the code of Red Hat elfutils through
  25    those well defined interfaces identified in the file named EXCEPTION
  26    found in the source code files (the "Approved Interfaces").  The files
  27    of Non-GPL Code may instantiate templates or use macros or inline
  28    functions from the Approved Interfaces without causing the resulting
  29    work to be covered by the GNU General Public License.  Only Red Hat,
  30    Inc. may make changes or additions to the list of Approved Interfaces.
  31    Red Hat's grant of this exception is conditioned upon your not adding
  32    any new exceptions.  If you wish to add a new Approved Interface or
  33    exception, please contact Red Hat.  You must obey the GNU General Public
  34    License in all respects for all of the Red Hat elfutils code and other
  35    code used in conjunction with Red Hat elfutils except the Non-GPL Code
  36    covered by this exception.  If you modify this file, you may extend this
  37    exception to your version of the file, but you are not obligated to do
  38    so.  If you do not wish to provide this exception without modification,
  39    you must delete this exception statement from your version and license
  40    this file solely under the GPL without exception.
  41
  42    Red Hat elfutils is an included package of the Open Invention Network.
  43    An included package of the Open Invention Network is a package for which
  44    Open Invention Network licensees cross-license their patents.  No patent
  45    license is granted, either expressly or impliedly, by designation as an
  46    included package.  Should you wish to participate in the Open Invention
  47    Network licensing program, please visit www.openinventionnetwork.com
  48    <http://www.openinventionnetwork.com>.  */
  49
  50 #ifndef _LIBDWFL_H
  51 #define _LIBDWFL_H      1
  52
  53 #include "libdw.h"
  54 #include <stdio.h>
  55
  56 /* Handle for a session using the library.  */
  57 typedef struct Dwfl Dwfl;
  58
  59 /* Handle for a module.  */
  60 typedef struct Dwfl_Module Dwfl_Module;
  61
  62 /* Handle describing a line record.  */
  63 typedef struct Dwfl_Line Dwfl_Line;
  64
  65 /* Callbacks.  */
  66 typedef struct
  67 {
  68   int (*find_elf) (Dwfl_Module *mod, void **userdata,
  69                    const char *modname, Dwarf_Addr base,
  70                    char **file_name, Elf **elfp);
  71
  72   int (*find_debuginfo) (Dwfl_Module *mod, void **userdata,
  73                          const char *modname, Dwarf_Addr base,
  74                          const char *file_name,
  75                          const char *debuglink_file, GElf_Word debuglink_crc,
  76                          char **debuginfo_file_name);
  77
  78   /* Fill *ADDR with the loaded address of the section called SECNAME in
  79      the given module.  Use (Dwarf_Addr) -1 if this section is omitted from
  80      accessible memory.  This is called exactly once for each SHF_ALLOC
  81      section that relocations affecting DWARF data refer to, so it can
  82      easily be used to collect state about the sections referenced.  */
  83   int (*section_address) (Dwfl_Module *mod, void **userdata,
  84                           const char *modname, Dwarf_Addr base,
  85                           const char *secname,
  86                           GElf_Word shndx, const GElf_Shdr *shdr,
  87                           Dwarf_Addr *addr);
  88
  89   char **debuginfo_path;        /* See dwfl_standard_find_debuginfo.  */
  90 } Dwfl_Callbacks;
  91
  92
  93 #ifdef __cplusplus
  94 extern "C" {
  95 #endif
  96
  97 /* Start a new session with the library.  */
  98 extern Dwfl *dwfl_begin (const Dwfl_Callbacks *callbacks)
  99   __nonnull_attribute__ (1);
 100
 101
 102 /* End a session.  */
 103 extern void dwfl_end (Dwfl *);
 104
 105 /* Return implementation's version string suitable for printing.  */
 106 extern const char *dwfl_version (Dwfl *);
 107
 108 /* Return error code of last failing function call.  This value is kept
 109    separately for each thread.  */
 110 extern int dwfl_errno (void);
 111
 112 /* Return error string for ERROR.  If ERROR is zero, return error string
 113    for most recent error or NULL if none occurred.  If ERROR is -1 the
 114    behaviour is similar to the last case except that not NULL but a legal
 115    string is returned.  */
 116 extern const char *dwfl_errmsg (int err);
 117
 118
 119 /* Start reporting the current set of segments and modules to the library.
 120    All existing segments are wiped.  Existing modules are marked to be
 121    deleted, and will not be found via dwfl_addrmodule et al if they are not
 122    re-reported before dwfl_report_end is called.  */
 123 extern void dwfl_report_begin (Dwfl *dwfl);
 124
 125 /* Report that segment NDX begins at PHDR->p_vaddr + BIAS.
 126    If NDX is < 0, the value succeeding the last call's NDX
 127    is used instead (zero on the first call).
 128
 129    If nonzero, the smallest PHDR->p_align value seen sets the
 130    effective page size for the address space DWFL describes.
 131    This is the granularity at which reported module boundary
 132    addresses will be considered to fall in or out of a segment.
 133
 134    Returns -1 for errors, or NDX (or its assigned replacement) on success.
 135
 136    When NDX is the value succeeding the last call's NDX (or is implicitly
 137    so as above), IDENT is nonnull and matches the value in the last call,
 138    and the PHDR and BIAS values reflect a segment that would be contiguous,
 139    in both memory and file, with the last segment reported, then this
 140    segment may be coalesced internally with preceding segments.  When given
 141    an address inside this segment, dwfl_addrsegment may return the NDX of a
 142    preceding contiguous segment.  To prevent coalesced segments, always
 143    pass a null pointer for IDENT.
 144
 145    The values passed are not stored (except to track coalescence).
 146    The only information that can be extracted from DWFL later is the
 147    mapping of an address to a segment index that starts at or below
 148    it.  Reporting segments at all is optional.  Its only benefit to
 149    the caller is to offer this quick lookup via dwfl_addrsegment,
 150    or use other segment-based calls.  */
 151 extern int dwfl_report_segment (Dwfl *dwfl, int ndx,
 152                                 const GElf_Phdr *phdr, GElf_Addr bias,
 153                                 const void *ident);
 154
 155 /* Report that a module called NAME spans addresses [START, END).
 156    Returns the module handle, either existing or newly allocated,
 157    or returns a null pointer for an allocation error.  */
 158 extern Dwfl_Module *dwfl_report_module (Dwfl *dwfl, const char *name,
 159                                         Dwarf_Addr start, Dwarf_Addr end);
 160
 161 /* Report a module with start and end addresses computed from the ELF
 162    program headers in the given file, plus BASE.  For an ET_REL file,
 163    does a simple absolute section layout starting at BASE.
 164    FD may be -1 to open FILE_NAME.  On success, FD is consumed by the
 165    library, and the `find_elf' callback will not be used for this module.  */
 166 extern Dwfl_Module *dwfl_report_elf (Dwfl *dwfl, const char *name,
 167                                      const char *file_name, int fd,
 168                                      GElf_Addr base);
 169
 170 /* Similar, but report the module for offline use.  All ET_EXEC files
 171    being reported must be reported before any relocatable objects.
 172    If this is used, dwfl_report_module and dwfl_report_elf may not be
 173    used in the same reporting session.  */
 174 extern Dwfl_Module *dwfl_report_offline (Dwfl *dwfl, const char *name,
 175                                          const char *file_name, int fd);
 176
 177
 178 /* Finish reporting the current set of modules to the library.
 179    If REMOVED is not null, it's called for each module that
 180    existed before but was not included in the current report.
 181    Returns a nonzero return value from the callback.
 182    The callback may call dwfl_report_module; doing so with the
 183    details of the module being removed prevents its removal.
 184    DWFL cannot be used until this function has returned zero.  */
 185 extern int dwfl_report_end (Dwfl *dwfl,
 186                             int (*removed) (Dwfl_Module *, void *,
 187                                             const char *, Dwarf_Addr,
 188                                             void *arg),
 189                             void *arg);
 190
 191 /* Start reporting additional modules to the library.  No calls but
 192    dwfl_report_* can be made on DWFL until dwfl_report_end is called.
 193    This is like dwfl_report_begin, but all the old modules are kept on.
 194    More dwfl_report_* calls can follow to add more modules.
 195    When dwfl_report_end is called, no old modules will be removed.  */
 196 extern void dwfl_report_begin_add (Dwfl *dwfl);
 197
 198
 199 /* Return the name of the module, and for each non-null argument store
 200    interesting details: *USERDATA is a location for storing your own
 201    pointer, **USERDATA is initially null; *START and *END give the address
 202    range covered by the module; *DWBIAS is the address bias for debugging
 203    information, and *SYMBIAS for symbol table entries (either is -1 if not
 204    yet accessed); *MAINFILE is the name of the ELF file, and *DEBUGFILE the
 205    name of the debuginfo file (might be equal to *MAINFILE; either is null
 206    if not yet accessed).  */
 207 extern const char *dwfl_module_info (Dwfl_Module *mod, void ***userdata,
 208                                      Dwarf_Addr *start, Dwarf_Addr *end,
 209                                      Dwarf_Addr *dwbias, Dwarf_Addr *symbias,
 210                                      const char **mainfile,
 211                                      const char **debugfile);
 212
 213 /* Iterate through the modules, starting the walk with OFFSET == 0.
 214    Calls *CALLBACK for each module as long as it returns DWARF_CB_OK.
 215    When *CALLBACK returns another value, the walk stops and the
 216    return value can be passed as OFFSET to resume it.  Returns 0 when
 217    there are no more modules, or -1 for errors.  */
 218 extern ptrdiff_t dwfl_getmodules (Dwfl *dwfl,
 219                                   int (*callback) (Dwfl_Module *, void **,
 220                                                    const char *, Dwarf_Addr,
 221                                                    void *arg),
 222                                   void *arg,
 223                                   ptrdiff_t offset);
 224
 225 /* Find the module containing the given address.  */
 226 extern Dwfl_Module *dwfl_addrmodule (Dwfl *dwfl, Dwarf_Addr address);
 227
 228 /* Find the segment, if any, and module, if any, containing ADDRESS.
 229    Returns a segment index returned by dwfl_report_segment, or -1
 230    if no segment matches the address.  Regardless of the return value,
 231    *MOD is always set to the module containing ADDRESS, or to null.  */
 232 extern int dwfl_addrsegment (Dwfl *dwfl, Dwarf_Addr address, Dwfl_Module **mod);
 233
 234
 235
 236 /* Report the known build ID bits associated with a module.
 237    If VADDR is nonzero, it gives the absolute address where those
 238    bits are found within the module.  This can be called at any
 239    time, but is usually used immediately after dwfl_report_module.
 240    Once the module's main ELF file is opened, the ID note found
 241    there takes precedence and cannot be changed.  */
 242 extern int dwfl_module_report_build_id (Dwfl_Module *mod,
 243                                         const unsigned char *bits, size_t len,
 244                                         GElf_Addr vaddr)
 245   __nonnull_attribute__ (2);
 246
 247 /* Extract the build ID bits associated with a module.
 248    Returns -1 for errors, 0 if no ID is known, or the number of ID bytes.
 249    When an ID is found, *BITS points to it; *VADDR is the absolute address
 250    at which the ID bits are found within the module, or 0 if unknown.
 251
 252    This returns 0 when the module's main ELF file has not yet been loaded
 253    and its build ID bits were not reported.  To ensure the ID is always
 254    returned when determinable, call dwfl_module_getelf first.  */
 255 extern int dwfl_module_build_id (Dwfl_Module *mod,
 256                                  const unsigned char **bits, GElf_Addr *vaddr)
 257   __nonnull_attribute__ (2, 3);
 258
 259
 260 /*** Standard callbacks ***/
 261
 262 /* These standard find_elf and find_debuginfo callbacks are
 263    controlled by a string specifying directories to look in.
 264    If `debuginfo_path' is set in the Dwfl_Callbacks structure
 265    and the char * it points to is not null, that supplies the
 266    string.  Otherwise a default path is used.
 267
 268    If the first character of the string is + or - that enables or
 269    disables CRC32 checksum validation when it's necessary.  The
 270    remainder of the string is composed of elements separated by
 271    colons.  Each element can start with + or - to override the
 272    global checksum behavior.  This flag is never relevant when
 273    working with build IDs, but it's always parsed in the path
 274    string.  The remainder of the element indicates a directory.
 275
 276    Searches by build ID consult only the elements naming absolute
 277    directory paths.  They look under those directories for a link
 278    named ".build-id/xx/yy" or ".build-id/xx/yy.debug", where "xxyy"
 279    is the lower-case hexadecimal representation of the ID bytes.
 280
 281    In searches for debuginfo by name, if the remainder of the
 282    element is empty, the directory containing the main file is
 283    tried; if it's an absolute path name, the absolute directory path
 284    containing the main file is taken as a subdirectory of this path;
 285    a relative path name is taken as a subdirectory of the directory
 286    containing the main file.  Hence for /bin/ls, the default string
 287    ":.debug:/usr/lib/debug" says to look in /bin, then /bin/.debug,
 288    then /usr/lib/debug/bin, for the file name in the .gnu_debuglink
 289    section (or "ls.debug" if none was found).  */
 290
 291 /* Standard find_elf callback function working solely on build ID.
 292    This can be tried first by any find_elf callback, to use the
 293    bits passed to dwfl_module_report_build_id, if any.  */
 294 extern int dwfl_build_id_find_elf (Dwfl_Module *, void **,
 295                                    const char *, Dwarf_Addr,
 296                                    char **, Elf **);
 297
 298 /* Standard find_debuginfo callback function working solely on build ID.
 299    This can be tried first by any find_debuginfo callback,
 300    to use the build ID bits from the main file when present.  */
 301 extern int dwfl_build_id_find_debuginfo (Dwfl_Module *, void **,
 302                                          const char *, Dwarf_Addr,
 303                                          const char *, const char *,
 304                                          GElf_Word, char **);
 305
 306 /* Standard find_debuginfo callback function.
 307    If a build ID is available, this tries first to use that.
 308    If there is no build ID or no valid debuginfo found by ID,
 309    it searches the debuginfo path by name, as described above.
 310    Any file found in the path is validated by build ID if possible,
 311    or else by CRC32 checksum if enabled, and skipped if it does not match.  */
 312 extern int dwfl_standard_find_debuginfo (Dwfl_Module *, void **,
 313                                          const char *, Dwarf_Addr,
 314                                          const char *, const char *,
 315                                          GElf_Word, char **);
 316
 317
 318 /* This callback must be used when using dwfl_offline_* to report modules,
 319    if ET_REL is to be supported.  */
 320 extern int dwfl_offline_section_address (Dwfl_Module *, void **,
 321                                          const char *, Dwarf_Addr,
 322                                          const char *, GElf_Word,
 323                                          const GElf_Shdr *,
 324                                          Dwarf_Addr *addr);
 325
 326
 327 /* Callbacks for working with kernel modules in the running Linux kernel.  */
 328 extern int dwfl_linux_kernel_find_elf (Dwfl_Module *, void **,
 329                                        const char *, Dwarf_Addr,
 330                                        char **, Elf **);
 331 extern int dwfl_linux_kernel_module_section_address (Dwfl_Module *, void **,
 332                                                      const char *, Dwarf_Addr,
 333                                                      const char *, GElf_Word,
 334                                                      const GElf_Shdr *,
 335                                                      Dwarf_Addr *addr);
 336
 337 /* Call dwfl_report_elf for the running Linux kernel.
 338    Returns zero on success, -1 if dwfl_report_module failed,
 339    or an errno code if opening the kernel binary failed.  */
 340 extern int dwfl_linux_kernel_report_kernel (Dwfl *dwfl);
 341
 342 /* Call dwfl_report_module for each kernel module in the running Linux kernel.
 343    Returns zero on success, -1 if dwfl_report_module failed,
 344    or an errno code if reading the list of modules failed.  */
 345 extern int dwfl_linux_kernel_report_modules (Dwfl *dwfl);
 346
 347 /* Report a kernel and its modules found on disk, for offline use.
 348    If RELEASE starts with '/', it names a directory to look in;
 349    if not, it names a directory to find under /lib/modules/;
 350    if null, /lib/modules/`uname -r` is used.
 351    Returns zero on success, -1 if dwfl_report_module failed,
 352    or an errno code if finding the files on disk failed.
 353
 354    If PREDICATE is not null, it is called with each module to be reported;
 355    its arguments are the module name, and the ELF file name or null if unknown,
 356    and its return value should be zero to skip the module, one to report it,
 357    or -1 to cause the call to fail and return errno.  */
 358 extern int dwfl_linux_kernel_report_offline (Dwfl *dwfl, const char *release,
 359                                              int (*predicate) (const char *,
 360                                                                const char *));
 361
 362 /* Examine an ET_CORE file and report modules based on its contents.
 363    This can follow a dwfl_report_offline call to bootstrap the
 364    DT_DEBUG method of following the dynamic linker link_map chain, in
 365    case the core file does not contain enough of the executable's text
 366    segment to locate its PT_DYNAMIC in the dump.  This might call
 367    dwfl_report_elf on file names found in the dump if reading some
 368    link_map files is the only way to ascertain those modules' addresses.
 369    Returns the number of modules reported, or -1 for errors.  */
 370 extern int dwfl_core_file_report (Dwfl *dwfl, Elf *elf);
 371
 372 /* Call dwfl_report_module for each file mapped into the address space of PID.
 373    Returns zero on success, -1 if dwfl_report_module failed,
 374    or an errno code if opening the kernel binary failed.  */
 375 extern int dwfl_linux_proc_report (Dwfl *dwfl, pid_t pid);
 376
 377 /* Similar, but reads an input stream in the format of Linux /proc/PID/maps
 378    files giving module layout, not the file for a live process.  */
 379 extern int dwfl_linux_proc_maps_report (Dwfl *dwfl, FILE *);
 380
 381 /* Trivial find_elf callback for use with dwfl_linux_proc_report.
 382    This uses the module name as a file name directly and tries to open it
 383    if it begin with a slash, or handles the magic string "[vdso]".  */
 384 extern int dwfl_linux_proc_find_elf (Dwfl_Module *mod, void **userdata,
 385                                      const char *module_name, Dwarf_Addr base,
 386                                      char **file_name, Elf **);
 387
 388 /* Standard argument parsing for using a standard callback set.  */
 389 struct argp;
 390 extern const struct argp *dwfl_standard_argp (void) __attribute__ ((const));
 391
 392
 393 /*** Relocation of addresses from Dwfl ***/
 394
 395 /* Return the number of relocatable bases associated with the module,
 396    which is zero for ET_EXEC and one for ET_DYN.  Returns -1 for errors.  */
 397 extern int dwfl_module_relocations (Dwfl_Module *mod);
 398
 399 /* Return the relocation base index associated with the *ADDRESS location,
 400    and adjust *ADDRESS to be an offset relative to that base.
 401    Returns -1 for errors.  */
 402 extern int dwfl_module_relocate_address (Dwfl_Module *mod,
 403                                          Dwarf_Addr *address);
 404
 405 /* Return the ELF section name for the given relocation base index;
 406    if SHNDXP is not null, set *SHNDXP to the ELF section index.
 407    For ET_DYN, returns "" and sets *SHNDXP to SHN_ABS; the relocation
 408    base is the runtime start address reported for the module.
 409    Returns null for errors.  */
 410 extern const char *dwfl_module_relocation_info (Dwfl_Module *mod,
 411                                                 unsigned int idx,
 412                                                 GElf_Word *shndxp);
 413
 414 /* Validate that ADDRESS and ADDRESS+OFFSET lie in a known module
 415    and both within the same contiguous region for relocation purposes.
 416    Returns zero for success and -1 for errors.  */
 417 extern int dwfl_validate_address (Dwfl *dwfl,
 418                                   Dwarf_Addr address, Dwarf_Sword offset);
 419
 420
 421 /*** ELF access functions ***/
 422
 423 /* Fetch the module main ELF file (where the allocated sections
 424    are found) for use with libelf.  If successful, fills in *BIAS
 425    with the difference between addresses within the loaded module
 426    and those in symbol tables or Dwarf information referring to it.  */
 427 extern Elf *dwfl_module_getelf (Dwfl_Module *, GElf_Addr *bias);
 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 /* Fetch one entry from the module's symbol table.  On errors, returns
 434    NULL.  If successful, fills in *SYM and returns the string for st_name.
 435    This works like gelf_getsym except that st_value is always adjusted to
 436    an absolute value based on the module's location, when the symbol is in
 437    an SHF_ALLOC section.  If SHNDXP is non-null, it's set with the section
 438    index (whether from st_shndx or extended index table); in case of a
 439    symbol in a non-allocated section, *SHNDXP is instead set to -1.  */
 440 extern const char *dwfl_module_getsym (Dwfl_Module *mod, int ndx,
 441                                        GElf_Sym *sym, GElf_Word *shndxp)
 442   __nonnull_attribute__ (3);
 443
 444 /* Find the symbol that ADDRESS lies inside, and return its name.  */
 445 extern const char *dwfl_module_addrname (Dwfl_Module *mod, GElf_Addr address);
 446
 447 /* Find the symbol that ADDRESS lies inside, and return detailed
 448    information as for dwfl_module_getsym (above).  */
 449 extern const char *dwfl_module_addrsym (Dwfl_Module *mod, GElf_Addr address,
 450                                         GElf_Sym *sym, GElf_Word *shndxp)
 451   __nonnull_attribute__ (3);
 452
 453 /* Find the ELF section that *ADDRESS lies inside and return it.
 454    On success, adjusts *ADDRESS to be relative to the section,
 455    and sets *BIAS to the difference between addresses used in
 456    the returned section's headers and run-time addresses.  */
 457 extern Elf_Scn *dwfl_module_address_section (Dwfl_Module *mod,
 458                                              Dwarf_Addr *address,
 459                                              Dwarf_Addr *bias)
 460   __nonnull_attribute__ (2, 3);
 461
 462
 463 /*** Dwarf access functions ***/
 464
 465 /* Fetch the module's debug information for use with libdw.
 466    If successful, fills in *BIAS with the difference between
 467    addresses within the loaded module and those  to use with libdw.  */
 468 extern Dwarf *dwfl_module_getdwarf (Dwfl_Module *, Dwarf_Addr *bias)
 469      __nonnull_attribute__ (2);
 470
 471 /* Get the libdw handle for each module.  */
 472 extern ptrdiff_t dwfl_getdwarf (Dwfl *,
 473                                 int (*callback) (Dwfl_Module *, void **,
 474                                                  const char *, Dwarf_Addr,
 475                                                  Dwarf *, Dwarf_Addr, void *),
 476                                 void *arg, ptrdiff_t offset);
 477
 478 /* Look up the module containing ADDR and return its debugging information,
 479    loading it if necessary.  */
 480 extern Dwarf *dwfl_addrdwarf (Dwfl *dwfl, Dwarf_Addr addr, Dwarf_Addr *bias)
 481      __nonnull_attribute__ (3);
 482
 483
 484 /* Find the CU containing ADDR and return its DIE.  */
 485 extern Dwarf_Die *dwfl_addrdie (Dwfl *dwfl, Dwarf_Addr addr, Dwarf_Addr *bias)
 486      __nonnull_attribute__ (3);
 487 extern Dwarf_Die *dwfl_module_addrdie (Dwfl_Module *mod,
 488                                        Dwarf_Addr addr, Dwarf_Addr *bias)
 489      __nonnull_attribute__ (3);
 490
 491 /* Iterate through the CUs, start with null for LASTCU.  */
 492 extern Dwarf_Die *dwfl_nextcu (Dwfl *dwfl, Dwarf_Die *lastcu, Dwarf_Addr *bias)
 493      __nonnull_attribute__ (3);
 494 extern Dwarf_Die *dwfl_module_nextcu (Dwfl_Module *mod,
 495                                       Dwarf_Die *lastcu, Dwarf_Addr *bias)
 496      __nonnull_attribute__ (3);
 497
 498 /* Return the module containing the CU DIE.  */
 499 extern Dwfl_Module *dwfl_cumodule (Dwarf_Die *cudie);
 500
 501
 502 /* Cache the source line information fo the CU and return the
 503    number of Dwfl_Line entries it has.  */
 504 extern int dwfl_getsrclines (Dwarf_Die *cudie, size_t *nlines);
 505
 506 /* Access one line number entry within the CU.  */
 507 extern Dwfl_Line *dwfl_onesrcline (Dwarf_Die *cudie, size_t idx);
 508
 509 /* Get source for address.  */
 510 extern Dwfl_Line *dwfl_module_getsrc (Dwfl_Module *mod, Dwarf_Addr addr);
 511 extern Dwfl_Line *dwfl_getsrc (Dwfl *dwfl, Dwarf_Addr addr);
 512
 513 /* Get address for source.  */
 514 extern int dwfl_module_getsrc_file (Dwfl_Module *mod,
 515                                     const char *fname, int lineno, int column,
 516                                     Dwfl_Line ***srcsp, size_t *nsrcs);
 517
 518 /* Return the module containing this line record.  */
 519 extern Dwfl_Module *dwfl_linemodule (Dwfl_Line *line);
 520
 521 /* Return the CU containing this line record.  */
 522 extern Dwarf_Die *dwfl_linecu (Dwfl_Line *line);
 523
 524 /* Return the source file name and fill in other information.
 525    Arguments may be null for unneeded fields.  */
 526 extern const char *dwfl_lineinfo (Dwfl_Line *line, Dwarf_Addr *addr,
 527                                   int *linep, int *colp,
 528                                   Dwarf_Word *mtime, Dwarf_Word *length);
 529
 530   /* Return the equivalent Dwarf_Line and the bias to apply to its address.  */
 531 extern Dwarf_Line *dwfl_dwarf_line (Dwfl_Line *line, Dwarf_Addr *bias);
 532
 533 /* Return the compilation directory (AT_comp_dir) from this line's CU.  */
 534 extern const char *dwfl_line_comp_dir (Dwfl_Line *line);
 535
 536
 537 /*** Machine backend access functions ***/
 538
 539 /* Return location expression to find return value given a
 540    DW_TAG_subprogram, DW_TAG_subroutine_type, or similar DIE describing
 541    function itself (whose DW_AT_type attribute describes its return type).
 542    The given DIE must come from the given module.  Returns -1 for errors.
 543    Returns zero if the function has no return value (e.g. "void" in C).
 544    Otherwise, *LOCOPS gets a location expression to find the return value,
 545    and returns the number of operations in the expression.  The pointer is
 546    permanently allocated at least as long as the module is live.  */
 547 extern int dwfl_module_return_value_location (Dwfl_Module *mod,
 548                                               Dwarf_Die *functypedie,
 549                                               const Dwarf_Op **locops);
 550
 551 /* Enumerate the DWARF register numbers and their names.
 552    For each register, CALLBACK gets its DWARF number, a string describing
 553    the register set (such as "integer" or "FPU"), a prefix used in
 554    assembler syntax (such as "%" or "$", may be ""), and the name for the
 555    register (contains identifier characters only, possibly all digits).
 556    The REGNAME string is valid only during the callback. */
 557 extern int dwfl_module_register_names (Dwfl_Module *mod,
 558                                        int (*callback) (void *arg,
 559                                                         int regno,
 560                                                         const char *setname,
 561                                                         const char *prefix,
 562                                                         const char *regname,
 563                                                         int bits, int type),
 564                                        void *arg);
 565
 566
 567 /* Find the CFI for this module.  Returns NULL if there is no CFI.
 568    On success, fills in *BIAS with the difference between addresses
 569    within the loaded module and those in the CFI referring to it.
 570    The pointer returned can be used until the module is cleaned up.
 571    Calling these more than once returns the same pointers.
 572
 573    dwfl_module_dwarf_cfi gets the '.debug_frame' information found with the
 574    rest of the DWARF information.  dwfl_module_eh_cfi gets the '.eh_frame'
 575    information found linked into the text.  A module might have either or
 576    both.  */
 577 extern Dwarf_CFI *dwfl_module_dwarf_cfi (Dwfl_Module *mod, Dwarf_Addr *bias);
 578 extern Dwarf_CFI *dwfl_module_eh_cfi (Dwfl_Module *mod, Dwarf_Addr *bias);
 579
 580
 581 #ifdef __cplusplus
 582 }
 583 #endif
 584
 585 #endif  /* libdwfl.h */