libdwarf: Compilation Unit (CU) Access

libdwarf

Loading...
Searching...
No Matches
Functions
Compilation Unit (CU) Access

## Functions
DW_API int | dwarf_next_cu_header_e (Dwarf_Debug dw_dbg, Dwarf_Bool dw_is_info, Dwarf_Die *dw_cu_die, Dwarf_Unsigned *dw_cu_header_length, Dwarf_Half *dw_version_stamp, Dwarf_Off *dw_abbrev_offset, Dwarf_Half *dw_address_size, Dwarf_Half *dw_length_size, Dwarf_Half *dw_extension_size, Dwarf_Sig8 *dw_type_signature, Dwarf_Unsigned *dw_typeoffset, Dwarf_Unsigned *dw_next_cu_header_offset, Dwarf_Half *dw_header_cu_type, Dwarf_Error *dw_error)
| Return information on the next CU header(e).
DW_API int | dwarf_next_cu_header_d (Dwarf_Debug dw_dbg, Dwarf_Bool dw_is_info, Dwarf_Unsigned *dw_cu_header_length, Dwarf_Half *dw_version_stamp, Dwarf_Off *dw_abbrev_offset, Dwarf_Half *dw_address_size, Dwarf_Half *dw_length_size, Dwarf_Half *dw_extension_size, Dwarf_Sig8 *dw_type_signature, Dwarf_Unsigned *dw_typeoffset, Dwarf_Unsigned *dw_next_cu_header_offset, Dwarf_Half *dw_header_cu_type, Dwarf_Error *dw_error)
| Return information on the next CU header(d).
DW_API int | dwarf_siblingof_c (Dwarf_Die dw_die, Dwarf_Die *dw_return_siblingdie, Dwarf_Error *dw_error)
| Return the next sibling DIE.
DW_API int | dwarf_siblingof_b (Dwarf_Debug dw_dbg, Dwarf_Die dw_die, Dwarf_Bool dw_is_info, Dwarf_Die *dw_return_siblingdie, Dwarf_Error *dw_error)
| Return the first DIE or the next sibling DIE.
DW_API int | dwarf_cu_header_basics (Dwarf_Die dw_die, Dwarf_Half *dw_version, Dwarf_Bool *dw_is_info, Dwarf_Bool *dw_is_dwo, Dwarf_Half *dw_offset_size, Dwarf_Half *dw_address_size, Dwarf_Half *dw_extension_size, Dwarf_Sig8 **dw_signature, Dwarf_Off *dw_offset_of_length, Dwarf_Unsigned *dw_total_byte_length, Dwarf_Error *dw_error)
| Return some CU-relative facts.
DW_API int | dwarf_child (Dwarf_Die dw_die, Dwarf_Die *dw_return_childdie, Dwarf_Error *dw_error)
| Return the child DIE, if any. The child may be the first of a list of sibling DIEs.
DW_API void | dwarf_dealloc_die (Dwarf_Die dw_die)
| Deallocate (free) a DIE.
DW_API int | dwarf_die_from_hash_signature (Dwarf_Debug dw_dbg, Dwarf_Sig8 *dw_hash_sig, const char *dw_sig_type, Dwarf_Die *dw_returned_CU_die, Dwarf_Error *dw_error)
| Return a CU DIE given a has signature.
DW_API int | dwarf_offdie_b (Dwarf_Debug dw_dbg, Dwarf_Off dw_offset, Dwarf_Bool dw_is_info, Dwarf_Die *dw_return_die, Dwarf_Error *dw_error)
| Return DIE given global (not CU-relative) offset.
DW_API int | dwarf_find_die_given_sig8 (Dwarf_Debug dw_dbg, Dwarf_Sig8 *dw_ref, Dwarf_Die *dw_die_out, Dwarf_Bool *dw_is_info, Dwarf_Error *dw_error)
| Return a DIE given a Dwarf_Sig8 hash.
DW_API Dwarf_Bool | dwarf_get_die_infotypes_flag (Dwarf_Die dw_die)
| Return the is_info flag.

## Detailed Description

## Function Documentation

## ◆ dwarf_child()

DW_API int dwarf_child | ( | Dwarf_Die | dw_die,
|  | Dwarf_Die * | dw_return_childdie,
|  | Dwarf_Error * | dw_error )

Return the child DIE, if any. The child may be the first of a list of sibling DIEs.

Parameters

  dw_die | We will return the first child of this DIE.
  dw_return_childdie | Returns the first child through the pointer. For subsequent dies siblings of the first, use dwarf_siblingof_c().
  dw_error | The usual Dwarf_Error*.

Returns
  Returns DW_DLV_OK etc. Returns DW_DLV_NO_ENTRY if dw_die has no children.

See also
  Using dwarf_child()

## ◆ dwarf_cu_header_basics()

DW_API int dwarf_cu_header_basics | ( | Dwarf_Die | dw_die,
|  | Dwarf_Half * | dw_version,
|  | Dwarf_Bool * | dw_is_info,
|  | Dwarf_Bool * | dw_is_dwo,
|  | Dwarf_Half * | dw_offset_size,
|  | Dwarf_Half * | dw_address_size,
|  | Dwarf_Half * | dw_extension_size,
|  | Dwarf_Sig8 ** | dw_signature,
|  | Dwarf_Off * | dw_offset_of_length,
|  | Dwarf_Unsigned * | dw_total_byte_length,
|  | Dwarf_Error * | dw_error )

Return some CU-relative facts.

Any Dwarf_Die will work. The values returned through the pointers are about the CU for a DIE

Parameters

  dw_die | Some open Dwarf_Die.
  dw_version | Returns the DWARF version: 2,3,4, or 5
  dw_is_info | Returns non-zero if the CU is .debug_info. Returns zero if the CU is .debug_types (DWARF4).
  dw_is_dwo | Returns ton-zero if the CU is a dwo/dwp object and zero if it is a standard object.
  dw_offset_size | Returns offset size, 4 and 8 are possible.
  dw_address_size | Almost always returns 4 or 8. Could be 2 in unusual circumstances.
  dw_extension_size | The sum of dw_offset_size and dw_extension_size are the count of the initial bytes of the CU. Standard lengths are 4 and 12. For 1990's SGI objects the length could be 8.
  dw_signature | Returns a pointer to an 8 byte signature.
  dw_offset_of_length | Returns the section offset of the initial byte of the CU.
  dw_total_byte_length | Returns the total length of the CU including the length field and the content of the CU.
  dw_error | The usual Dwarf_Error*.

Returns
  Returns DW_DLV_OK etc.

## ◆ dwarf_dealloc_die()

DW_API void dwarf_dealloc_die | ( | Dwarf_Die | dw_die | ) |

Deallocate (free) a DIE.

Parameters

  dw_die | Frees (deallocs) memory associated with this Dwarf_Die.

DIEs not freed explicitly will be freed by dwarf_finish().

## ◆ dwarf_die_from_hash_signature()

DW_API int dwarf_die_from_hash_signature | ( | Dwarf_Debug | dw_dbg,
|  | Dwarf_Sig8 * | dw_hash_sig,
|  | const char * | dw_sig_type,
|  | Dwarf_Die * | dw_returned_CU_die,
|  | Dwarf_Error * | dw_error )

Return a CU DIE given a has signature.

Parameters

  dw_dbg |
  dw_hash_sig | A pointer to an 8 byte signature to be looked up. in .debug_names.
  dw_sig_type | Valid type requests are "cu" and "tu"
  dw_returned_CU_die | Returns the found CU DIE if one is found.
  dw_error | The usual Dwarf_Error*.

Returns
  DW_DLV_OK means dw_returned_CU_die was set. DW_DLV_NO_ENTRY means the signature could not be found.

## ◆ dwarf_find_die_given_sig8()

DW_API int dwarf_find_die_given_sig8 | ( | Dwarf_Debug | dw_dbg,
|  | Dwarf_Sig8 * | dw_ref,
|  | Dwarf_Die * | dw_die_out,
|  | Dwarf_Bool * | dw_is_info,
|  | Dwarf_Error * | dw_error )

Return a DIE given a Dwarf_Sig8 hash.

Returns DIE and is_info flag if it finds the hash signature of a DIE. Often will be the CU DIE of DW_UT_split_type or DW_UT_type CU.

Parameters

  dw_dbg | The applicable Dwarf_Debug
  dw_ref | A pointer to a Dwarf_Sig8 struct whose content defines what is being searched for.
  dw_die_out | If found, this returns the found DIE itself.
  dw_is_info | If found, this returns section (.debug_is_info or .debug_is_types).
  dw_error | The usual error detail return pointer.

Returns
  Returns DW_DLV_OK etc.

## ◆ dwarf_get_die_infotypes_flag()

DW_API Dwarf_Bool dwarf_get_die_infotypes_flag | ( | Dwarf_Die | dw_die | ) |

Return the is_info flag.

So client software knows if a DIE is in debug_info or (DWARF4-only) debug_types.

Parameters

  dw_die | The DIE being queried.

Returns
  If non-zero the flag means the DIE is in .debug_info. Otherwise it means the DIE is in .debug_types.

## ◆ dwarf_next_cu_header_d()

DW_API int dwarf_next_cu_header_d | ( | Dwarf_Debug | dw_dbg,
|  | Dwarf_Bool | dw_is_info,
|  | Dwarf_Unsigned * | dw_cu_header_length,
|  | Dwarf_Half * | dw_version_stamp,
|  | Dwarf_Off * | dw_abbrev_offset,
|  | Dwarf_Half * | dw_address_size,
|  | Dwarf_Half * | dw_length_size,
|  | Dwarf_Half * | dw_extension_size,
|  | Dwarf_Sig8 * | dw_type_signature,
|  | Dwarf_Unsigned * | dw_typeoffset,
|  | Dwarf_Unsigned * | dw_next_cu_header_offset,
|  | Dwarf_Half * | dw_header_cu_type,
|  | Dwarf_Error * | dw_error )

Return information on the next CU header(d).

This is the version to use for linking against libdwarf v0.8.0 and earlier (and it also works for later versions).

Replace all uses of dwarf_next_cu_header_d() and use dwarf_next_cu_header_e instead.

Assuming you continue to use dwarf_next_cu_header_d() read the following carefully.

The library keeps track of where it is in the object file following a call to dwarf_next_cu_header_d() and it knows (see next paragraph) how to interpret dwarf_siblingof_b(dw_dbg,NULL,dw_is_info, &cu_die,...).

In order to read the DIE tree of the CU this records information in the dw_dbg data and after a successful call to dwarf_next_cu_header_d() only an immediate call to dwarf_siblingof_b(dw_dbg,NULL,dw_is_info, &cu_die,...) is guaranteed to return the correct DIE (a Compilation Unit DIE).

Avoid any call to libdwarf between a successful call to dwarf_next_cu_header_d() and dwarf_siblingof_b(dw_dbg,NULL,dw_is_info, &cu_die,...) to ensure the intended and correct Dwarf_Die is returned.

See also
  Example walking CUs(d)

All arguments are the same as dwarf_next_cu_header_e() except that there is no dw_cu_die argument in dwarf_next_cu_header_d().

## ◆ dwarf_next_cu_header_e()

DW_API int dwarf_next_cu_header_e | ( | Dwarf_Debug | dw_dbg,
|  | Dwarf_Bool | dw_is_info,
|  | Dwarf_Die * | dw_cu_die,
|  | Dwarf_Unsigned * | dw_cu_header_length,
|  | Dwarf_Half * | dw_version_stamp,
|  | Dwarf_Off * | dw_abbrev_offset,
|  | Dwarf_Half * | dw_address_size,
|  | Dwarf_Half * | dw_length_size,
|  | Dwarf_Half * | dw_extension_size,
|  | Dwarf_Sig8 * | dw_type_signature,
|  | Dwarf_Unsigned * | dw_typeoffset,
|  | Dwarf_Unsigned * | dw_next_cu_header_offset,
|  | Dwarf_Half * | dw_header_cu_type,
|  | Dwarf_Error * | dw_error )

Return information on the next CU header(e).

New in v0.9.0 November 2023.

dwarf_next_cu_header_e() is preferred over dwarf_next_cu_header_d() as the latter requires a second (immediate) step to access the CU-DIE of the CU.

With the CU-DIE returned by dwarf_next_cu_header_e() one calls dwarf_child() first (the CU-DIE has no siblings) and then one calls dwarf_siblingof_c() and dwarf_child() appropriately to descend the tree of DIEs.

Parameters

  dw_dbg | The Dwarf_Debug of interest.
  dw_is_info | Pass in TRUE if reading through .debug_info Pass in FALSE if reading through DWARF4 .debug_types.
  dw_cu_die | Pass in a pointer to a Dwarf_Die. the call sets the passed-in pointer to be a Compilation Unit Die for use with dwarf_child() or any other call requiring a Dwarf_Die argument.
  dw_cu_header_length | Returns the length of the just-read CU header.
  dw_version_stamp | Returns the version number (2 to 5) of the CU header just read.
  dw_abbrev_offset | Returns the .debug_abbrev offset from the the CU header just read.
  dw_address_size | Returns the address size specified for this CU, usually either 4 or 8.
  dw_length_size | Returns the offset size (the length of the size field from the header) specified for this CU, either 4 or 4.
  dw_extension_size | If the section is standard 64bit DWARF then this value is 4. Else the value is zero.
  dw_type_signature | If the CU is DW_UT_skeleton DW_UT_split_compile, DW_UT_split_type or DW_UT_type this is the type signature from the CU_header compiled into this field.
  dw_typeoffset | For DW_UT_split_type or DW_UT_type this is the type offset from the CU header.
  dw_next_cu_header_offset | The offset in the section of the next CU (unless there is a compiler bug this is rarely of interest).
  dw_header_cu_type | Returns DW_UT_compile, or other DW_UT value.
  dw_error | In case return is DW_DLV_ERROR dw_error is set to point to the error details.

Returns
  Returns DW_DLV_OK on success. Returns DW_DLV_NO_ENTRY if all CUs have been read.

See also
  Example walking CUs(e)

## ◆ dwarf_offdie_b()

DW_API int dwarf_offdie_b | ( | Dwarf_Debug | dw_dbg,
|  | Dwarf_Off | dw_offset,
|  | Dwarf_Bool | dw_is_info,
|  | Dwarf_Die * | dw_return_die,
|  | Dwarf_Error * | dw_error )

Return DIE given global (not CU-relative) offset.

This works whether or not the target section has had dwarf_next_cu_header_d() applied, the CU the offset exists in has been seen at all, or the target offset is one libdwarf has seen before.

Parameters

  dw_dbg | The applicable Dwarf_Debug
  dw_offset | The global offset of the DIE in the appropriate section.
  dw_is_info | Pass TRUE if the target is .debug_info. Pass FALSE if the target is .debug_types.
  dw_return_die | On success this returns a DIE pointer to the found DIE.
  dw_error | The usual Dwarf_Error*.

Returns
  DW_DLV_OK means dw_returned_die was found DW_DLV_NO_ENTRY is only possible if the offset is to a null DIE, and that is very unusual. Otherwise expect DW_DLV_ERROR.

See also
  Using dwarf_offdie_b()

## ◆ dwarf_siblingof_b()

DW_API int dwarf_siblingof_b | ( | Dwarf_Debug | dw_dbg,
|  | Dwarf_Die | dw_die,
|  | Dwarf_Bool | dw_is_info,
|  | Dwarf_Die * | dw_return_siblingdie,
|  | Dwarf_Error * | dw_error )

Return the first DIE or the next sibling DIE.

This function follows dwarf_next_cu_header_d() to return the CU-DIE that dwarf_next_cu_header_d() implies but does not reveal.

Aside from the special case required use of dwarf_siblingof_b() immediately following dwarf_next_cu_header_d(), dwarf_siblingof_c() is the faster function.

This function will eventually be deprecated.

Parameters

  dw_dbg | The Dwarf_Debug one is operating on.
  dw_die | Immediately after calling dwarf_next_cu_header_d pass in NULL to retrieve the CU DIE. Or pass in a known DIE and this will retrieve the next sibling in the chain.
  dw_is_info | Pass TRUE or FALSE to match the applicable dwarf_next_cu_header_d call.
  dw_return_siblingdie | The DIE returned through the pointer.
  dw_error | The usual error information, if any.

Returns
  Returns DW_DLV_OK etc.

See also
  example4
  dwarf_get_die_infotypes

## ◆ dwarf_siblingof_c()

DW_API int dwarf_siblingof_c | ( | Dwarf_Die | dw_die,
|  | Dwarf_Die * | dw_return_siblingdie,
|  | Dwarf_Error * | dw_error )

Return the next sibling DIE.

Parameters

  dw_die | Pass in a known DIE and this will retrieve the next sibling in the chain.
  dw_return_siblingdie | The DIE returned through the pointer.
  dw_error | The usual error information, if any.

Returns
  Returns DW_DLV_OK etc.

See also
  example4
  dwarf_get_die_infotypes