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 typedef struct bfd_target
 149 @{
 150   /* Identifies the kind of target, e.g., SunOS4, Ultrix, etc.  */
 151   char *name;
 152
 153  /* The "flavour" of a back end is a general indication about
 154     the contents of a file.  */
 155   enum bfd_flavour flavour;
 156
 157   /* The order of bytes within the data area of a file.  */
 158   enum bfd_endian byteorder;
 159
 160  /* The order of bytes within the header parts of a file.  */
 161   enum bfd_endian header_byteorder;
 162
 163   /* A mask of all the flags which an executable may have set -
 164      from the set @code{BFD_NO_FLAGS}, @code{HAS_RELOC}, ...@code{D_PAGED}.  */
 165   flagword object_flags;
 166
 167  /* A mask of all the flags which a section may have set - from
 168     the set @code{SEC_NO_FLAGS}, @code{SEC_ALLOC}, ...@code{SET_NEVER_LOAD}.  */
 169   flagword section_flags;
 170
 171  /* The character normally found at the front of a symbol.
 172     (if any), perhaps `_'.  */
 173   char symbol_leading_char;
 174
 175  /* The pad character for file names within an archive header.  */
 176   char ar_pad_char;
 177
 178   /* The maximum number of characters in an archive header.  */
 179   unsigned short ar_max_namelen;
 180
 181   /* Entries for byte swapping for data. These are different from the
 182      other entry points, since they don't take a BFD as the first argument.
 183      Certain other handlers could do the same.  */
 184   bfd_uint64_t   (*bfd_getx64) (const void *);
 185   bfd_int64_t    (*bfd_getx_signed_64) (const void *);
 186   void           (*bfd_putx64) (bfd_uint64_t, void *);
 187   bfd_vma        (*bfd_getx32) (const void *);
 188   bfd_signed_vma (*bfd_getx_signed_32) (const void *);
 189   void           (*bfd_putx32) (bfd_vma, void *);
 190   bfd_vma        (*bfd_getx16) (const void *);
 191   bfd_signed_vma (*bfd_getx_signed_16) (const void *);
 192   void           (*bfd_putx16) (bfd_vma, void *);
 193
 194   /* Byte swapping for the headers.  */
 195   bfd_uint64_t   (*bfd_h_getx64) (const void *);
 196   bfd_int64_t    (*bfd_h_getx_signed_64) (const void *);
 197   void           (*bfd_h_putx64) (bfd_uint64_t, void *);
 198   bfd_vma        (*bfd_h_getx32) (const void *);
 199   bfd_signed_vma (*bfd_h_getx_signed_32) (const void *);
 200   void           (*bfd_h_putx32) (bfd_vma, void *);
 201   bfd_vma        (*bfd_h_getx16) (const void *);
 202   bfd_signed_vma (*bfd_h_getx_signed_16) (const void *);
 203   void           (*bfd_h_putx16) (bfd_vma, void *);
 204
 205   /* Format dependent routines: these are vectors of entry points
 206      within the target vector structure, one for each format to check.  */
 207
 208   /* Check the format of a file being read.  Return a @code{bfd_target *} or zero.  */
 209   const struct bfd_target *(*_bfd_check_format[bfd_type_end]) (bfd *);
 210
 211   /* Set the format of a file being written.  */
 212   bfd_boolean (*_bfd_set_format[bfd_type_end]) (bfd *);
 213
 214   /* Write cached information into a file being written, at @code{bfd_close}.  */
 215   bfd_boolean (*_bfd_write_contents[bfd_type_end]) (bfd *);
 216
 217 @end example
 218 The general target vector.  These vectors are initialized using the
 219 BFD_JUMP_TABLE macros.
 220 @example
 221
 222   /* Generic entry points.  */
 223 #define BFD_JUMP_TABLE_GENERIC(NAME) \
 224   NAME##_close_and_cleanup, \
 225   NAME##_bfd_free_cached_info, \
 226   NAME##_new_section_hook, \
 227   NAME##_get_section_contents, \
 228   NAME##_get_section_contents_in_window
 229
 230   /* Called when the BFD is being closed to do any necessary cleanup.  */
 231   bfd_boolean (*_close_and_cleanup) (bfd *);
 232   /* Ask the BFD to free all cached information.  */
 233   bfd_boolean (*_bfd_free_cached_info) (bfd *);
 234   /* Called when a new section is created.  */
 235   bfd_boolean (*_new_section_hook) (bfd *, sec_ptr);
 236   /* Read the contents of a section.  */
 237   bfd_boolean (*_bfd_get_section_contents)
 238     (bfd *, sec_ptr, void *, file_ptr, bfd_size_type);
 239   bfd_boolean (*_bfd_get_section_contents_in_window)
 240     (bfd *, sec_ptr, bfd_window *, file_ptr, bfd_size_type);
 241
 242   /* Entry points to copy private data.  */
 243 #define BFD_JUMP_TABLE_COPY(NAME) \
 244   NAME##_bfd_copy_private_bfd_data, \
 245   NAME##_bfd_merge_private_bfd_data, \
 246   _bfd_generic_init_private_section_data, \
 247   NAME##_bfd_copy_private_section_data, \
 248   NAME##_bfd_copy_private_symbol_data, \
 249   NAME##_bfd_copy_private_header_data, \
 250   NAME##_bfd_set_private_flags, \
 251   NAME##_bfd_print_private_bfd_data
 252
 253   /* Called to copy BFD general private data from one object file
 254      to another.  */
 255   bfd_boolean (*_bfd_copy_private_bfd_data) (bfd *, bfd *);
 256   /* Called to merge BFD general private data from one object file
 257      to a common output file when linking.  */
 258   bfd_boolean (*_bfd_merge_private_bfd_data) (bfd *, bfd *);
 259   /* Called to initialize BFD private section data from one object file
 260      to another.  */
 261 #define bfd_init_private_section_data(ibfd, isec, obfd, osec, link_info) \
 262   BFD_SEND (obfd, _bfd_init_private_section_data, (ibfd, isec, obfd, osec, link_info))
 263   bfd_boolean (*_bfd_init_private_section_data)
 264     (bfd *, sec_ptr, bfd *, sec_ptr, struct bfd_link_info *);
 265   /* Called to copy BFD private section data from one object file
 266      to another.  */
 267   bfd_boolean (*_bfd_copy_private_section_data)
 268     (bfd *, sec_ptr, bfd *, sec_ptr);
 269   /* Called to copy BFD private symbol data from one symbol
 270      to another.  */
 271   bfd_boolean (*_bfd_copy_private_symbol_data)
 272     (bfd *, asymbol *, bfd *, asymbol *);
 273   /* Called to copy BFD private header data from one object file
 274      to another.  */
 275   bfd_boolean (*_bfd_copy_private_header_data)
 276     (bfd *, bfd *);
 277   /* Called to set private backend flags.  */
 278   bfd_boolean (*_bfd_set_private_flags) (bfd *, flagword);
 279
 280   /* Called to print private BFD data.  */
 281   bfd_boolean (*_bfd_print_private_bfd_data) (bfd *, void *);
 282
 283   /* Core file entry points.  */
 284 #define BFD_JUMP_TABLE_CORE(NAME) \
 285   NAME##_core_file_failing_command, \
 286   NAME##_core_file_failing_signal, \
 287   NAME##_core_file_matches_executable_p
 288
 289   char *      (*_core_file_failing_command) (bfd *);
 290   int         (*_core_file_failing_signal) (bfd *);
 291   bfd_boolean (*_core_file_matches_executable_p) (bfd *, bfd *);
 292
 293   /* Archive entry points.  */
 294 #define BFD_JUMP_TABLE_ARCHIVE(NAME) \
 295   NAME##_slurp_armap, \
 296   NAME##_slurp_extended_name_table, \
 297   NAME##_construct_extended_name_table, \
 298   NAME##_truncate_arname, \
 299   NAME##_write_armap, \
 300   NAME##_read_ar_hdr, \
 301   NAME##_openr_next_archived_file, \
 302   NAME##_get_elt_at_index, \
 303   NAME##_generic_stat_arch_elt, \
 304   NAME##_update_armap_timestamp
 305
 306   bfd_boolean (*_bfd_slurp_armap) (bfd *);
 307   bfd_boolean (*_bfd_slurp_extended_name_table) (bfd *);
 308   bfd_boolean (*_bfd_construct_extended_name_table)
 309     (bfd *, char **, bfd_size_type *, const char **);
 310   void        (*_bfd_truncate_arname) (bfd *, const char *, char *);
 311   bfd_boolean (*write_armap)
 312     (bfd *, unsigned int, struct orl *, unsigned int, int);
 313   void *      (*_bfd_read_ar_hdr_fn) (bfd *);
 314   bfd *       (*openr_next_archived_file) (bfd *, bfd *);
 315 #define bfd_get_elt_at_index(b,i) BFD_SEND (b, _bfd_get_elt_at_index, (b,i))
 316   bfd *       (*_bfd_get_elt_at_index) (bfd *, symindex);
 317   int         (*_bfd_stat_arch_elt) (bfd *, struct stat *);
 318   bfd_boolean (*_bfd_update_armap_timestamp) (bfd *);
 319
 320   /* Entry points used for symbols.  */
 321 #define BFD_JUMP_TABLE_SYMBOLS(NAME) \
 322   NAME##_get_symtab_upper_bound, \
 323   NAME##_canonicalize_symtab, \
 324   NAME##_make_empty_symbol, \
 325   NAME##_print_symbol, \
 326   NAME##_get_symbol_info, \
 327   NAME##_bfd_is_local_label_name, \
 328   NAME##_bfd_is_target_special_symbol, \
 329   NAME##_get_lineno, \
 330   NAME##_find_nearest_line, \
 331   _bfd_generic_find_line, \
 332   NAME##_find_inliner_info, \
 333   NAME##_bfd_make_debug_symbol, \
 334   NAME##_read_minisymbols, \
 335   NAME##_minisymbol_to_symbol
 336
 337   long        (*_bfd_get_symtab_upper_bound) (bfd *);
 338   long        (*_bfd_canonicalize_symtab)
 339     (bfd *, struct bfd_symbol **);
 340   struct bfd_symbol *
 341               (*_bfd_make_empty_symbol) (bfd *);
 342   void        (*_bfd_print_symbol)
 343     (bfd *, void *, struct bfd_symbol *, bfd_print_symbol_type);
 344 #define bfd_print_symbol(b,p,s,e) BFD_SEND (b, _bfd_print_symbol, (b,p,s,e))
 345   void        (*_bfd_get_symbol_info)
 346     (bfd *, struct bfd_symbol *, symbol_info *);
 347 #define bfd_get_symbol_info(b,p,e) BFD_SEND (b, _bfd_get_symbol_info, (b,p,e))
 348   bfd_boolean (*_bfd_is_local_label_name) (bfd *, const char *);
 349   bfd_boolean (*_bfd_is_target_special_symbol) (bfd *, asymbol *);
 350   alent *     (*_get_lineno) (bfd *, struct bfd_symbol *);
 351   bfd_boolean (*_bfd_find_nearest_line)
 352     (bfd *, struct bfd_section *, struct bfd_symbol **, bfd_vma,
 353      const char **, const char **, unsigned int *);
 354   bfd_boolean (*_bfd_find_line)
 355     (bfd *, struct bfd_symbol **, struct bfd_symbol *,
 356      const char **, unsigned int *);
 357   bfd_boolean (*_bfd_find_inliner_info)
 358     (bfd *, const char **, const char **, unsigned int *);
 359  /* Back-door to allow format-aware applications to create debug symbols
 360     while using BFD for everything else.  Currently used by the assembler
 361     when creating COFF files.  */
 362   asymbol *   (*_bfd_make_debug_symbol)
 363     (bfd *, void *, unsigned long size);
 364 #define bfd_read_minisymbols(b, d, m, s) \
 365   BFD_SEND (b, _read_minisymbols, (b, d, m, s))
 366   long        (*_read_minisymbols)
 367     (bfd *, bfd_boolean, void **, unsigned int *);
 368 #define bfd_minisymbol_to_symbol(b, d, m, f) \
 369   BFD_SEND (b, _minisymbol_to_symbol, (b, d, m, f))
 370   asymbol *   (*_minisymbol_to_symbol)
 371     (bfd *, bfd_boolean, const void *, asymbol *);
 372
 373   /* Routines for relocs.  */
 374 #define BFD_JUMP_TABLE_RELOCS(NAME) \
 375   NAME##_get_reloc_upper_bound, \
 376   NAME##_canonicalize_reloc, \
 377   NAME##_bfd_reloc_type_lookup, \
 378   NAME##_bfd_reloc_name_lookup
 379
 380   long        (*_get_reloc_upper_bound) (bfd *, sec_ptr);
 381   long        (*_bfd_canonicalize_reloc)
 382     (bfd *, sec_ptr, arelent **, struct bfd_symbol **);
 383   /* See documentation on reloc types.  */
 384   reloc_howto_type *
 385               (*reloc_type_lookup) (bfd *, bfd_reloc_code_real_type);
 386   reloc_howto_type *
 387               (*reloc_name_lookup) (bfd *, const char *);
 388
 389
 390   /* Routines used when writing an object file.  */
 391 #define BFD_JUMP_TABLE_WRITE(NAME) \
 392   NAME##_set_arch_mach, \
 393   NAME##_set_section_contents
 394
 395   bfd_boolean (*_bfd_set_arch_mach)
 396     (bfd *, enum bfd_architecture, unsigned long);
 397   bfd_boolean (*_bfd_set_section_contents)
 398     (bfd *, sec_ptr, const void *, file_ptr, bfd_size_type);
 399
 400   /* Routines used by the linker.  */
 401 #define BFD_JUMP_TABLE_LINK(NAME) \
 402   NAME##_sizeof_headers, \
 403   NAME##_bfd_get_relocated_section_contents, \
 404   NAME##_bfd_relax_section, \
 405   NAME##_bfd_link_hash_table_create, \
 406   NAME##_bfd_link_hash_table_free, \
 407   NAME##_bfd_link_add_symbols, \
 408   NAME##_bfd_link_just_syms, \
 409   NAME##_bfd_final_link, \
 410   NAME##_bfd_link_split_section, \
 411   NAME##_bfd_gc_sections, \
 412   NAME##_bfd_merge_sections, \
 413   NAME##_bfd_is_group_section, \
 414   NAME##_bfd_discard_group, \
 415   NAME##_section_already_linked, \
 416   NAME##_bfd_define_common_symbol
 417
 418   int         (*_bfd_sizeof_headers) (bfd *, struct bfd_link_info *);
 419   bfd_byte *  (*_bfd_get_relocated_section_contents)
 420     (bfd *, struct bfd_link_info *, struct bfd_link_order *,
 421      bfd_byte *, bfd_boolean, struct bfd_symbol **);
 422
 423   bfd_boolean (*_bfd_relax_section)
 424     (bfd *, struct bfd_section *, struct bfd_link_info *, bfd_boolean *);
 425
 426   /* Create a hash table for the linker.  Different backends store
 427      different information in this table.  */
 428   struct bfd_link_hash_table *
 429               (*_bfd_link_hash_table_create) (bfd *);
 430
 431   /* Release the memory associated with the linker hash table.  */
 432   void        (*_bfd_link_hash_table_free) (struct bfd_link_hash_table *);
 433
 434   /* Add symbols from this object file into the hash table.  */
 435   bfd_boolean (*_bfd_link_add_symbols) (bfd *, struct bfd_link_info *);
 436
 437   /* Indicate that we are only retrieving symbol values from this section.  */
 438   void        (*_bfd_link_just_syms) (asection *, struct bfd_link_info *);
 439
 440   /* Do a link based on the link_order structures attached to each
 441      section of the BFD.  */
 442   bfd_boolean (*_bfd_final_link) (bfd *, struct bfd_link_info *);
 443
 444   /* Should this section be split up into smaller pieces during linking.  */
 445   bfd_boolean (*_bfd_link_split_section) (bfd *, struct bfd_section *);
 446
 447   /* Remove sections that are not referenced from the output.  */
 448   bfd_boolean (*_bfd_gc_sections) (bfd *, struct bfd_link_info *);
 449
 450   /* Attempt to merge SEC_MERGE sections.  */
 451   bfd_boolean (*_bfd_merge_sections) (bfd *, struct bfd_link_info *);
 452
 453   /* Is this section a member of a group?  */
 454   bfd_boolean (*_bfd_is_group_section) (bfd *, const struct bfd_section *);
 455
 456   /* Discard members of a group.  */
 457   bfd_boolean (*_bfd_discard_group) (bfd *, struct bfd_section *);
 458
 459   /* Check if SEC has been already linked during a reloceatable or
 460      final link.  */
 461   void (*_section_already_linked) (bfd *, struct bfd_section *,
 462                                    struct bfd_link_info *);
 463
 464   /* Define a common symbol.  */
 465   bfd_boolean (*_bfd_define_common_symbol) (bfd *, struct bfd_link_info *,
 466                                             struct bfd_link_hash_entry *);
 467
 468   /* Routines to handle dynamic symbols and relocs.  */
 469 #define BFD_JUMP_TABLE_DYNAMIC(NAME) \
 470   NAME##_get_dynamic_symtab_upper_bound, \
 471   NAME##_canonicalize_dynamic_symtab, \
 472   NAME##_get_synthetic_symtab, \
 473   NAME##_get_dynamic_reloc_upper_bound, \
 474   NAME##_canonicalize_dynamic_reloc
 475
 476   /* Get the amount of memory required to hold the dynamic symbols.  */
 477   long        (*_bfd_get_dynamic_symtab_upper_bound) (bfd *);
 478   /* Read in the dynamic symbols.  */
 479   long        (*_bfd_canonicalize_dynamic_symtab)
 480     (bfd *, struct bfd_symbol **);
 481   /* Create synthetized symbols.  */
 482   long        (*_bfd_get_synthetic_symtab)
 483     (bfd *, long, struct bfd_symbol **, long, struct bfd_symbol **,
 484      struct bfd_symbol **);
 485   /* Get the amount of memory required to hold the dynamic relocs.  */
 486   long        (*_bfd_get_dynamic_reloc_upper_bound) (bfd *);
 487   /* Read in the dynamic relocs.  */
 488   long        (*_bfd_canonicalize_dynamic_reloc)
 489     (bfd *, arelent **, struct bfd_symbol **);
 490
 491 @end example
 492 A pointer to an alternative bfd_target in case the current one is not
 493 satisfactory.  This can happen when the target cpu supports both big
 494 and little endian code, and target chosen by the linker has the wrong
 495 endianness.  The function open_output() in ld/ldlang.c uses this field
 496 to find an alternative output format that is suitable.
 497 @example
 498   /* Opposite endian version of this target.  */
 499   const struct bfd_target * alternative_target;
 500
 501   /* Data for use by back-end routines, which isn't
 502      generic enough to belong in this structure.  */
 503   const void *backend_data;
 504
 505 @} bfd_target;
 506
 507 @end example
 508
 509 @findex bfd_set_default_target
 510 @subsubsection @code{bfd_set_default_target}
 511 @strong{Synopsis}
 512 @example
 513 bfd_boolean bfd_set_default_target (const char *name);
 514 @end example
 515 @strong{Description}@*
 516 Set the default target vector to use when recognizing a BFD.
 517 This takes the name of the target, which may be a BFD target
 518 name or a configuration triplet.
 519
 520 @findex bfd_find_target
 521 @subsubsection @code{bfd_find_target}
 522 @strong{Synopsis}
 523 @example
 524 const bfd_target *bfd_find_target (const char *target_name, bfd *abfd);
 525 @end example
 526 @strong{Description}@*
 527 Return a pointer to the transfer vector for the object target
 528 named @var{target_name}.  If @var{target_name} is @code{NULL},
 529 choose the one in the environment variable @code{GNUTARGET}; if
 530 that is null or not defined, then choose the first entry in the
 531 target list.  Passing in the string "default" or setting the
 532 environment variable to "default" will cause the first entry in
 533 the target list to be returned, and "target_defaulted" will be
 534 set in the BFD if @var{abfd} isn't @code{NULL}.  This causes
 535 @code{bfd_check_format} to loop over all the targets to find the
 536 one that matches the file being read.
 537
 538 @findex bfd_target_list
 539 @subsubsection @code{bfd_target_list}
 540 @strong{Synopsis}
 541 @example
 542 const char ** bfd_target_list (void);
 543 @end example
 544 @strong{Description}@*
 545 Return a freshly malloced NULL-terminated
 546 vector of the names of all the valid BFD targets. Do not
 547 modify the names.
 548
 549 @findex bfd_seach_for_target
 550 @subsubsection @code{bfd_seach_for_target}
 551 @strong{Synopsis}
 552 @example
 553 const bfd_target *bfd_search_for_target
 554    (int (*search_func) (const bfd_target *, void *),
 555     void *);
 556 @end example
 557 @strong{Description}@*
 558 Return a pointer to the first transfer vector in the list of
 559 transfer vectors maintained by BFD that produces a non-zero
 560 result when passed to the function @var{search_func}.  The
 561 parameter @var{data} is passed, unexamined, to the search
 562 function.
 563