1@section File formats
2A format is a BFD concept of high level file contents type. The
3formats supported by BFD are:
4
5@itemize @bullet
6
7@item
8@code{bfd_object}
9@end itemize
10The BFD may contain data, symbols, relocations and debug info.
11
12@itemize @bullet
13
14@item
15@code{bfd_archive}
16@end itemize
17The BFD contains other BFDs and an optional index.
18
19@itemize @bullet
20
21@item
22@code{bfd_core}
23@end itemize
24The BFD contains the result of an executable core dump.
25
26@subsection File format functions
27
28
29@findex bfd_check_format
30@subsubsection @code{bfd_check_format}
31@strong{Synopsis}
32@example
33bfd_boolean bfd_check_format (bfd *abfd, bfd_format format);
34@end example
35@strong{Description}@*
36Verify if the file attached to the BFD @var{abfd} is compatible
37with the format @var{format} (i.e., one of @code{bfd_object},
38@code{bfd_archive} or @code{bfd_core}).
39
40If the BFD has been set to a specific target before the
41call, only the named target and format combination is
42checked. If the target has not been set, or has been set to
43@code{default}, then all the known target backends is
44interrogated to determine a match.  If the default target
45matches, it is used.  If not, exactly one target must recognize
46the file, or an error results.
47
48The function returns @code{TRUE} on success, otherwise @code{FALSE}
49with one of the following error codes:
50
51@itemize @bullet
52
53@item
54@code{bfd_error_invalid_operation} -
55if @code{format} is not one of @code{bfd_object}, @code{bfd_archive} or
56@code{bfd_core}.
57
58@item
59@code{bfd_error_system_call} -
60if an error occured during a read - even some file mismatches
61can cause bfd_error_system_calls.
62
63@item
64@code{file_not_recognised} -
65none of the backends recognised the file format.
66
67@item
68@code{bfd_error_file_ambiguously_recognized} -
69more than one backend recognised the file format.
70@end itemize
71
72@findex bfd_check_format_matches
73@subsubsection @code{bfd_check_format_matches}
74@strong{Synopsis}
75@example
76bfd_boolean bfd_check_format_matches
77   (bfd *abfd, bfd_format format, char ***matching);
78@end example
79@strong{Description}@*
80Like @code{bfd_check_format}, except when it returns FALSE with
81@code{bfd_errno} set to @code{bfd_error_file_ambiguously_recognized}.  In that
82case, if @var{matching} is not NULL, it will be filled in with
83a NULL-terminated list of the names of the formats that matched,
84allocated with @code{malloc}.
85Then the user may choose a format and try again.
86
87When done with the list that @var{matching} points to, the caller
88should free it.
89
90@findex bfd_set_format
91@subsubsection @code{bfd_set_format}
92@strong{Synopsis}
93@example
94bfd_boolean bfd_set_format (bfd *abfd, bfd_format format);
95@end example
96@strong{Description}@*
97This function sets the file format of the BFD @var{abfd} to the
98format @var{format}. If the target set in the BFD does not
99support the format requested, the format is invalid, or the BFD
100is not open for writing, then an error occurs.
101
102@findex bfd_format_string
103@subsubsection @code{bfd_format_string}
104@strong{Synopsis}
105@example
106const char *bfd_format_string (bfd_format format);
107@end example
108@strong{Description}@*
109Return a pointer to a const string
110@code{invalid}, @code{object}, @code{archive}, @code{core}, or @code{unknown},
111depending upon the value of @var{format}.
112
113