Home | History | Annotate | Line # | Download | only in doc 
      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 @deftypefn {Function} bool bfd_check_format (bfd *abfd, bfd_format format); 
     32 Verify if the file attached to the BFD @var{abfd} is compatible
     33 with the format @var{format} (i.e., one of @code{bfd_object},
     34 @code{bfd_archive} or @code{bfd_core}).
     35 
     36 If the BFD has been set to a specific target before the
     37 call, only the named target and format combination is
     38 checked. If the target has not been set, or has been set to
     39 @code{default}, then all the known target backends is
     40 interrogated to determine a match.  If the default target
     41 matches, it is used.  If not, exactly one target must recognize
     42 the file, or an error results.
     43 
     44 The function returns @code{TRUE} on success, otherwise @code{FALSE}
     45 with one of the following error codes:
     46 
     47 @itemize @bullet
     48 
     49 @item
     50 @code{bfd_error_invalid_operation} -
     51 if @code{format} is not one of @code{bfd_object}, @code{bfd_archive} or
     52 @code{bfd_core}.
     53 
     54 @item
     55 @code{bfd_error_system_call} -
     56 if an error occured during a read - even some file mismatches
     57 can cause bfd_error_system_calls.
     58 
     59 @item
     60 @code{file_not_recognised} -
     61 none of the backends recognised the file format.
     62 
     63 @item
     64 @code{bfd_error_file_ambiguously_recognized} -
     65 more than one backend recognised the file format.
     66 @end itemize
     67 When calling bfd_check_format (or bfd_check_format_matches),
     68 any underlying file descriptor will be kept open for the
     69 duration of the call.  This is done to avoid races when
     70 another thread calls bfd_cache_close_all.  In this scenario,
     71 the thread calling bfd_check_format must call bfd_cache_close
     72 itself.
     73 
     74 @end deftypefn
     75 @findex bfd_check_format_matches
     76 @subsubsection @code{bfd_check_format_matches}
     77 @deftypefn {Function} bool bfd_check_format_matches (bfd *abfd, bfd_format format, char ***matching); 
     78 Like @code{bfd_check_format}, except when it returns FALSE with
     79 @code{bfd_errno} set to @code{bfd_error_file_ambiguously_recognized}.
     80 In that case, if @var{matching} is not NULL, it will be filled
     81 in with a NULL-terminated list of the names of the formats
     82 that matched, allocated with @code{malloc}.
     83 Then the user may choose a format and try again.
     84 
     85 When done with the list that @var{matching} points to, the caller
     86 should free it.
     87 
     88 @end deftypefn
     89 @findex bfd_set_format
     90 @subsubsection @code{bfd_set_format}
     91 @deftypefn {Function} bool bfd_set_format (bfd *abfd, bfd_format format); 
     92 This function sets the file format of the BFD @var{abfd} to the
     93 format @var{format}. If the target set in the BFD does not
     94 support the format requested, the format is invalid, or the BFD
     95 is not open for writing, then an error occurs.
     96 
     97 @end deftypefn
     98 @findex bfd_format_string
     99 @subsubsection @code{bfd_format_string}
    100 @deftypefn {Function} const char *bfd_format_string (bfd_format format); 
    101 Return a pointer to a const string
    102 @code{invalid}, @code{object}, @code{archive}, @code{core}, or @code{unknown},
    103 depending upon the value of @var{format}.
    104 
    105 @end deftypefn
    106