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