libdwarf: Object Sections Data

libdwarf

Loading...
Searching...
No Matches
Functions
Object Sections Data

## Functions
DW_API int | dwarf_get_die_section_name (Dwarf_Debug dw_dbg, Dwarf_Bool dw_is_info, const char **dw_sec_name, Dwarf_Error *dw_error)
| Get the real name a DIE section.
DW_API int | dwarf_get_die_section_name_b (Dwarf_Die dw_die, const char **dw_sec_name, Dwarf_Error *dw_error)
| Get the real name of a DIE section.
DW_API int | dwarf_get_macro_section_name (Dwarf_Debug dw_dbg, const char **dw_sec_name_out, Dwarf_Error *dw_err)
| Get the real name of a .debug_macro section.
DW_API int | dwarf_get_real_section_name (Dwarf_Debug dw_dbg, const char *dw_std_section_name, const char **dw_actual_sec_name_out, Dwarf_Small *dw_marked_zcompressed, Dwarf_Small *dw_marked_zlib_compressed, Dwarf_Small *dw_marked_shf_compressed, Dwarf_Unsigned *dw_compressed_length, Dwarf_Unsigned *dw_uncompressed_length, Dwarf_Error *dw_error)
| Get the real name of a section.
DW_API int | dwarf_get_frame_section_name (Dwarf_Debug dw_dbg, const char **dw_section_name_out, Dwarf_Error *dw_error)
| Get .debug_frame section name.
DW_API int | dwarf_get_frame_section_name_eh_gnu (Dwarf_Debug dw_dbg, const char **dw_section_name_out, Dwarf_Error *dw_error)
| Get GNU .eh_frame section name.
DW_API int | dwarf_get_aranges_section_name (Dwarf_Debug dw_dbg, const char **dw_section_name_out, Dwarf_Error *dw_error)
| Get .debug_aranges section name The usual arguments.
DW_API int | dwarf_get_ranges_section_name (Dwarf_Debug dw_dbg, const char **dw_section_name_out, Dwarf_Error *dw_error)
| Get .debug_ranges section name The usual arguments and return values.
DW_API int | dwarf_get_offset_size (Dwarf_Debug dw_dbg, Dwarf_Half *dw_offset_size, Dwarf_Error *dw_error)
| Get offset size as defined by the object.
DW_API int | dwarf_get_address_size (Dwarf_Debug dw_dbg, Dwarf_Half *dw_addr_size, Dwarf_Error *dw_error)
| Get the address size as defined by the object.
DW_API int | dwarf_get_string_section_name (Dwarf_Debug dw_dbg, const char **dw_section_name_out, Dwarf_Error *dw_error)
| Get the string table section name The usual arguments and return values.
DW_API int | dwarf_get_line_section_name (Dwarf_Debug dw_dbg, const char **dw_section_name_out, Dwarf_Error *dw_error)
| Get the line table section name The usual arguments and return values.
DW_API int | dwarf_get_line_section_name_from_die (Dwarf_Die dw_die, const char **dw_section_name_out, Dwarf_Error *dw_error)
| Get the line table section name.
DW_API int | dwarf_get_section_info_by_name_a (Dwarf_Debug dw_dbg, const char *dw_section_name, Dwarf_Addr *dw_section_addr, Dwarf_Unsigned *dw_section_size, Dwarf_Unsigned *dw_section_flags, Dwarf_Unsigned *dw_section_offset, Dwarf_Error *dw_error)
| Given a section name, get its size, address, etc.
DW_API int | dwarf_get_section_info_by_name (Dwarf_Debug dw_dbg, const char *dw_section_name, Dwarf_Addr *dw_section_addr, Dwarf_Unsigned *dw_section_size, Dwarf_Error *dw_error)
| Given a section name, get its size and address.
DW_API int | dwarf_get_section_info_by_index_a (Dwarf_Debug dw_dbg, int dw_section_index, const char **dw_section_name, Dwarf_Addr *dw_section_addr, Dwarf_Unsigned *dw_section_size, Dwarf_Unsigned *dw_section_flags, Dwarf_Unsigned *dw_section_offset, Dwarf_Error *dw_error)
| Given a section index, get its size and address, etc.
DW_API int | dwarf_get_section_info_by_index (Dwarf_Debug dw_dbg, int dw_section_index, const char **dw_section_name, Dwarf_Addr *dw_section_addr, Dwarf_Unsigned *dw_section_size, Dwarf_Error *dw_error)
| Given a section index, get its size and address.
DW_API int | dwarf_machine_architecture_a (Dwarf_Debug dw_dbg, Dwarf_Small *dw_ftype, Dwarf_Small *dw_obj_pointersize, Dwarf_Bool *dw_obj_is_big_endian, Dwarf_Unsigned *dw_obj_machine, Dwarf_Unsigned *dw_obj_type, Dwarf_Unsigned *dw_obj_flags, Dwarf_Small *dw_path_source, Dwarf_Unsigned *dw_ub_offset, Dwarf_Unsigned *dw_ub_count, Dwarf_Unsigned *dw_ub_index, Dwarf_Unsigned *dw_comdat_groupnumber)
| Get basic object information from Dwarf_Debug.
DW_API int | dwarf_machine_architecture (Dwarf_Debug dw_dbg, Dwarf_Small *dw_ftype, Dwarf_Small *dw_obj_pointersize, Dwarf_Bool *dw_obj_is_big_endian, Dwarf_Unsigned *dw_obj_machine, Dwarf_Unsigned *dw_obj_flags, Dwarf_Small *dw_path_source, Dwarf_Unsigned *dw_ub_offset, Dwarf_Unsigned *dw_ub_count, Dwarf_Unsigned *dw_ub_index, Dwarf_Unsigned *dw_comdat_groupnumber)
| Get basic object information original version.
DW_API Dwarf_Unsigned | dwarf_get_section_count (Dwarf_Debug dw_dbg)
| Get section count (of object file sections).
DW_API int | dwarf_get_section_max_offsets_d (Dwarf_Debug dw_dbg, Dwarf_Unsigned *dw_debug_info_size, Dwarf_Unsigned *dw_debug_abbrev_size, Dwarf_Unsigned *dw_debug_line_size, Dwarf_Unsigned *dw_debug_loc_size, Dwarf_Unsigned *dw_debug_aranges_size, Dwarf_Unsigned *dw_debug_macinfo_size, Dwarf_Unsigned *dw_debug_pubnames_size, Dwarf_Unsigned *dw_debug_str_size, Dwarf_Unsigned *dw_debug_frame_size, Dwarf_Unsigned *dw_debug_ranges_size, Dwarf_Unsigned *dw_debug_pubtypes_size, Dwarf_Unsigned *dw_debug_types_size, Dwarf_Unsigned *dw_debug_macro_size, Dwarf_Unsigned *dw_debug_str_offsets_size, Dwarf_Unsigned *dw_debug_sup_size, Dwarf_Unsigned *dw_debug_cu_index_size, Dwarf_Unsigned *dw_debug_tu_index_size, Dwarf_Unsigned *dw_debug_names_size, Dwarf_Unsigned *dw_debug_loclists_size, Dwarf_Unsigned *dw_debug_rnglists_size)
| Get section sizes for many sections.

## Detailed Description

These functions are not often used. They give access to section- and objectfile-related information, and that sort of information is not generally needed to understand DWARF content..

Section name access. Because names sections such as .debug_info might end with .dwo or be .zdebug or might not.

String pointers returned via these functions must not be freed, the strings are statically declared.

For non-Elf the name reported will be as if it were Elf sections. For example, not the names Macos puts in its object sections (which the Macos reader translates).

These calls returning selected object header {machine architecture,flags) and section (offset, flags) data are not of interest to most library callers: dwarf_machine_architecture(), dwarf_get_section_info_by_index_a(), and dwarf_get_section_info_by_name_a().

The simple calls will not be documented in full detail here.

## Function Documentation

## ◆ dwarf_get_address_size()

DW_API int dwarf_get_address_size | ( | Dwarf_Debug | dw_dbg,
|  | Dwarf_Half * | dw_addr_size,
|  | Dwarf_Error * | dw_error )

Get the address size as defined by the object.

This is not from DWARF information, it is from object file headers.

## ◆ dwarf_get_die_section_name()

DW_API int dwarf_get_die_section_name | ( | Dwarf_Debug | dw_dbg,
|  | Dwarf_Bool | dw_is_info,
|  | const char ** | dw_sec_name,
|  | Dwarf_Error * | dw_error )

Get the real name a DIE section.

dw_is_info

Parameters

  dw_dbg | The Dwarf_Debug of interest
  dw_is_info | We do not pass in a DIE, so we have to pass in TRUE for for .debug_info, or if DWARF4 .debug_types pass in FALSE.
  dw_sec_name | On success returns a pointer to the actual section name in the object file. Do not free the string.
  dw_error | The usual error argument to report error details.

Returns
  DW_DLV_OK etc.

## ◆ dwarf_get_die_section_name_b()

DW_API int dwarf_get_die_section_name_b | ( | Dwarf_Die | dw_die,
|  | const char ** | dw_sec_name,
|  | Dwarf_Error * | dw_error )

Get the real name of a DIE section.

The same as dwarf_get_die_section_name except we have a DIE so do not need dw_is_info as a argument.

## ◆ dwarf_get_frame_section_name()

DW_API int dwarf_get_frame_section_name | ( | Dwarf_Debug | dw_dbg,
|  | const char ** | dw_section_name_out,
|  | Dwarf_Error * | dw_error )

Get .debug_frame section name.

Returns
  returns DW_DLV_OK if the .debug_frame exists

## ◆ dwarf_get_frame_section_name_eh_gnu()

DW_API int dwarf_get_frame_section_name_eh_gnu | ( | Dwarf_Debug | dw_dbg,
|  | const char ** | dw_section_name_out,
|  | Dwarf_Error * | dw_error )

Get GNU .eh_frame section name.

Returns
  Returns DW_DLV_OK if the .debug_frame is present Returns DW_DLV_NO_ENTRY if it is not present.

## ◆ dwarf_get_line_section_name_from_die()

DW_API int dwarf_get_line_section_name_from_die | ( | Dwarf_Die | dw_die,
|  | const char ** | dw_section_name_out,
|  | Dwarf_Error * | dw_error )

Get the line table section name.

Parameters

  dw_die | Pass in a Dwarf_Die pointer.
  dw_section_name_out | On success returns the section name, usually some .debug_info* name but in DWARF4 could be a .debug_types* name.
  dw_error | On error returns the usual error pointer.

Returns
  Returns DW_DLV_OK etc.

## ◆ dwarf_get_offset_size()

DW_API int dwarf_get_offset_size | ( | Dwarf_Debug | dw_dbg,
|  | Dwarf_Half * | dw_offset_size,
|  | Dwarf_Error * | dw_error )

Get offset size as defined by the object.

This is not from DWARF information, it is from object file headers.

## ◆ dwarf_get_real_section_name()

DW_API int dwarf_get_real_section_name | ( | Dwarf_Debug | dw_dbg,
|  | const char * | dw_std_section_name,
|  | const char ** | dw_actual_sec_name_out,
|  | Dwarf_Small * | dw_marked_zcompressed,
|  | Dwarf_Small * | dw_marked_zlib_compressed,
|  | Dwarf_Small * | dw_marked_shf_compressed,
|  | Dwarf_Unsigned * | dw_compressed_length,
|  | Dwarf_Unsigned * | dw_uncompressed_length,
|  | Dwarf_Error * | dw_error )

Get the real name of a section.

If the object has section groups only the sections in the group in dw_dbg will be found.

Whether .zdebug or ZLIB or SHF_COMPRESSED is the marker there is just one uncompress algorithm (zlib) for all three cases.

Parameters

  dw_dbg | The Dwarf_Debug of interest.
  dw_std_section_name | Pass in a standard section name, such as .debug_info or .debug_info.dwo .
  dw_actual_sec_name_out | On success returns the actual section name from the object file.
  dw_marked_zcompressed | On success returns TRUE if the original section name ends in .zdebug
  dw_marked_zlib_compressed | On success returns TRUE if the section has the ZLIB string at the front of the section.
  dw_marked_shf_compressed | On success returns TRUE if the section flag (Elf SHF_COMPRESSED) is marked as compressed.
  dw_compressed_length | On success if the section was compressed it returns the original section length in the object file.
  dw_uncompressed_length | On success if the section was compressed this returns the uncompressed length of the object section.
  dw_error | On error returns the error usual details.

Returns
  The usual DW_DLV_OK etc. If the section is not relevant to this Dwarf_Debug or is not in the object file at all, returns DW_DLV_NO_ENTRY

## ◆ dwarf_get_section_count()

DW_API Dwarf_Unsigned dwarf_get_section_count | ( | Dwarf_Debug | dw_dbg | ) |

Get section count (of object file sections).

Return the section count. Returns 0 if the dw_dbg argument is improper in any way.

Parameters

  dw_dbg | Pass in a valid Dwarf_Debug of interest.

Returns
  Returns the count of sections in the object file or zero.

## ◆ dwarf_get_section_info_by_index()

DW_API int dwarf_get_section_info_by_index | ( | Dwarf_Debug | dw_dbg,
|  | int | dw_section_index,
|  | const char ** | dw_section_name,
|  | Dwarf_Addr * | dw_section_addr,
|  | Dwarf_Unsigned * | dw_section_size,
|  | Dwarf_Error * | dw_error )

Given a section index, get its size and address.

See dwarf_get_section_info_by_index_a() for the newest version which returns additional values.

Fields and meanings in dwarf_get_section_info_by_index() are the same as in dwarf_get_section_info_by_index_a() except that the arguments dw_section_flags and dw_section_offset are missing here.

## ◆ dwarf_get_section_info_by_index_a()

DW_API int dwarf_get_section_info_by_index_a | ( | Dwarf_Debug | dw_dbg,
|  | int | dw_section_index,
|  | const char ** | dw_section_name,
|  | Dwarf_Addr * | dw_section_addr,
|  | Dwarf_Unsigned * | dw_section_size,
|  | Dwarf_Unsigned * | dw_section_flags,
|  | Dwarf_Unsigned * | dw_section_offset,
|  | Dwarf_Error * | dw_error )

Given a section index, get its size and address, etc.

See dwarf_get_section_info_by_index() for the older and still current version.

Any of the pointers dw_section_addr, dw_section_size, dw_section_flags, and dw_section_offset may be passed in as zero and those will be ignored by the function.

Parameters

  dw_dbg | The Dwarf_Debug of interest.
  dw_section_index | Pass in an index, 0 through N-1 where N is the count returned from dwarf_get_section_count . As an index type -int- works in practice, but should really be Dwarf_Unsigned.
  dw_section_name | On success returns a pointer to the section name as it appears in the object file.
  dw_section_addr | On success returns the section address as defined by an object header.
  dw_section_size | On success returns the section size as defined by an object header.
  dw_section_flags | On success returns the section flags as defined by an object header. The flag meaning depends on which object format is being read and the meaning is defined by the object format. In PE object files this field is called Characteristics. We hope it is of some use.
  dw_section_offset | On success returns the section offset as defined by an object header. The offset meaning is supposedly an object file offset but the meaning depends on the object file type(!). We hope it is of some use.
  dw_error | On error returns the usual error pointer.

Returns
  Returns DW_DLV_OK etc.

## ◆ dwarf_get_section_info_by_name()

DW_API int dwarf_get_section_info_by_name | ( | Dwarf_Debug | dw_dbg,
|  | const char * | dw_section_name,
|  | Dwarf_Addr * | dw_section_addr,
|  | Dwarf_Unsigned * | dw_section_size,
|  | Dwarf_Error * | dw_error )

Given a section name, get its size and address.

See dwarf_get_section_info_by_name_a() for the newest version which returns additional values.

Fields and meanings in dwarf_get_section_info_by_name() are the same as in dwarf_get_section_info_by_name_a() except that the arguments dw_section_flags and dw_section_offset are missing here.

## ◆ dwarf_get_section_info_by_name_a()

DW_API int dwarf_get_section_info_by_name_a | ( | Dwarf_Debug | dw_dbg,
|  | const char * | dw_section_name,
|  | Dwarf_Addr * | dw_section_addr,
|  | Dwarf_Unsigned * | dw_section_size,
|  | Dwarf_Unsigned * | dw_section_flags,
|  | Dwarf_Unsigned * | dw_section_offset,
|  | Dwarf_Error * | dw_error )

Given a section name, get its size, address, etc.

New in v0.9.0 November 2023.

This is not often used and is completely unnecessary for most to call.

See dwarf_get_section_info_by_name() for the older and still current version.

Any of the pointers dw_section_addr, dw_section_size, dw_section_flags, and dw_section_offset may be passed in as zero and those will be ignored by the function.

Parameters

  dw_dbg | The Dwarf_Debug of interest.
  dw_section_name | Pass in a pointer to a section name. It must be an exact match to the real section name.
  dw_section_addr | On success returns the section address as defined by an object header.
  dw_section_size | On success returns the section size as defined by an object header.
  dw_section_flags | On success returns the section flags as defined by an object header. The flag meaning depends on which object format is being read and the meaning is defined by the object format. We hope it is of some use. In PE object files this field is called Characteristics.
  dw_section_offset | On success returns the section offset as defined by an object header. The offset meaning is supposedly an object file offset but the meaning depends on the object file type(!). We hope it is of some use.
  dw_error | On error returns the usual error pointer.

Returns
  Returns DW_DLV_OK etc.

## ◆ dwarf_get_section_max_offsets_d()

DW_API int dwarf_get_section_max_offsets_d | ( | Dwarf_Debug | dw_dbg,
|  | Dwarf_Unsigned * | dw_debug_info_size,
|  | Dwarf_Unsigned * | dw_debug_abbrev_size,
|  | Dwarf_Unsigned * | dw_debug_line_size,
|  | Dwarf_Unsigned * | dw_debug_loc_size,
|  | Dwarf_Unsigned * | dw_debug_aranges_size,
|  | Dwarf_Unsigned * | dw_debug_macinfo_size,
|  | Dwarf_Unsigned * | dw_debug_pubnames_size,
|  | Dwarf_Unsigned * | dw_debug_str_size,
|  | Dwarf_Unsigned * | dw_debug_frame_size,
|  | Dwarf_Unsigned * | dw_debug_ranges_size,
|  | Dwarf_Unsigned * | dw_debug_pubtypes_size,
|  | Dwarf_Unsigned * | dw_debug_types_size,
|  | Dwarf_Unsigned * | dw_debug_macro_size,
|  | Dwarf_Unsigned * | dw_debug_str_offsets_size,
|  | Dwarf_Unsigned * | dw_debug_sup_size,
|  | Dwarf_Unsigned * | dw_debug_cu_index_size,
|  | Dwarf_Unsigned * | dw_debug_tu_index_size,
|  | Dwarf_Unsigned * | dw_debug_names_size,
|  | Dwarf_Unsigned * | dw_debug_loclists_size,
|  | Dwarf_Unsigned * | dw_debug_rnglists_size )

Get section sizes for many sections.

The list of sections is incomplete and the argument list is ... too long ... making this an unusual function

Originally a hack so clients could verify offsets. Added so that one can detect broken offsets (which happened in an IRIX executable larger than 2GB with MIPSpro 7.3.1.3 toolchain.).

Parameters

  dw_dbg | Pass in a valid Dwarf_Debug of interest.

Returns
  If the dw_dbg is non-null it returns DW_DLV_OK. If dw_dbg is NULL it returns DW_DLV_NO_ENTRY.

## ◆ dwarf_machine_architecture()

DW_API int dwarf_machine_architecture | ( | Dwarf_Debug | dw_dbg,
|  | Dwarf_Small * | dw_ftype,
|  | Dwarf_Small * | dw_obj_pointersize,
|  | Dwarf_Bool * | dw_obj_is_big_endian,
|  | Dwarf_Unsigned * | dw_obj_machine,
|  | Dwarf_Unsigned * | dw_obj_flags,
|  | Dwarf_Small * | dw_path_source,
|  | Dwarf_Unsigned * | dw_ub_offset,
|  | Dwarf_Unsigned * | dw_ub_count,
|  | Dwarf_Unsigned * | dw_ub_index,
|  | Dwarf_Unsigned * | dw_comdat_groupnumber )

Get basic object information original version.

Identical to dwarf_machine_architecture_a() except that this older version does not have the the dw_obj_type argument so it cannot return the Elf e_type value..

## ◆ dwarf_machine_architecture_a()

DW_API int dwarf_machine_architecture_a | ( | Dwarf_Debug | dw_dbg,
|  | Dwarf_Small * | dw_ftype,
|  | Dwarf_Small * | dw_obj_pointersize,
|  | Dwarf_Bool * | dw_obj_is_big_endian,
|  | Dwarf_Unsigned * | dw_obj_machine,
|  | Dwarf_Unsigned * | dw_obj_type,
|  | Dwarf_Unsigned * | dw_obj_flags,
|  | Dwarf_Small * | dw_path_source,
|  | Dwarf_Unsigned * | dw_ub_offset,
|  | Dwarf_Unsigned * | dw_ub_count,
|  | Dwarf_Unsigned * | dw_ub_index,
|  | Dwarf_Unsigned * | dw_comdat_groupnumber )

Get basic object information from Dwarf_Debug.

Not all the fields here are relevant for all object types, and the dw_obj_machine and dw_obj_flags have ABI-defined values which have nothing to do with DWARF.

This version added December 2024 with an additional argument: dw_obj_type.

dwarf_ub_offset, dw_ub_count, dw_ub_index only apply to DW_FTYPE_APPLEUNIVERSAL.

dw_comdat_groupnumber only applies to DW_FTYPE_ELF.

Other than dw_dbg one can pass in NULL for any pointer parameter whose value is not of interest.

Parameters

  dw_dbg | The Dwarf_Debug of interest.
  dw_ftype | Pass in a pointer. On success the value pointed to will be set to the the applicable DW_FTYPE value (see libdwarf.h).
  dw_obj_pointersize | Pass in a pointer. On success the value pointed to will be set to the the applicable pointer size, which is almost always either 4 or 8.
  dw_obj_is_big_endian | Pass in a pointer. On success the value pointed to will be set to either 1 (the object being read is big-endia) or 0 (the object being read is little-endian.
  dw_obj_machine | Pass in a pointer. On success the value pointed to will be set to a value that the specific ABI uses for the machine-architecture the object file says it is for.
  dw_obj_type | Pass in a pointer. On success the value pointed to will be set to a value that the specific ABI uses for the machine-architecture the object file says it is for (for ELF is elf header e_type).
  dw_obj_flags | Pass in a pointer. On success the value pointed to will be set to a value that the specific ABI uses for a header record flags word (in a PE object the flags word is called Characteristics ).
  dw_path_source | Pass in a pointer. On success the value pointed to will be set to a value that libdwarf sets to a DW_PATHSOURCE value indicating what caused the file path.
  dw_ub_offset | Pass in a pointer. On success if the value of dw_ftype is DW_FTYPE_APPLEUNIVERSAL the returned value will be set to the count (in all other cases, the value is set to 0)
  dw_ub_count | Pass in a pointer. On success if the value of dw_ftype is DW_FTYPE_APPLEUNIVERSAL the returned value will be set to the number of object files in the binary (in all other cases, the value is set to 0)
  dw_ub_index | Pass in a pointer. On success if the value of dw_ftype is DW_FTYPE_APPLEUNIVERSAL the returned value will be set to the number of the specific object from the universal-binary, usable values are 0 through dw_ub_count-1. (in all other cases, the value is set to 0)
  dw_comdat_groupnumber | Pass in a pointer. On success if the value of dw_ftype is DW_FTYPE_ELF the returned value will be the comdat group being referenced. (in all other cases, the value is set to 0)

Returns
  Returns DW_DLV_NO_ENTRY if the Dwarf_Debug passed in is null or stale. Otherwise returns DW_DLV_OK and non-null return-value pointers will have meaningful data.