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