| @section File formats | |
| A format is a BFD concept of high level file contents type. The | |
| formats supported by BFD are: | |
| @itemize @bullet | |
| @item | |
| @code{bfd_object} | |
| @end itemize | |
| The BFD may contain data, symbols, relocations and debug info. | |
| @itemize @bullet | |
| @item | |
| @code{bfd_archive} | |
| @end itemize | |
| The BFD contains other BFDs and an optional index. | |
| @itemize @bullet | |
| @item | |
| @code{bfd_core} | |
| @end itemize | |
| The BFD contains the result of an executable core dump. | |
| @subsection File format functions | |
| @findex bfd_check_format | |
| @subsubsection @code{bfd_check_format} | |
| @strong{Synopsis} | |
| @example | |
| bfd_boolean bfd_check_format (bfd *abfd, bfd_format format); | |
| @end example | |
| @strong{Description}@* | |
| Verify if the file attached to the BFD @var{abfd} is compatible | |
| with the format @var{format} (i.e., one of @code{bfd_object}, | |
| @code{bfd_archive} or @code{bfd_core}). | |
| If the BFD has been set to a specific target before the | |
| call, only the named target and format combination is | |
| checked. If the target has not been set, or has been set to | |
| @code{default}, then all the known target backends is | |
| interrogated to determine a match. If the default target | |
| matches, it is used. If not, exactly one target must recognize | |
| the file, or an error results. | |
| The function returns @code{TRUE} on success, otherwise @code{FALSE} | |
| with one of the following error codes: | |
| @itemize @bullet | |
| @item | |
| @code{bfd_error_invalid_operation} - | |
| if @code{format} is not one of @code{bfd_object}, @code{bfd_archive} or | |
| @code{bfd_core}. | |
| @item | |
| @code{bfd_error_system_call} - | |
| if an error occured during a read - even some file mismatches | |
| can cause bfd_error_system_calls. | |
| @item | |
| @code{file_not_recognised} - | |
| none of the backends recognised the file format. | |
| @item | |
| @code{bfd_error_file_ambiguously_recognized} - | |
| more than one backend recognised the file format. | |
| @end itemize | |
| @findex bfd_check_format_matches | |
| @subsubsection @code{bfd_check_format_matches} | |
| @strong{Synopsis} | |
| @example | |
| bfd_boolean bfd_check_format_matches | |
| (bfd *abfd, bfd_format format, char ***matching); | |
| @end example | |
| @strong{Description}@* | |
| Like @code{bfd_check_format}, except when it returns FALSE with | |
| @code{bfd_errno} set to @code{bfd_error_file_ambiguously_recognized}. In that | |
| case, if @var{matching} is not NULL, it will be filled in with | |
| a NULL-terminated list of the names of the formats that matched, | |
| allocated with @code{malloc}. | |
| Then the user may choose a format and try again. | |
| When done with the list that @var{matching} points to, the caller | |
| should free it. | |
| @findex bfd_set_format | |
| @subsubsection @code{bfd_set_format} | |
| @strong{Synopsis} | |
| @example | |
| bfd_boolean bfd_set_format (bfd *abfd, bfd_format format); | |
| @end example | |
| @strong{Description}@* | |
| This function sets the file format of the BFD @var{abfd} to the | |
| format @var{format}. If the target set in the BFD does not | |
| support the format requested, the format is invalid, or the BFD | |
| is not open for writing, then an error occurs. | |
| @findex bfd_format_string | |
| @subsubsection @code{bfd_format_string} | |
| @strong{Synopsis} | |
| @example | |
| const char *bfd_format_string (bfd_format format); | |
| @end example | |
| @strong{Description}@* | |
| Return a pointer to a const string | |
| @code{invalid}, @code{object}, @code{archive}, @code{core}, or @code{unknown}, | |
| depending upon the value of @var{format}. | |