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

Functions

Detailed Description

Function Documentation

◆ dwarf_child()

◆ dwarf_cu_header_basics()

◆ dwarf_dealloc_die()

◆ dwarf_die_from_hash_signature()

◆ dwarf_find_die_given_sig8()

◆ dwarf_get_die_infotypes_flag()

◆ dwarf_next_cu_header_d()

◆ dwarf_next_cu_header_e()

◆ dwarf_offdie_b()

◆ dwarf_siblingof_b()

◆ dwarf_siblingof_c()