libdwarf: Libdwarf Initialization Functions

libdwarf

Loading...
Searching...
No Matches
Functions
Libdwarf Initialization Functions

## Functions
DW_API int | dwarf_init_path (const char *dw_path, char *dw_true_path_out_buffer, unsigned int dw_true_path_bufferlen, unsigned int dw_groupnumber, Dwarf_Handler dw_errhand, Dwarf_Ptr dw_errarg, Dwarf_Debug *dw_dbg, Dwarf_Error *dw_error)
| Initialization based on path, the most common initialization.
DW_API int | dwarf_init_path_a (const char *dw_path, char *dw_true_path_out_buffer, unsigned int dw_true_path_bufferlen, unsigned int dw_groupnumber, unsigned int dw_universalnumber, Dwarf_Handler dw_errhand, Dwarf_Ptr dw_errarg, Dwarf_Debug *dw_dbg, Dwarf_Error *dw_error)
| Initialization based on path.
DW_API int | dwarf_init_path_dl (const char *dw_path, char *dw_true_path_out_buffer, unsigned int dw_true_path_bufferlen, unsigned int dw_groupnumber, Dwarf_Handler dw_errhand, Dwarf_Ptr dw_errarg, Dwarf_Debug *dw_dbg, char **dw_dl_path_array, unsigned int dw_dl_path_array_size, unsigned char *dw_dl_path_source, Dwarf_Error *dw_error)
| Initialization following GNU debuglink section data.
DW_API int | dwarf_init_path_dl_a (const char *dw_path, char *dw_true_path_out_buffer, unsigned int dw_true_path_bufferlen, unsigned int dw_groupnumber, unsigned int dw_universalnumber, Dwarf_Handler dw_errhand, Dwarf_Ptr dw_errarg, Dwarf_Debug *dw_dbg, char **dw_dl_path_array, unsigned int dw_dl_path_array_size, unsigned char *dw_dl_path_source, Dwarf_Error *dw_error)
| Initialization based on path with debuglink.
DW_API int | dwarf_init_b (int dw_fd, unsigned int dw_groupnumber, Dwarf_Handler dw_errhand, Dwarf_Ptr dw_errarg, Dwarf_Debug *dw_dbg, Dwarf_Error *dw_error)
| Initialization based on Unix/Linux (etc) fd.
DW_API int | dwarf_finish (Dwarf_Debug dw_dbg)
| Close the initialized dw_dbg and free all data libdwarf has for this dw_dbg.
DW_API int | dwarf_object_init_b (Dwarf_Obj_Access_Interface_a *dw_obj, Dwarf_Handler dw_errhand, Dwarf_Ptr dw_errarg, unsigned int dw_groupnumber, Dwarf_Debug *dw_dbg, Dwarf_Error *dw_error)
| Used to access DWARF information in memory or in an object format unknown to libdwarf.
DW_API int | dwarf_object_finish (Dwarf_Debug dw_dbg)
| Used to close the object_init dw_dbg.
DW_API int | dwarf_set_tied_dbg (Dwarf_Debug dw_split_dbg, Dwarf_Debug dw_tied_dbg, Dwarf_Error *dw_error)
| Use with split dwarf.
DW_API int | dwarf_get_tied_dbg (Dwarf_Debug dw_dbg, Dwarf_Debug *dw_tieddbg_out, Dwarf_Error *dw_error)
| Use with split dwarf.

## Detailed Description

# Initialization And Finish Operations

Opening and closing libdwarf on object files.

## Function Documentation

## ◆ dwarf_finish()

DW_API int dwarf_finish | ( | Dwarf_Debug | dw_dbg | ) |

Close the initialized dw_dbg and free all data libdwarf has for this dw_dbg.

Parameters

  dw_dbg | Close the dbg.

Returns
  May return DW_DLV_ERROR if something is very wrong: no further information is available.. May return DW_DLV_NO_ENTRY but no further information is available. Normally returns DW_DLV_OK.

There is nothing the caller can do with the return value except report it somehow. Most callers ignore the return value.

## ◆ dwarf_get_tied_dbg()

DW_API int dwarf_get_tied_dbg | ( | Dwarf_Debug | dw_dbg,
|  | Dwarf_Debug * | dw_tieddbg_out,
|  | Dwarf_Error * | dw_error )

Use with split dwarf.

Given a main Dwarf_Debug this returns the tied Dwarf_Debug if there is one or else returns null(0).

Before v0.11.0 it was not defined what this returned if the tied-Dwarf_Debug was passed in, but it would have returned null(0) in that case. Unlikely anyone uses this call as callers had the tied and base dbg when calling dwarf_set_tied_dbg().

Parameters

  dw_dbg | Pass in a non-null Dwarf_Debug which is either a main-Dwarf_Debug or a tied-Dwarf_Debug.
  dw_tieddbg_out | On success returns the applicable tied-Dwarf_Debug through the pointer. If dw_dbg is a tied-Dwarf_Debug the function returns null(0) through the poiner. If there is no tied-Dwarf_Debug (meaning there is just a main-Dwarf_Debug) the function returns null (0) through the pointer.
  dw_error | If the dw_dbg is invalid or damaged then the function returns DW_DLV_ERROR and dw_error is set to point to the error details.

Returns
  DW_DLV_OK or DW_DLV_ERROR. Never returns DW_DLV_NO_ENTRY.

## ◆ dwarf_init_b()

DW_API int dwarf_init_b | ( | int | dw_fd,
|  | unsigned int | dw_groupnumber,
|  | Dwarf_Handler | dw_errhand,
|  | Dwarf_Ptr | dw_errarg,
|  | Dwarf_Debug * | dw_dbg,
|  | Dwarf_Error * | dw_error )

Initialization based on Unix/Linux (etc) fd.

In case DW_DLV_ERROR returned be sure to call dwarf_dealloc_error even though the returned Dwarf_Debug is NULL.

Parameters

  dw_fd | An open Unix/Linux/etc fd on the object file.
  dw_groupnumber | The value passed in should be DW_GROUPNUMBER_ANY unless one wishes to other than a standard group.
  dw_errhand | Pass in NULL unless one wishes libdwarf to call this error handling function (which you must write) instead of passing meaningful values to the dw_error argument.
  dw_errarg | If dw_errorhand is non-null, then this value (a pointer or integer that means something to you) is passed to the dw_errhand function in case that is helpful to you.
  dw_dbg | On success, *dw_dbg is set to a pointer to a new Dwarf_Debug structure to be used in calls to libdwarf functions.
  dw_error | In case return is DW_DLV_ERROR dw_error is set to point to the error details.

Returns
  DW_DLV_OK etc.

## ◆ dwarf_init_path()

DW_API int dwarf_init_path | ( | const char * | dw_path,
|  | char * | dw_true_path_out_buffer,
|  | unsigned int | dw_true_path_bufferlen,
|  | unsigned int | dw_groupnumber,
|  | Dwarf_Handler | dw_errhand,
|  | Dwarf_Ptr | dw_errarg,
|  | Dwarf_Debug * | dw_dbg,
|  | Dwarf_Error * | dw_error )

Initialization based on path, the most common initialization.

On a Mach-O universal binary this function can only return information about the first (zero index) object in the universal binary.

Parameters

  dw_path | Pass in the path to the object file to open.
  dw_true_path_out_buffer | Pass in NULL or the name of a string buffer (The buffer should be initialized with an initial NUL byte) The returned string will be null-terminated. The path actually used is copied to true_path_out. If true_path_buffer len is zero or true_path_out_buffer is zero then the Special Macos processing will not occur, nor will the GNU_debuglink processing occur. In case GNU debuglink data was followed or Macos dSYM applies the true_path_out will not match path and the initial byte will be non-null. The value put in true_path_out is the actual file name.
  dw_true_path_bufferlen | Pass in the length in bytes of the buffer.
  dw_groupnumber | The value passed in should be DW_GROUPNUMBER_ANY unless one wishes to other than a standard group.
  dw_errhand | Pass in NULL unless one wishes libdwarf to call this error handling function (which you must write) instead of passing meaningful values to the dw_error argument.
  dw_errarg | If dw_errorhand is non-null, then this value (a pointer or integer that means something to you) is passed to the dw_errhand function in case that is helpful to you.
  dw_dbg | On success, *dw_dbg is set to a pointer to a new Dwarf_Debug structure to be used in calls to libdwarf functions.
  dw_error | In case return is DW_DLV_ERROR dw_error is set to point to the error details.

Returns
  DW_DLV_OK etc.

Details on separate DWARF object access

See also
  dwarf_init_path_dl dwarf_init_b
  Using dwarf_init_path()

## ◆ dwarf_init_path_a()

DW_API int dwarf_init_path_a | ( | const char * | dw_path,
|  | char * | dw_true_path_out_buffer,
|  | unsigned int | dw_true_path_bufferlen,
|  | unsigned int | dw_groupnumber,
|  | unsigned int | dw_universalnumber,
|  | Dwarf_Handler | dw_errhand,
|  | Dwarf_Ptr | dw_errarg,
|  | Dwarf_Debug * | dw_dbg,
|  | Dwarf_Error * | dw_error )

Initialization based on path.

This identical to dwarf_init_path() except that it adds a new argument, dw_universalnumber, with which you can specify which object in a Mach-O universal binary you wish to open.

It is always safe and appropriate to pass zero as the dw_universalnumber. Elf and PE and (non-universal) Mach-O object files ignore the value of dw_universalnumber.

## ◆ dwarf_init_path_dl()

DW_API int dwarf_init_path_dl | ( | const char * | dw_path,
|  | char * | dw_true_path_out_buffer,
|  | unsigned int | dw_true_path_bufferlen,
|  | unsigned int | dw_groupnumber,
|  | Dwarf_Handler | dw_errhand,
|  | Dwarf_Ptr | dw_errarg,
|  | Dwarf_Debug * | dw_dbg,
|  | char ** | dw_dl_path_array,
|  | unsigned int | dw_dl_path_array_size,
|  | unsigned char * | dw_dl_path_source,
|  | Dwarf_Error * | dw_error )

Initialization following GNU debuglink section data.

Sets the true-path with DWARF if there is appropriate debuglink data available.

In case DW_DLV_ERROR returned be sure to call dwarf_dealloc_error even though the returned Dwarf_Debug is NULL.

Parameters

  dw_path | Pass in the path to the object file to open.
  dw_true_path_out_buffer | Pass in NULL or the name of a string buffer.
  dw_true_path_bufferlen | Pass in the length in bytes of the buffer.
  dw_groupnumber | The value passed in should be DW_GROUPNUMBER_ANY unless one wishes to other than a standard group.
  dw_errhand | Pass in NULL, normally. If non-null one wishes libdwarf to call this error handling function (which you must write) instead of passing meaningful values to the dw_error argument.
  dw_errarg | Pass in NULL, normally. If dw_errorhand is non-null, then this value (a pointer or integer that means something to you) is passed to the dw_errhand function in case that is helpful to you.
  dw_dbg | On success, *dw_dbg is set to a pointer to a new Dwarf_Debug structure to be used in calls to libdwarf functions.
  dw_dl_path_array | debuglink processing allows a user-specified set of file paths and this argument allows one to specify these. Pass in a pointer to array of pointers to strings which you, the caller, have filled in. The strings should be alternate paths (see the GNU debuglink documentation.)
  dw_dl_path_array_size | Specify the size of the dw_dl_path_array.
  dw_dl_path_source | returns DW_PATHSOURCE_basic or other such value so the caller can know how the true-path was resolved.
  dw_error | In case return is DW_DLV_ERROR dw_error is set to point to the error details.

Returns
  DW_DLV_OK etc.

Details on separate DWARF object access

See also
  Using dwarf_init_path_dl()

## ◆ dwarf_init_path_dl_a()

DW_API int dwarf_init_path_dl_a | ( | const char * | dw_path,
|  | char * | dw_true_path_out_buffer,
|  | unsigned int | dw_true_path_bufferlen,
|  | unsigned int | dw_groupnumber,
|  | unsigned int | dw_universalnumber,
|  | Dwarf_Handler | dw_errhand,
|  | Dwarf_Ptr | dw_errarg,
|  | Dwarf_Debug * | dw_dbg,
|  | char ** | dw_dl_path_array,
|  | unsigned int | dw_dl_path_array_size,
|  | unsigned char * | dw_dl_path_source,
|  | Dwarf_Error * | dw_error )

Initialization based on path with debuglink.

This identical to dwarf_init_path_dl() except that it adds a new argument, dw_universalnumber, with which you can specify which object in a Mach-O universal binary you wish to open.

It is always safe and appropriate to pass zero as the dw_universalnumber. Elf and PE and (non-universal) Mach-O object files ignore the value of dw_universalnumber.

Mach-O objects do not contain or use debuglink data.

## ◆ dwarf_object_finish()

DW_API int dwarf_object_finish | ( | Dwarf_Debug | dw_dbg | ) |

Used to close the object_init dw_dbg.

Close the dw_dbg opened by dwarf_object_init_b().

Parameters

  dw_dbg | Must be an open Dwarf_Debug opened by dwarf_object_init_b(). The init call dw_obj data is not freed by the call to dwarf_object_finish.

Returns
  The return value DW_DLV_OK etc is useless, one could possibly report it somehow. Callers usually ignore the return value.

## ◆ dwarf_object_init_b()

DW_API int dwarf_object_init_b | ( | Dwarf_Obj_Access_Interface_a * | dw_obj,
|  | Dwarf_Handler | dw_errhand,
|  | Dwarf_Ptr | dw_errarg,
|  | unsigned int | dw_groupnumber,
|  | Dwarf_Debug * | dw_dbg,
|  | Dwarf_Error * | dw_error )

Used to access DWARF information in memory or in an object format unknown to libdwarf.

In case DW_DLV_ERROR returned be sure to call dwarf_dealloc_error even though the returned Dwarf_Debug is NULL.

Since libdwarf is not reading the object directly in this case it us up to the code actually reading the object to check the object file for format and do sufficient format-specific checks for correctness and return DW_DLV_ERROR if object checks fail.

See also
  userobjread src/bin/dwarfexample/jitreader.c

Parameters

  dw_obj | A data structure filled out by the caller so libdwarf can access DWARF data not in a supported object file format.
  dw_errhand | Pass in NULL normally.
  dw_groupnumber | The value passed in should be DW_GROUPNUMBER_ANY unless one wishes to other than a standard group (quite unlikely for this interface).
  dw_dbg | On success, *dw_dbg is set to a pointer to a new Dwarf_Debug structure to be used in calls to libdwarf functions.
  dw_error | In case return is DW_DLV_ERROR dw_error is set to point to the error details.

Returns
  The usual value: DW_DLV_OK etc.

## ◆ dwarf_set_tied_dbg()

DW_API int dwarf_set_tied_dbg | ( | Dwarf_Debug | dw_split_dbg,
|  | Dwarf_Debug | dw_tied_dbg,
|  | Dwarf_Error * | dw_error )

Use with split dwarf.

In libdwarf usage the object file being reported on [a] is opened with dwarf_init_path() or the like. If that object file [a] is a split-dwarf object then important data needed to report all of what is in the object file [a] needs an open Dwarf_Debug on the base object file [b] (usually the base executable object). Here we call that executable object file [b] the tied object.

See DWARF5 Appendix F.

Parameters

  dw_split_dbg | Pass in an open dbg, on a split-dwarf object file with (normally) lots of DWARF but no executable code.
  dw_tied_dbg | Pass in an open dbg on an executable (we call it a tied dbg here) which has minimal DWARF (to save space in the executable).
  dw_error | In case return is DW_DLV_ERROR dw_error is set to point to the error details.

Returns
  DW_DLV_OK etc.

See also
  Attaching a tied dbg
  Detaching a tied dbg