|
libdwarf
|
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... | |
When DWARF is separate from a normal shared object. Has nothing to do with split-dwarf/debug-fission.
| 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.
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.
| dw_dbg | The Dwarf_Debug of interest. |
| dw_debuglink_path_returned | On success returns a pointer to a path in the debuglink section. Do not free! |
| dw_crc_returned | On success returns a pointer to a 4 byte area through the pointer. |
| dw_debuglink_fullpath_returned | On 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_returned | On success returns the strlen() of dw_debuglink_fullpath_returned . |
| dw_buildid_type_returned | On success returns a pointer to integer with a type code. See the buildid definition. |
| dw_buildid_owner_name_returned | On success returns a pointer to the owner name from the buildid section. Do not free this. |
| dw_buildid_returned | On success returns a pointer to a sequence of bytes containing the buildid. |
| dw_buildid_length_returned | On success this is set to the length of the set of bytes pointed to by dw_buildid_returned . |
| dw_paths_returned | On 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_returned | On success returns the length of the array of string pointers dw_paths_returned points at. |
| dw_error | The usual pointer to return error details. |
| 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.
| Defaults | to 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. |
| 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.
| dw_dbg | Pass in the Dwarf_Debug of interest. |
| dw_pathname | Pass in a pathname to add to the list of global paths used by debuglink. |
| dw_error | The usual pointer to return error details. |
| 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.
| dw_dbg | Pass 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_crcbuf | Pass in a pointer to a 4 byte area to hold the returned crc, on success the function puts the 4 bytes there. |
| dw_error | The usual pointer to return error details. |
| 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.
| dw_buf | Pass in a pointer to some bytes on which the crc calculation as done in debuglink is to be done. |
| dw_len | Pass in the length in bytes of dw_buf. |
| dw_init | Pass in the initial 32 bit value, zero is the right choice. |
1.8.17