Fast Access to .debug_names DWARF5

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 cu 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_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)
	Return 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)
	Return the value set defined by this entry. More...

Detailed Description

The section is new in DWARF5 and 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
	)

Parameters

dw_dbg	The Dwarf_Debug of interest.
dw_starting_offset	Read this section starting at offset zero.
dw_dn	On success returns a pointer to a set of data allowing access to the table.
dw_offset_of_next_table	On success returns Offset just past the end of the the opened table.
dw_error	On 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

)

Parameters

dw_dn

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

Of interest mainly to debugging issues with compilers or debuggers.

Parameters

dw_dn	A Dwarf_Dnames_Head pointer.
dw_index	An index (starting at zero) into a table constructed of abbrev data. These indexes are derived from abbrev data and are not in the abbrev data itself.
dw_abbrev_offset	Returns the offset of the abbrev table entry for this names table entry.
dw_abbrev_code	Returns the abbrev code for the abbrev at offset dw_abbrev_offset.
dw_abbrev_tag	Returns the tag for the abbrev at offset dw_abbrev_offset.
dw_array_size	The size you allocated in each of the following two arrays.
dw_idxattr_array	Pass 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_array	Pass 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_count	Returns 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
	)

We do not describe these returned values. Other than for dw_dn and dw_error passing pointers you do not care about as NULL is fine. Of course no value can be returned through those passed as NULL.

Any program referencing a names table will need at least a few of these 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
	)

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
	)

Indexes to the cu/tu/ tables start at 0.

Some values in dw_offset are actually offsets, such as for DW_IDX_die_offset. DW_IDX_compile_unit and DW_IDX_type_unit are indexes into the table specified by dw_type and are returned through dw_offset field;

Parameters

dw_dn	The table of interest.
dw_type	Pass in the type, "cu" or "tu"
dw_index_number	For "cu" index range is 0 through K-1 For "tu" index range is 0 through T+F-1
dw_offset	Zero if it cannot be determined. (check the return value!).
dw_sig	the Dwarf_Sig8 is filled in with a signature if the TU index is T through T+F-1
dw_error	On 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
	)

Parameters

dw_dn	The Dwarf_Dnames_Head of interest.
dw_bucket_number	Pass in a bucket number Bucket numbers start at 0.
dw_index	On success returns the index of the appropriate name entry. Name entry indexes start at one, a zero index means the bucket is unused.
dw_indexcount	On success returns the number of name entries in the bucket.
dw_error	On 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 the name and other data from a single name table entry.

Parameters

dw_dn	The table of interest.
dw_name_index	Pass in the desired index, start at one.
dw_bucket_number	On success returns a bucket number, zero if no buckets present.
dw_hash_value	The hash value, all zeros if no hashes present
dw_offset_to_debug_str	The offset to the .debug_str section string.
dw_ptrtostr	if dw_ptrtostr non-null returns a pointer to the applicable string here.
dw_offset_in_entrypool	Returns the offset in the entrypool
dw_abbrev_number	Returned from entrypool.
dw_abbrev_tag	Returned from entrypool abbrev data.
dw_array_size	Size of array you provide to hold DW_IDX index attribute and form numbers. Possibly 10 suffices for practical purposes.
dw_idxattr_array	Array space you provide, for idx attribute numbers (function will initialize it). The final entry in the array will be 0.
dw_form_array	Array you provide, for form numbers (function will initialize it). The final entry in the array will be 0.
dw_idxattr_count	Array entries needed. Might be larger than dw_array_size, meaning not all entries could be returned in your array.
dw_error	On 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_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 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_dn	Pass in the debug names table of interest.
dw_offset_in_entrypool	The record offset (in the entry pool table) of the first record of IDX attributes. Starts at zero.
dw_abbrev_code	On success returns the abbrev code of the idx attributes for the pool entry.
dw_tag	On success returns the TAG of the DIE referred to by this entrypool entry.
dw_value_count	On success returns the number of distinct values imply by this entry.
dw_index_of_abbrev	On success returns the index of the abbrev index/form pairs in the abbreviation table.
dw_offset_of_initial_value	On success returns the entry pool offset of the sequence of bytes containing values, such as a CU index or a DIE offset.
dw_error	The 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
	)

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_dn	Pass in the debug names table of interest.
dw_index_of_abbrev	Pass in the abbreviation index.
dw_offset_in_entrypool_of_values	Pass in the offset of the values returned by dw_offset_of_initial_value above.
dw_arrays_length	Pass 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_number	Create an array of Dwarf_Half values, dw_arrays_length long, and pass a pointer to the first entry here.
dw_array_form	Create an array of Dwarf_Half values, dw_arrays_length long, and pass a pointer to the first entry here.
dw_array_of_offsets	Create an array of Dwarf_Unsigned values, dw_arrays_length long, and pass a pointer to the first entry here.
dw_array_of_signatures	Create an array of Dwarf_Sig8 structs, dw_arrays_length long, and pass a pointer to the first entry here.
dw_offset_of_next_entrypool	On success returns the offset of the next entrypool. A value here is usable in the next call to dwarf_dnames_entrypool.
dw_single_cu	On 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_offset	On 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_error	The 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.