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 */ 586
