libdwfl/libdwfl.h

   1 /* Interfaces for libdwfl.
   2    Copyright (C) 2005, 2006 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.  This is called exactly once for each SHF_ALLOC
  80      section that relocations affecting DWARF data refer to, so it can
  81      easily be used to collect state about the sections referenced.  */
  82   int (*section_address) (Dwfl_Module *mod, void **userdata,
  83                           const char *modname, Dwarf_Addr base,
  84                           const char *secname,
  85                           GElf_Word shndx, const GElf_Shdr *shdr,
  86                           Dwarf_Addr *addr);
  87
  88   char **debuginfo_path;        /* See dwfl_standard_find_debuginfo.  */
  89 } Dwfl_Callbacks;
  90
  91
  92 #ifdef __cplusplus
  93 extern "C" {
  94 #endif
  95
  96 /* Start a new session with the library.  */
  97 extern Dwfl *dwfl_begin (const Dwfl_Callbacks *callbacks);
  98
  99 /* End a session.  */
 100 extern void dwfl_end (Dwfl *);
 101
 102 /* Return implementation's version string suitable for printing.  */
 103 extern const char *dwfl_version (Dwfl *);
 104
 105 /* Return error code of last failing function call.  This value is kept
 106    separately for each thread.  */
 107 extern int dwfl_errno (void);
 108
 109 /* Return error string for ERROR.  If ERROR is zero, return error string
 110    for most recent error or NULL if none occurred.  If ERROR is -1 the
 111    behaviour is similar to the last case except that not NULL but a legal
 112    string is returned.  */
 113 extern const char *dwfl_errmsg (int err);
 114
 115
 116 /* Start reporting the current set of modules to the library.  No calls but
 117    dwfl_report_* can be made on DWFL until dwfl_report_end is called.  */
 118 extern void dwfl_report_begin (Dwfl *dwfl);
 119
 120 /* Report that a module called NAME spans addresses [START, END).
 121    Returns the module handle, either existing or newly allocated,
 122    or returns a null pointer for an allocation error.  */
 123 extern Dwfl_Module *dwfl_report_module (Dwfl *dwfl, const char *name,
 124                                         Dwarf_Addr start, Dwarf_Addr end);
 125
 126 /* Report a module with start and end addresses computed from the ELF
 127    program headers in the given file, plus BASE.  For an ET_REL file,
 128    does a simple absolute section layout starting at BASE.
 129    FD may be -1 to open FILE_NAME.  On success, FD is consumed by the
 130    library, and the `find_elf' callback will not be used for this module.  */
 131 extern Dwfl_Module *dwfl_report_elf (Dwfl *dwfl, const char *name,
 132                                      const char *file_name, int fd,
 133                                      GElf_Addr base);
 134
 135 /* Similar, but report the module for offline use.  All ET_EXEC files
 136    being reported must be reported before any relocatable objects.
 137    If this is used, dwfl_report_module and dwfl_report_elf may not be
 138    used in the same reporting session.  */
 139 extern Dwfl_Module *dwfl_report_offline (Dwfl *dwfl, const char *name,
 140                                          const char *file_name, int fd);
 141
 142
 143 /* Finish reporting the current set of modules to the library.
 144    If REMOVED is not null, it's called for each module that
 145    existed before but was not included in the current report.
 146    Returns a nonzero return value from the callback.
 147    The callback may call dwfl_report_module; doing so with the
 148    details of the module being removed prevents its removal.
 149    DWFL cannot be used until this function has returned zero.  */
 150 extern int dwfl_report_end (Dwfl *dwfl,
 151                             int (*removed) (Dwfl_Module *, void *,
 152                                             const char *, Dwarf_Addr,
 153                                             void *arg),
 154                             void *arg);
 155
 156 /* Return the name of the module, and for each non-null argument store
 157    interesting details: *USERDATA is a location for storing your own
 158    pointer, **USERDATA is initially null; *START and *END give the address
 159    range covered by the module; *DWBIAS is the address bias for debugging
 160    information, and *SYMBIAS for symbol table entries (either is -1 if not
 161    yet accessed); *MAINFILE is the name of the ELF file, and *DEBUGFILE the
 162    name of the debuginfo file (might be equal to *MAINFILE; either is null
 163    if not yet accessed).  */
 164 extern const char *dwfl_module_info (Dwfl_Module *mod, void ***userdata,
 165                                      Dwarf_Addr *start, Dwarf_Addr *end,
 166                                      Dwarf_Addr *dwbias, Dwarf_Addr *symbias,
 167                                      const char **mainfile,
 168                                      const char **debugfile);
 169
 170 /* Iterate through the modules, starting the walk with OFFSET == 0.
 171    Calls *CALLBACK for each module as long as it returns DWARF_CB_OK.
 172    When *CALLBACK returns another value, the walk stops and the
 173    return value can be passed as OFFSET to resume it.  Returns 0 when
 174    there are no more modules, or -1 for errors.  */
 175 extern ptrdiff_t dwfl_getmodules (Dwfl *dwfl,
 176                                   int (*callback) (Dwfl_Module *, void **,
 177                                                    const char *, Dwarf_Addr,
 178                                                    void *arg),
 179                                   void *arg,
 180                                   ptrdiff_t offset);
 181
 182 /* Find the module containing the given address.  */
 183 extern Dwfl_Module *dwfl_addrmodule (Dwfl *dwfl, Dwarf_Addr address);
 184
 185
 186 /*** Standard callbacks ***/
 187
 188 /* Standard find_debuginfo callback function.
 189    This is controlled by a string specifying directories to look in.
 190    If `debuginfo_path' is set in the Dwfl_Callbacks structure
 191    and the char * it points to is not null, that supplies the string.
 192    Otherwise a default path is used.
 193
 194    If the first character of the string is + or - that says to check or to
 195    ignore (respectively) the CRC32 checksum from the .gnu_debuglink
 196    section.  The default is to check it.  The remainder of the string is
 197    composed of elements separated by colons.  Each element can start with +
 198    or - to override the global checksum behavior.  If the remainder of the
 199    element is empty, the directory containing the main file is tried; if
 200    it's an absolute path name, the absolute directory path containing the
 201    main file is taken as a subdirectory of this path; a relative path name
 202    is taken as a subdirectory of the directory containing the main file.
 203    Hence for /bin/ls, string ":.debug:/usr/lib/debug" says to look in /bin,
 204    then /bin/.debug, then /usr/lib/debug/bin, for the file name in the
 205    .gnu_debuglink section (or "ls.debug" if none was found).  */
 206
 207 extern int dwfl_standard_find_debuginfo (Dwfl_Module *, void **,
 208                                          const char *, Dwarf_Addr,
 209                                          const char *, const char *,
 210                                          GElf_Word, char **);
 211
 212
 213 /* This callback must be used when using dwfl_offline_* to report modules,
 214    if ET_REL is to be supported.  */
 215 extern int dwfl_offline_section_address (Dwfl_Module *, void **,
 216                                          const char *, Dwarf_Addr,
 217                                          const char *, GElf_Word,
 218                                          const GElf_Shdr *,
 219                                          Dwarf_Addr *addr);
 220
 221
 222 /* Callbacks for working with kernel modules in the running Linux kernel.  */
 223 extern int dwfl_linux_kernel_find_elf (Dwfl_Module *, void **,
 224                                        const char *, Dwarf_Addr,
 225                                        char **, Elf **);
 226 extern int dwfl_linux_kernel_module_section_address (Dwfl_Module *, void **,
 227                                                      const char *, Dwarf_Addr,
 228                                                      const char *, GElf_Word,
 229                                                      const GElf_Shdr *,
 230                                                      Dwarf_Addr *addr);
 231
 232 /* Call dwfl_report_elf for the running Linux kernel.
 233    Returns zero on success, -1 if dwfl_report_module failed,
 234    or an errno code if opening the kernel binary failed.  */
 235 extern int dwfl_linux_kernel_report_kernel (Dwfl *dwfl);
 236
 237 /* Call dwfl_report_module for each kernel module in the running Linux kernel.
 238    Returns zero on success, -1 if dwfl_report_module failed,
 239    or an errno code if reading the list of modules failed.  */
 240 extern int dwfl_linux_kernel_report_modules (Dwfl *dwfl);
 241
 242 /* Report a kernel and its modules found on disk, for offline use.
 243    If RELEASE starts with '/', it names a directory to look in;
 244    if not, it names a directory to find under /lib/modules/;
 245    if null, /lib/modules/`uname -r` is used.
 246    Returns zero on success, -1 if dwfl_report_module failed,
 247    or an errno code if finding the files on disk failed.
 248
 249    If PREDICATE is not null, it is called with each module to be reported;
 250    its arguments are the module name, and the ELF file name or null if unknown,
 251    and its return value should be zero to skip the module, one to report it,
 252    or -1 to cause the call to fail and return errno.  */
 253 extern int dwfl_linux_kernel_report_offline (Dwfl *dwfl, const char *release,
 254                                              int (*predicate) (const char *,
 255                                                                const char *));
 256
 257
 258 /* Call dwfl_report_module for each file mapped into the address space of PID.
 259    Returns zero on success, -1 if dwfl_report_module failed,
 260    or an errno code if opening the kernel binary failed.  */
 261 extern int dwfl_linux_proc_report (Dwfl *dwfl, pid_t pid);
 262
 263 /* Similar, but reads an input stream in the format of Linux /proc/PID/maps
 264    files giving module layout, not the file for a live process.  */
 265 extern int dwfl_linux_proc_maps_report (Dwfl *dwfl, FILE *);
 266
 267 /* Trivial find_elf callback for use with dwfl_linux_proc_report.
 268    This uses the module name as a file name directly and tries to open it
 269    if it begin with a slash, or handles the magic string "[vdso]".  */
 270 extern int dwfl_linux_proc_find_elf (Dwfl_Module *mod, void **userdata,
 271                                      const char *module_name, Dwarf_Addr base,
 272                                      char **file_name, Elf **);
 273
 274 /* Standard argument parsing for using a standard callback set.  */
 275 struct argp;
 276 extern const struct argp *dwfl_standard_argp (void) __attribute__ ((const));
 277
 278
 279 /*** Relocation of addresses from Dwfl ***/
 280
 281 /* Return the number of relocatable bases associated with the module,
 282    which is zero for ET_EXEC and one for ET_DYN.  Returns -1 for errors.  */
 283 extern int dwfl_module_relocations (Dwfl_Module *mod);
 284
 285 /* Return the relocation base index associated with the *ADDRESS location,
 286    and adjust *ADDRESS to be an offset relative to that base.
 287    Returns -1 for errors.  */
 288 extern int dwfl_module_relocate_address (Dwfl_Module *mod,
 289                                          Dwarf_Addr *address);
 290
 291 /* Return the ELF section name for the given relocation base index;
 292    if SHNDXP is not null, set *SHNDXP to the ELF section index.
 293    For ET_DYN, returns "" and sets *SHNDXP to SHN_ABS; the relocation
 294    base is the runtime start address reported for the module.
 295    Returns null for errors.  */
 296 extern const char *dwfl_module_relocation_info (Dwfl_Module *mod,
 297                                                 unsigned int idx,
 298                                                 GElf_Word *shndxp);
 299
 300 /* Validate that ADDRESS and ADDRESS+OFFSET lie in a known module
 301    and both within the same contiguous region for relocation purposes.
 302    Returns zero for success and -1 for errors.  */
 303 extern int dwfl_validate_address (Dwfl *dwfl,
 304                                   Dwarf_Addr address, Dwarf_Sword offset);
 305
 306
 307 /*** ELF access functions ***/
 308
 309 /* Fetch the module main ELF file (where the allocated sections
 310    are found) for use with libelf.  If successful, fills in *BIAS
 311    with the difference between addresses within the loaded module
 312    and those in symbol tables or Dwarf information referring to it.  */
 313 extern Elf *dwfl_module_getelf (Dwfl_Module *, GElf_Addr *bias);
 314
 315 /* Return the number of symbols in the module's symbol table,
 316    or -1 for errors.  */
 317 extern int dwfl_module_getsymtab (Dwfl_Module *mod);
 318
 319 /* Fetch one entry from the module's symbol table.  On errors, returns
 320    NULL.  If successful, fills in *SYM and returns the string for st_name.
 321    This works like gelf_getsym except that st_value is always adjusted
 322    to an absolute value based on the module's location.  If SHNDXP is
 323    non-null, it's set with the section index (whether from st_shndx or
 324    extended index table).  */
 325 extern const char *dwfl_module_getsym (Dwfl_Module *mod, int ndx,
 326                                        GElf_Sym *sym, GElf_Word *shndxp)
 327   __nonnull_attribute__ (3);
 328
 329 /* Find the symbol that ADDRESS lies inside, and return its name.  */
 330 extern const char *dwfl_module_addrname (Dwfl_Module *mod, GElf_Addr address);
 331
 332
 333 /*** Dwarf access functions ***/
 334
 335 /* Fetch the module's debug information for use with libdw.
 336    If successful, fills in *BIAS with the difference between
 337    addresses within the loaded module and those  to use with libdw.  */
 338 extern Dwarf *dwfl_module_getdwarf (Dwfl_Module *, Dwarf_Addr *bias)
 339      __nonnull_attribute__ (2);
 340
 341 /* Get the libdw handle for each module.  */
 342 extern ptrdiff_t dwfl_getdwarf (Dwfl *,
 343                                 int (*callback) (Dwfl_Module *, void **,
 344                                                  const char *, Dwarf_Addr,
 345                                                  Dwarf *, Dwarf_Addr, void *),
 346                                 void *arg, ptrdiff_t offset);
 347
 348 /* Look up the module containing ADDR and return its debugging information,
 349    loading it if necessary.  */
 350 extern Dwarf *dwfl_addrdwarf (Dwfl *dwfl, Dwarf_Addr addr, Dwarf_Addr *bias)
 351      __nonnull_attribute__ (3);
 352
 353
 354 /* Find the CU containing ADDR and return its DIE.  */
 355 extern Dwarf_Die *dwfl_addrdie (Dwfl *dwfl, Dwarf_Addr addr, Dwarf_Addr *bias)
 356      __nonnull_attribute__ (3);
 357 extern Dwarf_Die *dwfl_module_addrdie (Dwfl_Module *mod,
 358                                        Dwarf_Addr addr, Dwarf_Addr *bias)
 359      __nonnull_attribute__ (3);
 360
 361 /* Iterate through the CUs, start with null for LASTCU.  */
 362 extern Dwarf_Die *dwfl_nextcu (Dwfl *dwfl, Dwarf_Die *lastcu, Dwarf_Addr *bias)
 363      __nonnull_attribute__ (3);
 364 extern Dwarf_Die *dwfl_module_nextcu (Dwfl_Module *mod,
 365                                       Dwarf_Die *lastcu, Dwarf_Addr *bias)
 366      __nonnull_attribute__ (3);
 367
 368 /* Return the module containing the CU DIE.  */
 369 extern Dwfl_Module *dwfl_cumodule (Dwarf_Die *cudie);
 370
 371
 372 /* Cache the source line information fo the CU and return the
 373    number of Dwfl_Line entries it has.  */
 374 extern int dwfl_getsrclines (Dwarf_Die *cudie, size_t *nlines);
 375
 376 /* Access one line number entry within the CU.  */
 377 extern Dwfl_Line *dwfl_onesrcline (Dwarf_Die *cudie, size_t idx);
 378
 379 /* Get source for address.  */
 380 extern Dwfl_Line *dwfl_module_getsrc (Dwfl_Module *mod, Dwarf_Addr addr);
 381 extern Dwfl_Line *dwfl_getsrc (Dwfl *dwfl, Dwarf_Addr addr);
 382
 383 /* Get address for source.  */
 384 extern int dwfl_module_getsrc_file (Dwfl_Module *mod,
 385                                     const char *fname, int lineno, int column,
 386                                     Dwfl_Line ***srcsp, size_t *nsrcs);
 387
 388 /* Return the module containing this line record.  */
 389 extern Dwfl_Module *dwfl_linemodule (Dwfl_Line *line);
 390
 391 /* Return the CU containing this line record.  */
 392 extern Dwarf_Die *dwfl_linecu (Dwfl_Line *line);
 393
 394 /* Return the source file name and fill in other information.
 395    Arguments may be null for unneeded fields.  */
 396 extern const char *dwfl_lineinfo (Dwfl_Line *line, Dwarf_Addr *addr,
 397                                   int *linep, int *colp,
 398                                   Dwarf_Word *mtime, Dwarf_Word *length);
 399
 400 /* Return the compilation directory (AT_comp_dir) from this line's CU.  */
 401 extern const char *dwfl_line_comp_dir (Dwfl_Line *line);
 402
 403
 404 /*** Machine backend access functions ***/
 405
 406 /* Return location expression to find return value given a
 407    DW_TAG_subprogram, DW_TAG_subroutine_type, or similar DIE describing
 408    function itself (whose DW_AT_type attribute describes its return type).
 409    The given DIE must come from the given module.  Returns -1 for errors.
 410    Returns zero if the function has no return value (e.g. "void" in C).
 411    Otherwise, *LOCOPS gets a location expression to find the return value,
 412    and returns the number of operations in the expression.  The pointer is
 413    permanently allocated at least as long as the module is live.  */
 414 extern int dwfl_module_return_value_location (Dwfl_Module *mod,
 415                                               Dwarf_Die *functypedie,
 416                                               const Dwarf_Op **locops);
 417
 418 /* Enumerate the DWARF register numbers and their names.
 419    For each register, CALLBACK gets its DWARF number, a string describing
 420    the register set (such as "integer" or "FPU"), a prefix used in
 421    assembler syntax (such as "%" or "$", may be ""), and the name for the
 422    register (contains identifier characters only, possibly all digits).
 423    The REGNAME string is valid only during the callback. */
 424 extern int dwfl_module_register_names (Dwfl_Module *mod,
 425                                        int (*callback) (void *arg,
 426                                                         int regno,
 427                                                         const char *setname,
 428                                                         const char *prefix,
 429                                                         const char *regname),
 430                                        void *arg);
 431
 432
 433 #ifdef __cplusplus
 434 }
 435 #endif
 436
 437 #endif  /* libdwfl.h */