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