contrib/binutils/bfd/doc/format.texi

   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
  74    (bfd *abfd, bfd_format format, 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