libdwarf
Functions
CU Data-Compilation Unit (CU) Access

Access to each CU sequentially. More...

Functions

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)
 Returns information on the next CU header. More...
 
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)
 Retrieve the first DIE or the next sibling. More...
 
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)
 Some CU-relative facts. More...
 
int dwarf_child (Dwarf_Die dw_die, Dwarf_Die *dw_return_childdie, Dwarf_Error *dw_error)
 Get the child DIE, if any. The child may be the first of a list of sibling DIEs. More...
 
void dwarf_dealloc_die (Dwarf_Die dw_die)
 Deallocate (free) a DIE. More...
 
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)
 Given a has signature, retrieve the applicable CU die. More...
 
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)
 Finding die given global (not CU-relative) offset. More...
 
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)
 Retrieves a DIE from a DW_UT_split_type or DW_UT_type CU. More...
 
Dwarf_Bool dwarf_get_die_infotypes_flag (Dwarf_Die dw_die)
 Returns the is_info flag. More...
 

Detailed Description

Access to each CU sequentially.

Function Documentation

◆ dwarf_next_cu_header_d()

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 
)

Returns information on the next CU header.

The library keeps track of where it is in the object file and it knows where to find 'next'.

Parameters
dw_dbgThe Dwarf_Debug of interest.
dw_is_infoPass in TRUE if reading through .debug_info Pass in FALSE if reading through DWARF4 .debug_types.
dw_cu_header_lengthReturns the length of the just-read CU header.
dw_version_stampReturns the version number (2 to 5) of the CU header just read.
dw_abbrev_offsetReturns the .debug_abbrev offset from the the CU header just read.
dw_address_sizeReturns the address size specified for this CU, usually either 4 or 8.
dw_length_sizeReturns the offset size (the length of the size field from the header) specified for this CU, either 4 or 4.
dw_extension_sizeIf the section is standard 64bit DWARF then this value is 4. Else the value is zero.
dw_type_signatureIf 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_typeoffsetFor DW_UT_split_type or DW_UT_type this is the type offset from the CU header.
dw_next_cu_header_offsetThe offset in the section of the next CU (unless there is a compiler bug this is rarely of interest).
dw_header_cu_typeReturns DW_UT_compile, or other DW_UT value.
dw_errorIn 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.

◆ dwarf_siblingof_b()

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 
)

Retrieve the first DIE or the next sibling.

Parameters
dw_dbgThe Dwarf_Debug one is operating on.
dw_dieImmediately 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_infoPass TRUE or FALSE to match the applicable dwarf_next_cu_header_d call.
dw_return_siblingdieThe DIE returned through the pointer.
dw_errorThe usual error information, if any.
Returns
Returns DW_DLV_OK etc.
See also
Example dwarf_siblingofb call
dwarf_get_die_infotypes

◆ dwarf_cu_header_basics()

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 
)

Some CU-relative facts.

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

Parameters
dw_dieSome open Dwarf_Die.
dw_versionReturns the DWARF version: 2,3,4, or 5
dw_is_infoReturns non-zero if the CU is .debug_info. Returns zero if the CU is .debug_types (DWARF4).
dw_is_dwoReturns ton-zero if the CU is a dwo/dwp object and zero if it is a standard object.
dw_offset_sizeReturns offset size, 4 and 8 are possible.
dw_address_sizeAlmost always returns 4 or 8. Could be 2 in unusual circumstances.
dw_extension_sizeThe 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_signatureReturns a pointer to an 8 byte signature.
dw_offset_of_lengthReturns the section offset of the initial byte of the CU.
dw_total_byte_lengthReturns the total length of the CU including the length field and the content of the CU.
dw_errorThe usual Dwarf_Error*.
Returns
Returns DW_DLV_OK etc.

◆ dwarf_child()

int dwarf_child ( Dwarf_Die  dw_die,
Dwarf_Die dw_return_childdie,
Dwarf_Error dw_error 
)

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

Parameters
dw_dieWe will return the first child of this DIE.
dw_return_childdieReturns the first child through the pointer. For subsequent dies siblings of the first, use dwarf_siblingof_b().
dw_errorThe usual Dwarf_Error*.
Returns
Returns DW_DLV_OK etc. Returns DW_DLV_NO_ENTRY if dw_die has no children.
See also
Example dwarf_child call

◆ dwarf_dealloc_die()

void dwarf_dealloc_die ( Dwarf_Die  dw_die)

Deallocate (free) a DIE.

Parameters
dw_dieFrees (deallocs) memory associated with this Dwarf_Die.

◆ dwarf_die_from_hash_signature()

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 
)

Given a has signature, retrieve the applicable CU die.

Parameters
dw_dbg
dw_hash_sigA pointer to an 8 byte signature to be looked up. in .debug_names.
dw_sig_typeValid type requests are "cu" and "tu"
dw_returned_CU_dieReturns the found CU DIE if one is found.
dw_errorThe 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_offdie_b()

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 
)

Finding 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_dbgThe applicable Dwarf_Debug
dw_offsetThe global offset of the DIE in the appropriate section.
dw_is_infoPass TRUE if the target is .debug_info, else pass FALSE if the target is .debug_types.
dw_return_dieOn success this returns a DIE pointer to the found DIE.
dw_errorThe 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
Example dwarf_offdie_b call

◆ dwarf_find_die_given_sig8()

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 
)

Retrieves a DIE from a DW_UT_split_type or DW_UT_type CU.

returns DIE and is_info flag if it finds the referenced DW_UT_split_type or DW_UT_type CU.

Parameters
dw_dbgThe applicable Dwarf_Debug
dw_refA pointer to a Dwarf_Sig8 struct whose content defines what is being searched for.
dw_die_outIf found, this returns the found DIE itself.
dw_is_infoIf found, this returns section (.debug_is_info or .debug_is_types).
dw_errorThe usual error detail return pointer.
Returns
Returns DW_DLV_OK etc.

◆ dwarf_get_die_infotypes_flag()

Dwarf_Bool dwarf_get_die_infotypes_flag ( Dwarf_Die  dw_die)

Returns the is_info flag.

So client software knows if a DIE is in debug_info or debug_types.

Parameters
dw_dieThe 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.