format.texi revision 1.3
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