Next: , Previous: , Up: BFD Front End   [Contents][Index]

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.

The BFD error is thread-local.

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_sorry,
  bfd_error_on_input,
  bfd_error_invalid_error_code
}
bfd_error_type;

2.2.1.1 bfd_get_error

Function: bfd_error_type bfd_get_error (void);

Return the current BFD error condition.

2.2.1.2 bfd_set_error

Function: void bfd_set_error (bfd_error_type error_tag);

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

Function: void bfd_set_input_error (bfd *input, bfd_error_type error_tag);

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

Function: const char *bfd_errmsg (bfd_error_type error_tag);

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

Function: void bfd_perror (const char *message);

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

Function: char *bfd_asprintf (const char *fmt, ...);

Primarily for error reporting, this function is like libiberty’s xasprintf except that it can return NULL on no memory and the returned string should not be freed. Uses a thread-local malloc’d buffer managed by libbfd, _bfd_error_buf. Be aware that a call to this function frees the result of any previous call. bfd_errmsg (bfd_error_on_input) also calls this function.

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);


typedef int (*bfd_print_callback) (void *, const char *, ...);

2.2.2.1 bfd_print_error

Function: void bfd_print_error (bfd_print_callback print_func, void *stream, const char *fmt, va_list ap);

This formats FMT and AP according to BFD "printf" rules, sending the output to STREAM by repeated calls to PRINT_FUNC. PRINT_FUNC is a printf-like function; it does not need to implement the BFD printf format extensions. This can be used in a callback that is set via bfd_set_error_handler to turn the error into ordinary output.

2.2.2.2 _bfd_error_handler

Function: void _bfd_error_handler (const char *fmt, ...) ATTRIBUTE_PRINTF_1;

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

Function: bfd_error_handler_type bfd_set_error_handler (bfd_error_handler_type);

Set the BFD error handler function. Returns the previous function.

2.2.2.4 _bfd_set_error_handler_caching

Function: struct per_xvec_messages *_bfd_set_error_handler_caching (struct per_xvec_messages *);

Set the BFD error handler function to one that stores messages to the per_xvec_messages object. Returns the previous object to which messages are stored. Note that two sequential calls to this with a non-NULL argument will cause output to be dropped, rather than gathered.

2.2.2.5 _bfd_restore_error_handler_caching

Function: void _bfd_restore_error_handler_caching (struct per_xvec_messages *);

Reset the BFD error handler object to an earlier value.

2.2.2.6 bfd_set_error_program_name

Function: void bfd_set_error_program_name (const char *);

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

Function: const char *_bfd_get_error_program_name (void);

Get the program name used when printing a BFD error.

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

Function: bfd_assert_handler_type bfd_set_assert_handler (bfd_assert_handler_type);

Set the BFD assert handler function. Returns the previous function.

Next: bfd_init, Previous: typedef bfd, Up: BFD Front End   [Contents][Index]