contrib/binutils-2.17/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 @subsection File format functions
  27
  28
  29 @findex bfd_check_format
  30 @subsubsection @code{bfd_check_format}
  31 @strong{Synopsis}
  32 @example
  33 bfd_boolean bfd_check_format (bfd *abfd, bfd_format format);
  34 @end example
  35 @strong{Description}@*
  36 Verify if the file attached to the BFD @var{abfd} is compatible
  37 with the format @var{format} (i.e., one of @code{bfd_object},
  38 @code{bfd_archive} or @code{bfd_core}).
  39
  40 If the BFD has been set to a specific target before the
  41 call, only the named target and format combination is
  42 checked. If the target has not been set, or has been set to
  43 @code{default}, then all the known target backends is
  44 interrogated to determine a match.  If the default target
  45 matches, it is used.  If not, exactly one target must recognize
  46 the file, or an error results.
  47
  48 The function returns @code{TRUE} on success, otherwise @code{FALSE}
  49 with one of the following error codes:
  50
  51 @itemize @bullet
  52
  53 @item
  54 @code{bfd_error_invalid_operation} -
  55 if @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} -
  60 if an error occured during a read - even some file mismatches
  61 can cause bfd_error_system_calls.
  62
  63 @item
  64 @code{file_not_recognised} -
  65 none of the backends recognised the file format.
  66
  67 @item
  68 @code{bfd_error_file_ambiguously_recognized} -
  69 more 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
  76 bfd_boolean bfd_check_format_matches
  77    (bfd *abfd, bfd_format format, char ***matching);
  78 @end example
  79 @strong{Description}@*
  80 Like @code{bfd_check_format}, except when it returns FALSE with
  81 @code{bfd_errno} set to @code{bfd_error_file_ambiguously_recognized}.  In that
  82 case, if @var{matching} is not NULL, it will be filled in with
  83 a NULL-terminated list of the names of the formats that matched,
  84 allocated with @code{malloc}.
  85 Then the user may choose a format and try again.
  86
  87 When done with the list that @var{matching} points to, the caller
  88 should free it.
  89
  90 @findex bfd_set_format
  91 @subsubsection @code{bfd_set_format}
  92 @strong{Synopsis}
  93 @example
  94 bfd_boolean bfd_set_format (bfd *abfd, bfd_format format);
  95 @end example
  96 @strong{Description}@*
  97 This function sets the file format of the BFD @var{abfd} to the
  98 format @var{format}. If the target set in the BFD does not
  99 support the format requested, the format is invalid, or the BFD
 100 is 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
 106 const char *bfd_format_string (bfd_format format);
 107 @end example
 108 @strong{Description}@*
 109 Return a pointer to a const string
 110 @code{invalid}, @code{object}, @code{archive}, @code{core}, or @code{unknown},
 111 depending upon the value of @var{format}.
 112