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

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.

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

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 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_basedbg	Pass in an open dbg, on an object file with (normally) lots of DWARF..
dw_tied_dbg	Pass in an open dbg on an executable 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
	)

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

Functions

Detailed Description

Initialization And Finish Operations

Function Documentation

◆ dwarf_init_path()

◆ dwarf_init_path_dl()

◆ dwarf_init_b()

◆ dwarf_finish()

◆ dwarf_object_init_b()

◆ dwarf_object_finish()

◆ dwarf_set_tied_dbg()

◆ dwarf_get_tied_dbg()