libdwarf
Functions
Access GNU .gnu_debuglink, build-id.

When DWARF is separate from a normal shared object. Has nothing to do with split-dwarf/debug-fission. More...

Functions

int dwarf_gnu_debuglink (Dwarf_Debug dw_dbg, char **dw_debuglink_path_returned, unsigned char **dw_crc_returned, char **dw_debuglink_fullpath_returned, unsigned int *dw_debuglink_path_length_returned, unsigned int *dw_buildid_type_returned, char **dw_buildid_owner_name_returned, unsigned char **dw_buildid_returned, unsigned int *dw_buildid_length_returned, char ***dw_paths_returned, unsigned int *dw_paths_length_returned, Dwarf_Error *dw_error)
 Find a separated DWARF object file. More...
 
int dwarf_suppress_debuglink_crc (int dw_suppress)
 Suppressing crc calculations. More...
 
int dwarf_add_debuglink_global_path (Dwarf_Debug dw_dbg, const char *dw_pathname, Dwarf_Error *dw_error)
 Adding debuglink global paths. More...
 
int dwarf_crc32 (Dwarf_Debug dw_dbg, unsigned char *dw_crcbuf, Dwarf_Error *dw_error)
 Crc32 used for debuglink crc calculation. More...
 
unsigned int dwarf_basic_crc32 (const unsigned char *dw_buf, unsigned long dw_len, unsigned int dw_init)
 Public interface to the real crc calculation. More...
 

Detailed Description

When DWARF is separate from a normal shared object. Has nothing to do with split-dwarf/debug-fission.

Function Documentation

◆ dwarf_gnu_debuglink()

int dwarf_gnu_debuglink ( Dwarf_Debug  dw_dbg,
char **  dw_debuglink_path_returned,
unsigned char **  dw_crc_returned,
char **  dw_debuglink_fullpath_returned,
unsigned int *  dw_debuglink_path_length_returned,
unsigned int *  dw_buildid_type_returned,
char **  dw_buildid_owner_name_returned,
unsigned char **  dw_buildid_returned,
unsigned int *  dw_buildid_length_returned,
char ***  dw_paths_returned,
unsigned int *  dw_paths_length_returned,
Dwarf_Error dw_error 
)

Find a separated DWARF object file.

.gnu_debuglink and/or the section .note.gnu.build-id.

Unless something is odd and you want to know details of the two sections you will not need this function.

See also
https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html
Example using GNU debuglink

If no debuglink then name_returned,crc_returned and debuglink_path_returned will get set 0 through the pointers.

If no .note.gnu.build-id then buildid_length_returned, and buildid_returned will be set 0 through the pointers.

In most cases output arguments can be passed as zero and the function will simply not return data through such arguments. Useful if you only care about some of the data potentially returned.

Caller frees space returned by debuglink_fullpath_returned.

Parameters
dw_dbgThe Dwarf_Debug of interest.
dw_debuglink_path_returnedOn success returns a pointer to a path in the debuglink section. Do not free!
dw_crc_returnedOn success returns a pointer to a 4 byte area through the pointer.
dw_debuglink_fullpath_returnedOn success returns a pointer to a full path computed from debuglink data of a correct path to a file with DWARF sections. Free this string when no longer of interest.
dw_debuglink_path_length_returnedOn success returns the strlen() of dw_debuglink_fullpath_returned .
dw_buildid_type_returnedOn success returns a pointer to integer with a type code. See the buildid definition.
dw_buildid_owner_name_returnedOn success returns a pointer to the owner name from the buildid section. Do not free this.
dw_buildid_returnedOn success returns a pointer to a sequence of bytes containing the buildid.
dw_buildid_length_returnedOn success this is set to the length of the set of bytes pointed to by dw_buildid_returned .
dw_paths_returnedOn success returns a pointer to an array of pointers to strings, each with a global path. It actually points to an array of pointers followed by a blob of strings, and freeing all of that just means calling free(dw_paths_returned).
dw_paths_length_returnedOn success returns the length of the array of string pointers dw_paths_returned points at.
dw_errorThe usual pointer to return error details.
Returns
Returns DW_DLV_OK etc.

◆ dwarf_suppress_debuglink_crc()

int dwarf_suppress_debuglink_crc ( int  dw_suppress)

Suppressing crc calculations.

The .gnu_debuglink section contains a compilation-system created crc (4 byte) value. If dwarf_init_path[_dl]() is called such a section can result in the reader/consumer calculating the crc value of a different object file. Which on a large object file could seem slow. See https://en.wikipedia.org/wiki/Cyclic_redundancy_check

When one is confident that any debug_link file found is the appropriate one one can call dwarf_suppress_debuglink_crc with a non-zero argument and any dwarf_init_path[_dl] call will skip debuglink crc calculations and just assume the crc would match whenever it applies. This is a global flag, applies to all Dwarf_Debug opened after the call in the program execution.

Does not apply to the .note.gnu.buildid section as that section never implies the reader/consumer needs to do a crc calculation.

Parameters
Defaultsto 0. Pass in 1 to suppress future calculation of crc values to verify a debuglink target is correct. So use only when you know this is safe. Pass in 0 to ensure future dwarf_init_path_dl calls compute debuglink CRC values as required.
Returns
Returns the previous value of the global flag.

Details on separate DWARF object access

◆ dwarf_add_debuglink_global_path()

int dwarf_add_debuglink_global_path ( Dwarf_Debug  dw_dbg,
const char *  dw_pathname,
Dwarf_Error dw_error 
)

Adding debuglink global paths.

Only really inside dwarfexample/dwdebuglink.c so we can show all that is going on. The following has the explanation for how debuglink and global paths interact.

See also
https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html
Parameters
dw_dbgPass in the Dwarf_Debug of interest.
dw_pathnamePass in a pathname to add to the list of global paths used by debuglink.
dw_errorThe usual pointer to return error details.
Returns
Returns DW_DLV_OK etc.

◆ dwarf_crc32()

int dwarf_crc32 ( Dwarf_Debug  dw_dbg,
unsigned char *  dw_crcbuf,
Dwarf_Error dw_error 
)

Crc32 used for debuglink crc calculation.

Caller passes pointer to array of 4 unsigned char provided by the caller and if this returns DW_DLV_OK that is filled in.

Parameters
dw_dbgPass in an open dw_dbg. When you attempted to open it, and it succeeded then pass the it via the Dwarf_Debug The function reads the file into memory and performs a crc calculation.
dw_crcbufPass in a pointer to a 4 byte area to hold the returned crc, on success the function puts the 4 bytes there.
dw_errorThe usual pointer to return error details.
Returns
Returns DW_DLV_OK etc.

◆ dwarf_basic_crc32()

unsigned int dwarf_basic_crc32 ( const unsigned char *  dw_buf,
unsigned long  dw_len,
unsigned int  dw_init 
)

Public interface to the real crc calculation.

It is unlikely this is useful.

Parameters
dw_bufPass in a pointer to some bytes on which the crc calculation as done in debuglink is to be done.
dw_lenPass in the length in bytes of dw_buf.
dw_initPass in the initial 32 bit value, zero is the right choice.
Returns
Returns an int (assumed 32 bits int!) with the calculated crc.