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