libdwarf: Miscellaneous Functions

libdwarf

Loading...
Searching...
No Matches
Functions | Variables
Miscellaneous Functions

## Functions
DW_API const char * | dwarf_package_version (void)
| Return the version string in the library.
DW_API int | dwarf_set_stringcheck (int dw_stringcheck)
| Turn off libdwarf checks of strings.
DW_API int | dwarf_set_reloc_application (int dw_apply)
| Set libdwarf response to *.rela relocations.
DW_API void | dwarf_record_cmdline_options (Dwarf_Cmdline_Options dw_dd_options)
| Tell libdwarf to add verbosity to Line Header errors By default the flag in the struct argument is zero. dwarfdump uses this when -v used on dwarfdump.
DW_API int | dwarf_set_de_alloc_flag (int dw_v)
| Eliminate libdwarf tracking of allocations Independent of any Dwarf_Debug and applicable to all whenever the setting is changed. Defaults to non-zero.
DW_API int | dwarf_library_allow_dup_attr (int dw_v)
| Eliminate libdwarf checking attribute duplication.
DW_API Dwarf_Small | dwarf_set_default_address_size (Dwarf_Debug dw_dbg, Dwarf_Small dw_value)
| Set the address size on a Dwarf_Debug.
DW_API int | dwarf_get_universalbinary_count (Dwarf_Debug dw_dbg, Dwarf_Unsigned *dw_current_index, Dwarf_Unsigned *dw_available_count)
| Retrieve universal binary index.

## Variables
DW_API void(*)(void *, const void *, unsigned long) | dwarf_get_endian_copy_function (Dwarf_Debug dw_dbg)
| Get a pointer to the applicable swap/noswap function.
DW_API Dwarf_Cmdline_Options | dwarf_cmdline_options

## Detailed Description

## Function Documentation

## ◆ dwarf_get_universalbinary_count()

DW_API int dwarf_get_universalbinary_count | ( | Dwarf_Debug | dw_dbg,
|  | Dwarf_Unsigned * | dw_current_index,
|  | Dwarf_Unsigned * | dw_available_count )

Retrieve universal binary index.

For Mach-O universal binaries this returns relevant information.

For non-universal binaries (Mach-O, Elf, or PE) the values are not meaningful, so the function returns DW_DLV_NO_ENTRY..

Parameters

  dw_dbg | The Dwarf_Debug of interest.
  dw_current_index | If dw_current_index is passed in non-null the function returns the universal-binary index of the current object (which came from a universal binary).
  dw_available_count | If dw_current_index is passed in non-null the function returns the count of binaries in the universal binary.

Returns
  Returns DW_DLV_NO_ENTRY if the object file is not from a Mach-O universal binary. Returns DW_DLV_NO_ENTRY if dw_dbg is passed in NULL. Never returns DW_DLV_ERROR.

## ◆ dwarf_library_allow_dup_attr()

DW_API int dwarf_library_allow_dup_attr | ( | int | dw_v | ) |

Eliminate libdwarf checking attribute duplication.

Independent of any Dwarf_Debug, this is sets a global flag in libdwarf and is applicable to all whenever the setting is changed. Defaults to zero so by default libdwarf does check every set of abbreviations for duplicate attributes.

DWARF5 Sec 2.2 Attribute Types Each attribute value is characterized by an attribute name. No more than one attribute with a given name may appear in any debugging information entry. Essentially the same wording is in Sec 2.2 of DWARF2, DWARF3 and DWARF4.

Do not call this with non-zero dw_v unless you really want the library to avoid this basic DWARF-correctness check.

Since
  {0.12.0}

Parameters

  dw_v | If non-zero passed in libdwarf will avoid the checks and will not return errors for an abbreviation list with duplicate attributes.

Returns
  Returns the previous version of the flag.

## ◆ dwarf_package_version()

DW_API const char * dwarf_package_version | ( | void |  | ) |

Return the version string in the library.

An example: "0.3.0" which is a Semantic Version identifier. Before September 2021 the version string was a date, for example "20210528", which is in ISO date format. See DW_LIBDWARF_VERSION DW_LIBDWARF_VERSION_MAJOR DW_LIBDWARF_VERSION_MINOR DW_LIBDWARF_VERSION_MICRO

Returns
  The Package Version built into libdwarf.so or libdwarf.a

## ◆ dwarf_record_cmdline_options()

DW_API void dwarf_record_cmdline_options | ( | Dwarf_Cmdline_Options | dw_dd_options | ) |

Tell libdwarf to add verbosity to Line Header errors By default the flag in the struct argument is zero. dwarfdump uses this when -v used on dwarfdump.

See also
  dwarf_register_printf_callback

Parameters

  dw_dd_options | The structure has one flag, and if the flag is nonzero and there is an error in reading a line table header the function passes back detail error messages via dwarf_register_printf_callback.

## ◆ dwarf_set_de_alloc_flag()

DW_API int dwarf_set_de_alloc_flag | ( | int | dw_v | ) |

Eliminate libdwarf tracking of allocations Independent of any Dwarf_Debug and applicable to all whenever the setting is changed. Defaults to non-zero.

Parameters

  dw_v | If zero passed in libdwarf will run somewhat faster and library memory allocations will not all be tracked and dwarf_finish() will be unable to free/dealloc some things. User code can do the necessary deallocs (as documented), but the normal guarantee that libdwarf will clean up is revoked. If non-zero passed in libdwarf will resume or continue tracking allocations

Returns
  Returns the previous version of the flag.

## ◆ dwarf_set_default_address_size()

DW_API Dwarf_Small dwarf_set_default_address_size | ( | Dwarf_Debug | dw_dbg,
|  | Dwarf_Small | dw_value )

Set the address size on a Dwarf_Debug.

DWARF information CUs and other section DWARF headers define a CU-specific address size, but this Dwarf_Debug value is used when other address size information does not exist, for example in a DWARF2 CIE or FDE.

Parameters

  dw_dbg | The Dwarf_Debug of interest.
  dw_value | Sets the address size for the Dwarf_Debug to a non-zero value. The default address size is derived from headers in the object file. Values larger than the size of Dwarf_Addr are not set. If zero passed the default is not changed.

Returns
  Returns the last set address size.

## ◆ dwarf_set_reloc_application()

DW_API int dwarf_set_reloc_application | ( | int | dw_apply | ) |

Set libdwarf response to *.rela relocations.

dw_apply defaults to 1 and means apply all '.rela' relocations on reading in a dwarf object section of such relocations. Best to just ignore this function It applies to all Dwarf_Debug open and all opened later in this library instance.

Parameters

  dw_apply | Pass in a zero to turn off reading and applying of .rela relocations, which will likely break reading of .o object files but probably will not break reading executables or shared objects. Pass in non zero (it is really just an 8 bit value, so use a small value) to turn off inspecting .rela sections.

Returns
  Returns the previous value of the apply flag.

## ◆ dwarf_set_stringcheck()

DW_API int dwarf_set_stringcheck | ( | int | dw_stringcheck | ) |

Turn off libdwarf checks of strings.

Zero is the default and means do all string length validity checks. It applies to all Dwarf_Debug open and all opened later in this library instance.

Parameters

  dw_stringcheck | Pass in a small non-zero value to turn off all libdwarf string validity checks. It speeds up libdwarf, but...is dangerous and voids all promises the library will not segfault.

Returns
  Returns the previous value of this flag.

## Variable Documentation

## ◆ dwarf_get_endian_copy_function

DW_API void(*)(void *, const void *, unsigned long) dwarf_get_endian_copy_function(Dwarf_Debug dw_dbg) | ( | Dwarf_Debug | dw_dbg | ) |

Get a pointer to the applicable swap/noswap function.

the function pointer returned enables libdwarf users to use the same 64bit/32bit/16bit word copy as libdwarf does internally for the Dwarf_Debug passed in. The function makes it possible for libdwarf to read either endianness.

Parameters

  dw_dbg | Pass in a pointer to the applicable Dwarf_Debug.

Returns
  a pointer to a copy function. If the object file referred to and the libdwarf reading that file are the same endianness the function returned will, when called, do a simple memcpy, effectively, while otherwise it would do a byte-swapping copy. It seems unlikely this will be useful to most library users. To call the copy function returned the first argument must be a pointer to the target word and the second must be a pointer to the input word. The third argument is the length to be copied and it must be 2,4,or 8.