1 files changed, 112 insertions, 0 deletions
diff --git a/bfd/doc/format.texi b/bfd/doc/format.texi
new file mode 100644
index 0000000..9674acf
--- /dev/null
+++ b/bfd/doc/format.texi
@@ -0,0 +1,112 @@
+@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}.
+