bfd: Error reporting
2.2 Error reporting
===================
Most BFD functions return nonzero on success (check their individual
documentation for precise semantics). On an error, they call
'bfd_set_error' to set an error condition that callers can check by
calling 'bfd_get_error'. If that returns 'bfd_error_system_call', then
check 'errno'.
The easiest way to report a BFD error to the user is to use
'bfd_perror'.
2.2.1 Type 'bfd_error_type'
---------------------------
The values returned by 'bfd_get_error' are defined by the enumerated
type 'bfd_error_type'.
typedef enum bfd_error
{
bfd_error_no_error = 0,
bfd_error_system_call,
bfd_error_invalid_target,
bfd_error_wrong_format,
bfd_error_wrong_object_format,
bfd_error_invalid_operation,
bfd_error_no_memory,
bfd_error_no_symbols,
bfd_error_no_armap,
bfd_error_no_more_archived_files,
bfd_error_malformed_archive,
bfd_error_missing_dso,
bfd_error_file_not_recognized,
bfd_error_file_ambiguously_recognized,
bfd_error_no_contents,
bfd_error_nonrepresentable_section,
bfd_error_no_debug_section,
bfd_error_bad_value,
bfd_error_file_truncated,
bfd_error_file_too_big,
bfd_error_on_input,
bfd_error_invalid_error_code
}
bfd_error_type;
2.2.1.1 'bfd_get_error'
.......................
*Synopsis*
bfd_error_type bfd_get_error (void);
*Description*
Return the current BFD error condition.
2.2.1.2 'bfd_set_error'
.......................
*Synopsis*
void bfd_set_error (bfd_error_type error_tag);
*Description*
Set the BFD error condition to be ERROR_TAG.
ERROR_TAG must not be bfd_error_on_input. Use bfd_set_input_error
for input errors instead.
2.2.1.3 'bfd_set_input_error'
.............................
*Synopsis*
void bfd_set_input_error (bfd *input, bfd_error_type error_tag);
*Description*
Set the BFD error condition to be bfd_error_on_input. INPUT is the
input bfd where the error occurred, and ERROR_TAG the bfd_error_type
error.
2.2.1.4 'bfd_errmsg'
....................
*Synopsis*
const char *bfd_errmsg (bfd_error_type error_tag);
*Description*
Return a string describing the error ERROR_TAG, or the system error if
ERROR_TAG is 'bfd_error_system_call'.
2.2.1.5 'bfd_perror'
....................
*Synopsis*
void bfd_perror (const char *message);
*Description*
Print to the standard error stream a string describing the last BFD
error that occurred, or the last system error if the last BFD error was
a system call failure. If MESSAGE is non-NULL and non-empty, the error
string printed is preceded by MESSAGE, a colon, and a space. It is
followed by a newline.
2.2.2 BFD error handler
-----------------------
Some BFD functions want to print messages describing the problem. They
call a BFD error handler function. This function may be overridden by
the program.
The BFD error handler acts like vprintf.
typedef void (*bfd_error_handler_type) (const char *, va_list);
2.2.2.1 '_bfd_error_handler'
............................
*Synopsis*
void _bfd_error_handler (const char *fmt, ...) ATTRIBUTE_PRINTF_1;
*Description*
This is the default routine to handle BFD error messages. Like fprintf
(stderr, ...), but also handles some extra format specifiers.
%pA section name from section. For group components, prints group
name too. %pB file name from bfd. For archive components, prints
archive too.
Beware: Only supports a maximum of 9 format arguments.
2.2.2.2 'bfd_set_error_handler'
...............................
*Synopsis*
bfd_error_handler_type bfd_set_error_handler (bfd_error_handler_type);
*Description*
Set the BFD error handler function. Returns the previous function.
2.2.2.3 'bfd_set_error_program_name'
....................................
*Synopsis*
void bfd_set_error_program_name (const char *);
*Description*
Set the program name to use when printing a BFD error. This is printed
before the error message followed by a colon and space. The string must
not be changed after it is passed to this function.
2.2.3 BFD assert handler
------------------------
If BFD finds an internal inconsistency, the bfd assert handler is called
with information on the BFD version, BFD source file and line. If this
happens, most programs linked against BFD are expected to want to exit
with an error, or mark the current BFD operation as failed, so it is
recommended to override the default handler, which just calls
_bfd_error_handler and continues.
typedef void (*bfd_assert_handler_type) (const char *bfd_formatmsg,
const char *bfd_version,
const char *bfd_file,
int bfd_line);
2.2.3.1 'bfd_set_assert_handler'
................................
*Synopsis*
bfd_assert_handler_type bfd_set_assert_handler (bfd_assert_handler_type);
*Description*
Set the BFD assert handler function. Returns the previous function.
Info Catalog
bfd: typedef bfd
bfd: BFD front end
bfd: Miscellaneous