libdwarf
Functions
Libdwarf Initialization Functions

Opening and closing libdwarf on object files. More...

Functions

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. More...
 
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. More...
 
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) path This version allows specifying any number of debuglink global paths to search on for debuglink targets. More...
 
int dwarf_finish (Dwarf_Debug dw_dbg)
 Close the initialized dw_dbg and free all data libdwarf has for this dw_dbg. More...
 
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. More...
 
int dwarf_object_finish (Dwarf_Debug dw_dbg)
 Used to close the object_init dw_dbg. More...
 
int dwarf_set_tied_dbg (Dwarf_Debug dw_basedbg, Dwarf_Debug dw_tied_dbg, Dwarf_Error *dw_error)
 Use with split dwarf. More...
 
int dwarf_get_tied_dbg (Dwarf_Debug dw_dbg, Dwarf_Debug *dw_tieddbg_out, Dwarf_Error *dw_error)
 Use with split dwarf. More...
 

Detailed Description

Opening and closing libdwarf on object files.

Initialization And Finish Operations

Function Documentation

◆ dwarf_init_path()

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.

Parameters
dw_pathPass in the path to the object file to open.
dw_true_path_out_bufferPass 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_bufferlenPass in the length in bytes of the buffer.
dw_groupnumberThe value passed in should be DW_GROUPNUMBER_ANY unless one wishes to other than a standard group.
dw_errhandPass 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_errargIf 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_dbgOn success, *dw_dbg is set to a pointer to a new Dwarf_Debug structure to be used in calls to libdwarf functions.
dw_errorIn 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
Example of dwarf_init_path

◆ dwarf_init_path_dl()

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.

Parameters
dw_pathPass in the path to the object file to open.
dw_true_path_out_bufferPass in NULL or the name of a string buffer.
dw_true_path_bufferlenPass in the length in bytes of the buffer.
dw_groupnumberThe value passed in should be DW_GROUPNUMBER_ANY unless one wishes to other than a standard group.
dw_errhandPass 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_errargPass 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_dbgOn 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_arraydebuglink 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_sizeSpecify the size of the dw_dl_path_array.
dw_dl_path_sourcereturns DW_PATHSOURCE_basic or other such value so the caller can know how the true-path was resolved.
dw_errorIn 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
Example of dwarf_init_path_dl

◆ dwarf_init_b()

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) path This version allows specifying any number of debuglink global paths to search on for debuglink targets.

Parameters
dw_fdAn open Unix/Linux/etc fd on the object file.
dw_groupnumberThe value passed in should be DW_GROUPNUMBER_ANY unless one wishes to other than a standard group.
dw_errhandPass 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_errargIf 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_dbgOn success, *dw_dbg is set to a pointer to a new Dwarf_Debug structure to be used in calls to libdwarf functions.
dw_errorIn case return is DW_DLV_ERROR dw_error is set to point to the error details.
Returns
DW_DLV_OK etc.

◆ dwarf_finish()

int dwarf_finish ( Dwarf_Debug  dw_dbg)

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

Parameters
dw_dbgClose 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.

◆ dwarf_object_init_b()

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.

See also
Jitreader Demonstrating DWARF without a file.

and

See also
dw_noobject Reading DWARF not in object file
Parameters
dw_objA data structure filled out by the caller so libdwarf can access DWARF data not in a supported object file format.
dw_errhandPass in NULL normally.
dw_errargPass in NULL normally.
dw_groupnumberThe value passed in should be DW_GROUPNUMBER_ANY unless one wishes to other than a standard group (quite unlikely for this interface).
dw_dbgOn success, *dw_dbg is set to a pointer to a new Dwarf_Debug structure to be used in calls to libdwarf functions.
dw_errorIn 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_object_finish()

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_dbgMust 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 pretty useless, there is not much you can do with it.

◆ dwarf_set_tied_dbg()

int dwarf_set_tied_dbg ( Dwarf_Debug  dw_basedbg,
Dwarf_Debug  dw_tied_dbg,
Dwarf_Error dw_error 
)

Use with split dwarf.

Parameters
dw_basedbgPass in an open dbg, on an object file with (normally) lots of DWARF..
dw_tied_dbgPass in an open dbg on an executable which has minimal DWARF to save space in the executable.
dw_errorIn 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

◆ dwarf_get_tied_dbg()

int dwarf_get_tied_dbg ( Dwarf_Debug  dw_dbg,
Dwarf_Debug dw_tieddbg_out,
Dwarf_Error dw_error 
)

Use with split dwarf.

Given a base Dwarf_Debug this returns the tied Dwarf_Debug. Unlikely anyone uses this call as you had the tied and base dbg when calling dwarf_set_tied_dbg().