1 /* Interfaces for libdwfl.
2    Copyright (C) 2005-2010, 2013 Red Hat, Inc.
3    This file is part of elfutils.
4 
5    This file is free software; you can redistribute it and/or modify
6    it under the terms of either
7 
8      * the GNU Lesser General Public License as published by the Free
9        Software Foundation; either version 3 of the License, or (at
10        your option) any later version
11 
12    or
13 
14      * the GNU General Public License as published by the Free
15        Software Foundation; either version 2 of the License, or (at
16        your option) any later version
17 
18    or both in parallel, as here.
19 
20    elfutils is distributed in the hope that it will be useful, but
21    WITHOUT ANY WARRANTY; without even the implied warranty of
22    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
23    General Public License for more details.
24 
25    You should have received copies of the GNU General Public License and
26    the GNU Lesser General Public License along with this program.  If
27    not, see <http://www.gnu.org/licenses/>.  */
28 
29 #ifndef _LIBDWFL_H
30 #define _LIBDWFL_H	1
31 
32 #include "libdw.h"
33 #include <stdio.h>
34 
35 /* Handle for a session using the library.  */
36 typedef struct Dwfl Dwfl;
37 
38 /* Handle for a module.  */
39 typedef struct Dwfl_Module Dwfl_Module;
40 
41 /* Handle describing a line record.  */
42 typedef struct Dwfl_Line Dwfl_Line;
43 
44 /* This holds information common for all the frames of one backtrace for
45    a partical thread/task/TID.  Several threads belong to one Dwfl.  */
46 typedef struct Dwfl_Thread Dwfl_Thread;
47 
48 /* This holds everything we know about the state of the frame at a particular
49    PC location described by an FDE belonging to Dwfl_Thread.  */
50 typedef struct Dwfl_Frame Dwfl_Frame;
51 
52 /* Callbacks.  */
53 typedef struct
54 {
55   int (*find_elf) (Dwfl_Module *mod, void **userdata,
56 		   const char *modname, Dwarf_Addr base,
57 		   char **file_name, Elf **elfp);
58 
59   int (*find_debuginfo) (Dwfl_Module *mod, void **userdata,
60 			 const char *modname, Dwarf_Addr base,
61 			 const char *file_name,
62 			 const char *debuglink_file, GElf_Word debuglink_crc,
63 			 char **debuginfo_file_name);
64 
65   /* Fill *ADDR with the loaded address of the section called SECNAME in
66      the given module.  Use (Dwarf_Addr) -1 if this section is omitted from
67      accessible memory.  This is called exactly once for each SHF_ALLOC
68      section that relocations affecting DWARF data refer to, so it can
69      easily be used to collect state about the sections referenced.  */
70   int (*section_address) (Dwfl_Module *mod, void **userdata,
71 			  const char *modname, Dwarf_Addr base,
72 			  const char *secname,
73 			  GElf_Word shndx, const GElf_Shdr *shdr,
74 			  Dwarf_Addr *addr);
75 
76   char **debuginfo_path;	/* See dwfl_standard_find_debuginfo.  */
77 } Dwfl_Callbacks;
78 
79 
80 #ifdef __cplusplus
81 extern "C" {
82 #endif
83 
84 /* Start a new session with the library.  */
85 extern Dwfl *dwfl_begin (const Dwfl_Callbacks *callbacks)
86   __nonnull_attribute__ (1);
87 
88 
89 /* End a session.  */
90 extern void dwfl_end (Dwfl *);
91 
92 /* Return implementation's version string suitable for printing.  */
93 extern const char *dwfl_version (Dwfl *);
94 
95 /* Return error code of last failing function call.  This value is kept
96    separately for each thread.  */
97 extern int dwfl_errno (void);
98 
99 /* Return error string for ERROR.  If ERROR is zero, return error string
100    for most recent error or NULL if none occurred.  If ERROR is -1 the
101    behaviour is similar to the last case except that not NULL but a legal
102    string is returned.  */
103 extern const char *dwfl_errmsg (int err);
104 
105 
106 /* Start reporting the current set of segments and modules to the library.
107    All existing segments are wiped.  Existing modules are marked to be
108    deleted, and will not be found via dwfl_addrmodule et al if they are not
109    re-reported before dwfl_report_end is called.  */
110 extern void dwfl_report_begin (Dwfl *dwfl);
111 
112 /* Report that segment NDX begins at PHDR->p_vaddr + BIAS.
113    If NDX is < 0, the value succeeding the last call's NDX
114    is used instead (zero on the first call).
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.  */
138 extern 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.  */
145 extern 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).  */
160 extern 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.  */
168 extern 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.  */
179 extern 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.  */
190 extern 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).  */
201 extern 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.  */
212 extern 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.  */
220 extern 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.  */
226 extern 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.  */
236 extern 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.  */
249 extern 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.  */
290 extern 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.  */
297 extern 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.  */
308 extern 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.  */
316 extern 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.  */
324 extern int dwfl_linux_kernel_find_elf (Dwfl_Module *, void **,
325 				       const char *, Dwarf_Addr,
326 				       char **, Elf **);
327 extern 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.  */
336 extern 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.  */
341 extern 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.  */
354 extern 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.  */
368 extern 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.  */
373 extern 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.  */
377 extern 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]".  */
382 extern 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.  */
387 struct argp;
388 extern 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.  */
395 extern 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.  */
400 extern 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.  */
408 extern 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.  */
415 extern 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.  */
425 extern 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.  */
430 extern 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.  */
437 extern 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.  */
451 extern 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.  */
475 extern 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.  */
482 extern 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.  */
503 extern 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.  */
518 extern 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.  */
526 extern 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.  */
537 extern Dwarf *dwfl_module_getdwarf (Dwfl_Module *, Dwarf_Addr *bias)
538      __nonnull_attribute__ (2);
539 
540 /* Get the libdw handle for each module.  */
541 extern 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.  */
549 extern 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.  */
554 extern Dwarf_Die *dwfl_addrdie (Dwfl *dwfl, Dwarf_Addr addr, Dwarf_Addr *bias)
555      __nonnull_attribute__ (3);
556 extern 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.  */
561 extern Dwarf_Die *dwfl_nextcu (Dwfl *dwfl, Dwarf_Die *lastcu, Dwarf_Addr *bias)
562      __nonnull_attribute__ (3);
563 extern 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.  */
568 extern 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.  */
573 extern int dwfl_getsrclines (Dwarf_Die *cudie, size_t *nlines);
574 
575 /* Access one line number entry within the CU.  */
576 extern Dwfl_Line *dwfl_onesrcline (Dwarf_Die *cudie, size_t idx);
577 
578 /* Get source for address.  */
579 extern Dwfl_Line *dwfl_module_getsrc (Dwfl_Module *mod, Dwarf_Addr addr);
580 extern Dwfl_Line *dwfl_getsrc (Dwfl *dwfl, Dwarf_Addr addr);
581 
582 /* Get address for source.  */
583 extern 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.  */
588 extern Dwfl_Module *dwfl_linemodule (Dwfl_Line *line);
589 
590 /* Return the CU containing this line record.  */
591 extern 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.  */
595 extern 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.  */
600 extern 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.  */
603 extern 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.  */
616 extern 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. */
626 extern 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.  */
646 extern Dwarf_CFI *dwfl_module_dwarf_cfi (Dwfl_Module *mod, Dwarf_Addr *bias);
647 extern Dwarf_CFI *dwfl_module_eh_cfi (Dwfl_Module *mod, Dwarf_Addr *bias);
648 
649 
650 typedef 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.  */
714 bool 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.  */
722 extern 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.  */
733 extern 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.  */
738 pid_t dwfl_pid (Dwfl *dwfl)
739   __nonnull_attribute__ (1);
740 
741 /* Return DWFL from which THREAD was created using dwfl_getthreads.  */
742 Dwfl *dwfl_thread_dwfl (Dwfl_Thread *thread)
743   __nonnull_attribute__ (1);
744 
745 /* Return positive TID (thread ID) for THREAD.  This function never fails.  */
746 pid_t dwfl_thread_tid (Dwfl_Thread *thread)
747   __nonnull_attribute__ (1);
748 
749 /* Return thread for frame STATE.  This function never fails.  */
750 Dwfl_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.  */
757 bool 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.  */
765 void 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.  */
773 int 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.  */
787 int 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 ().  */
797 int 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.  */
807 bool 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