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