Ben Cheng | 25b3c04 | 2013-11-20 14:45:36 -0800 | [diff] [blame] | 1 | /* Interfaces for libdwfl. |
Elliott Hughes | 0333382 | 2015-02-18 22:19:45 -0800 | [diff] [blame^] | 2 | Copyright (C) 2005-2010, 2013 Red Hat, Inc. |
| 3 | This file is part of elfutils. |
Ben Cheng | 25b3c04 | 2013-11-20 14:45:36 -0800 | [diff] [blame] | 4 | |
Elliott Hughes | 0333382 | 2015-02-18 22:19:45 -0800 | [diff] [blame^] | 5 | This file is free software; you can redistribute it and/or modify |
| 6 | it under the terms of either |
Ben Cheng | 25b3c04 | 2013-11-20 14:45:36 -0800 | [diff] [blame] | 7 | |
Elliott Hughes | 0333382 | 2015-02-18 22:19:45 -0800 | [diff] [blame^] | 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 |
Ben Cheng | 25b3c04 | 2013-11-20 14:45:36 -0800 | [diff] [blame] | 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 | |
Elliott Hughes | 0333382 | 2015-02-18 22:19:45 -0800 | [diff] [blame^] | 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/>. */ |
Ben Cheng | 25b3c04 | 2013-11-20 14:45:36 -0800 | [diff] [blame] | 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 | |
Elliott Hughes | 0333382 | 2015-02-18 22:19:45 -0800 | [diff] [blame^] | 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 | |
Ben Cheng | 25b3c04 | 2013-11-20 14:45:36 -0800 | [diff] [blame] | 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 | |
Elliott Hughes | 0333382 | 2015-02-18 22:19:45 -0800 | [diff] [blame^] | 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. |
Ben Cheng | 25b3c04 | 2013-11-20 14:45:36 -0800 | [diff] [blame] | 150 | FD may be -1 to open FILE_NAME. On success, FD is consumed by the |
Elliott Hughes | 0333382 | 2015-02-18 22:19:45 -0800 | [diff] [blame^] | 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). */ |
Ben Cheng | 25b3c04 | 2013-11-20 14:45:36 -0800 | [diff] [blame] | 160 | extern Dwfl_Module *dwfl_report_elf (Dwfl *dwfl, const char *name, |
| 161 | const char *file_name, int fd, |
Elliott Hughes | 0333382 | 2015-02-18 22:19:45 -0800 | [diff] [blame^] | 162 | GElf_Addr base, bool add_p_vaddr); |
Ben Cheng | 25b3c04 | 2013-11-20 14:45:36 -0800 | [diff] [blame] | 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 | containing the main file is taken as a subdirectory of this path; |
| 279 | a relative path name is taken as a subdirectory of the directory |
| 280 | containing the main file. Hence for /bin/ls, the default string |
| 281 | ":.debug:/usr/lib/debug" says to look in /bin, then /bin/.debug, |
| 282 | then /usr/lib/debug/bin, for the file name in the .gnu_debuglink |
| 283 | 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. */ |
| 288 | extern 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. */ |
| 295 | extern 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. */ |
| 306 | extern 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. */ |
| 314 | extern 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. */ |
| 322 | extern int dwfl_linux_kernel_find_elf (Dwfl_Module *, void **, |
| 323 | const char *, Dwarf_Addr, |
| 324 | char **, Elf **); |
| 325 | extern 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. */ |
| 334 | extern 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. */ |
| 339 | extern 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. */ |
| 352 | extern 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 |
Elliott Hughes | 0333382 | 2015-02-18 22:19:45 -0800 | [diff] [blame^] | 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. */ |
| 366 | extern int dwfl_core_file_report (Dwfl *dwfl, Elf *elf, const char *executable); |
Ben Cheng | 25b3c04 | 2013-11-20 14:45:36 -0800 | [diff] [blame] | 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, |
Elliott Hughes | 0333382 | 2015-02-18 22:19:45 -0800 | [diff] [blame^] | 370 | or an errno code if opening the proc files failed. */ |
Ben Cheng | 25b3c04 | 2013-11-20 14:45:36 -0800 | [diff] [blame] | 371 | extern 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. */ |
| 375 | extern 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]". */ |
| 380 | extern 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. */ |
| 385 | struct argp; |
| 386 | extern const struct argp *dwfl_standard_argp (void) __attribute__ ((const)); |
| 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. */ |
| 393 | extern 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. */ |
| 398 | extern 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. */ |
| 406 | extern 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. */ |
| 413 | extern 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. */ |
Elliott Hughes | 0333382 | 2015-02-18 22:19:45 -0800 | [diff] [blame^] | 423 | extern Elf *dwfl_module_getelf (Dwfl_Module *, GElf_Addr *bias) |
| 424 | __nonnull_attribute__ (1, 2); |
Ben Cheng | 25b3c04 | 2013-11-20 14:45:36 -0800 | [diff] [blame] | 425 | |
| 426 | /* Return the number of symbols in the module's symbol table, |
| 427 | or -1 for errors. */ |
| 428 | extern int dwfl_module_getsymtab (Dwfl_Module *mod); |
| 429 | |
Elliott Hughes | 0333382 | 2015-02-18 22:19:45 -0800 | [diff] [blame^] | 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. */ |
| 435 | extern int dwfl_module_getsymtab_first_global (Dwfl_Module *mod); |
| 436 | |
Ben Cheng | 25b3c04 | 2013-11-20 14:45:36 -0800 | [diff] [blame] | 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 |
Elliott Hughes | 0333382 | 2015-02-18 22:19:45 -0800 | [diff] [blame^] | 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. */ |
Ben Cheng | 25b3c04 | 2013-11-20 14:45:36 -0800 | [diff] [blame] | 449 | extern const char *dwfl_module_getsym (Dwfl_Module *mod, int ndx, |
| 450 | GElf_Sym *sym, GElf_Word *shndxp) |
| 451 | __nonnull_attribute__ (3); |
| 452 | |
Elliott Hughes | 0333382 | 2015-02-18 22:19:45 -0800 | [diff] [blame^] | 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. */ |
| 473 | extern 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 | |
Ben Cheng | 25b3c04 | 2013-11-20 14:45:36 -0800 | [diff] [blame] | 479 | /* Find the symbol that ADDRESS lies inside, and return its name. */ |
| 480 | extern const char *dwfl_module_addrname (Dwfl_Module *mod, GElf_Addr address); |
| 481 | |
Elliott Hughes | 0333382 | 2015-02-18 22:19:45 -0800 | [diff] [blame^] | 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 wil be |
| 485 | matched against either the adjusted st_value or the associated |
| 486 | function entry value as described in dwfl_module_getsym_info. If |
| 487 | OFFSET is not NULL it will be filled in with the difference from |
| 488 | the start of the symbol (or function entry). If SYM is not NULL it |
| 489 | is filled in with the symbol associated with the matched ADDRESS. |
| 490 | The SYM->ST_VALUE itself isn't adjusted in any way. Fills in ELFP, |
| 491 | if not NULL, with the ELF file the symbol originally came from. |
| 492 | Note that symbols can come from either the main, debug or auxiliary |
| 493 | ELF symbol file (either dynsym or symtab). If SHNDXP is non-null, |
| 494 | it's set with the section index (whether from st_shndx or extended |
| 495 | index table). Fills in BIAS, if not NULL, with the difference |
| 496 | between addresses within the loaded module and those in symbol |
| 497 | table of the ELF file. Note that the address matched against the |
| 498 | symbol might be in a different section than the returned symbol. |
| 499 | The section in the main elf file in ADDRESS falls can be found with |
| 500 | dwfl_module_address_section. */ |
| 501 | extern 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); |
| 506 | |
Ben Cheng | 25b3c04 | 2013-11-20 14:45:36 -0800 | [diff] [blame] | 507 | /* Find the symbol that ADDRESS lies inside, and return detailed |
Elliott Hughes | 0333382 | 2015-02-18 22:19:45 -0800 | [diff] [blame^] | 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. */ |
Ben Cheng | 25b3c04 | 2013-11-20 14:45:36 -0800 | [diff] [blame] | 516 | extern 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. */ |
| 524 | extern 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. */ |
| 535 | extern Dwarf *dwfl_module_getdwarf (Dwfl_Module *, Dwarf_Addr *bias) |
| 536 | __nonnull_attribute__ (2); |
| 537 | |
| 538 | /* Get the libdw handle for each module. */ |
| 539 | extern 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. */ |
| 547 | extern 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. */ |
| 552 | extern Dwarf_Die *dwfl_addrdie (Dwfl *dwfl, Dwarf_Addr addr, Dwarf_Addr *bias) |
| 553 | __nonnull_attribute__ (3); |
| 554 | extern 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. */ |
| 559 | extern Dwarf_Die *dwfl_nextcu (Dwfl *dwfl, Dwarf_Die *lastcu, Dwarf_Addr *bias) |
| 560 | __nonnull_attribute__ (3); |
| 561 | extern 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. */ |
| 566 | extern Dwfl_Module *dwfl_cumodule (Dwarf_Die *cudie); |
| 567 | |
| 568 | |
| 569 | /* Cache the source line information fo the CU and return the |
| 570 | number of Dwfl_Line entries it has. */ |
| 571 | extern int dwfl_getsrclines (Dwarf_Die *cudie, size_t *nlines); |
| 572 | |
| 573 | /* Access one line number entry within the CU. */ |
| 574 | extern Dwfl_Line *dwfl_onesrcline (Dwarf_Die *cudie, size_t idx); |
| 575 | |
| 576 | /* Get source for address. */ |
| 577 | extern Dwfl_Line *dwfl_module_getsrc (Dwfl_Module *mod, Dwarf_Addr addr); |
| 578 | extern Dwfl_Line *dwfl_getsrc (Dwfl *dwfl, Dwarf_Addr addr); |
| 579 | |
| 580 | /* Get address for source. */ |
| 581 | extern 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. */ |
| 586 | extern Dwfl_Module *dwfl_linemodule (Dwfl_Line *line); |
| 587 | |
| 588 | /* Return the CU containing this line record. */ |
| 589 | extern 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. */ |
| 593 | extern 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. */ |
| 598 | extern 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. */ |
| 601 | extern 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. */ |
| 614 | extern 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. */ |
| 624 | extern 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. */ |
| 644 | extern Dwarf_CFI *dwfl_module_dwarf_cfi (Dwfl_Module *mod, Dwarf_Addr *bias); |
| 645 | extern Dwarf_CFI *dwfl_module_eh_cfi (Dwfl_Module *mod, Dwarf_Addr *bias); |
| 646 | |
| 647 | |
Elliott Hughes | 0333382 | 2015-02-18 22:19:45 -0800 | [diff] [blame^] | 648 | typedef 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. */ |
| 712 | bool 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. */ |
| 720 | extern 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. */ |
| 731 | extern 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. */ |
| 736 | pid_t dwfl_pid (Dwfl *dwfl) |
| 737 | __nonnull_attribute__ (1); |
| 738 | |
| 739 | /* Return DWFL from which THREAD was created using dwfl_getthreads. */ |
| 740 | Dwfl *dwfl_thread_dwfl (Dwfl_Thread *thread) |
| 741 | __nonnull_attribute__ (1); |
| 742 | |
| 743 | /* Return positive TID (thread ID) for THREAD. This function never fails. */ |
| 744 | pid_t dwfl_thread_tid (Dwfl_Thread *thread) |
| 745 | __nonnull_attribute__ (1); |
| 746 | |
| 747 | /* Return thread for frame STATE. This function never fails. */ |
| 748 | Dwfl_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. */ |
| 755 | bool 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. */ |
| 763 | void 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. */ |
| 771 | int 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. */ |
| 785 | int 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 (). */ |
| 795 | int 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 substract 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. */ |
| 805 | bool dwfl_frame_pc (Dwfl_Frame *state, Dwarf_Addr *pc, bool *isactivation) |
| 806 | __nonnull_attribute__ (1, 2); |
| 807 | |
Ben Cheng | 25b3c04 | 2013-11-20 14:45:36 -0800 | [diff] [blame] | 808 | #ifdef __cplusplus |
| 809 | } |
| 810 | #endif |
| 811 | |
| 812 | #endif /* libdwfl.h */ |