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