libdwarf: Fast Access to .debug_pubnames and more.

libdwarf

Loading...
Searching...
No Matches
Macros | Functions
Fast Access to .debug_pubnames and more.

## Macros
#define | DW_GL_GLOBALS 0 /* .debug_pubnames and .debug_names */
#define | DW_GL_PUBTYPES 1 /* .debug_pubtypes */
#define | DW_GL_FUNCS 2 /* .debug_funcnames */
#define | DW_GL_TYPES 3 /* .debug_typenames */
#define | DW_GL_VARS 4 /* .debug_varnames */
#define | DW_GL_WEAKS 5 /* .debug_weaknames */

## Functions
DW_API int | dwarf_get_globals (Dwarf_Debug dw_dbg, Dwarf_Global **dw_globals, Dwarf_Signed *dw_number_of_globals, Dwarf_Error *dw_error)
| Global name space operations, .debug_pubnames access.
DW_API int | dwarf_get_pubtypes (Dwarf_Debug dw_dbg, Dwarf_Global **dw_pubtypes, Dwarf_Signed *dw_number_of_pubtypes, Dwarf_Error *dw_error)
| Global debug_types access.
DW_API int | dwarf_globals_by_type (Dwarf_Debug dw_dbg, int dw_requested_section, Dwarf_Global **dw_contents, Dwarf_Signed *dw_count, Dwarf_Error *dw_error)
| Allocate Any Fast Access DWARF2-DWARF4.
DW_API void | dwarf_globals_dealloc (Dwarf_Debug dw_dbg, Dwarf_Global *dw_global_like, Dwarf_Signed dw_count)
| Dealloc the Dwarf_Global data.
DW_API int | dwarf_globname (Dwarf_Global dw_global, char **dw_returned_name, Dwarf_Error *dw_error)
| Return the name of a global-like data item.
DW_API int | dwarf_global_die_offset (Dwarf_Global dw_global, Dwarf_Off *dw_die_offset, Dwarf_Error *dw_error)
| Return the DIE offset of a global data item.
DW_API int | dwarf_global_cu_offset (Dwarf_Global dw_global, Dwarf_Off *dw_cu_header_offset, Dwarf_Error *dw_error)
| Return the CU header data of a global data item.
DW_API int | dwarf_global_name_offsets (Dwarf_Global dw_global, char **dw_returned_name, Dwarf_Off *dw_die_offset, Dwarf_Off *dw_cu_die_offset, Dwarf_Error *dw_error)
| Return the name and offsets of a global entry.
DW_API Dwarf_Half | dwarf_global_tag_number (Dwarf_Global dw_global)
| Return the DW_TAG number of a global entry.
DW_API int | dwarf_get_globals_header (Dwarf_Global dw_global, int *dw_category, Dwarf_Off *dw_offset_pub_header, Dwarf_Unsigned *dw_length_size, Dwarf_Unsigned *dw_length_pub, Dwarf_Unsigned *dw_version, Dwarf_Unsigned *dw_header_info_offset, Dwarf_Unsigned *dw_info_length, Dwarf_Error *dw_error)
| For more complete globals printing.
DW_API int | dwarf_return_empty_pubnames (Dwarf_Debug dw_dbg, int dw_flag)
| A flag for dwarfdump on pubnames, pubtypes etc.

## Detailed Description

Pubnames and Pubtypes overview

These functions each read one of a set of sections designed for fast access by name, but they are not always emitted as they each have somewhat limited and inflexible capabilities. So you may not see many of these.

All have the same set of functions with a name reflecting the specific object section involved. Only the first, of type Dwarf_Global, is documented here in full detail as the others do the same jobs just each for their applicable object section..

## Function Documentation

## ◆ dwarf_get_globals()

DW_API int dwarf_get_globals | ( | Dwarf_Debug | dw_dbg,
|  | Dwarf_Global ** | dw_globals,
|  | Dwarf_Signed * | dw_number_of_globals,
|  | Dwarf_Error * | dw_error )

Global name space operations, .debug_pubnames access.

This accesses .debug_pubnames and .debug_names sections. Section .debug_pubnames is defined in DWARF2, DWARF3, and DWARF4. Section .debug_names is defined in DWARF5 and contains lots of information, but only the part of the wealth of information that this interface allows can be retrieved here. See dwarf_dnames_header() for access to all. debug_names data.

The code here, as of 0.4.3, September 3 2022, returns data from either section.

See also
  Using dwarf_get_globals()

Parameters

  dw_dbg | The Dwarf_Debug of interest.
  dw_globals | On success returns an array of pointers to opaque structs..
  dw_number_of_globals | On success returns the number of entries in the array.
  dw_error | On error dw_error is set to point to the error details.

Returns
  The usual value: DW_DLV_OK etc. Returns DW_DLV_NO_ENTRY if the section is not present.

## ◆ dwarf_get_globals_header()

DW_API int dwarf_get_globals_header | ( | Dwarf_Global | dw_global,
|  | int * | dw_category,
|  | Dwarf_Off * | dw_offset_pub_header,
|  | Dwarf_Unsigned * | dw_length_size,
|  | Dwarf_Unsigned * | dw_length_pub,
|  | Dwarf_Unsigned * | dw_version,
|  | Dwarf_Unsigned * | dw_header_info_offset,
|  | Dwarf_Unsigned * | dw_info_length,
|  | Dwarf_Error * | dw_error )

For more complete globals printing.

For each CU represented in .debug_pubnames, etc, there is a .debug_pubnames header. For any given Dwarf_Global this returns the content of the applicable header. This does not include header information from any .debug_names headers.

The function declaration changed at version 0.6.0.

## ◆ dwarf_get_pubtypes()

DW_API int dwarf_get_pubtypes | ( | Dwarf_Debug | dw_dbg,
|  | Dwarf_Global ** | dw_pubtypes,
|  | Dwarf_Signed * | dw_number_of_pubtypes,
|  | Dwarf_Error * | dw_error )

Global debug_types access.

Parameters

  dw_dbg | The Dwarf_Debug of interest.
  dw_pubtypes | On success returns an array of pointers to opaque structs..
  dw_number_of_pubtypes | On success returns the number of entries in the array.
  dw_error | On error dw_error is set to point to the error details.

Returns
  The usual value: DW_DLV_OK etc. Returns DW_DLV_NO_ENTRY if the section is not present.

Same function name as 0.5.0 and earlier, but the data type changes to Dwarf_Global

dwarf_get_pubtypes() is an alternate name for dwarf_globals_by_type(..,DW_GL_PUBTYPES,..).

## ◆ dwarf_global_cu_offset()

DW_API int dwarf_global_cu_offset | ( | Dwarf_Global | dw_global,
|  | Dwarf_Off * | dw_cu_header_offset,
|  | Dwarf_Error * | dw_error )

Return the CU header data of a global data item.

A CU header offset is rarely useful.

Parameters

  dw_global | The Dwarf_Global of interest.
  dw_cu_header_offset | On success a the section-global offset of a CU header is returned.
  dw_error | On error dw_error is set to point to the error details.

Returns
  The usual value: DW_DLV_OK etc.

## ◆ dwarf_global_die_offset()

DW_API int dwarf_global_die_offset | ( | Dwarf_Global | dw_global,
|  | Dwarf_Off * | dw_die_offset,
|  | Dwarf_Error * | dw_error )

Return the DIE offset of a global data item.

Parameters

  dw_global | The Dwarf_Global of interest.
  dw_die_offset | On success a the section-global DIE offset of a data item is returned.
  dw_error | On error dw_error is set to point to the error details.

Returns
  The usual value: DW_DLV_OK etc.

## ◆ dwarf_global_name_offsets()

DW_API int dwarf_global_name_offsets | ( | Dwarf_Global | dw_global,
|  | char ** | dw_returned_name,
|  | Dwarf_Off * | dw_die_offset,
|  | Dwarf_Off * | dw_cu_die_offset,
|  | Dwarf_Error * | dw_error )

Return the name and offsets of a global entry.

Parameters

  dw_global | The Dwarf_Global of interest.
  dw_returned_name | On success a pointer to the name (a null-terminated string) is returned.
  dw_die_offset | On success a the section-global DIE offset of the global with the name.
  dw_cu_die_offset | On success a the section-global offset of the relevant CU DIE is returned.
  dw_error | On error dw_error is set to point to the error details.

Returns
  The usual value: DW_DLV_OK etc.

## ◆ dwarf_global_tag_number()

DW_API Dwarf_Half dwarf_global_tag_number | ( | Dwarf_Global | dw_global | ) |

Return the DW_TAG number of a global entry.

Parameters

  dw_global | The Dwarf_Global of interest.

Returns
  If the Dwarf_Global refers to a global from the .debug_names section the return value is the DW_TAG for the DIE in the global entry, for example DW_TAG_subprogram. In case of error or if the section for this global was not .debug_names zero is returned.

## ◆ dwarf_globals_by_type()

DW_API int dwarf_globals_by_type | ( | Dwarf_Debug | dw_dbg,
|  | int | dw_requested_section,
|  | Dwarf_Global ** | dw_contents,
|  | Dwarf_Signed * | dw_count,
|  | Dwarf_Error * | dw_error )

Allocate Any Fast Access DWARF2-DWARF4.

This interface new in 0.6.0. Simplfies access by replace dwarf_get_pubtypes, dwarf_get_funcs, dwarf_get_types, dwarfget_vars, and dwarf_get_weaks with a single set of types.

Parameters

  dw_dbg | The Dwarf_Debug of interest.
  dw_requested_section | Pass in one of the values DW_GL_GLOBALS through DW_GL_WEAKS to select the section to extract data from.
  dw_contents | On success returns an array of pointers to opaque structs.
  dw_count | On success returns the number of entries in the array.
  dw_error | On error dw_error is set to point to the error details.

Returns
  The usual value: DW_DLV_OK etc. Returns DW_DLV_NO_ENTRY if the section is not present.

## ◆ dwarf_globals_dealloc()

DW_API void dwarf_globals_dealloc | ( | Dwarf_Debug | dw_dbg,
|  | Dwarf_Global * | dw_global_like,
|  | Dwarf_Signed | dw_count )

Dealloc the Dwarf_Global data.

Parameters

  dw_dbg | The Dwarf_Debug of interest.
  dw_global_like | The array of globals/types/etc data to dealloc (free).
  dw_count | The number of entries in the array.

## ◆ dwarf_globname()

DW_API int dwarf_globname | ( | Dwarf_Global | dw_global,
|  | char ** | dw_returned_name,
|  | Dwarf_Error * | dw_error )

Return the name of a global-like data item.

Parameters

  dw_global | The Dwarf_Global of interest.
  dw_returned_name | On success a pointer to the name (a null-terminated string) is returned.
  dw_error | On error dw_error is set to point to the error details.

Returns
  The usual value: DW_DLV_OK etc.

## ◆ dwarf_return_empty_pubnames()

DW_API int dwarf_return_empty_pubnames | ( | Dwarf_Debug | dw_dbg,
|  | int | dw_flag )

A flag for dwarfdump on pubnames, pubtypes etc.

Sets a flag in the dbg. Always returns DW_DLV_OK. Applies to all the sections of this kind: pubnames, pubtypes, funcs, typenames,vars, weaks. Ensures empty content (meaning no offset/name tuples, but with a header) for a CU shows up rather than being suppressed.

Primarily useful if one wants to note any pointless header data in the section.

Pubnames and Pubtypes overview

Parameters

  dw_dbg | The Dwarf_Debug of interest.
  dw_flag | Must be the value one.

Returns
  Returns DW_DLV_OK. Always.