Branch data Line data Source code
1 : : /* Interfaces for libdw.
2 : : Copyright (C) 2002-2010 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 _LIBDW_H
30 : : #define _LIBDW_H 1
31 : :
32 : : #include <gelf.h>
33 : : #include <stdbool.h>
34 : : #include <stddef.h>
35 : :
36 : :
37 : : #if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 3)
38 : : # define __nonnull_attribute__(...) __attribute__ ((__nonnull__ (__VA_ARGS__)))
39 : : # define __deprecated_attribute__ __attribute__ ((__deprecated__))
40 : : #else
41 : : # define __nonnull_attribute__(args...)
42 : : # define __deprecated_attribute__
43 : : #endif
44 : :
45 : :
46 : : #ifdef __GNUC_STDC_INLINE__
47 : : # define __libdw_extern_inline extern __inline __attribute__ ((__gnu_inline__))
48 : : #else
49 : : # define __libdw_extern_inline extern __inline
50 : : #endif
51 : :
52 : :
53 : : /* Mode for the session. */
54 : : typedef enum
55 : : {
56 : : DWARF_C_READ, /* Read .. */
57 : : DWARF_C_RDWR, /* Read and write .. */
58 : : DWARF_C_WRITE, /* Write .. */
59 : : }
60 : : Dwarf_Cmd;
61 : :
62 : :
63 : : /* Callback results. */
64 : : enum
65 : : {
66 : : DWARF_CB_OK = 0,
67 : : DWARF_CB_ABORT
68 : : };
69 : :
70 : :
71 : : /* Error values. */
72 : : enum
73 : : {
74 : : DW_TAG_invalid = 0
75 : : #define DW_TAG_invalid DW_TAG_invalid
76 : : };
77 : :
78 : :
79 : : /* Type for offset in DWARF file. */
80 : : typedef GElf_Off Dwarf_Off;
81 : :
82 : : /* Type for address in DWARF file. */
83 : : typedef GElf_Addr Dwarf_Addr;
84 : :
85 : : /* Integer types. Big enough to hold any numeric value. */
86 : : typedef GElf_Xword Dwarf_Word;
87 : : typedef GElf_Sxword Dwarf_Sword;
88 : : /* For the times we know we do not need that much. */
89 : : typedef GElf_Half Dwarf_Half;
90 : :
91 : :
92 : : /* DWARF abbreviation record. */
93 : : typedef struct Dwarf_Abbrev Dwarf_Abbrev;
94 : :
95 : : /* Returned to show the last DIE has be returned. */
96 : : #define DWARF_END_ABBREV ((Dwarf_Abbrev *) -1l)
97 : :
98 : : /* Source code line information for CU. */
99 : : typedef struct Dwarf_Lines_s Dwarf_Lines;
100 : :
101 : : /* One source code line information. */
102 : : typedef struct Dwarf_Line_s Dwarf_Line;
103 : :
104 : : /* Source file information. */
105 : : typedef struct Dwarf_Files_s Dwarf_Files;
106 : :
107 : : /* One address range record. */
108 : : typedef struct Dwarf_Arange_s Dwarf_Arange;
109 : :
110 : : /* Address ranges of a file. */
111 : : typedef struct Dwarf_Aranges_s Dwarf_Aranges;
112 : :
113 : : /* CU representation. */
114 : : struct Dwarf_CU;
115 : :
116 : : /* Macro information. */
117 : : typedef struct Dwarf_Macro_s Dwarf_Macro;
118 : :
119 : : /* Attribute representation. */
120 : : typedef struct
121 : : {
122 : : unsigned int code;
123 : : unsigned int form;
124 : : unsigned char *valp;
125 : : struct Dwarf_CU *cu;
126 : : } Dwarf_Attribute;
127 : :
128 : :
129 : : /* Data block representation. */
130 : : typedef struct
131 : : {
132 : : Dwarf_Word length;
133 : : unsigned char *data;
134 : : } Dwarf_Block;
135 : :
136 : :
137 : : /* DIE information. */
138 : : typedef struct
139 : : {
140 : : /* The offset can be computed from the address. */
141 : : void *addr;
142 : : struct Dwarf_CU *cu;
143 : : Dwarf_Abbrev *abbrev;
144 : : // XXX We'll see what other information will be needed.
145 : : long int padding__;
146 : : } Dwarf_Die;
147 : :
148 : : /* Returned to show the last DIE has be returned. */
149 : : #define DWARF_END_DIE ((Dwarf_Die *) -1l)
150 : :
151 : :
152 : : /* Global symbol information. */
153 : : typedef struct
154 : : {
155 : : Dwarf_Off cu_offset;
156 : : Dwarf_Off die_offset;
157 : : const char *name;
158 : : } Dwarf_Global;
159 : :
160 : :
161 : : /* One operation in a DWARF location expression.
162 : : A location expression is an array of these. */
163 : : typedef struct
164 : : {
165 : : uint8_t atom; /* Operation */
166 : : Dwarf_Word number; /* Operand */
167 : : Dwarf_Word number2; /* Possible second operand */
168 : : Dwarf_Word offset; /* Offset in location expression */
169 : : } Dwarf_Op;
170 : :
171 : :
172 : : /* This describes one Common Information Entry read from a CFI section.
173 : : Pointers here point into the DATA->d_buf block passed to dwarf_next_cfi. */
174 : : typedef struct
175 : : {
176 : : Dwarf_Off CIE_id; /* Always DW_CIE_ID_64 in Dwarf_CIE structures. */
177 : :
178 : : /* Instruction stream describing initial state used by FDEs. If
179 : : we did not understand the whole augmentation string and it did
180 : : not use 'z', then there might be more augmentation data here
181 : : (and in FDEs) before the actual instructions. */
182 : : const uint8_t *initial_instructions;
183 : : const uint8_t *initial_instructions_end;
184 : :
185 : : Dwarf_Word code_alignment_factor;
186 : : Dwarf_Sword data_alignment_factor;
187 : : Dwarf_Word return_address_register;
188 : :
189 : : const char *augmentation; /* Augmentation string. */
190 : :
191 : : /* Augmentation data, might be NULL. The size is correct only if
192 : : we understood the augmentation string sufficiently. */
193 : : const uint8_t *augmentation_data;
194 : : size_t augmentation_data_size;
195 : : size_t fde_augmentation_data_size;
196 : : } Dwarf_CIE;
197 : :
198 : : /* This describes one Frame Description Entry read from a CFI section.
199 : : Pointers here point into the DATA->d_buf block passed to dwarf_next_cfi. */
200 : : typedef struct
201 : : {
202 : : /* Section offset of CIE this FDE refers to. This will never be
203 : : DW_CIE_ID_64 in an FDE. If this value is DW_CIE_ID_64, this is
204 : : actually a Dwarf_CIE structure. */
205 : : Dwarf_Off CIE_pointer;
206 : :
207 : : /* We can't really decode anything further without looking up the CIE
208 : : and checking its augmentation string. Here follows the encoded
209 : : initial_location and address_range, then any augmentation data,
210 : : then the instruction stream. This FDE describes PC locations in
211 : : the byte range [initial_location, initial_location+address_range).
212 : : When the CIE augmentation string uses 'z', the augmentation data is
213 : : a DW_FORM_block (self-sized). Otherwise, when we understand the
214 : : augmentation string completely, fde_augmentation_data_size gives
215 : : the number of bytes of augmentation data before the instructions. */
216 : : const uint8_t *start;
217 : : const uint8_t *end;
218 : : } Dwarf_FDE;
219 : :
220 : : /* Each entry in a CFI section is either a CIE described by Dwarf_CIE or
221 : : an FDE described by Dward_FDE. Check CIE_id to see which you have. */
222 : : typedef union
223 : : {
224 : : Dwarf_Off CIE_id; /* Always DW_CIE_ID_64 in Dwarf_CIE structures. */
225 : : Dwarf_CIE cie;
226 : : Dwarf_FDE fde;
227 : : } Dwarf_CFI_Entry;
228 : :
229 : : #define dwarf_cfi_cie_p(entry) ((entry)->cie.CIE_id == DW_CIE_ID_64)
230 : :
231 : : /* Opaque type representing a frame state described by CFI. */
232 : : typedef struct Dwarf_Frame_s Dwarf_Frame;
233 : :
234 : : /* Opaque type representing a CFI section found in a DWARF or ELF file. */
235 : : typedef struct Dwarf_CFI_s Dwarf_CFI;
236 : :
237 : :
238 : : /* Handle for debug sessions. */
239 : : typedef struct Dwarf Dwarf;
240 : :
241 : :
242 : : /* Out-Of-Memory handler. */
243 : : #if __GNUC__ < 4
244 : : typedef void (*Dwarf_OOM) (void);
245 : : #else
246 : : typedef void (*__attribute__ ((noreturn)) Dwarf_OOM) (void);
247 : : #endif
248 : :
249 : :
250 : : #ifdef __cplusplus
251 : : extern "C" {
252 : : #endif
253 : :
254 : : /* Create a handle for a new debug session. */
255 : : extern Dwarf *dwarf_begin (int fildes, Dwarf_Cmd cmd);
256 : :
257 : : /* Create a handle for a new debug session for an ELF file. */
258 : : extern Dwarf *dwarf_begin_elf (Elf *elf, Dwarf_Cmd cmd, Elf_Scn *scngrp);
259 : :
260 : : /* Retrieve ELF descriptor used for DWARF access. */
261 : : extern Elf *dwarf_getelf (Dwarf *dwarf);
262 : :
263 : : /* Release debugging handling context. */
264 : : extern int dwarf_end (Dwarf *dwarf);
265 : :
266 : :
267 : : /* Get the data block for the .debug_info section. */
268 : : extern Elf_Data *dwarf_getscn_info (Dwarf *dwarf);
269 : :
270 : : /* Read the header for the DWARF CU. */
271 : : extern int dwarf_nextcu (Dwarf *dwarf, Dwarf_Off off, Dwarf_Off *next_off,
272 : : size_t *header_sizep, Dwarf_Off *abbrev_offsetp,
273 : : uint8_t *address_sizep, uint8_t *offset_sizep)
274 : : __nonnull_attribute__ (3);
275 : :
276 : : /* Read the header of a DWARF CU or type unit. If TYPE_SIGNATUREP is not
277 : : null, this reads a type unit from the .debug_types section; otherwise
278 : : this reads a CU from the .debug_info section. */
279 : : extern int dwarf_next_unit (Dwarf *dwarf, Dwarf_Off off, Dwarf_Off *next_off,
280 : : size_t *header_sizep, Dwarf_Half *versionp,
281 : : Dwarf_Off *abbrev_offsetp,
282 : : uint8_t *address_sizep, uint8_t *offset_sizep,
283 : : uint64_t *type_signaturep, Dwarf_Off *type_offsetp)
284 : : __nonnull_attribute__ (3);
285 : :
286 : :
287 : : /* Decode one DWARF CFI entry (CIE or FDE) from the raw section data.
288 : : The E_IDENT from the originating ELF file indicates the address
289 : : size and byte order used in the CFI section contained in DATA;
290 : : EH_FRAME_P should be true for .eh_frame format and false for
291 : : .debug_frame format. OFFSET is the byte position in the section
292 : : to start at; on return *NEXT_OFFSET is filled in with the byte
293 : : position immediately after this entry.
294 : :
295 : : On success, returns 0 and fills in *ENTRY; use dwarf_cfi_cie_p to
296 : : see whether ENTRY->cie or ENTRY->fde is valid.
297 : :
298 : : On errors, returns -1. Some format errors will permit safely
299 : : skipping to the next CFI entry though the current one is unusable.
300 : : In that case, *NEXT_OFF will be updated before a -1 return.
301 : :
302 : : If there are no more CFI entries left in the section,
303 : : returns 1 and sets *NEXT_OFFSET to (Dwarf_Off) -1. */
304 : : extern int dwarf_next_cfi (const unsigned char e_ident[],
305 : : Elf_Data *data, bool eh_frame_p,
306 : : Dwarf_Off offset, Dwarf_Off *next_offset,
307 : : Dwarf_CFI_Entry *entry)
308 : : __nonnull_attribute__ (1, 2, 5, 6);
309 : :
310 : : /* Use the CFI in the DWARF .debug_frame section.
311 : : Returns NULL if there is no such section (not an error).
312 : : The pointer returned can be used until dwarf_end is called on DWARF,
313 : : and must not be passed to dwarf_cfi_end.
314 : : Calling this more than once returns the same pointer. */
315 : : extern Dwarf_CFI *dwarf_getcfi (Dwarf *dwarf);
316 : :
317 : : /* Use the CFI in the ELF file's exception-handling data.
318 : : Returns NULL if there is no such data.
319 : : The pointer returned can be used until elf_end is called on ELF,
320 : : and must be passed to dwarf_cfi_end before then.
321 : : Calling this more than once allocates independent data structures. */
322 : : extern Dwarf_CFI *dwarf_getcfi_elf (Elf *elf);
323 : :
324 : : /* Release resources allocated by dwarf_getcfi_elf. */
325 : : extern int dwarf_cfi_end (Dwarf_CFI *cache);
326 : :
327 : :
328 : : /* Return DIE at given offset in .debug_info section. */
329 : : extern Dwarf_Die *dwarf_offdie (Dwarf *dbg, Dwarf_Off offset,
330 : : Dwarf_Die *result) __nonnull_attribute__ (3);
331 : :
332 : : /* Return DIE at given offset in .debug_types section. */
333 : : extern Dwarf_Die *dwarf_offdie_types (Dwarf *dbg, Dwarf_Off offset,
334 : : Dwarf_Die *result)
335 : : __nonnull_attribute__ (3);
336 : :
337 : : /* Return offset of DIE. */
338 : : extern Dwarf_Off dwarf_dieoffset (Dwarf_Die *die);
339 : :
340 : : /* Return offset of DIE in CU. */
341 : : extern Dwarf_Off dwarf_cuoffset (Dwarf_Die *die);
342 : :
343 : : /* Return CU DIE containing given DIE. */
344 : : extern Dwarf_Die *dwarf_diecu (Dwarf_Die *die, Dwarf_Die *result,
345 : : uint8_t *address_sizep, uint8_t *offset_sizep)
346 : : __nonnull_attribute__ (2);
347 : :
348 : : /* Return CU DIE containing given address. */
349 : : extern Dwarf_Die *dwarf_addrdie (Dwarf *dbg, Dwarf_Addr addr,
350 : : Dwarf_Die *result) __nonnull_attribute__ (3);
351 : :
352 : : /* Return child of current DIE. */
353 : : extern int dwarf_child (Dwarf_Die *die, Dwarf_Die *result)
354 : : __nonnull_attribute__ (2);
355 : :
356 : : /* Locates the first sibling of DIE and places it in RESULT.
357 : : Returns 0 if a sibling was found, -1 if something went wrong.
358 : : Returns 1 if no sibling could be found and, if RESULT is not
359 : : the same as DIE, it sets RESULT->addr to the address of the
360 : : (non-sibling) DIE that follows this one, or NULL if this DIE
361 : : was the last one in the compilation unit. */
362 : : extern int dwarf_siblingof (Dwarf_Die *die, Dwarf_Die *result)
363 : : __nonnull_attribute__ (2);
364 : :
365 : : /* Check whether the DIE has children. */
366 : : extern int dwarf_haschildren (Dwarf_Die *die) __nonnull_attribute__ (1);
367 : :
368 : : /* Walks the attributes of DIE, starting at the one OFFSET bytes in,
369 : : calling the CALLBACK function for each one. Stops if the callback
370 : : function ever returns a value other than DWARF_CB_OK and returns the
371 : : offset of the offending attribute. If the end of the attributes
372 : : is reached 1 is returned. If something goes wrong -1 is returned and
373 : : the dwarf error number is set. */
374 : : extern ptrdiff_t dwarf_getattrs (Dwarf_Die *die,
375 : : int (*callback) (Dwarf_Attribute *, void *),
376 : : void *arg, ptrdiff_t offset)
377 : : __nonnull_attribute__ (2);
378 : :
379 : : /* Return tag of given DIE. */
380 : : extern int dwarf_tag (Dwarf_Die *die) __nonnull_attribute__ (1);
381 : :
382 : :
383 : : /* Return specific attribute of DIE. */
384 : : extern Dwarf_Attribute *dwarf_attr (Dwarf_Die *die, unsigned int search_name,
385 : : Dwarf_Attribute *result)
386 : : __nonnull_attribute__ (3);
387 : :
388 : : /* Check whether given DIE has specific attribute. */
389 : : extern int dwarf_hasattr (Dwarf_Die *die, unsigned int search_name);
390 : :
391 : : /* These are the same as dwarf_attr and dwarf_hasattr, respectively,
392 : : but they resolve an indirect attribute through DW_AT_abstract_origin. */
393 : : extern Dwarf_Attribute *dwarf_attr_integrate (Dwarf_Die *die,
394 : : unsigned int search_name,
395 : : Dwarf_Attribute *result)
396 : : __nonnull_attribute__ (3);
397 : : extern int dwarf_hasattr_integrate (Dwarf_Die *die, unsigned int search_name);
398 : :
399 : :
400 : :
401 : :
402 : : /* Check whether given attribute has specific form. */
403 : : extern int dwarf_hasform (Dwarf_Attribute *attr, unsigned int search_form);
404 : :
405 : : /* Return attribute code of given attribute. */
406 : : extern unsigned int dwarf_whatattr (Dwarf_Attribute *attr);
407 : :
408 : : /* Return form code of given attribute. */
409 : : extern unsigned int dwarf_whatform (Dwarf_Attribute *attr);
410 : :
411 : :
412 : : /* Return string associated with given attribute. */
413 : : extern const char *dwarf_formstring (Dwarf_Attribute *attrp);
414 : :
415 : : /* Return unsigned constant represented by attribute. */
416 : : extern int dwarf_formudata (Dwarf_Attribute *attr, Dwarf_Word *return_uval)
417 : : __nonnull_attribute__ (2);
418 : :
419 : : /* Return signed constant represented by attribute. */
420 : : extern int dwarf_formsdata (Dwarf_Attribute *attr, Dwarf_Sword *return_uval)
421 : : __nonnull_attribute__ (2);
422 : :
423 : : /* Return address represented by attribute. */
424 : : extern int dwarf_formaddr (Dwarf_Attribute *attr, Dwarf_Addr *return_addr)
425 : : __nonnull_attribute__ (2);
426 : :
427 : : /* This function is deprecated. Always use dwarf_formref_die instead.
428 : : Return reference offset represented by attribute. */
429 : : extern int dwarf_formref (Dwarf_Attribute *attr, Dwarf_Off *return_offset)
430 : : __nonnull_attribute__ (2) __deprecated_attribute__;
431 : :
432 : : /* Look up the DIE in a reference-form attribute. */
433 : : extern Dwarf_Die *dwarf_formref_die (Dwarf_Attribute *attr, Dwarf_Die *die_mem)
434 : : __nonnull_attribute__ (2);
435 : :
436 : : /* Return block represented by attribute. */
437 : : extern int dwarf_formblock (Dwarf_Attribute *attr, Dwarf_Block *return_block)
438 : : __nonnull_attribute__ (2);
439 : :
440 : : /* Return flag represented by attribute. */
441 : : extern int dwarf_formflag (Dwarf_Attribute *attr, bool *return_bool)
442 : : __nonnull_attribute__ (2);
443 : :
444 : :
445 : : /* Simplified attribute value access functions. */
446 : :
447 : : /* Return string in name attribute of DIE. */
448 : : extern const char *dwarf_diename (Dwarf_Die *die);
449 : :
450 : : /* Return high PC attribute of DIE. */
451 : : extern int dwarf_highpc (Dwarf_Die *die, Dwarf_Addr *return_addr)
452 : : __nonnull_attribute__ (2);
453 : :
454 : : /* Return low PC attribute of DIE. */
455 : : extern int dwarf_lowpc (Dwarf_Die *die, Dwarf_Addr *return_addr)
456 : : __nonnull_attribute__ (2);
457 : :
458 : : /* Return entry_pc or low_pc attribute of DIE. */
459 : : extern int dwarf_entrypc (Dwarf_Die *die, Dwarf_Addr *return_addr)
460 : : __nonnull_attribute__ (2);
461 : :
462 : : /* Return 1 if DIE's lowpc/highpc or ranges attributes match the PC address,
463 : : 0 if not, or -1 for errors. */
464 : : extern int dwarf_haspc (Dwarf_Die *die, Dwarf_Addr pc);
465 : :
466 : : /* Enumerate the PC address ranges covered by this DIE, covering all
467 : : addresses where dwarf_haspc returns true. In the first call OFFSET
468 : : should be zero and *BASEP need not be initialized. Returns -1 for
469 : : errors, zero when there are no more address ranges to report, or a
470 : : nonzero OFFSET value to pass to the next call. Each subsequent call
471 : : must preserve *BASEP from the prior call. Successful calls fill in
472 : : *STARTP and *ENDP with a contiguous address range. */
473 : : extern ptrdiff_t dwarf_ranges (Dwarf_Die *die,
474 : : ptrdiff_t offset, Dwarf_Addr *basep,
475 : : Dwarf_Addr *startp, Dwarf_Addr *endp);
476 : :
477 : :
478 : : /* Return byte size attribute of DIE. */
479 : : extern int dwarf_bytesize (Dwarf_Die *die);
480 : :
481 : : /* Return bit size attribute of DIE. */
482 : : extern int dwarf_bitsize (Dwarf_Die *die);
483 : :
484 : : /* Return bit offset attribute of DIE. */
485 : : extern int dwarf_bitoffset (Dwarf_Die *die);
486 : :
487 : : /* Return array order attribute of DIE. */
488 : : extern int dwarf_arrayorder (Dwarf_Die *die);
489 : :
490 : : /* Return source language attribute of DIE. */
491 : : extern int dwarf_srclang (Dwarf_Die *die);
492 : :
493 : :
494 : : /* Get abbreviation at given offset for given DIE. */
495 : : extern Dwarf_Abbrev *dwarf_getabbrev (Dwarf_Die *die, Dwarf_Off offset,
496 : : size_t *lengthp);
497 : :
498 : : /* Get abbreviation at given offset in .debug_abbrev section. */
499 : : extern int dwarf_offabbrev (Dwarf *dbg, Dwarf_Off offset, size_t *lengthp,
500 : : Dwarf_Abbrev *abbrevp)
501 : : __nonnull_attribute__ (4);
502 : :
503 : : /* Get abbreviation code. */
504 : : extern unsigned int dwarf_getabbrevcode (Dwarf_Abbrev *abbrev);
505 : :
506 : : /* Get abbreviation tag. */
507 : : extern unsigned int dwarf_getabbrevtag (Dwarf_Abbrev *abbrev);
508 : :
509 : : /* Return true if abbreviation is children flag set. */
510 : : extern int dwarf_abbrevhaschildren (Dwarf_Abbrev *abbrev);
511 : :
512 : : /* Get number of attributes of abbreviation. */
513 : : extern int dwarf_getattrcnt (Dwarf_Abbrev *abbrev, size_t *attrcntp)
514 : : __nonnull_attribute__ (2);
515 : :
516 : : /* Get specific attribute of abbreviation. */
517 : : extern int dwarf_getabbrevattr (Dwarf_Abbrev *abbrev, size_t idx,
518 : : unsigned int *namep, unsigned int *formp,
519 : : Dwarf_Off *offset);
520 : :
521 : :
522 : : /* Get string from-debug_str section. */
523 : : extern const char *dwarf_getstring (Dwarf *dbg, Dwarf_Off offset,
524 : : size_t *lenp);
525 : :
526 : :
527 : : /* Get public symbol information. */
528 : : extern ptrdiff_t dwarf_getpubnames (Dwarf *dbg,
529 : : int (*callback) (Dwarf *, Dwarf_Global *,
530 : : void *),
531 : : void *arg, ptrdiff_t offset)
532 : : __nonnull_attribute__ (2);
533 : :
534 : :
535 : : /* Get source file information for CU. */
536 : : extern int dwarf_getsrclines (Dwarf_Die *cudie, Dwarf_Lines **lines,
537 : : size_t *nlines) __nonnull_attribute__ (2, 3);
538 : :
539 : : /* Return one of the source lines of the CU. */
540 : : extern Dwarf_Line *dwarf_onesrcline (Dwarf_Lines *lines, size_t idx);
541 : :
542 : : /* Get the file source files used in the CU. */
543 : : extern int dwarf_getsrcfiles (Dwarf_Die *cudie, Dwarf_Files **files,
544 : : size_t *nfiles)
545 : : __nonnull_attribute__ (2);
546 : :
547 : :
548 : : /* Get source for address in CU. */
549 : : extern Dwarf_Line *dwarf_getsrc_die (Dwarf_Die *cudie, Dwarf_Addr addr);
550 : :
551 : : /* Get source for file and line number. */
552 : : extern int dwarf_getsrc_file (Dwarf *dbg, const char *fname, int line, int col,
553 : : Dwarf_Line ***srcsp, size_t *nsrcs)
554 : : __nonnull_attribute__ (2, 5, 6);
555 : :
556 : :
557 : : /* Return line address. */
558 : : extern int dwarf_lineaddr (Dwarf_Line *line, Dwarf_Addr *addrp);
559 : :
560 : : /* Return line VLIW operation index. */
561 : : extern int dwarf_lineop_index (Dwarf_Line *line, unsigned int *op_indexp);
562 : :
563 : : /* Return line number. */
564 : : extern int dwarf_lineno (Dwarf_Line *line, int *linep)
565 : : __nonnull_attribute__ (2);
566 : :
567 : : /* Return column in line. */
568 : : extern int dwarf_linecol (Dwarf_Line *line, int *colp)
569 : : __nonnull_attribute__ (2);
570 : :
571 : : /* Return true if record is for beginning of a statement. */
572 : : extern int dwarf_linebeginstatement (Dwarf_Line *line, bool *flagp)
573 : : __nonnull_attribute__ (2);
574 : :
575 : : /* Return true if record is for end of sequence. */
576 : : extern int dwarf_lineendsequence (Dwarf_Line *line, bool *flagp)
577 : : __nonnull_attribute__ (2);
578 : :
579 : : /* Return true if record is for beginning of a basic block. */
580 : : extern int dwarf_lineblock (Dwarf_Line *line, bool *flagp)
581 : : __nonnull_attribute__ (2);
582 : :
583 : : /* Return true if record is for end of prologue. */
584 : : extern int dwarf_lineprologueend (Dwarf_Line *line, bool *flagp)
585 : : __nonnull_attribute__ (2);
586 : :
587 : : /* Return true if record is for beginning of epilogue. */
588 : : extern int dwarf_lineepiloguebegin (Dwarf_Line *line, bool *flagp)
589 : : __nonnull_attribute__ (2);
590 : :
591 : : /* Return instruction-set architecture in this record. */
592 : : extern int dwarf_lineisa (Dwarf_Line *line, unsigned int *isap)
593 : : __nonnull_attribute__ (2);
594 : :
595 : : /* Return code path discriminator in this record. */
596 : : extern int dwarf_linediscriminator (Dwarf_Line *line, unsigned int *discp)
597 : : __nonnull_attribute__ (2);
598 : :
599 : :
600 : : /* Find line information for address. */
601 : : extern const char *dwarf_linesrc (Dwarf_Line *line,
602 : : Dwarf_Word *mtime, Dwarf_Word *length);
603 : :
604 : : /* Return file information. */
605 : : extern const char *dwarf_filesrc (Dwarf_Files *file, size_t idx,
606 : : Dwarf_Word *mtime, Dwarf_Word *length);
607 : :
608 : : /* Return the directory list used in the file information extracted.
609 : : (*RESULT)[0] is the CU's DW_AT_comp_dir value, and may be null.
610 : : (*RESULT)[0..*NDIRS-1] are the compile-time include directory path
611 : : encoded by the compiler. */
612 : : extern int dwarf_getsrcdirs (Dwarf_Files *files,
613 : : const char *const **result, size_t *ndirs)
614 : : __nonnull_attribute__ (2, 3);
615 : :
616 : :
617 : : /* Return location expression, decoded as a list of operations. */
618 : : extern int dwarf_getlocation (Dwarf_Attribute *attr, Dwarf_Op **expr,
619 : : size_t *exprlen) __nonnull_attribute__ (2, 3);
620 : :
621 : : /* Return location expressions. If the attribute uses a location list,
622 : : ADDRESS selects the relevant location expressions from the list.
623 : : There can be multiple matches, resulting in multiple expressions to
624 : : return. EXPRS and EXPRLENS are parallel arrays of NLOCS slots to
625 : : fill in. Returns the number of locations filled in, or -1 for
626 : : errors. If EXPRS is a null pointer, stores nothing and returns the
627 : : total number of locations. A return value of zero means that the
628 : : location list indicated no value is accessible. */
629 : : extern int dwarf_getlocation_addr (Dwarf_Attribute *attr, Dwarf_Addr address,
630 : : Dwarf_Op **exprs, size_t *exprlens,
631 : : size_t nlocs);
632 : :
633 : : /* Return the block associated with a DW_OP_implicit_value operation.
634 : : The OP pointer must point into an expression that dwarf_getlocation
635 : : or dwarf_getlocation_addr has returned given the same ATTR. */
636 : : extern int dwarf_getlocation_implicit_value (Dwarf_Attribute *attr,
637 : : const Dwarf_Op *op,
638 : : Dwarf_Block *return_block)
639 : : __nonnull_attribute__ (2, 3);
640 : :
641 : : /* Return the attribute indicated by a DW_OP_GNU_implicit_pointer operation.
642 : : The OP pointer must point into an expression that dwarf_getlocation
643 : : or dwarf_getlocation_addr has returned given the same ATTR.
644 : : The result is the DW_AT_location or DW_AT_const_value attribute
645 : : of the OP->number DIE. */
646 : : extern int dwarf_getlocation_implicit_pointer (Dwarf_Attribute *attr,
647 : : const Dwarf_Op *op,
648 : : Dwarf_Attribute *result)
649 : : __nonnull_attribute__ (2, 3);
650 : :
651 : :
652 : : /* Compute the byte-size of a type DIE according to DWARF rules.
653 : : For most types, this is just DW_AT_byte_size.
654 : : For DW_TAG_array_type it can apply much more complex rules. */
655 : : extern int dwarf_aggregate_size (Dwarf_Die *die, Dwarf_Word *size);
656 : :
657 : :
658 : : /* Return scope DIEs containing PC address.
659 : : Sets *SCOPES to a malloc'd array of Dwarf_Die structures,
660 : : and returns the number of elements in the array.
661 : : (*SCOPES)[0] is the DIE for the innermost scope containing PC,
662 : : (*SCOPES)[1] is the DIE for the scope containing that scope, and so on.
663 : : Returns -1 for errors or 0 if no scopes match PC. */
664 : : extern int dwarf_getscopes (Dwarf_Die *cudie, Dwarf_Addr pc,
665 : : Dwarf_Die **scopes);
666 : :
667 : : /* Return scope DIEs containing the given DIE.
668 : : Sets *SCOPES to a malloc'd array of Dwarf_Die structures,
669 : : and returns the number of elements in the array.
670 : : (*SCOPES)[0] is a copy of DIE.
671 : : (*SCOPES)[1] is the DIE for the scope containing that scope, and so on.
672 : : Returns -1 for errors or 0 if DIE is not found in any scope entry. */
673 : : extern int dwarf_getscopes_die (Dwarf_Die *die, Dwarf_Die **scopes);
674 : :
675 : :
676 : : /* Search SCOPES[0..NSCOPES-1] for a variable called NAME.
677 : : Ignore the first SKIP_SHADOWS scopes that match the name.
678 : : If MATCH_FILE is not null, accept only declaration in that source file;
679 : : if MATCH_LINENO or MATCH_LINECOL are also nonzero, accept only declaration
680 : : at that line and column.
681 : :
682 : : If successful, fill in *RESULT with the DIE of the variable found,
683 : : and return N where SCOPES[N] is the scope defining the variable.
684 : : Return -1 for errors or -2 for no matching variable found. */
685 : : extern int dwarf_getscopevar (Dwarf_Die *scopes, int nscopes,
686 : : const char *name, int skip_shadows,
687 : : const char *match_file,
688 : : int match_lineno, int match_linecol,
689 : : Dwarf_Die *result);
690 : :
691 : :
692 : :
693 : : /* Return list address ranges. */
694 : : extern int dwarf_getaranges (Dwarf *dbg, Dwarf_Aranges **aranges,
695 : : size_t *naranges)
696 : : __nonnull_attribute__ (2);
697 : :
698 : : /* Return one of the address range entries. */
699 : : extern Dwarf_Arange *dwarf_onearange (Dwarf_Aranges *aranges, size_t idx);
700 : :
701 : : /* Return information in address range record. */
702 : : extern int dwarf_getarangeinfo (Dwarf_Arange *arange, Dwarf_Addr *addrp,
703 : : Dwarf_Word *lengthp, Dwarf_Off *offsetp);
704 : :
705 : : /* Get address range which includes given address. */
706 : : extern Dwarf_Arange *dwarf_getarange_addr (Dwarf_Aranges *aranges,
707 : : Dwarf_Addr addr);
708 : :
709 : :
710 : :
711 : : /* Get functions in CUDIE. */
712 : : extern ptrdiff_t dwarf_getfuncs (Dwarf_Die *cudie,
713 : : int (*callback) (Dwarf_Die *, void *),
714 : : void *arg, ptrdiff_t offset);
715 : :
716 : :
717 : : /* Return file name containing definition of the given declaration. */
718 : : extern const char *dwarf_decl_file (Dwarf_Die *decl);
719 : :
720 : : /* Get line number of beginning of given declaration. */
721 : : extern int dwarf_decl_line (Dwarf_Die *decl, int *linep)
722 : : __nonnull_attribute__ (2);
723 : :
724 : : /* Get column number of beginning of given declaration. */
725 : : extern int dwarf_decl_column (Dwarf_Die *decl, int *colp)
726 : : __nonnull_attribute__ (2);
727 : :
728 : :
729 : : /* Return nonzero if given function is an abstract inline definition. */
730 : : extern int dwarf_func_inline (Dwarf_Die *func);
731 : :
732 : : /* Find each concrete inlined instance of the abstract inline definition. */
733 : : extern int dwarf_func_inline_instances (Dwarf_Die *func,
734 : : int (*callback) (Dwarf_Die *, void *),
735 : : void *arg);
736 : :
737 : :
738 : : /* Find the appropriate PC location or locations for function entry
739 : : breakpoints for the given DW_TAG_subprogram DIE. Returns -1 for errors.
740 : : On success, returns the number of breakpoint locations (never zero)
741 : : and sets *BKPTS to a malloc'd vector of addresses. */
742 : : extern int dwarf_entry_breakpoints (Dwarf_Die *die, Dwarf_Addr **bkpts);
743 : :
744 : :
745 : : /* Call callback function for each of the macro information entry for
746 : : the CU. */
747 : : extern ptrdiff_t dwarf_getmacros (Dwarf_Die *cudie,
748 : : int (*callback) (Dwarf_Macro *, void *),
749 : : void *arg, ptrdiff_t offset)
750 : : __nonnull_attribute__ (2);
751 : :
752 : : /* Return macro opcode. */
753 : : extern int dwarf_macro_opcode (Dwarf_Macro *macro, unsigned int *opcodep)
754 : : __nonnull_attribute__ (2);
755 : :
756 : : /* Return first macro parameter. */
757 : : extern int dwarf_macro_param1 (Dwarf_Macro *macro, Dwarf_Word *paramp)
758 : : __nonnull_attribute__ (2);
759 : :
760 : : /* Return second macro parameter. */
761 : : extern int dwarf_macro_param2 (Dwarf_Macro *macro, Dwarf_Word *paramp,
762 : : const char **strp);
763 : :
764 : :
765 : : /* Compute what's known about a call frame when the PC is at ADDRESS.
766 : : Returns 0 for success or -1 for errors.
767 : : On success, *FRAME is a malloc'd pointer. */
768 : : extern int dwarf_cfi_addrframe (Dwarf_CFI *cache,
769 : : Dwarf_Addr address, Dwarf_Frame **frame)
770 : : __nonnull_attribute__ (3);
771 : :
772 : : /* Return the DWARF register number used in FRAME to denote
773 : : the return address in FRAME's caller frame. The remaining
774 : : arguments can be non-null to fill in more information.
775 : :
776 : : Fill [*START, *END) with the PC range to which FRAME's information applies.
777 : : Fill in *SIGNALP to indicate whether this is a signal-handling frame.
778 : : If true, this is the implicit call frame that calls a signal handler.
779 : : This frame's "caller" is actually the interrupted state, not a call;
780 : : its return address is an exact PC, not a PC after a call instruction. */
781 : : extern int dwarf_frame_info (Dwarf_Frame *frame,
782 : : Dwarf_Addr *start, Dwarf_Addr *end, bool *signalp);
783 : :
784 : : /* Return a DWARF expression that yields the Canonical Frame Address at
785 : : this frame state. Returns -1 for errors, or zero for success, with
786 : : *NOPS set to the number of operations stored at *OPS. That pointer
787 : : can be used only as long as FRAME is alive and unchanged. *NOPS is
788 : : zero if the CFA cannot be determined here. Note that if nonempty,
789 : : *OPS is a DWARF expression, not a location description--append
790 : : DW_OP_stack_value to a get a location description for the CFA. */
791 : : extern int dwarf_frame_cfa (Dwarf_Frame *frame, Dwarf_Op **ops, size_t *nops)
792 : : __nonnull_attribute__ (2);
793 : :
794 : : /* Deliver a DWARF location description that yields the location or
795 : : value of DWARF register number REGNO in the state described by FRAME.
796 : :
797 : : Returns -1 for errors or zero for success, setting *NOPS to the
798 : : number of operations in the array stored at *OPS. Note the last
799 : : operation is DW_OP_stack_value if there is no mutable location but
800 : : only a computable value.
801 : :
802 : : *NOPS zero with *OPS set to OPS_MEM means CFI says the caller's
803 : : REGNO is "undefined", i.e. it's call-clobbered and cannot be recovered.
804 : :
805 : : *NOPS zero with *OPS set to a null pointer means CFI says the
806 : : caller's REGNO is "same_value", i.e. this frame did not change it;
807 : : ask the caller frame where to find it.
808 : :
809 : : For common simple expressions *OPS is OPS_MEM. For arbitrary DWARF
810 : : expressions in the CFI, *OPS is an internal pointer that can be used as
811 : : long as the Dwarf_CFI used to create FRAME remains alive. */
812 : : extern int dwarf_frame_register (Dwarf_Frame *frame, int regno,
813 : : Dwarf_Op ops_mem[3],
814 : : Dwarf_Op **ops, size_t *nops)
815 : : __nonnull_attribute__ (3, 4, 5);
816 : :
817 : :
818 : : /* Return error code of last failing function call. This value is kept
819 : : separately for each thread. */
820 : : extern int dwarf_errno (void);
821 : :
822 : : /* Return error string for ERROR. If ERROR is zero, return error string
823 : : for most recent error or NULL is none occurred. If ERROR is -1 the
824 : : behaviour is similar to the last case except that not NULL but a legal
825 : : string is returned. */
826 : : extern const char *dwarf_errmsg (int err);
827 : :
828 : :
829 : : /* Register new Out-Of-Memory handler. The old handler is returned. */
830 : : extern Dwarf_OOM dwarf_new_oom_handler (Dwarf *dbg, Dwarf_OOM handler);
831 : :
832 : :
833 : : /* Inline optimizations. */
834 : : #ifdef __OPTIMIZE__
835 : : /* Return attribute code of given attribute. */
836 : : __libdw_extern_inline unsigned int
837 : : dwarf_whatattr (Dwarf_Attribute *attr)
838 : : {
839 [ + - ]: 2547885 : return attr == NULL ? 0 : attr->code;
840 : : }
841 : :
842 : : /* Return attribute code of given attribute. */
843 : : __libdw_extern_inline unsigned int
844 : : dwarf_whatform (Dwarf_Attribute *attr)
845 : : {
846 [ + - ]: 2547885 : return attr == NULL ? 0 : attr->form;
847 : : }
848 : : #endif /* Optimize. */
849 : :
850 : : #ifdef __cplusplus
851 : : }
852 : : #endif
853 : :
854 : : #endif /* libdw.h */
|
