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