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