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