Libdwarf Initialization Functions

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_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. 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_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. 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) fd. 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_split_dbg, 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

Initialization And Finish Operations

Opening and closing libdwarf on object files.

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
	)

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()

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
	)

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()

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
	)

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()

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
	)

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_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
	)

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_finish()

int dwarf_finish

(

Dwarf_Debug

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_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
	)

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

See also

Demonstrating reading DWARF without a file.

and

See also

dw_noobject Reading DWARF not in object file

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_errarg	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_object_finish()

int dwarf_object_finish

(

Dwarf_Debug

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_set_tied_dbg()

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

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

dwarf_get_tied_dbg()

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

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().