1 /* Interfaces for libdwfl.
2 Copyright (C) 2005-2010 Red Hat, Inc.
3 This file is part of elfutils.
5 This file is free software; you can redistribute it and/or modify
6 it under the terms of either
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
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
18 or both in parallel, as here.
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.
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/>. */
35 /* Handle for a session using the library. */
36 typedef struct Dwfl Dwfl;
38 /* Handle for a module. */
39 typedef struct Dwfl_Module Dwfl_Module;
41 /* Handle describing a line record. */
42 typedef struct Dwfl_Line Dwfl_Line;
47 int (*find_elf) (Dwfl_Module *mod, void **userdata,
48 const char *modname, Dwarf_Addr base,
49 char **file_name, Elf **elfp);
51 int (*find_debuginfo) (Dwfl_Module *mod, void **userdata,
52 const char *modname, Dwarf_Addr base,
53 const char *file_name,
54 const char *debuglink_file, GElf_Word debuglink_crc,
55 char **debuginfo_file_name);
57 /* Fill *ADDR with the loaded address of the section called SECNAME in
58 the given module. Use (Dwarf_Addr) -1 if this section is omitted from
59 accessible memory. This is called exactly once for each SHF_ALLOC
60 section that relocations affecting DWARF data refer to, so it can
61 easily be used to collect state about the sections referenced. */
62 int (*section_address) (Dwfl_Module *mod, void **userdata,
63 const char *modname, Dwarf_Addr base,
65 GElf_Word shndx, const GElf_Shdr *shdr,
68 char **debuginfo_path; /* See dwfl_standard_find_debuginfo. */
76 /* Start a new session with the library. */
77 extern Dwfl *dwfl_begin (const Dwfl_Callbacks *callbacks)
78 __nonnull_attribute__ (1);
82 extern void dwfl_end (Dwfl *);
84 /* Return implementation's version string suitable for printing. */
85 extern const char *dwfl_version (Dwfl *);
87 /* Return error code of last failing function call. This value is kept
88 separately for each thread. */
89 extern int dwfl_errno (void);
91 /* Return error string for ERROR. If ERROR is zero, return error string
92 for most recent error or NULL if none occurred. If ERROR is -1 the
93 behaviour is similar to the last case except that not NULL but a legal
94 string is returned. */
95 extern const char *dwfl_errmsg (int err);
98 /* Start reporting the current set of segments and modules to the library.
99 All existing segments are wiped. Existing modules are marked to be
100 deleted, and will not be found via dwfl_addrmodule et al if they are not
101 re-reported before dwfl_report_end is called. */
102 extern void dwfl_report_begin (Dwfl *dwfl);
104 /* Report that segment NDX begins at PHDR->p_vaddr + BIAS.
105 If NDX is < 0, the value succeeding the last call's NDX
106 is used instead (zero on the first call).
108 If nonzero, the smallest PHDR->p_align value seen sets the
109 effective page size for the address space DWFL describes.
110 This is the granularity at which reported module boundary
111 addresses will be considered to fall in or out of a segment.
113 Returns -1 for errors, or NDX (or its assigned replacement) on success.
115 When NDX is the value succeeding the last call's NDX (or is implicitly
116 so as above), IDENT is nonnull and matches the value in the last call,
117 and the PHDR and BIAS values reflect a segment that would be contiguous,
118 in both memory and file, with the last segment reported, then this
119 segment may be coalesced internally with preceding segments. When given
120 an address inside this segment, dwfl_addrsegment may return the NDX of a
121 preceding contiguous segment. To prevent coalesced segments, always
122 pass a null pointer for IDENT.
124 The values passed are not stored (except to track coalescence).
125 The only information that can be extracted from DWFL later is the
126 mapping of an address to a segment index that starts at or below
127 it. Reporting segments at all is optional. Its only benefit to
128 the caller is to offer this quick lookup via dwfl_addrsegment,
129 or use other segment-based calls. */
130 extern int dwfl_report_segment (Dwfl *dwfl, int ndx,
131 const GElf_Phdr *phdr, GElf_Addr bias,
134 /* Report that a module called NAME spans addresses [START, END).
135 Returns the module handle, either existing or newly allocated,
136 or returns a null pointer for an allocation error. */
137 extern Dwfl_Module *dwfl_report_module (Dwfl *dwfl, const char *name,
138 Dwarf_Addr start, Dwarf_Addr end);
140 /* Report a module with start and end addresses computed from the ELF
141 program headers in the given file, plus BASE. For an ET_REL file,
142 does a simple absolute section layout starting at BASE.
143 FD may be -1 to open FILE_NAME. On success, FD is consumed by the
144 library, and the `find_elf' callback will not be used for this module. */
145 extern Dwfl_Module *dwfl_report_elf (Dwfl *dwfl, const char *name,
146 const char *file_name, int fd,
149 /* Similar, but report the module for offline use. All ET_EXEC files
150 being reported must be reported before any relocatable objects.
151 If this is used, dwfl_report_module and dwfl_report_elf may not be
152 used in the same reporting session. */
153 extern Dwfl_Module *dwfl_report_offline (Dwfl *dwfl, const char *name,
154 const char *file_name, int fd);
157 /* Finish reporting the current set of modules to the library.
158 If REMOVED is not null, it's called for each module that
159 existed before but was not included in the current report.
160 Returns a nonzero return value from the callback.
161 The callback may call dwfl_report_module; doing so with the
162 details of the module being removed prevents its removal.
163 DWFL cannot be used until this function has returned zero. */
164 extern int dwfl_report_end (Dwfl *dwfl,
165 int (*removed) (Dwfl_Module *, void *,
166 const char *, Dwarf_Addr,
170 /* Start reporting additional modules to the library. No calls but
171 dwfl_report_* can be made on DWFL until dwfl_report_end is called.
172 This is like dwfl_report_begin, but all the old modules are kept on.
173 More dwfl_report_* calls can follow to add more modules.
174 When dwfl_report_end is called, no old modules will be removed. */
175 extern void dwfl_report_begin_add (Dwfl *dwfl);
178 /* Return the name of the module, and for each non-null argument store
179 interesting details: *USERDATA is a location for storing your own
180 pointer, **USERDATA is initially null; *START and *END give the address
181 range covered by the module; *DWBIAS is the address bias for debugging
182 information, and *SYMBIAS for symbol table entries (either is -1 if not
183 yet accessed); *MAINFILE is the name of the ELF file, and *DEBUGFILE the
184 name of the debuginfo file (might be equal to *MAINFILE; either is null
185 if not yet accessed). */
186 extern const char *dwfl_module_info (Dwfl_Module *mod, void ***userdata,
187 Dwarf_Addr *start, Dwarf_Addr *end,
188 Dwarf_Addr *dwbias, Dwarf_Addr *symbias,
189 const char **mainfile,
190 const char **debugfile);
192 /* Iterate through the modules, starting the walk with OFFSET == 0.
193 Calls *CALLBACK for each module as long as it returns DWARF_CB_OK.
194 When *CALLBACK returns another value, the walk stops and the
195 return value can be passed as OFFSET to resume it. Returns 0 when
196 there are no more modules, or -1 for errors. */
197 extern ptrdiff_t dwfl_getmodules (Dwfl *dwfl,
198 int (*callback) (Dwfl_Module *, void **,
199 const char *, Dwarf_Addr,
204 /* Find the module containing the given address. */
205 extern Dwfl_Module *dwfl_addrmodule (Dwfl *dwfl, Dwarf_Addr address);
207 /* Find the segment, if any, and module, if any, containing ADDRESS.
208 Returns a segment index returned by dwfl_report_segment, or -1
209 if no segment matches the address. Regardless of the return value,
210 *MOD is always set to the module containing ADDRESS, or to null. */
211 extern int dwfl_addrsegment (Dwfl *dwfl, Dwarf_Addr address, Dwfl_Module **mod);
215 /* Report the known build ID bits associated with a module.
216 If VADDR is nonzero, it gives the absolute address where those
217 bits are found within the module. This can be called at any
218 time, but is usually used immediately after dwfl_report_module.
219 Once the module's main ELF file is opened, the ID note found
220 there takes precedence and cannot be changed. */
221 extern int dwfl_module_report_build_id (Dwfl_Module *mod,
222 const unsigned char *bits, size_t len,
224 __nonnull_attribute__ (2);
226 /* Extract the build ID bits associated with a module.
227 Returns -1 for errors, 0 if no ID is known, or the number of ID bytes.
228 When an ID is found, *BITS points to it; *VADDR is the absolute address
229 at which the ID bits are found within the module, or 0 if unknown.
231 This returns 0 when the module's main ELF file has not yet been loaded
232 and its build ID bits were not reported. To ensure the ID is always
233 returned when determinable, call dwfl_module_getelf first. */
234 extern int dwfl_module_build_id (Dwfl_Module *mod,
235 const unsigned char **bits, GElf_Addr *vaddr)
236 __nonnull_attribute__ (2, 3);
239 /*** Standard callbacks ***/
241 /* These standard find_elf and find_debuginfo callbacks are
242 controlled by a string specifying directories to look in.
243 If `debuginfo_path' is set in the Dwfl_Callbacks structure
244 and the char * it points to is not null, that supplies the
245 string. Otherwise a default path is used.
247 If the first character of the string is + or - that enables or
248 disables CRC32 checksum validation when it's necessary. The
249 remainder of the string is composed of elements separated by
250 colons. Each element can start with + or - to override the
251 global checksum behavior. This flag is never relevant when
252 working with build IDs, but it's always parsed in the path
253 string. The remainder of the element indicates a directory.
255 Searches by build ID consult only the elements naming absolute
256 directory paths. They look under those directories for a link
257 named ".build-id/xx/yy" or ".build-id/xx/yy.debug", where "xxyy"
258 is the lower-case hexadecimal representation of the ID bytes.
260 In searches for debuginfo by name, if the remainder of the
261 element is empty, the directory containing the main file is
262 tried; if it's an absolute path name, the absolute directory path
263 containing the main file is taken as a subdirectory of this path;
264 a relative path name is taken as a subdirectory of the directory
265 containing the main file. Hence for /bin/ls, the default string
266 ":.debug:/usr/lib/debug" says to look in /bin, then /bin/.debug,
267 then /usr/lib/debug/bin, for the file name in the .gnu_debuglink
268 section (or "ls.debug" if none was found). */
270 /* Standard find_elf callback function working solely on build ID.
271 This can be tried first by any find_elf callback, to use the
272 bits passed to dwfl_module_report_build_id, if any. */
273 extern int dwfl_build_id_find_elf (Dwfl_Module *, void **,
274 const char *, Dwarf_Addr,
277 /* Standard find_debuginfo callback function working solely on build ID.
278 This can be tried first by any find_debuginfo callback,
279 to use the build ID bits from the main file when present. */
280 extern int dwfl_build_id_find_debuginfo (Dwfl_Module *, void **,
281 const char *, Dwarf_Addr,
282 const char *, const char *,
285 /* Standard find_debuginfo callback function.
286 If a build ID is available, this tries first to use that.
287 If there is no build ID or no valid debuginfo found by ID,
288 it searches the debuginfo path by name, as described above.
289 Any file found in the path is validated by build ID if possible,
290 or else by CRC32 checksum if enabled, and skipped if it does not match. */
291 extern int dwfl_standard_find_debuginfo (Dwfl_Module *, void **,
292 const char *, Dwarf_Addr,
293 const char *, const char *,
297 /* This callback must be used when using dwfl_offline_* to report modules,
298 if ET_REL is to be supported. */
299 extern int dwfl_offline_section_address (Dwfl_Module *, void **,
300 const char *, Dwarf_Addr,
301 const char *, GElf_Word,
306 /* Callbacks for working with kernel modules in the running Linux kernel. */
307 extern int dwfl_linux_kernel_find_elf (Dwfl_Module *, void **,
308 const char *, Dwarf_Addr,
310 extern int dwfl_linux_kernel_module_section_address (Dwfl_Module *, void **,
311 const char *, Dwarf_Addr,
312 const char *, GElf_Word,
316 /* Call dwfl_report_elf for the running Linux kernel.
317 Returns zero on success, -1 if dwfl_report_module failed,
318 or an errno code if opening the kernel binary failed. */
319 extern int dwfl_linux_kernel_report_kernel (Dwfl *dwfl);
321 /* Call dwfl_report_module for each kernel module in the running Linux kernel.
322 Returns zero on success, -1 if dwfl_report_module failed,
323 or an errno code if reading the list of modules failed. */
324 extern int dwfl_linux_kernel_report_modules (Dwfl *dwfl);
326 /* Report a kernel and its modules found on disk, for offline use.
327 If RELEASE starts with '/', it names a directory to look in;
328 if not, it names a directory to find under /lib/modules/;
329 if null, /lib/modules/`uname -r` is used.
330 Returns zero on success, -1 if dwfl_report_module failed,
331 or an errno code if finding the files on disk failed.
333 If PREDICATE is not null, it is called with each module to be reported;
334 its arguments are the module name, and the ELF file name or null if unknown,
335 and its return value should be zero to skip the module, one to report it,
336 or -1 to cause the call to fail and return errno. */
337 extern int dwfl_linux_kernel_report_offline (Dwfl *dwfl, const char *release,
338 int (*predicate) (const char *,
341 /* Examine an ET_CORE file and report modules based on its contents.
342 This can follow a dwfl_report_offline call to bootstrap the
343 DT_DEBUG method of following the dynamic linker link_map chain, in
344 case the core file does not contain enough of the executable's text
345 segment to locate its PT_DYNAMIC in the dump. This might call
346 dwfl_report_elf on file names found in the dump if reading some
347 link_map files is the only way to ascertain those modules' addresses.
348 Returns the number of modules reported, or -1 for errors. */
349 extern int dwfl_core_file_report (Dwfl *dwfl, Elf *elf);
351 /* Call dwfl_report_module for each file mapped into the address space of PID.
352 Returns zero on success, -1 if dwfl_report_module failed,
353 or an errno code if opening the kernel binary failed. */
354 extern int dwfl_linux_proc_report (Dwfl *dwfl, pid_t pid);
356 /* Similar, but reads an input stream in the format of Linux /proc/PID/maps
357 files giving module layout, not the file for a live process. */
358 extern int dwfl_linux_proc_maps_report (Dwfl *dwfl, FILE *);
360 /* Trivial find_elf callback for use with dwfl_linux_proc_report.
361 This uses the module name as a file name directly and tries to open it
362 if it begin with a slash, or handles the magic string "[vdso]". */
363 extern int dwfl_linux_proc_find_elf (Dwfl_Module *mod, void **userdata,
364 const char *module_name, Dwarf_Addr base,
365 char **file_name, Elf **);
367 /* Standard argument parsing for using a standard callback set. */
369 extern const struct argp *dwfl_standard_argp (void) __attribute__ ((const));
372 /*** Relocation of addresses from Dwfl ***/
374 /* Return the number of relocatable bases associated with the module,
375 which is zero for ET_EXEC and one for ET_DYN. Returns -1 for errors. */
376 extern int dwfl_module_relocations (Dwfl_Module *mod);
378 /* Return the relocation base index associated with the *ADDRESS location,
379 and adjust *ADDRESS to be an offset relative to that base.
380 Returns -1 for errors. */
381 extern int dwfl_module_relocate_address (Dwfl_Module *mod,
382 Dwarf_Addr *address);
384 /* Return the ELF section name for the given relocation base index;
385 if SHNDXP is not null, set *SHNDXP to the ELF section index.
386 For ET_DYN, returns "" and sets *SHNDXP to SHN_ABS; the relocation
387 base is the runtime start address reported for the module.
388 Returns null for errors. */
389 extern const char *dwfl_module_relocation_info (Dwfl_Module *mod,
393 /* Validate that ADDRESS and ADDRESS+OFFSET lie in a known module
394 and both within the same contiguous region for relocation purposes.
395 Returns zero for success and -1 for errors. */
396 extern int dwfl_validate_address (Dwfl *dwfl,
397 Dwarf_Addr address, Dwarf_Sword offset);
400 /*** ELF access functions ***/
402 /* Fetch the module main ELF file (where the allocated sections
403 are found) for use with libelf. If successful, fills in *BIAS
404 with the difference between addresses within the loaded module
405 and those in symbol tables or Dwarf information referring to it. */
406 extern Elf *dwfl_module_getelf (Dwfl_Module *, GElf_Addr *bias)
407 __nonnull_attribute__ (1, 2);
409 /* Return the number of symbols in the module's symbol table,
411 extern int dwfl_module_getsymtab (Dwfl_Module *mod);
413 /* Fetch one entry from the module's symbol table. On errors, returns
414 NULL. If successful, fills in *SYM and returns the string for st_name.
415 This works like gelf_getsym except that st_value is always adjusted to
416 an absolute value based on the module's location, when the symbol is in
417 an SHF_ALLOC section. If SHNDXP is non-null, it's set with the section
418 index (whether from st_shndx or extended index table); in case of a
419 symbol in a non-allocated section, *SHNDXP is instead set to -1. */
420 extern const char *dwfl_module_getsym (Dwfl_Module *mod, int ndx,
421 GElf_Sym *sym, GElf_Word *shndxp)
422 __nonnull_attribute__ (3);
424 /* Find the symbol that ADDRESS lies inside, and return its name. */
425 extern const char *dwfl_module_addrname (Dwfl_Module *mod, GElf_Addr address);
427 /* Find the symbol that ADDRESS lies inside, and return detailed
428 information as for dwfl_module_getsym (above). */
429 extern const char *dwfl_module_addrsym (Dwfl_Module *mod, GElf_Addr address,
430 GElf_Sym *sym, GElf_Word *shndxp)
431 __nonnull_attribute__ (3);
433 /* Find the ELF section that *ADDRESS lies inside and return it.
434 On success, adjusts *ADDRESS to be relative to the section,
435 and sets *BIAS to the difference between addresses used in
436 the returned section's headers and run-time addresses. */
437 extern Elf_Scn *dwfl_module_address_section (Dwfl_Module *mod,
440 __nonnull_attribute__ (2, 3);
443 /*** Dwarf access functions ***/
445 /* Fetch the module's debug information for use with libdw.
446 If successful, fills in *BIAS with the difference between
447 addresses within the loaded module and those to use with libdw. */
448 extern Dwarf *dwfl_module_getdwarf (Dwfl_Module *, Dwarf_Addr *bias)
449 __nonnull_attribute__ (2);
451 /* Get the libdw handle for each module. */
452 extern ptrdiff_t dwfl_getdwarf (Dwfl *,
453 int (*callback) (Dwfl_Module *, void **,
454 const char *, Dwarf_Addr,
455 Dwarf *, Dwarf_Addr, void *),
456 void *arg, ptrdiff_t offset);
458 /* Look up the module containing ADDR and return its debugging information,
459 loading it if necessary. */
460 extern Dwarf *dwfl_addrdwarf (Dwfl *dwfl, Dwarf_Addr addr, Dwarf_Addr *bias)
461 __nonnull_attribute__ (3);
464 /* Find the CU containing ADDR and return its DIE. */
465 extern Dwarf_Die *dwfl_addrdie (Dwfl *dwfl, Dwarf_Addr addr, Dwarf_Addr *bias)
466 __nonnull_attribute__ (3);
467 extern Dwarf_Die *dwfl_module_addrdie (Dwfl_Module *mod,
468 Dwarf_Addr addr, Dwarf_Addr *bias)
469 __nonnull_attribute__ (3);
471 /* Iterate through the CUs, start with null for LASTCU. */
472 extern Dwarf_Die *dwfl_nextcu (Dwfl *dwfl, Dwarf_Die *lastcu, Dwarf_Addr *bias)
473 __nonnull_attribute__ (3);
474 extern Dwarf_Die *dwfl_module_nextcu (Dwfl_Module *mod,
475 Dwarf_Die *lastcu, Dwarf_Addr *bias)
476 __nonnull_attribute__ (3);
478 /* Return the module containing the CU DIE. */
479 extern Dwfl_Module *dwfl_cumodule (Dwarf_Die *cudie);
482 /* Cache the source line information fo the CU and return the
483 number of Dwfl_Line entries it has. */
484 extern int dwfl_getsrclines (Dwarf_Die *cudie, size_t *nlines);
486 /* Access one line number entry within the CU. */
487 extern Dwfl_Line *dwfl_onesrcline (Dwarf_Die *cudie, size_t idx);
489 /* Get source for address. */
490 extern Dwfl_Line *dwfl_module_getsrc (Dwfl_Module *mod, Dwarf_Addr addr);
491 extern Dwfl_Line *dwfl_getsrc (Dwfl *dwfl, Dwarf_Addr addr);
493 /* Get address for source. */
494 extern int dwfl_module_getsrc_file (Dwfl_Module *mod,
495 const char *fname, int lineno, int column,
496 Dwfl_Line ***srcsp, size_t *nsrcs);
498 /* Return the module containing this line record. */
499 extern Dwfl_Module *dwfl_linemodule (Dwfl_Line *line);
501 /* Return the CU containing this line record. */
502 extern Dwarf_Die *dwfl_linecu (Dwfl_Line *line);
504 /* Return the source file name and fill in other information.
505 Arguments may be null for unneeded fields. */
506 extern const char *dwfl_lineinfo (Dwfl_Line *line, Dwarf_Addr *addr,
507 int *linep, int *colp,
508 Dwarf_Word *mtime, Dwarf_Word *length);
510 /* Return the equivalent Dwarf_Line and the bias to apply to its address. */
511 extern Dwarf_Line *dwfl_dwarf_line (Dwfl_Line *line, Dwarf_Addr *bias);
513 /* Return the compilation directory (AT_comp_dir) from this line's CU. */
514 extern const char *dwfl_line_comp_dir (Dwfl_Line *line);
517 /*** Machine backend access functions ***/
519 /* Return location expression to find return value given a
520 DW_TAG_subprogram, DW_TAG_subroutine_type, or similar DIE describing
521 function itself (whose DW_AT_type attribute describes its return type).
522 The given DIE must come from the given module. Returns -1 for errors.
523 Returns zero if the function has no return value (e.g. "void" in C).
524 Otherwise, *LOCOPS gets a location expression to find the return value,
525 and returns the number of operations in the expression. The pointer is
526 permanently allocated at least as long as the module is live. */
527 extern int dwfl_module_return_value_location (Dwfl_Module *mod,
528 Dwarf_Die *functypedie,
529 const Dwarf_Op **locops);
531 /* Enumerate the DWARF register numbers and their names.
532 For each register, CALLBACK gets its DWARF number, a string describing
533 the register set (such as "integer" or "FPU"), a prefix used in
534 assembler syntax (such as "%" or "$", may be ""), and the name for the
535 register (contains identifier characters only, possibly all digits).
536 The REGNAME string is valid only during the callback. */
537 extern int dwfl_module_register_names (Dwfl_Module *mod,
538 int (*callback) (void *arg,
547 /* Find the CFI for this module. Returns NULL if there is no CFI.
548 On success, fills in *BIAS with the difference between addresses
549 within the loaded module and those in the CFI referring to it.
550 The pointer returned can be used until the module is cleaned up.
551 Calling these more than once returns the same pointers.
553 dwfl_module_dwarf_cfi gets the '.debug_frame' information found with the
554 rest of the DWARF information. dwfl_module_eh_cfi gets the '.eh_frame'
555 information found linked into the text. A module might have either or
557 extern Dwarf_CFI *dwfl_module_dwarf_cfi (Dwfl_Module *mod, Dwarf_Addr *bias);
558 extern Dwarf_CFI *dwfl_module_eh_cfi (Dwfl_Module *mod, Dwarf_Addr *bias);
565 #endif /* libdwfl.h */