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

source code of include/elfutils/libdwfl.h