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