Compilation Unit (CU) Access

Functions
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). More...
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) More...
int	dwarf_siblingof_c (Dwarf_Die dw_die, Dwarf_Die *dw_return_siblingdie, Dwarf_Error *dw_error)
	Return the next sibling DIE. 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)
	Return the first DIE or the next sibling DIE. 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)
	Return some CU-relative facts. More...
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. 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)
	Return a CU DIE given a has signature. 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)
	Return 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)
	Return a DIE given a Dwarf_Sig8 hash. More...
Dwarf_Bool	dwarf_get_die_infotypes_flag (Dwarf_Die dw_die)
	Return the is_info flag. More...

Detailed Description

Function Documentation

dwarf_next_cu_header_e()

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
	)

New in v0.9.0 November 2023.

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

It returns the CU_DIE pointer through dw_cu_die;

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_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
	)

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

This version will eventually be deprecated.

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

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 here.

dwarf_siblingof_c()

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

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

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
	)

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_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
	)

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_child()

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

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_dealloc_die()

void dwarf_dealloc_die

(

Dwarf_Die

dw_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()

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
	)

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_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
	)

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_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
	)

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()

Dwarf_Bool dwarf_get_die_infotypes_flag

(

Dwarf_Die

dw_die

)

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.