Ben Cheng | 25b3c04 | 2013-11-20 14:45:36 -0800 | [diff] [blame] | 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 */ |