libdwfl/libdwfl.h

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