|
libdwarf
|
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. | |
| int | dwarf_suppress_debuglink_crc (int dw_suppress) |
| Suppressing crc calculations. | |
| int | dwarf_add_debuglink_global_path (Dwarf_Debug dw_dbg, const char *dw_pathname, Dwarf_Error *dw_error) |
| Adding debuglink global paths. | |
| int | dwarf_crc32 (Dwarf_Debug dw_dbg, unsigned char *dw_crcbuf, Dwarf_Error *dw_error) |
| Crc32 used for debuglink crc calculation. | |
| 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. | |
When DWARF sections are in a differenct object than the executable or a normal shared object. The special GNU section provides a way to name the object file with DWARF.
libdwarf will attempt to use this data to find the object file with DWARF.
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 | ||
| ) |
.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.
If dw_debuglink_fullpath returned is set by the call the space allocated must be freed by the caller with free(dw_debuglink_fullpath_returned).
if dw_debuglink_paths_returned is set by the call the space allocated must be free by the caller with free(dw_debuglink_paths_returned).
dwarf_finish() will not free strings dw_debuglink_fullpath_returned or dw_debuglink_paths_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 sets a pointer to an array of pointers to strings, each with a global path. These strings must be freed by the caller, dwarf_finish() will not free these strings. Call 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 | ) |
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.
| dw_suppress | 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 | ||
| ) |
Used inside src/bin/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 | ||
| ) |
Caller passes pointer to array of 4 unsigned char provided by the caller and if this returns DW_DLV_OK that array is filled in.
Callers must guarantee dw_crcbuf points to at least 4 bytes of writable memory. Passing in a null dw_crcbug results in an immediate return of DW_DLV_NO_ENTRY and the pointer is not used.
| 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 | ||
| ) |
It is unlikely this is useful. The calculation will not produce a return matching that of Linux/Macos if the compiler implements unsigned int or signed int as 16 bits long.
The caller must guarantee that dw_buf is non-null and pointing to dw_len bytes of readable memory. If dw_buf is NULL then 0 is immediately returned and there is no indication of error.
| 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.9.8