libdwarf
Functions
CU Data-Debugging Information Entry Access

This is the main interface to attributes of a DIE. More...

Functions

int dwarf_die_abbrev_global_offset (Dwarf_Die dw_die, Dwarf_Off *dw_abbrev_offset, Dwarf_Unsigned *dw_abbrev_count, Dwarf_Error *dw_error)
 Returns the abbrev section offset of a DIE's abbrevs. More...
 
int dwarf_tag (Dwarf_Die dw_die, Dwarf_Half *dw_return_tag, Dwarf_Error *dw_error)
 Get TAG value of DIE. More...
 
int dwarf_dieoffset (Dwarf_Die dw_die, Dwarf_Off *dw_return_offset, Dwarf_Error *dw_error)
 Returns the global section offset of the DIE. More...
 
int dwarf_debug_addr_index_to_addr (Dwarf_Die dw_die, Dwarf_Unsigned dw_index, Dwarf_Addr *dw_return_addr, Dwarf_Error *dw_error)
 Extract address given address index. DWARF5. More...
 
Dwarf_Bool dwarf_addr_form_is_indexed (int dw_form)
 Informs if a DW_FORM is an indexed form. More...
 
int dwarf_CU_dieoffset_given_die (Dwarf_Die dw_die, Dwarf_Off *dw_return_offset, Dwarf_Error *dw_error)
 Returns the CU DIE offset given any DIE. More...
 
int dwarf_get_cu_die_offset_given_cu_header_offset_b (Dwarf_Debug dw_dbg, Dwarf_Off dw_in_cu_header_offset, Dwarf_Bool dw_is_info, Dwarf_Off *dw_out_cu_die_offset, Dwarf_Error *dw_error)
 Returns the CU DIE section offset given CU header offset. More...
 
int dwarf_die_CU_offset (Dwarf_Die dw_die, Dwarf_Off *dw_return_offset, Dwarf_Error *dw_error)
 returns the CU relative offset of the DIE. More...
 
int dwarf_die_CU_offset_range (Dwarf_Die dw_die, Dwarf_Off *dw_return_CU_header_offset, Dwarf_Off *dw_return_CU_length_bytes, Dwarf_Error *dw_error)
 Returns the offset length of the entire CU of a DIE. More...
 
int dwarf_attr (Dwarf_Die dw_die, Dwarf_Half dw_attrnum, Dwarf_Attribute *dw_returned_attr, Dwarf_Error *dw_error)
 Given DIE and attribute number return a Dwarf_attribute. More...
 
int dwarf_die_text (Dwarf_Die dw_die, Dwarf_Half dw_attrnum, char **dw_ret_name, Dwarf_Error *dw_error)
 Given DIE and attribute number return a string. More...
 
int dwarf_diename (Dwarf_Die dw_die, char **dw_diename, Dwarf_Error *dw_error)
 Return the string from a DW_AT_name attribute. More...
 
int dwarf_die_abbrev_code (Dwarf_Die dw_die)
 Return the DIE abbrev code. More...
 
int dwarf_die_abbrev_children_flag (Dwarf_Die dw_die, Dwarf_Half *dw_ab_has_child)
 Returns TRUE if the DIE has children. More...
 
int dwarf_validate_die_sibling (Dwarf_Die dw_sibling, Dwarf_Off *dw_offset)
 Validate a sibling DIE. More...
 
int dwarf_hasattr (Dwarf_Die dw_die, Dwarf_Half dw_attrnum, Dwarf_Bool *dw_returned_bool, Dwarf_Error *dw_error)
 Tells whether a DIE has a particular attribute. More...
 
int dwarf_offset_list (Dwarf_Debug dw_dbg, Dwarf_Off dw_offset, Dwarf_Bool dw_is_info, Dwarf_Off **dw_offbuf, Dwarf_Unsigned *dw_offcount, Dwarf_Error *dw_error)
 Returns an array of DIE children offsets. More...
 
int dwarf_get_die_address_size (Dwarf_Die dw_die, Dwarf_Half *dw_addr_size, Dwarf_Error *dw_error)
 Get the address size applying to a DIE. More...
 
int dwarf_die_offsets (Dwarf_Die dw_die, Dwarf_Off *dw_global_offset, Dwarf_Off *dw_local_offset, Dwarf_Error *dw_error)
 Return section and CU-local offsets of a DIE. More...
 
int dwarf_get_version_of_die (Dwarf_Die dw_die, Dwarf_Half *dw_version, Dwarf_Half *dw_offset_size)
 Get the version and offset size. More...
 
int dwarf_lowpc (Dwarf_Die dw_die, Dwarf_Addr *dw_returned_addr, Dwarf_Error *dw_error)
 Returns the DW_AT_low_pc value. More...
 
int dwarf_highpc_b (Dwarf_Die dw_die, Dwarf_Addr *dw_return_addr, Dwarf_Half *dw_return_form, enum Dwarf_Form_Class *dw_return_class, Dwarf_Error *dw_error)
 Returns the DW_AT_hipc address value. More...
 
int dwarf_dietype_offset (Dwarf_Die dw_die, Dwarf_Off *dw_return_offset, Dwarf_Error *dw_error)
 Returns the offset from the DW_AT_type attribute. More...
 
int dwarf_bytesize (Dwarf_Die dw_die, Dwarf_Unsigned *dw_returned_size, Dwarf_Error *dw_error)
 Returns the value of the attribute DW_AT_byte_size. More...
 
int dwarf_bitsize (Dwarf_Die dw_die, Dwarf_Unsigned *dw_returned_size, Dwarf_Error *dw_error)
 Returns the value of the attribute DW_AT_bitsize. More...
 
int dwarf_bitoffset (Dwarf_Die dw_die, Dwarf_Half *dw_attrnum, Dwarf_Unsigned *dw_returned_offset, Dwarf_Error *dw_error)
 Returns the bit offset attribute of a DIE. More...
 
int dwarf_srclang (Dwarf_Die dw_die, Dwarf_Unsigned *dw_returned_lang, Dwarf_Error *dw_error)
 Returns the value of the DW_AT_language attribute. More...
 
int dwarf_arrayorder (Dwarf_Die dw_die, Dwarf_Unsigned *dw_returned_order, Dwarf_Error *dw_error)
 Returns the value of the DW_AT_ordering attribute. More...
 

Detailed Description

This is the main interface to attributes of a DIE.

Function Documentation

◆ dwarf_die_abbrev_global_offset()

int dwarf_die_abbrev_global_offset ( Dwarf_Die  dw_die,
Dwarf_Off dw_abbrev_offset,
Dwarf_Unsigned dw_abbrev_count,
Dwarf_Error dw_error 
)

Returns the abbrev section offset of a DIE's abbrevs.

So we can associate a DIE's abbreviations with the contents the abbreviations section. Useful for detailed printing and analysis of abbreviations

Parameters
dw_dieThe DIE of interest
dw_abbrev_offsetOn success is set to the global offset in the .debug_abbrev section of the abbreviations for the DIE.
dw_abbrev_countOn success is set to the count of abbreviations in the .debug_abbrev section of the abbreviations for the DIE.
dw_errorThe usual error detail return pointer.
Returns
Returns DW_DLV_OK etc.

◆ dwarf_tag()

int dwarf_tag ( Dwarf_Die  dw_die,
Dwarf_Half dw_return_tag,
Dwarf_Error dw_error 
)

Get TAG value of DIE.

Parameters
dw_dieThe DIE of interest
dw_return_tagOn success, set to the DW_TAG value of the DIE.
dw_errorThe usual error detail return pointer.
Returns
Returns DW_DLV_OK etc.

◆ dwarf_dieoffset()

int dwarf_dieoffset ( Dwarf_Die  dw_die,
Dwarf_Off dw_return_offset,
Dwarf_Error dw_error 
)

Returns the global section offset of the DIE.

Parameters
dw_dieThe DIE of interest
dw_return_offsetOn success the offset refers to the section of the DIE itself, which may be .debug_offset or .debug_types.
dw_errorThe usual error detail return pointer.
Returns
Returns DW_DLV_OK etc.

◆ dwarf_debug_addr_index_to_addr()

int dwarf_debug_addr_index_to_addr ( Dwarf_Die  dw_die,
Dwarf_Unsigned  dw_index,
Dwarf_Addr dw_return_addr,
Dwarf_Error dw_error 
)

Extract address given address index. DWARF5.

Parameters
dw_dieThe DIE of interest
dw_indexAn index into .debug_addr. This will look first for .debug_addr in the dbg object DIE and if not there will look in the tied object if that is available.
dw_return_addrOn success the address is returned through the pointer.
dw_errorThe usual error detail return pointer.
Returns
Returns DW_DLV_OK etc.

◆ dwarf_addr_form_is_indexed()

Dwarf_Bool dwarf_addr_form_is_indexed ( int  dw_form)

Informs if a DW_FORM is an indexed form.

Reading a CU DIE with DW_AT_low_pc an indexed value can be problematic as several different FORMs are indexed. Some in DWARF5 others being extensions to DWARF4 and DWARF5. Indexed forms interact with DW_AT_addr_base in a DIE making this a very relevant distinction.

◆ dwarf_CU_dieoffset_given_die()

int dwarf_CU_dieoffset_given_die ( Dwarf_Die  dw_die,
Dwarf_Off dw_return_offset,
Dwarf_Error dw_error 
)

Returns the CU DIE offset given any DIE.

Returns the global debug_info section offset of the CU die in the CU containing the given_die (the passed in DIE can be any DIE).

See also
dwarf_get_cu_die_offset_given_cu_header_offset_b
Example dwarf_offset_given_die
Parameters
dw_dieThe die being queried.
dw_return_offsetReturns the section offset of the CU DIE for dw_die.
dw_errorThe usual error detail return pointer.
Returns
Returns DW_DLV_OK etc.

◆ dwarf_get_cu_die_offset_given_cu_header_offset_b()

int dwarf_get_cu_die_offset_given_cu_header_offset_b ( Dwarf_Debug  dw_dbg,
Dwarf_Off  dw_in_cu_header_offset,
Dwarf_Bool  dw_is_info,
Dwarf_Off dw_out_cu_die_offset,
Dwarf_Error dw_error 
)

Returns the CU DIE section offset given CU header offset.

Returns the CU die global offset if one knows the CU header global offset.

See also
dwarf_CU_dieoffset_given_die
Parameters
dw_dbgThe Dwarf_Debug of interest.
dw_in_cu_header_offsetThe CU header offset.
dw_is_infoIf TRUE the CU header offset is in .debug_info. Otherwise the CU header offset is in .debug_types.
dw_out_cu_die_offsetThe CU DIE offset returned through this pointer.
dw_errorThe usual error detail return pointer.
Returns
Returns DW_DLV_OK etc.

◆ dwarf_die_CU_offset()

int dwarf_die_CU_offset ( Dwarf_Die  dw_die,
Dwarf_Off dw_return_offset,
Dwarf_Error dw_error 
)

returns the CU relative offset of the DIE.

See also
dwarf_CU_dieoffset_given_die
Parameters
dw_dieThe DIE being queried.
dw_return_offsetReturns the CU relative offset of this DIE.
dw_errorThe usual error detail return pointer.
Returns
Returns DW_DLV_OK etc.

◆ dwarf_die_CU_offset_range()

int dwarf_die_CU_offset_range ( Dwarf_Die  dw_die,
Dwarf_Off dw_return_CU_header_offset,
Dwarf_Off dw_return_CU_length_bytes,
Dwarf_Error dw_error 
)

Returns the offset length of the entire CU of a DIE.

Parameters
dw_dieThe DIE being queried.
dw_return_CU_header_offsetOn success returns the section offset of the CU this DIE is in.
dw_return_CU_length_bytesOn success returns the CU length of the CU this DIE is in, including the CU length, header, and all DIEs.
dw_errorThe usual error detail return pointer.
Returns
Returns DW_DLV_OK etc.

◆ dwarf_attr()

int dwarf_attr ( Dwarf_Die  dw_die,
Dwarf_Half  dw_attrnum,
Dwarf_Attribute dw_returned_attr,
Dwarf_Error dw_error 
)

Given DIE and attribute number return a Dwarf_attribute.

Returns DW_DLV_NO_ENTRY if the DIE has no attribute dw_attrnum.

Parameters
dw_dieThe DIE of interest.
dw_attrnumAn attribute number, for example DW_AT_name.
dw_returned_attrOn success a Dwarf_Attribute pointer is returned and it should eventually be deallocated.
dw_errorThe usual error detail return pointer.
Returns
Returns DW_DLV_OK etc.

◆ dwarf_die_text()

int dwarf_die_text ( Dwarf_Die  dw_die,
Dwarf_Half  dw_attrnum,
char **  dw_ret_name,
Dwarf_Error dw_error 
)

Given DIE and attribute number return a string.

Returns DW_DLV_NO_ENTRY if the DIE has no attribute dw_attrnum.

Parameters
dw_dieThe DIE of interest.
dw_attrnumAn attribute number, for example DW_AT_name.
dw_ret_nameOn success a pointer to the string is returned. Do not free the string. Many attributes allow various forms that directly or indirectly contain strings and this follows all of them to their string.
dw_errorThe usual error detail return pointer.
Returns
Returns DW_DLV_OK etc.

◆ dwarf_diename()

int dwarf_diename ( Dwarf_Die  dw_die,
char **  dw_diename,
Dwarf_Error dw_error 
)

Return the string from a DW_AT_name attribute.

Returns DW_DLV_NO_ENTRY if the DIE has no attribute DW_AT_name

Parameters
dw_dieThe DIE of interest.
dw_dienameOn success a pointer to the string is returned. Do not free the string. Various forms directly or indirectly contain strings and this follows all of them to their string.
dw_errorThe usual error detail return pointer.
Returns
Returns DW_DLV_OK etc.

◆ dwarf_die_abbrev_code()

int dwarf_die_abbrev_code ( Dwarf_Die  dw_die)

Return the DIE abbrev code.

The Abbrev code for a DIE is an integer assigned by the compiler within a particular CU. For .debug_names abbreviations the situation is different.

Returns the abbrev code of the die. Cannot fail.

Parameters
dw_dieThe DIE of interest.
Returns
The abbrev code. of the DIE.

◆ dwarf_die_abbrev_children_flag()

int dwarf_die_abbrev_children_flag ( Dwarf_Die  dw_die,
Dwarf_Half dw_ab_has_child 
)

Returns TRUE if the DIE has children.

Parameters
dw_dieA DIE.
dw_ab_has_childSets TRUE though the pointer if the DIE has children. Otherwise sets FALSE.
Returns
Returns TRUE if the DIE has a child DIE. Else returns FALSE.

◆ dwarf_validate_die_sibling()

int dwarf_validate_die_sibling ( Dwarf_Die  dw_sibling,
Dwarf_Off dw_offset 
)

Validate a sibling DIE.

This is used by dwarfdump (when dwarfdump is checking for valid DWARF but it depends on the caller to have done precise setup. Ignore it. It has to change.

◆ dwarf_hasattr()

int dwarf_hasattr ( Dwarf_Die  dw_die,
Dwarf_Half  dw_attrnum,
Dwarf_Bool dw_returned_bool,
Dwarf_Error dw_error 
)

Tells whether a DIE has a particular attribute.

Parameters
dw_dieThe DIE of interest.
dw_attrnumThe attribute number we are asking about, DW_AT_name for example.
dw_returned_boolOn success is set TRUE if dw_die has dw_attrnum.
dw_errorThe usual error detail return pointer.
Returns
Never returns DW_DLV_NO_ENTRY. Returns DW_DLV_OK unless there is an error, in which case it returns DW_DLV_ERROR and sets dw_error to the error details.

◆ dwarf_offset_list()

int dwarf_offset_list ( Dwarf_Debug  dw_dbg,
Dwarf_Off  dw_offset,
Dwarf_Bool  dw_is_info,
Dwarf_Off **  dw_offbuf,
Dwarf_Unsigned dw_offcount,
Dwarf_Error dw_error 
)

Returns an array of DIE children offsets.

Given a DIE offset and dw_is_info, returns an array of DIE offsets of the children of DIE.

Parameters
dw_dbgThe Dwarf_Debug of interest.
dw_offsetA DIE offset.
dw_is_infoIf TRUE says to use the offset in .debug_info. Else .debug_types.
dw_offbufA pointer to an array of offsets is returned through the pointer.
dw_offcountThe number of elements in offbuf. IF the DIE has no children it could be zero, in which case offbuf and dw_offcount are not touched.
dw_errorThe usual error detail return pointer.
Returns
Returns DW_DLV_OK etc. DW_DLV_NO_ENTRY means there are no children of the DIE, hence no list of child offsets.
See also
Example using dwarf_offset_list

◆ dwarf_get_die_address_size()

int dwarf_get_die_address_size ( Dwarf_Die  dw_die,
Dwarf_Half dw_addr_size,
Dwarf_Error dw_error 
)

Get the address size applying to a DIE.

Parameters
dw_dieThe DIE of interest.
dw_addr_sizeOn success, returns the address size that applies to dw_die. Normally 4 or 8.
dw_errorThe usual error detail return pointer.
Returns
Returns DW_DLV_OK etc.

◆ dwarf_die_offsets()

int dwarf_die_offsets ( Dwarf_Die  dw_die,
Dwarf_Off dw_global_offset,
Dwarf_Off dw_local_offset,
Dwarf_Error dw_error 
)

Return section and CU-local offsets of a DIE.

Parameters
dw_dieThe DIE of interest.
dw_global_offsetOn success returns the offset of the DIE in its section.
dw_local_offsetOn success returns the offset of the DIE within its CU.
dw_errorThe usual error detail return pointer.
Returns
Returns DW_DLV_OK etc.

◆ dwarf_get_version_of_die()

int dwarf_get_version_of_die ( Dwarf_Die  dw_die,
Dwarf_Half dw_version,
Dwarf_Half dw_offset_size 
)

Get the version and offset size.

The values returned apply to the CU this DIE belongs to. This is useful as preparation for calling dwarf_get_form_class

Parameters
dw_dieThe DIE of interest.
dw_versionReturns the version of the CU this DIE is contained in. Standard version numbers are 2 through 5.
dw_offset_sizeReturns the offset_size (4 or 8) of the CU this DIE is contained in.

◆ dwarf_lowpc()

int dwarf_lowpc ( Dwarf_Die  dw_die,
Dwarf_Addr dw_returned_addr,
Dwarf_Error dw_error 
)

Returns the DW_AT_low_pc value.

Parameters
dw_dieThe DIE of interest.
dw_returned_addrOn success returns, through the pointer, the address DW_AT_low_pc defines.
dw_errorThe usual error detail return pointer.
Returns
Returns DW_DLV_OK etc.

◆ dwarf_highpc_b()

int dwarf_highpc_b ( Dwarf_Die  dw_die,
Dwarf_Addr dw_return_addr,
Dwarf_Half dw_return_form,
enum Dwarf_Form_Class dw_return_class,
Dwarf_Error dw_error 
)

Returns the DW_AT_hipc address value.

Calculating the high pc involves several elements which we don't describe here. See the DWARF5 standard. This is accessing the DW_AT_high_pc attribute.

Parameters
dw_dieThe DIE of interest.
dw_return_addrOn success returns the high-pc address for this DIE.
dw_return_formOn success returns the actual FORM for this attribute.
dw_return_classOn success returns the FORM CLASS for this attribute.
dw_errorThe usual error detail return pointer.
Returns
Returns DW_DLV_OK etc.

◆ dwarf_dietype_offset()

int dwarf_dietype_offset ( Dwarf_Die  dw_die,
Dwarf_Off dw_return_offset,
Dwarf_Error dw_error 
)

Returns the offset from the DW_AT_type attribute.

The offset returned is is a global offset of a type DIE. If this CU is DWARF4 the offset would be in .debug_types, otherwise it is in .debug_info.

Parameters
dw_dieThe DIE of interest.
dw_return_offsetIf successful, returns the offset through the pointer.
dw_errorThe usual error detail return pointer.
Returns
Returns DW_DLV_OK etc.

◆ dwarf_bytesize()

int dwarf_bytesize ( Dwarf_Die  dw_die,
Dwarf_Unsigned dw_returned_size,
Dwarf_Error dw_error 
)

Returns the value of the attribute DW_AT_byte_size.

Parameters
dw_dieThe DIE of interest.
dw_returned_sizeIf successful, returns the size through the pointer.
dw_errorThe usual error detail return pointer.
Returns
Returns DW_DLV_OK etc.

◆ dwarf_bitsize()

int dwarf_bitsize ( Dwarf_Die  dw_die,
Dwarf_Unsigned dw_returned_size,
Dwarf_Error dw_error 
)

Returns the value of the attribute DW_AT_bitsize.

Parameters
dw_dieThe DIE of interest.
dw_returned_sizeIf successful, returns the size through the pointer.
dw_errorThe usual error detail return pointer.
Returns
Returns DW_DLV_OK etc.

◆ dwarf_bitoffset()

int dwarf_bitoffset ( Dwarf_Die  dw_die,
Dwarf_Half dw_attrnum,
Dwarf_Unsigned dw_returned_offset,
Dwarf_Error dw_error 
)

Returns the bit offset attribute of a DIE.

If the attribute is DW_AT_data_bit_offset (DWARF4, DWARF5) the returned bit offset has one meaning. If the attribute is DW_AT_bit_offset (DWARF2, DWARF3) the meaning is quite different.

Parameters
dw_dieThe DIE of interest.
dw_attrnumIf successful, returns the number of the attribute (DW_AT_data_bit_offset or DW_AT_bit_offset)
dw_returned_offsetIf successful, returns the bit offset value.
dw_errorThe usual error detail return pointer.
Returns
Returns DW_DLV_OK etc.

◆ dwarf_srclang()

int dwarf_srclang ( Dwarf_Die  dw_die,
Dwarf_Unsigned dw_returned_lang,
Dwarf_Error dw_error 
)

Returns the value of the DW_AT_language attribute.

The DIE should be a CU DIE.

Parameters
dw_dieThe DIE of interest.
dw_returned_langOn success returns the language code (normally only found on a CU DIE). For example DW_LANG_C
dw_errorThe usual error detail return pointer.
Returns
Returns DW_DLV_OK etc.

◆ dwarf_arrayorder()

int dwarf_arrayorder ( Dwarf_Die  dw_die,
Dwarf_Unsigned dw_returned_order,
Dwarf_Error dw_error 
)

Returns the value of the DW_AT_ordering attribute.

Parameters
dw_dieThe DIE of interest.
dw_returned_orderOn success returns the ordering value. For example DW_ORD_row_major
dw_errorThe usual error detail return pointer.
Returns
Returns DW_DLV_OK etc.