bfd/doc/targets.texi

   1 @section Targets
   2
   3
   4 @strong{Description}@*
   5 Each port of BFD to a different machine requires the creation
   6 of a target back end. All the back end provides to the root
   7 part of BFD is a structure containing pointers to functions
   8 which perform certain low level operations on files. BFD
   9 translates the applications's requests through a pointer into
  10 calls to the back end routines.
  11
  12 When a file is opened with @code{bfd_openr}, its format and
  13 target are unknown. BFD uses various mechanisms to determine
  14 how to interpret the file. The operations performed are:
  15
  16 @itemize @bullet
  17
  18 @item
  19 Create a BFD by calling the internal routine
  20 @code{_bfd_new_bfd}, then call @code{bfd_find_target} with the
  21 target string supplied to @code{bfd_openr} and the new BFD pointer.
  22
  23 @item
  24 If a null target string was provided to @code{bfd_find_target},
  25 look up the environment variable @code{GNUTARGET} and use
  26 that as the target string.
  27
  28 @item
  29 If the target string is still @code{NULL}, or the target string is
  30 @code{default}, then use the first item in the target vector
  31 as the target type, and set @code{target_defaulted} in the BFD to
  32 cause @code{bfd_check_format} to loop through all the targets.
  33 @xref{bfd_target}.  @xref{Formats}.
  34
  35 @item
  36 Otherwise, inspect the elements in the target vector
  37 one by one, until a match on target name is found. When found,
  38 use it.
  39
  40 @item
  41 Otherwise return the error @code{bfd_error_invalid_target} to
  42 @code{bfd_openr}.
  43
  44 @item
  45 @code{bfd_openr} attempts to open the file using
  46 @code{bfd_open_file}, and returns the BFD.
  47 @end itemize
  48 Once the BFD has been opened and the target selected, the file
  49 format may be determined. This is done by calling
  50 @code{bfd_check_format} on the BFD with a suggested format.
  51 If @code{target_defaulted} has been set, each possible target
  52 type is tried to see if it recognizes the specified format.
  53 @code{bfd_check_format} returns @code{TRUE} when the caller guesses right.
  54 @menu
  55 * bfd_target::
  56 @end menu
  57
  58 @node bfd_target,  , Targets, Targets
  59
  60 @subsection bfd_target
  61
  62
  63 @strong{Description}@*
  64 This structure contains everything that BFD knows about a
  65 target. It includes things like its byte order, name, and which
  66 routines to call to do various operations.
  67
  68 Every BFD points to a target structure with its @code{xvec}
  69 member.
  70
  71 The macros below are used to dispatch to functions through the
  72 @code{bfd_target} vector. They are used in a number of macros further
  73 down in @file{bfd.h}, and are also used when calling various
  74 routines by hand inside the BFD implementation.  The @var{arglist}
  75 argument must be parenthesized; it contains all the arguments
  76 to the called function.
  77
  78 They make the documentation (more) unpleasant to read, so if
  79 someone wants to fix this and not break the above, please do.
  80 @example
  81 #define BFD_SEND(bfd, message, arglist) \
  82   ((*((bfd)->xvec->message)) arglist)
  83
  84 #ifdef DEBUG_BFD_SEND
  85 #undef BFD_SEND
  86 #define BFD_SEND(bfd, message, arglist) \
  87   (((bfd) && (bfd)->xvec && (bfd)->xvec->message) ? \
  88     ((*((bfd)->xvec->message)) arglist) : \
  89     (bfd_assert (__FILE__,__LINE__), NULL))
  90 #endif
  91 @end example
  92 For operations which index on the BFD format:
  93 @example
  94 #define BFD_SEND_FMT(bfd, message, arglist) \
  95   (((bfd)->xvec->message[(int) ((bfd)->format)]) arglist)
  96
  97 #ifdef DEBUG_BFD_SEND
  98 #undef BFD_SEND_FMT
  99 #define BFD_SEND_FMT(bfd, message, arglist) \
 100   (((bfd) && (bfd)->xvec && (bfd)->xvec->message) ? \
 101    (((bfd)->xvec->message[(int) ((bfd)->format)]) arglist) : \
 102    (bfd_assert (__FILE__,__LINE__), NULL))
 103 #endif
 104
 105 @end example
 106 This is the structure which defines the type of BFD this is.  The
 107 @code{xvec} member of the struct @code{bfd} itself points here.  Each
 108 module that implements access to a different target under BFD,
 109 defines one of these.
 110
 111 FIXME, these names should be rationalised with the names of
 112 the entry points which call them. Too bad we can't have one
 113 macro to define them both!
 114 @example
 115 enum bfd_flavour
 116 @{
 117   bfd_target_unknown_flavour,
 118   bfd_target_aout_flavour,
 119   bfd_target_coff_flavour,
 120   bfd_target_ecoff_flavour,
 121   bfd_target_xcoff_flavour,
 122   bfd_target_elf_flavour,
 123   bfd_target_ieee_flavour,
 124   bfd_target_nlm_flavour,
 125   bfd_target_oasys_flavour,
 126   bfd_target_tekhex_flavour,
 127   bfd_target_srec_flavour,
 128   bfd_target_verilog_flavour,
 129   bfd_target_ihex_flavour,
 130   bfd_target_som_flavour,
 131   bfd_target_os9k_flavour,
 132   bfd_target_versados_flavour,
 133   bfd_target_msdos_flavour,
 134   bfd_target_ovax_flavour,
 135   bfd_target_evax_flavour,
 136   bfd_target_mmo_flavour,
 137   bfd_target_mach_o_flavour,
 138   bfd_target_pef_flavour,
 139   bfd_target_pef_xlib_flavour,
 140   bfd_target_sym_flavour
 141 @};
 142
 143 enum bfd_endian @{ BFD_ENDIAN_BIG, BFD_ENDIAN_LITTLE, BFD_ENDIAN_UNKNOWN @};
 144
 145 /* Forward declaration.  */
 146 typedef struct bfd_link_info _bfd_link_info;
 147
 148 /* Forward declaration.  */
 149 typedef struct flag_info flag_info;
 150
 151 typedef struct bfd_target
 152 @{
 153   /* Identifies the kind of target, e.g., SunOS4, Ultrix, etc.  */
 154   char *name;
 155
 156  /* The "flavour" of a back end is a general indication about
 157     the contents of a file.  */
 158   enum bfd_flavour flavour;
 159
 160   /* The order of bytes within the data area of a file.  */
 161   enum bfd_endian byteorder;
 162
 163  /* The order of bytes within the header parts of a file.  */
 164   enum bfd_endian header_byteorder;
 165
 166   /* A mask of all the flags which an executable may have set -
 167      from the set @code{BFD_NO_FLAGS}, @code{HAS_RELOC}, ...@code{D_PAGED}.  */
 168   flagword object_flags;
 169
 170  /* A mask of all the flags which a section may have set - from
 171     the set @code{SEC_NO_FLAGS}, @code{SEC_ALLOC}, ...@code{SET_NEVER_LOAD}.  */
 172   flagword section_flags;
 173
 174  /* The character normally found at the front of a symbol.
 175     (if any), perhaps `_'.  */
 176   char symbol_leading_char;
 177
 178  /* The pad character for file names within an archive header.  */
 179   char ar_pad_char;
 180
 181   /* The maximum number of characters in an archive header.  */
 182   unsigned char ar_max_namelen;
 183
 184   /* How well this target matches, used to select between various
 185      possible targets when more than one target matches.  */
 186   unsigned char match_priority;
 187
 188   /* Entries for byte swapping for data. These are different from the
 189      other entry points, since they don't take a BFD as the first argument.
 190      Certain other handlers could do the same.  */
 191   bfd_uint64_t   (*bfd_getx64) (const void *);
 192   bfd_int64_t    (*bfd_getx_signed_64) (const void *);
 193   void           (*bfd_putx64) (bfd_uint64_t, void *);
 194   bfd_vma        (*bfd_getx32) (const void *);
 195   bfd_signed_vma (*bfd_getx_signed_32) (const void *);
 196   void           (*bfd_putx32) (bfd_vma, void *);
 197   bfd_vma        (*bfd_getx16) (const void *);
 198   bfd_signed_vma (*bfd_getx_signed_16) (const void *);
 199   void           (*bfd_putx16) (bfd_vma, void *);
 200
 201   /* Byte swapping for the headers.  */
 202   bfd_uint64_t   (*bfd_h_getx64) (const void *);
 203   bfd_int64_t    (*bfd_h_getx_signed_64) (const void *);
 204   void           (*bfd_h_putx64) (bfd_uint64_t, void *);
 205   bfd_vma        (*bfd_h_getx32) (const void *);
 206   bfd_signed_vma (*bfd_h_getx_signed_32) (const void *);
 207   void           (*bfd_h_putx32) (bfd_vma, void *);
 208   bfd_vma        (*bfd_h_getx16) (const void *);
 209   bfd_signed_vma (*bfd_h_getx_signed_16) (const void *);
 210   void           (*bfd_h_putx16) (bfd_vma, void *);
 211
 212   /* Format dependent routines: these are vectors of entry points
 213      within the target vector structure, one for each format to check.  */
 214
 215   /* Check the format of a file being read.  Return a @code{bfd_target *} or zero.  */
 216   const struct bfd_target *(*_bfd_check_format[bfd_type_end]) (bfd *);
 217
 218   /* Set the format of a file being written.  */
 219   bfd_boolean (*_bfd_set_format[bfd_type_end]) (bfd *);
 220
 221   /* Write cached information into a file being written, at @code{bfd_close}.  */
 222   bfd_boolean (*_bfd_write_contents[bfd_type_end]) (bfd *);
 223
 224 @end example
 225 The general target vector.  These vectors are initialized using the
 226 BFD_JUMP_TABLE macros.
 227 @example
 228
 229   /* Generic entry points.  */
 230 #define BFD_JUMP_TABLE_GENERIC(NAME) \
 231   NAME##_close_and_cleanup, \
 232   NAME##_bfd_free_cached_info, \
 233   NAME##_new_section_hook, \
 234   NAME##_get_section_contents, \
 235   NAME##_get_section_contents_in_window
 236
 237   /* Called when the BFD is being closed to do any necessary cleanup.  */
 238   bfd_boolean (*_close_and_cleanup) (bfd *);
 239   /* Ask the BFD to free all cached information.  */
 240   bfd_boolean (*_bfd_free_cached_info) (bfd *);
 241   /* Called when a new section is created.  */
 242   bfd_boolean (*_new_section_hook) (bfd *, sec_ptr);
 243   /* Read the contents of a section.  */
 244   bfd_boolean (*_bfd_get_section_contents)
 245     (bfd *, sec_ptr, void *, file_ptr, bfd_size_type);
 246   bfd_boolean (*_bfd_get_section_contents_in_window)
 247     (bfd *, sec_ptr, bfd_window *, file_ptr, bfd_size_type);
 248
 249   /* Entry points to copy private data.  */
 250 #define BFD_JUMP_TABLE_COPY(NAME) \
 251   NAME##_bfd_copy_private_bfd_data, \
 252   NAME##_bfd_merge_private_bfd_data, \
 253   _bfd_generic_init_private_section_data, \
 254   NAME##_bfd_copy_private_section_data, \
 255   NAME##_bfd_copy_private_symbol_data, \
 256   NAME##_bfd_copy_private_header_data, \
 257   NAME##_bfd_set_private_flags, \
 258   NAME##_bfd_print_private_bfd_data
 259
 260   /* Called to copy BFD general private data from one object file
 261      to another.  */
 262   bfd_boolean (*_bfd_copy_private_bfd_data) (bfd *, bfd *);
 263   /* Called to merge BFD general private data from one object file
 264      to a common output file when linking.  */
 265   bfd_boolean (*_bfd_merge_private_bfd_data) (bfd *, bfd *);
 266   /* Called to initialize BFD private section data from one object file
 267      to another.  */
 268 #define bfd_init_private_section_data(ibfd, isec, obfd, osec, link_info) \
 269   BFD_SEND (obfd, _bfd_init_private_section_data, (ibfd, isec, obfd, osec, link_info))
 270   bfd_boolean (*_bfd_init_private_section_data)
 271     (bfd *, sec_ptr, bfd *, sec_ptr, struct bfd_link_info *);
 272   /* Called to copy BFD private section data from one object file
 273      to another.  */
 274   bfd_boolean (*_bfd_copy_private_section_data)
 275     (bfd *, sec_ptr, bfd *, sec_ptr);
 276   /* Called to copy BFD private symbol data from one symbol
 277      to another.  */
 278   bfd_boolean (*_bfd_copy_private_symbol_data)
 279     (bfd *, asymbol *, bfd *, asymbol *);
 280   /* Called to copy BFD private header data from one object file
 281      to another.  */
 282   bfd_boolean (*_bfd_copy_private_header_data)
 283     (bfd *, bfd *);
 284   /* Called to set private backend flags.  */
 285   bfd_boolean (*_bfd_set_private_flags) (bfd *, flagword);
 286
 287   /* Called to print private BFD data.  */
 288   bfd_boolean (*_bfd_print_private_bfd_data) (bfd *, void *);
 289
 290   /* Core file entry points.  */
 291 #define BFD_JUMP_TABLE_CORE(NAME) \
 292   NAME##_core_file_failing_command, \
 293   NAME##_core_file_failing_signal, \
 294   NAME##_core_file_matches_executable_p, \
 295   NAME##_core_file_pid
 296
 297   char *      (*_core_file_failing_command) (bfd *);
 298   int         (*_core_file_failing_signal) (bfd *);
 299   bfd_boolean (*_core_file_matches_executable_p) (bfd *, bfd *);
 300   int         (*_core_file_pid) (bfd *);
 301
 302   /* Archive entry points.  */
 303 #define BFD_JUMP_TABLE_ARCHIVE(NAME) \
 304   NAME##_slurp_armap, \
 305   NAME##_slurp_extended_name_table, \
 306   NAME##_construct_extended_name_table, \
 307   NAME##_truncate_arname, \
 308   NAME##_write_armap, \
 309   NAME##_read_ar_hdr, \
 310   NAME##_write_ar_hdr, \
 311   NAME##_openr_next_archived_file, \
 312   NAME##_get_elt_at_index, \
 313   NAME##_generic_stat_arch_elt, \
 314   NAME##_update_armap_timestamp
 315
 316   bfd_boolean (*_bfd_slurp_armap) (bfd *);
 317   bfd_boolean (*_bfd_slurp_extended_name_table) (bfd *);
 318   bfd_boolean (*_bfd_construct_extended_name_table)
 319     (bfd *, char **, bfd_size_type *, const char **);
 320   void        (*_bfd_truncate_arname) (bfd *, const char *, char *);
 321   bfd_boolean (*write_armap)
 322     (bfd *, unsigned int, struct orl *, unsigned int, int);
 323   void *      (*_bfd_read_ar_hdr_fn) (bfd *);
 324   bfd_boolean (*_bfd_write_ar_hdr_fn) (bfd *, bfd *);
 325   bfd *       (*openr_next_archived_file) (bfd *, bfd *);
 326 #define bfd_get_elt_at_index(b,i) BFD_SEND (b, _bfd_get_elt_at_index, (b,i))
 327   bfd *       (*_bfd_get_elt_at_index) (bfd *, symindex);
 328   int         (*_bfd_stat_arch_elt) (bfd *, struct stat *);
 329   bfd_boolean (*_bfd_update_armap_timestamp) (bfd *);
 330
 331   /* Entry points used for symbols.  */
 332 #define BFD_JUMP_TABLE_SYMBOLS(NAME) \
 333   NAME##_get_symtab_upper_bound, \
 334   NAME##_canonicalize_symtab, \
 335   NAME##_make_empty_symbol, \
 336   NAME##_print_symbol, \
 337   NAME##_get_symbol_info, \
 338   NAME##_bfd_is_local_label_name, \
 339   NAME##_bfd_is_target_special_symbol, \
 340   NAME##_get_lineno, \
 341   NAME##_find_nearest_line, \
 342   _bfd_generic_find_line, \
 343   NAME##_find_inliner_info, \
 344   NAME##_bfd_make_debug_symbol, \
 345   NAME##_read_minisymbols, \
 346   NAME##_minisymbol_to_symbol
 347
 348   long        (*_bfd_get_symtab_upper_bound) (bfd *);
 349   long        (*_bfd_canonicalize_symtab)
 350     (bfd *, struct bfd_symbol **);
 351   struct bfd_symbol *
 352               (*_bfd_make_empty_symbol) (bfd *);
 353   void        (*_bfd_print_symbol)
 354     (bfd *, void *, struct bfd_symbol *, bfd_print_symbol_type);
 355 #define bfd_print_symbol(b,p,s,e) BFD_SEND (b, _bfd_print_symbol, (b,p,s,e))
 356   void        (*_bfd_get_symbol_info)
 357     (bfd *, struct bfd_symbol *, symbol_info *);
 358 #define bfd_get_symbol_info(b,p,e) BFD_SEND (b, _bfd_get_symbol_info, (b,p,e))
 359   bfd_boolean (*_bfd_is_local_label_name) (bfd *, const char *);
 360   bfd_boolean (*_bfd_is_target_special_symbol) (bfd *, asymbol *);
 361   alent *     (*_get_lineno) (bfd *, struct bfd_symbol *);
 362   bfd_boolean (*_bfd_find_nearest_line)
 363     (bfd *, struct bfd_section *, struct bfd_symbol **, bfd_vma,
 364      const char **, const char **, unsigned int *);
 365   bfd_boolean (*_bfd_find_line)
 366     (bfd *, struct bfd_symbol **, struct bfd_symbol *,
 367      const char **, unsigned int *);
 368   bfd_boolean (*_bfd_find_inliner_info)
 369     (bfd *, const char **, const char **, unsigned int *);
 370  /* Back-door to allow format-aware applications to create debug symbols
 371     while using BFD for everything else.  Currently used by the assembler
 372     when creating COFF files.  */
 373   asymbol *   (*_bfd_make_debug_symbol)
 374     (bfd *, void *, unsigned long size);
 375 #define bfd_read_minisymbols(b, d, m, s) \
 376   BFD_SEND (b, _read_minisymbols, (b, d, m, s))
 377   long        (*_read_minisymbols)
 378     (bfd *, bfd_boolean, void **, unsigned int *);
 379 #define bfd_minisymbol_to_symbol(b, d, m, f) \
 380   BFD_SEND (b, _minisymbol_to_symbol, (b, d, m, f))
 381   asymbol *   (*_minisymbol_to_symbol)
 382     (bfd *, bfd_boolean, const void *, asymbol *);
 383
 384   /* Routines for relocs.  */
 385 #define BFD_JUMP_TABLE_RELOCS(NAME) \
 386   NAME##_get_reloc_upper_bound, \
 387   NAME##_canonicalize_reloc, \
 388   NAME##_bfd_reloc_type_lookup, \
 389   NAME##_bfd_reloc_name_lookup
 390
 391   long        (*_get_reloc_upper_bound) (bfd *, sec_ptr);
 392   long        (*_bfd_canonicalize_reloc)
 393     (bfd *, sec_ptr, arelent **, struct bfd_symbol **);
 394   /* See documentation on reloc types.  */
 395   reloc_howto_type *
 396               (*reloc_type_lookup) (bfd *, bfd_reloc_code_real_type);
 397   reloc_howto_type *
 398               (*reloc_name_lookup) (bfd *, const char *);
 399
 400
 401   /* Routines used when writing an object file.  */
 402 #define BFD_JUMP_TABLE_WRITE(NAME) \
 403   NAME##_set_arch_mach, \
 404   NAME##_set_section_contents
 405
 406   bfd_boolean (*_bfd_set_arch_mach)
 407     (bfd *, enum bfd_architecture, unsigned long);
 408   bfd_boolean (*_bfd_set_section_contents)
 409     (bfd *, sec_ptr, const void *, file_ptr, bfd_size_type);
 410
 411   /* Routines used by the linker.  */
 412 #define BFD_JUMP_TABLE_LINK(NAME) \
 413   NAME##_sizeof_headers, \
 414   NAME##_bfd_get_relocated_section_contents, \
 415   NAME##_bfd_relax_section, \
 416   NAME##_bfd_link_hash_table_create, \
 417   NAME##_bfd_link_hash_table_free, \
 418   NAME##_bfd_link_add_symbols, \
 419   NAME##_bfd_link_just_syms, \
 420   NAME##_bfd_copy_link_hash_symbol_type, \
 421   NAME##_bfd_final_link, \
 422   NAME##_bfd_link_split_section, \
 423   NAME##_bfd_gc_sections, \
 424   NAME##_bfd_lookup_section_flags, \
 425   NAME##_bfd_merge_sections, \
 426   NAME##_bfd_is_group_section, \
 427   NAME##_bfd_discard_group, \
 428   NAME##_section_already_linked, \
 429   NAME##_bfd_define_common_symbol
 430
 431   int         (*_bfd_sizeof_headers) (bfd *, struct bfd_link_info *);
 432   bfd_byte *  (*_bfd_get_relocated_section_contents)
 433     (bfd *, struct bfd_link_info *, struct bfd_link_order *,
 434      bfd_byte *, bfd_boolean, struct bfd_symbol **);
 435
 436   bfd_boolean (*_bfd_relax_section)
 437     (bfd *, struct bfd_section *, struct bfd_link_info *, bfd_boolean *);
 438
 439   /* Create a hash table for the linker.  Different backends store
 440      different information in this table.  */
 441   struct bfd_link_hash_table *
 442               (*_bfd_link_hash_table_create) (bfd *);
 443
 444   /* Release the memory associated with the linker hash table.  */
 445   void        (*_bfd_link_hash_table_free) (struct bfd_link_hash_table *);
 446
 447   /* Add symbols from this object file into the hash table.  */
 448   bfd_boolean (*_bfd_link_add_symbols) (bfd *, struct bfd_link_info *);
 449
 450   /* Indicate that we are only retrieving symbol values from this section.  */
 451   void        (*_bfd_link_just_syms) (asection *, struct bfd_link_info *);
 452
 453   /* Copy the symbol type of a linker hash table entry.  */
 454 #define bfd_copy_link_hash_symbol_type(b, t, f) \
 455   BFD_SEND (b, _bfd_copy_link_hash_symbol_type, (b, t, f))
 456   void (*_bfd_copy_link_hash_symbol_type)
 457     (bfd *, struct bfd_link_hash_entry *, struct bfd_link_hash_entry *);
 458
 459   /* Do a link based on the link_order structures attached to each
 460      section of the BFD.  */
 461   bfd_boolean (*_bfd_final_link) (bfd *, struct bfd_link_info *);
 462
 463   /* Should this section be split up into smaller pieces during linking.  */
 464   bfd_boolean (*_bfd_link_split_section) (bfd *, struct bfd_section *);
 465
 466   /* Remove sections that are not referenced from the output.  */
 467   bfd_boolean (*_bfd_gc_sections) (bfd *, struct bfd_link_info *);
 468
 469   /* Sets the bitmask of allowed and disallowed section flags.  */
 470   void (*_bfd_lookup_section_flags) (struct bfd_link_info *,
 471                                      struct flag_info *);
 472
 473   /* Attempt to merge SEC_MERGE sections.  */
 474   bfd_boolean (*_bfd_merge_sections) (bfd *, struct bfd_link_info *);
 475
 476   /* Is this section a member of a group?  */
 477   bfd_boolean (*_bfd_is_group_section) (bfd *, const struct bfd_section *);
 478
 479   /* Discard members of a group.  */
 480   bfd_boolean (*_bfd_discard_group) (bfd *, struct bfd_section *);
 481
 482   /* Check if SEC has been already linked during a reloceatable or
 483      final link.  */
 484   bfd_boolean (*_section_already_linked) (bfd *, asection *,
 485                                           struct bfd_link_info *);
 486
 487   /* Define a common symbol.  */
 488   bfd_boolean (*_bfd_define_common_symbol) (bfd *, struct bfd_link_info *,
 489                                             struct bfd_link_hash_entry *);
 490
 491   /* Routines to handle dynamic symbols and relocs.  */
 492 #define BFD_JUMP_TABLE_DYNAMIC(NAME) \
 493   NAME##_get_dynamic_symtab_upper_bound, \
 494   NAME##_canonicalize_dynamic_symtab, \
 495   NAME##_get_synthetic_symtab, \
 496   NAME##_get_dynamic_reloc_upper_bound, \
 497   NAME##_canonicalize_dynamic_reloc
 498
 499   /* Get the amount of memory required to hold the dynamic symbols.  */
 500   long        (*_bfd_get_dynamic_symtab_upper_bound) (bfd *);
 501   /* Read in the dynamic symbols.  */
 502   long        (*_bfd_canonicalize_dynamic_symtab)
 503     (bfd *, struct bfd_symbol **);
 504   /* Create synthetized symbols.  */
 505   long        (*_bfd_get_synthetic_symtab)
 506     (bfd *, long, struct bfd_symbol **, long, struct bfd_symbol **,
 507      struct bfd_symbol **);
 508   /* Get the amount of memory required to hold the dynamic relocs.  */
 509   long        (*_bfd_get_dynamic_reloc_upper_bound) (bfd *);
 510   /* Read in the dynamic relocs.  */
 511   long        (*_bfd_canonicalize_dynamic_reloc)
 512     (bfd *, arelent **, struct bfd_symbol **);
 513
 514 @end example
 515 A pointer to an alternative bfd_target in case the current one is not
 516 satisfactory.  This can happen when the target cpu supports both big
 517 and little endian code, and target chosen by the linker has the wrong
 518 endianness.  The function open_output() in ld/ldlang.c uses this field
 519 to find an alternative output format that is suitable.
 520 @example
 521   /* Opposite endian version of this target.  */
 522   const struct bfd_target * alternative_target;
 523
 524   /* Data for use by back-end routines, which isn't
 525      generic enough to belong in this structure.  */
 526   const void *backend_data;
 527
 528 @} bfd_target;
 529
 530 @end example
 531
 532 @findex bfd_set_default_target
 533 @subsubsection @code{bfd_set_default_target}
 534 @strong{Synopsis}
 535 @example
 536 bfd_boolean bfd_set_default_target (const char *name);
 537 @end example
 538 @strong{Description}@*
 539 Set the default target vector to use when recognizing a BFD.
 540 This takes the name of the target, which may be a BFD target
 541 name or a configuration triplet.
 542
 543 @findex bfd_find_target
 544 @subsubsection @code{bfd_find_target}
 545 @strong{Synopsis}
 546 @example
 547 const bfd_target *bfd_find_target (const char *target_name, bfd *abfd);
 548 @end example
 549 @strong{Description}@*
 550 Return a pointer to the transfer vector for the object target
 551 named @var{target_name}.  If @var{target_name} is @code{NULL},
 552 choose the one in the environment variable @code{GNUTARGET}; if
 553 that is null or not defined, then choose the first entry in the
 554 target list.  Passing in the string "default" or setting the
 555 environment variable to "default" will cause the first entry in
 556 the target list to be returned, and "target_defaulted" will be
 557 set in the BFD if @var{abfd} isn't @code{NULL}.  This causes
 558 @code{bfd_check_format} to loop over all the targets to find the
 559 one that matches the file being read.
 560
 561 @findex bfd_get_target_info
 562 @subsubsection @code{bfd_get_target_info}
 563 @strong{Synopsis}
 564 @example
 565 const bfd_target *bfd_get_target_info (const char *target_name,
 566     bfd *abfd,
 567     bfd_boolean *is_bigendian,
 568     int *underscoring,
 569     const char **def_target_arch);
 570 @end example
 571 @strong{Description}@*
 572 Return a pointer to the transfer vector for the object target
 573 named @var{target_name}.  If @var{target_name} is @code{NULL},
 574 choose the one in the environment variable @code{GNUTARGET}; if
 575 that is null or not defined, then choose the first entry in the
 576 target list.  Passing in the string "default" or setting the
 577 environment variable to "default" will cause the first entry in
 578 the target list to be returned, and "target_defaulted" will be
 579 set in the BFD if @var{abfd} isn't @code{NULL}.  This causes
 580 @code{bfd_check_format} to loop over all the targets to find the
 581 one that matches the file being read.
 582 If @var{is_bigendian} is not @code{NULL}, then set this value to target's
 583 endian mode. True for big-endian, FALSE for little-endian or for
 584 invalid target.
 585 If @var{underscoring} is not @code{NULL}, then set this value to target's
 586 underscoring mode. Zero for none-underscoring, -1 for invalid target,
 587 else the value of target vector's symbol underscoring.
 588 If @var{def_target_arch} is not @code{NULL}, then set it to the architecture
 589 string specified by the target_name.
 590
 591 @findex bfd_target_list
 592 @subsubsection @code{bfd_target_list}
 593 @strong{Synopsis}
 594 @example
 595 const char ** bfd_target_list (void);
 596 @end example
 597 @strong{Description}@*
 598 Return a freshly malloced NULL-terminated
 599 vector of the names of all the valid BFD targets. Do not
 600 modify the names.
 601
 602 @findex bfd_seach_for_target
 603 @subsubsection @code{bfd_seach_for_target}
 604 @strong{Synopsis}
 605 @example
 606 const bfd_target *bfd_search_for_target
 607    (int (*search_func) (const bfd_target *, void *),
 608     void *);
 609 @end example
 610 @strong{Description}@*
 611 Return a pointer to the first transfer vector in the list of
 612 transfer vectors maintained by BFD that produces a non-zero
 613 result when passed to the function @var{search_func}.  The
 614 parameter @var{data} is passed, unexamined, to the search
 615 function.
 616