libdwarf: Fast Access to .debug_names DWARF5

libdwarf

Loading...
Searching...
No Matches
Functions
Fast Access to .debug_names DWARF5

## Functions
DW_API 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.
DW_API void | dwarf_dealloc_dnames (Dwarf_Dnames_Head dw_dn)
| Frees all the malloc data associated with dw_dn.
DW_API 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.
DW_API 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.
DW_API 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.
DW_API 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.
DW_API 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.
DW_API 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.
DW_API 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.
DW_API 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.

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

DW_API void dwarf_dealloc_dnames | ( | Dwarf_Dnames_Head | dw_dn | ) |

Frees all the malloc data associated with 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()

DW_API 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_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_bucket()

DW_API 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_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_cu_table()

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

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

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

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

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

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.

## ◆ dwarf_dnames_header()

DW_API 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_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_dnames_name()

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

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

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

DW_API 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. 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).