Untitled Document: Error reporting

Next: Miscellaneous, Previous: typedef bfd, 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`.

#### 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. If error_tag is bfd_error_on_input, then this function takes two more parameters, the input bfd where the error occurred, and the bfd_error_type error.

#### 2.2.1.3 `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.4 `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 printf.

    typedef void (*bfd_error_handler_type) (const char *, ...);

#### 2.2.2.1 `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.2 `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.2.3 `bfd_get_error_handler`

Synopsis

    bfd_error_handler_type bfd_get_error_handler (void);

Description
Return the BFD error handler 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.

#### 2.2.3.2 `bfd_get_assert_handler`

Synopsis

    bfd_assert_handler_type bfd_get_assert_handler (void);

Description
Return the BFD assert handler function.

Next: Miscellaneous, Previous: typedef bfd, Up: BFD front end [Contents][Index]