libdwarf: Harmless Error recording

libdwarf

Loading...
Searching...
No Matches
Macros | Functions
Harmless Error recording

## Macros
#define | DW_HARMLESS_ERROR_CIRCULAR_LIST_DEFAULT_SIZE 4
| Default size of the libdwarf-internal circular list.

## Functions
DW_API int | dwarf_get_harmless_error_list (Dwarf_Debug dw_dbg, unsigned int dw_count, const char **dw_errmsg_ptrs_array, unsigned int *dw_newerr_count)
| Get the harmless error count and content.
DW_API unsigned int | dwarf_set_harmless_error_list_size (Dwarf_Debug dw_dbg, unsigned int dw_maxcount)
| The size of the circular list of strings libdwarf holds internally may be set and reset as needed. If it is shortened excess messages are simply dropped. It returns the previous size. If zero passed in the size is unchanged and it simply returns the current size.
DW_API int | dwarf_set_harmless_errors_enabled (Dwarf_Debug dw_dbg, int dw_v)
| Enable or disable libdwarf tracking of harmless errors. Harmless errors are used by tools like dwarfdump. Disabling harmless errors can improve performance by avoiding string copies. Defaults to enabled.
DW_API void | dwarf_insert_harmless_error (Dwarf_Debug dw_dbg, char *dw_newerror)
| Harmless Error Insertion is only for testing.

## Detailed Description

The harmless error list is a fixed size circular buffer of errors we note but which do not stop us from processing the object. Created so dwarfdump or other tools can report such inconsequential errors without causing anything to stop early.

You can change the list size from the default of DW_HARMLESS_ERROR_CIRCULAR_LIST_DEFAULT_SIZE at any time for a Dwarf_Debug dbg.

Harmless error data is dealloc'd by dwarf_finish().

## Function Documentation

## ◆ dwarf_get_harmless_error_list()

DW_API int dwarf_get_harmless_error_list | ( | Dwarf_Debug | dw_dbg,
|  | unsigned int | dw_count,
|  | const char ** | dw_errmsg_ptrs_array,
|  | unsigned int * | dw_newerr_count )

Get the harmless error count and content.

User code supplies size of array of pointers dw_errmsg_ptrs_array in count and the array of pointers (the pointers themselves need not be initialized). The pointers returned in the array of pointers are invalidated by ANY call to libdwarf. Use them before making another libdwarf call! The array of string pointers passed in always has a final null pointer, so if there are N pointers the and M actual strings, then MIN(M,N-1) pointers are set to point to error strings. The array of pointers to strings always terminates with a NULL pointer. Do not free the strings. Every string is null-terminated.

Each call empties the error list (discarding all current entries). and fills in your array

Parameters

  dw_dbg | The applicable Dwarf_Debug.
  dw_count | The number of string buffers. If count is passed as zero no elements of the array are touched.
  dw_errmsg_ptrs_array | A pointer to a user-created array of pointer to const char.
  dw_newerr_count | If non-NULL the count of harmless errors pointers since the last call is returned through the pointer. If dw_count is greater than zero the first dw_count of the pointers in the user-created array point to null-terminated strings. Do not free the strings. print or copy the strings before any other libdwarf call.

Returns
  Returns DW_DLV_NO_ENTRY if no harmless errors were noted so far. Returns DW_DLV_OK if there are harmless errors. Never returns DW_DLV_ERROR.

If DW_DLV_NO_ENTRY is returned none of the arguments other than dw_dbg are touched or used.

## ◆ dwarf_insert_harmless_error()

DW_API void dwarf_insert_harmless_error | ( | Dwarf_Debug | dw_dbg,
|  | char * | dw_newerror )

Harmless Error Insertion is only for testing.

Useful for testing the harmless error mechanism.

Parameters

  dw_dbg | Pass in an open Dwarf_Debug
  dw_newerror | Pass in a string whose content the function inserts as a harmless error (which dwarf_get_harmless_error_list will retrieve).

## ◆ dwarf_set_harmless_error_list_size()

DW_API unsigned int dwarf_set_harmless_error_list_size | ( | Dwarf_Debug | dw_dbg,
|  | unsigned int | dw_maxcount )

The size of the circular list of strings libdwarf holds internally may be set and reset as needed. If it is shortened excess messages are simply dropped. It returns the previous size. If zero passed in the size is unchanged and it simply returns the current size.

Parameters

  dw_dbg | The applicable Dwarf_Debug.
  dw_maxcount | Set the new internal buffer count to a number greater than zero.

Returns
  returns the current size of the internal circular buffer if dw_maxcount is zero. If dw_maxcount is greater than zero the internal array is adjusted to hold that many and the previous number of harmless errors possible in the circular buffer is returned.

## ◆ dwarf_set_harmless_errors_enabled()

DW_API int dwarf_set_harmless_errors_enabled | ( | Dwarf_Debug | dw_dbg,
|  | int | dw_v )

Enable or disable libdwarf tracking of harmless errors. Harmless errors are used by tools like dwarfdump. Disabling harmless errors can improve performance by avoiding string copies. Defaults to enabled.

Parameters

  dw_dbg | Pass in an open Dwarf_Debug
  dw_v | If zero passed in, harmless errors will not be tracked and libdwarf will run somewhat faster If non-zero passed in libdwarf will resume or continue tracking harmless errors

Returns
  Returns the previous version of the flag.