libdwarf
Functions
Fast Access-Access to .debug_names DWARF5

The section is new in DWARF5 supersedes .debug_pubnames and .debug_pubtypes in DWARF2, DWARF3, and DWARF4. More...

Functions

int dwarf_dnames_header (Dwarf_Debug dw_dbg, Dwarf_Off dw_starting_offset, Dwarf_Dnames_Head *dw_dn, Dwarf_Off *dw_offset_of_next_table, Dwarf_Error *dw_error)
 Open access to a .debug_names table. More...
 
void dwarf_dealloc_dnames (Dwarf_Dnames_Head dw_dn)
 Frees all the malloc data associated with dw_dn. More...
 
int dwarf_dnames_abbrevtable (Dwarf_Dnames_Head dw_dn, Dwarf_Unsigned dw_index, Dwarf_Unsigned *dw_abbrev_offset, Dwarf_Unsigned *dw_abbrev_code, Dwarf_Unsigned *dw_abbrev_tag, Dwarf_Unsigned dw_array_size, Dwarf_Half *dw_idxattr_array, Dwarf_Half *dw_form_array, Dwarf_Unsigned *dw_idxattr_count)
 Access to the abbrevs table content. More...
 
int dwarf_dnames_sizes (Dwarf_Dnames_Head dw_dn, Dwarf_Unsigned *dw_comp_unit_count, Dwarf_Unsigned *dw_local_type_unit_count, Dwarf_Unsigned *dw_foreign_type_unit_count, Dwarf_Unsigned *dw_bucket_count, Dwarf_Unsigned *dw_name_count, Dwarf_Unsigned *dw_abbrev_table_size, Dwarf_Unsigned *dw_entry_pool_size, Dwarf_Unsigned *dw_augmentation_string_size, char **dw_augmentation_string, Dwarf_Unsigned *dw_section_size, Dwarf_Half *dw_table_version, Dwarf_Half *dw_offset_size, Dwarf_Error *dw_error)
 Sizes and counts from the debug names table. More...
 
int dwarf_dnames_offsets (Dwarf_Dnames_Head dw_dn, Dwarf_Unsigned *dw_header_offset, Dwarf_Unsigned *dw_cu_table_offset, Dwarf_Unsigned *dw_tu_local_offset, Dwarf_Unsigned *dw_foreign_tu_offset, Dwarf_Unsigned *dw_bucket_offset, Dwarf_Unsigned *dw_hashes_offset, Dwarf_Unsigned *dw_stringoffsets_offset, Dwarf_Unsigned *dw_entryoffsets_offset, Dwarf_Unsigned *dw_abbrev_table_offset, Dwarf_Unsigned *dw_entry_pool_offset, Dwarf_Error *dw_error)
 Offsets from the debug names table. More...
 
int dwarf_dnames_cu_table (Dwarf_Dnames_Head dw_dn, const char *dw_type, Dwarf_Unsigned dw_index_number, Dwarf_Unsigned *dw_offset, Dwarf_Sig8 *dw_sig, Dwarf_Error *dw_error)
 Each debug names list entry one at a time. More...
 
int dwarf_dnames_bucket (Dwarf_Dnames_Head dw_dn, Dwarf_Unsigned dw_bucket_number, Dwarf_Unsigned *dw_index, Dwarf_Unsigned *dw_indexcount, Dwarf_Error *dw_error)
 Access to bucket contents. More...
 
int dwarf_dnames_name (Dwarf_Dnames_Head dw_dn, Dwarf_Unsigned dw_name_index, Dwarf_Unsigned *dw_bucket_number, Dwarf_Unsigned *dw_hash_value, Dwarf_Unsigned *dw_offset_to_debug_str, char **dw_ptrtostr, Dwarf_Unsigned *dw_offset_in_entrypool, Dwarf_Unsigned *dw_abbrev_number, Dwarf_Half *dw_abbrev_tag, Dwarf_Unsigned dw_array_size, Dwarf_Half *dw_idxattr_array, Dwarf_Half *dw_form_array, Dwarf_Unsigned *dw_idxattr_count, Dwarf_Error *dw_error)
 Retrieve a name table entry. More...
 
int dwarf_dnames_abbrev_by_code (Dwarf_Dnames_Head dw_dn, Dwarf_Half dw_abbrev_code, Dwarf_Half *dw_tag, Dwarf_Unsigned *dw_index_of_abbrev, Dwarf_Unsigned *dw_number_of_attr_form_entries)
 Find an abbrev set by abbrev code. More...
 
int dwarf_dnames_abbrev_form_by_index (Dwarf_Dnames_Head dw_dn, Dwarf_Unsigned dw_abbrev_entry_index, Dwarf_Unsigned dw_abbrev_form_index, Dwarf_Unsigned *dw_idx_attr, Dwarf_Unsigned *dw_form, Dwarf_Error *dw_error)
 Returns a specific idxattribute form pair. More...
 
int dwarf_dnames_entrypool (Dwarf_Dnames_Head dw_dn, Dwarf_Unsigned dw_offset_in_entrypool, Dwarf_Unsigned *dw_abbrev_code, Dwarf_Half *dw_tag, Dwarf_Unsigned *dw_value_count, Dwarf_Unsigned *dw_index_of_abbrev, Dwarf_Unsigned *dw_offset_of_initial_value, Dwarf_Error *dw_error)
 Returns a the set of values from an entrypool entry. More...
 
int dwarf_dnames_entrypool_values (Dwarf_Dnames_Head dw_dn, Dwarf_Unsigned dw_index_of_abbrev, Dwarf_Unsigned dw_offset_in_entrypool_of_values, Dwarf_Unsigned dw_arrays_length, Dwarf_Half *dw_array_idx_number, Dwarf_Half *dw_array_form, Dwarf_Unsigned *dw_array_of_offsets, Dwarf_Sig8 *dw_array_of_signatures, Dwarf_Bool *dw_single_cu, Dwarf_Unsigned *dw_cu_offset, Dwarf_Unsigned *dw_offset_of_next_entrypool, Dwarf_Error *dw_error)
 Returns the value set defined by this entry. More...
 

Detailed Description

The section is new in DWARF5 supersedes .debug_pubnames and .debug_pubtypes in DWARF2, DWARF3, and DWARF4.

The functions provide a detailed reporting of the content and structure of the table (so one can build one's own search table) but they are not particularly helpful for searching.

A new function (more than one?) would be needed for convenient searching.

Function Documentation

◆ dwarf_dnames_header()

int dwarf_dnames_header ( Dwarf_Debug  dw_dbg,
Dwarf_Off  dw_starting_offset,
Dwarf_Dnames_Head dw_dn,
Dwarf_Off dw_offset_of_next_table,
Dwarf_Error dw_error 
)

Open access to a .debug_names table.

Parameters
dw_dbgThe Dwarf_Debug of interest.
dw_starting_offsetRead this section starting at offset zero.
dw_dnOn success returns a pointer to a set of data allowing access to the table.
dw_offset_of_next_tableOn success returns Offset just past the end of the the opened table.
dw_errorOn error dw_error is set to point to the error details.
Returns
The usual value: DW_DLV_OK etc. If there is no such table or if dw_starting_offset is past the end of the section it returns DW_DLV_NO_ENTRY.

◆ dwarf_dealloc_dnames()

void dwarf_dealloc_dnames ( Dwarf_Dnames_Head  dw_dn)

Frees all the malloc data associated with dw_dn.

Parameters
dw_dnA Dwarf_Dnames_Head pointer. Callers should zero the pointer passed in as soon as possible after this returns as the pointer is then stale.

◆ dwarf_dnames_abbrevtable()

int dwarf_dnames_abbrevtable ( Dwarf_Dnames_Head  dw_dn,
Dwarf_Unsigned  dw_index,
Dwarf_Unsigned dw_abbrev_offset,
Dwarf_Unsigned dw_abbrev_code,
Dwarf_Unsigned dw_abbrev_tag,
Dwarf_Unsigned  dw_array_size,
Dwarf_Half dw_idxattr_array,
Dwarf_Half dw_form_array,
Dwarf_Unsigned dw_idxattr_count 
)

Access to the abbrevs table content.

Of interest mainly to debugging issues with compilers or debuggers.

Parameters
dw_dnA Dwarf_Dnames_Head pointer.
dw_indexThe Names table index (starts at one) for.
dw_abbrev_offsetReturns the offset of the abbrev table entry for this names table entry.
dw_abbrev_codeReturns the abbrev code for the abbrev at offset dw_abbrev_offset.
dw_abbrev_tagReturns the tag for the abbrev at offset dw_abbrev_offset.
dw_array_sizeThe size you allocated in each of the following two arrays.
dw_idxattr_arrayPass in an array you allocated where the function returns and array of index attributes (DW_IDX) for this dw_abbrev_code. The last attribute code in the array is zero.
dw_form_arrayPass in an array you allocated where the function returns and array of forms for this dw_abbrev_code (paralled to dw_idxattr_array). The last form code in the array is zero.
dw_idxattr_countReturns the actual idxattribute/form count (including the terminating 0,0 pair. If the array_size passed in is less than this value the array returned is incomplete. Array entries needed. Might be larger than dw_array_size, meaning not all entries could be returned in your arrays.
Returns
Returns DW_DLV_OK on success. If the offset does not refer to a known part of the abbrev table it returns DW_DLV_NO_ENTRY. Never returns DW_DLV_ERROR.

◆ dwarf_dnames_sizes()

int dwarf_dnames_sizes ( Dwarf_Dnames_Head  dw_dn,
Dwarf_Unsigned dw_comp_unit_count,
Dwarf_Unsigned dw_local_type_unit_count,
Dwarf_Unsigned dw_foreign_type_unit_count,
Dwarf_Unsigned dw_bucket_count,
Dwarf_Unsigned dw_name_count,
Dwarf_Unsigned dw_abbrev_table_size,
Dwarf_Unsigned dw_entry_pool_size,
Dwarf_Unsigned dw_augmentation_string_size,
char **  dw_augmentation_string,
Dwarf_Unsigned dw_section_size,
Dwarf_Half dw_table_version,
Dwarf_Half dw_offset_size,
Dwarf_Error dw_error 
)

Sizes and counts from the debug names table.

We do not describe these returned values.

See DWARF5 section 6.1.1 "Lookup By Name" particularly the graph page 139. dw_comp_unit_count is K(k), dw_local_type_unit_count is T(t), and dw_foreign_type_unit_count is F(f).

◆ dwarf_dnames_offsets()

int dwarf_dnames_offsets ( Dwarf_Dnames_Head  dw_dn,
Dwarf_Unsigned dw_header_offset,
Dwarf_Unsigned dw_cu_table_offset,
Dwarf_Unsigned dw_tu_local_offset,
Dwarf_Unsigned dw_foreign_tu_offset,
Dwarf_Unsigned dw_bucket_offset,
Dwarf_Unsigned dw_hashes_offset,
Dwarf_Unsigned dw_stringoffsets_offset,
Dwarf_Unsigned dw_entryoffsets_offset,
Dwarf_Unsigned dw_abbrev_table_offset,
Dwarf_Unsigned dw_entry_pool_offset,
Dwarf_Error dw_error 
)

Offsets from the debug names table.

We do not describe these returned values, which refer to the .debug_names section.

The header offset is a section offset. The rest are offsets from the header.

See DWARF5 section 6.1.1 "Lookup By Name"

◆ dwarf_dnames_cu_table()

int dwarf_dnames_cu_table ( Dwarf_Dnames_Head  dw_dn,
const char *  dw_type,
Dwarf_Unsigned  dw_index_number,
Dwarf_Unsigned dw_offset,
Dwarf_Sig8 dw_sig,
Dwarf_Error dw_error 
)

Each debug names list entry one at a time.

The DWARF5 standard reserves index 0, so index numbers start at 1.

Parameters
dw_dnThe table of interest.
dw_typePass in the type, "cu" or "tu"
dw_index_numberFor "cu" index range is 1 through K For "tu" index range is 1 through T+F
dw_offsetSection offset of the target CU Zero if it cannot be determined.
dw_sigthe Dwarf_Sig8 is filled in with a signature if the TU index is T+1 through T+F
dw_errorOn error dw_error is set to point to the error details.
Returns
The usual value: DW_DLV_OK etc.

◆ dwarf_dnames_bucket()

int dwarf_dnames_bucket ( Dwarf_Dnames_Head  dw_dn,
Dwarf_Unsigned  dw_bucket_number,
Dwarf_Unsigned dw_index,
Dwarf_Unsigned dw_indexcount,
Dwarf_Error dw_error 
)

Access to bucket contents.

Parameters
dw_dnThe Dwarf_Dnames_Head of interest.
dw_bucket_numberPass in a bucket number Bucket numbers start at 0.
dw_indexOn success returns the index of the appropriate name entry. Name entry indexes start at one, a zero index means the bucket is unused.
dw_indexcountOn success returns the number of name entries in the bucket.
dw_errorOn error dw_error is set to point to the error details.
Returns
The usual value: DW_DLV_OK etc. An out of range dw_index_number gets a return if DW_DLV_NO_ENTRY

◆ dwarf_dnames_name()

int dwarf_dnames_name ( Dwarf_Dnames_Head  dw_dn,
Dwarf_Unsigned  dw_name_index,
Dwarf_Unsigned dw_bucket_number,
Dwarf_Unsigned dw_hash_value,
Dwarf_Unsigned dw_offset_to_debug_str,
char **  dw_ptrtostr,
Dwarf_Unsigned dw_offset_in_entrypool,
Dwarf_Unsigned dw_abbrev_number,
Dwarf_Half dw_abbrev_tag,
Dwarf_Unsigned  dw_array_size,
Dwarf_Half dw_idxattr_array,
Dwarf_Half dw_form_array,
Dwarf_Unsigned dw_idxattr_count,
Dwarf_Error dw_error 
)

Retrieve a name table entry.

For now, ignore this function as it does almost none of that the description promises. Most arguments are ignored.

Parameters
dw_dnThe table of interest.
dw_name_indexPass in the desired index, start at one.
dw_bucket_numberOn success returns a bucket number, zero if no buckets present.
dw_hash_valueThe hash value, all zeros if no hashes present
dw_offset_to_debug_strThe offset to the .debug_str section string.
dw_ptrtostrif dw_ptrtostr non-null returns a pointer to the applicable string here.
dw_offset_in_entrypoolReturns the offset in the entrypool
dw_abbrev_numberReturned from entrypool
dw_abbrev_tagReturned from entrypool abbrev data
dw_array_sizeSize of array you provide (even number). Possibly 20 to 40 suffices for practical purposes.
dw_idxattr_arrayArray you provide, for idx attribute numbers (function will initialize it). The final entry in the array will be 0.
dw_form_arrayArray you provide, for form numbers (function will initialize it). The final entry in the array will be 0.
dw_idxattr_countArray entries needed. Might be larger than dw_array_size, meaning not all entries could be returned in your array.
dw_errorOn error dw_error is set to point to the error details.
Returns
The usual value: DW_DLV_OK etc. If the index passed in is outside the valid range returns DW_DLV_NO_ENTRY.

◆ dwarf_dnames_abbrev_by_code()

int dwarf_dnames_abbrev_by_code ( Dwarf_Dnames_Head  dw_dn,
Dwarf_Half  dw_abbrev_code,
Dwarf_Half dw_tag,
Dwarf_Unsigned dw_index_of_abbrev,
Dwarf_Unsigned dw_number_of_attr_form_entries 
)

Find an abbrev set by abbrev code.

Useful for a quick look at what an abbrev record contains.

Parameters
dw_dnPass in the debug names table of interest.
dw_abbrev_codePass in the abbrev code of interest. These are not array indexes, they are compiler assigned numbers, often not in any meaningful sequence.
dw_tagIf non-null and the call succeeds, the DW_TAG value applying to this abbreviation is returned.
dw_index_of_abbrevIf non-null and the call succeeds, the index number assigned by libdwarf to this abbrev set is returned. The numbers are sequential, 0,1, etc. The trailing 0,0 pair is counted.
dw_number_of_attr_form_entriesIf non-null and the call succeeds, the number of attribute-form pairs in this abbrev is returned. The count includes the terminating 0,0 pair.
Returns
Returns either DW_DLV_OK or, if the abbrev code is not found, returns DW_DLV_NO_ENTRY.

◆ dwarf_dnames_abbrev_form_by_index()

int dwarf_dnames_abbrev_form_by_index ( Dwarf_Dnames_Head  dw_dn,
Dwarf_Unsigned  dw_abbrev_entry_index,
Dwarf_Unsigned  dw_abbrev_form_index,
Dwarf_Unsigned dw_idx_attr,
Dwarf_Unsigned dw_form,
Dwarf_Error dw_error 
)

Returns a specific idxattribute form pair.

You will find calling

See also
dwarf_dnames_abbrev_by_code useful to get the CU Data-Ranges data DW_AT_ranges you need here.
Parameters
dw_dnPass in the debug names table of interest.
dw_abbrev_entry_indexPass in the index number for an abbreviation record. Numbers start at 0.
dw_abbrev_form_indexPass in an index to an attr/form array. Indexes start with 0.
dw_idx_attrOn success returns the DW_IDX value in the idxattr-form pair.
dw_formOn success returns the DW_FORM value in the idxattr-form pair.
dw_errorOn error returns the usual error details.
Returns
DW_DLV_OK is returned if the specified entry exists. DW_DLV_NO_ENTRY is returned if the specified indexes do not designate an entry (an index out of range). DW_DLV_ERROR is returned in case of an internal error or corrupt section content.

◆ dwarf_dnames_entrypool()

int dwarf_dnames_entrypool ( Dwarf_Dnames_Head  dw_dn,
Dwarf_Unsigned  dw_offset_in_entrypool,
Dwarf_Unsigned dw_abbrev_code,
Dwarf_Half dw_tag,
Dwarf_Unsigned dw_value_count,
Dwarf_Unsigned dw_index_of_abbrev,
Dwarf_Unsigned dw_offset_of_initial_value,
Dwarf_Error dw_error 
)

Returns a the set of values from an entrypool entry.

Returns the basic data about an entrypool record and enables correct calling of dwarf_dnames_entrypool_values (see below). The two-stage approach makes it simple for callers to prepare for the number of values that will be returned by dwarf_dnames_entrypool_values()

Parameters
dw_dnPass in the debug names table of interest.
dw_offset_in_entrypoolThe record offset (in the entry pool table) of the first record of IDX attributes. Starts at zero.
dw_abbrev_codeOn success returns the abbrev code of the idx attributes for the pool entry.
dw_tagOn success returns the TAG of the DIE referred to by this entrypool entry.
dw_value_countOn success returns the number of distinct values imply by this entry.
dw_index_of_abbrevOn success returns the index of the abbrev index/form pairs in the abbreviation table.
dw_offset_of_initial_valueOn success returns the entry pool offset of the sequence of bytes containing values, such as a CU index or a DIE offset.
dw_errorThe usual error detail record
Returns
DW_DLV_OK is returned if the specified name entry exists. DW_DLV_NO_ENTRY is returned if the specified offset is outside the size of the table. DW_DLV_ERROR is returned in case of an internal error or corrupt section content.

◆ dwarf_dnames_entrypool_values()

int dwarf_dnames_entrypool_values ( Dwarf_Dnames_Head  dw_dn,
Dwarf_Unsigned  dw_index_of_abbrev,
Dwarf_Unsigned  dw_offset_in_entrypool_of_values,
Dwarf_Unsigned  dw_arrays_length,
Dwarf_Half dw_array_idx_number,
Dwarf_Half dw_array_form,
Dwarf_Unsigned dw_array_of_offsets,
Dwarf_Sig8 dw_array_of_signatures,
Dwarf_Bool dw_single_cu,
Dwarf_Unsigned dw_cu_offset,
Dwarf_Unsigned dw_offset_of_next_entrypool,
Dwarf_Error dw_error 
)

Returns the value set defined by this entry.

Call here after calling dwarf_dnames_entrypool to provide data to call this function correctly.

This retrieves the index attribute values that identify a names table name.

The caller allocates a set of arrays and the function fills them in. If dw_array_idx_number[n] is DW_IDX_type_hash then dw_array_of_signatures[n] contains the hash. For other IDX values dw_array_of_offsets[n] contains the value being returned.

Parameters
dw_dnPass in the debug names table of interest.
dw_index_of_abbrevPass in the abbreviation index.
dw_offset_in_entrypool_of_valuesPass in the offset of the values returned by dw_offset_of_initial_value above.
dw_arrays_lengthPass in the array length of each of the following four fields. The dw_value_count returned above is what you need to use.
dw_array_idx_numberCreate an array of Dwarf_Half values, dw_arrays_length long, and pass a pointer to the first entry here.
dw_array_formCreate an array of Dwarf_Half values, dw_arrays_length long, and pass a pointer to the first entry here.
dw_array_of_offsetsCreate an array of Dwarf_Unsigned values, dw_arrays_length long, and pass a pointer to the first entry here.
dw_array_of_signaturesCreate an array of Dwarf_Sig8 structs, dw_arrays_length long, and pass a pointer to the first entry here.
dw_offset_of_next_entrypoolOn success returns the offset of the next entrypool. A value here is usable in the next call to dwarf_dnames_entrypool.
dw_single_cuOn success, if it is a single-cu name table there is likely no DW_IDX_compile_unit. So we return TRUE via this flag in such a case.
dw_cu_offsetOn success, for a single-cu name table with no DW_IDX_compile_unit this is set to the CU offset from that single CU-table entry.
dw_errorThe usual error detail record
Returns
DW_DLV_OK is returned if the specified name entry exists. DW_DLV_NO_ENTRY is returned if the specified offset is outside the size of the table. DW_DLV_ERROR is returned in case of an internal error or corrupt section content.