contrib/binutils-2.17/bfd/doc/bfdt.texi

   1 @section @code{typedef bfd}
   2 A BFD has type @code{bfd}; objects of this type are the
   3 cornerstone of any application using BFD. Using BFD
   4 consists of making references though the BFD and to data in the BFD.
   5
   6 Here is the structure that defines the type @code{bfd}.  It
   7 contains the major data about the file and pointers
   8 to the rest of the data.
   9
  10
  11 @example
  12
  13 struct bfd
  14 @{
  15   /* A unique identifier of the BFD  */
  16   unsigned int id;
  17
  18   /* The filename the application opened the BFD with.  */
  19   const char *filename;
  20
  21   /* A pointer to the target jump table.  */
  22   const struct bfd_target *xvec;
  23
  24   /* The IOSTREAM, and corresponding IO vector that provide access
  25      to the file backing the BFD.  */
  26   void *iostream;
  27   const struct bfd_iovec *iovec;
  28
  29   /* Is the file descriptor being cached?  That is, can it be closed as
  30      needed, and re-opened when accessed later?  */
  31   bfd_boolean cacheable;
  32
  33   /* Marks whether there was a default target specified when the
  34      BFD was opened. This is used to select which matching algorithm
  35      to use to choose the back end.  */
  36   bfd_boolean target_defaulted;
  37
  38   /* The caching routines use these to maintain a
  39      least-recently-used list of BFDs.  */
  40   struct bfd *lru_prev, *lru_next;
  41
  42   /* When a file is closed by the caching routines, BFD retains
  43      state information on the file here...  */
  44   ufile_ptr where;
  45
  46   /* ... and here: (``once'' means at least once).  */
  47   bfd_boolean opened_once;
  48
  49   /* Set if we have a locally maintained mtime value, rather than
  50      getting it from the file each time.  */
  51   bfd_boolean mtime_set;
  52
  53   /* File modified time, if mtime_set is TRUE.  */
  54   long mtime;
  55
  56   /* Reserved for an unimplemented file locking extension.  */
  57   int ifd;
  58
  59   /* The format which belongs to the BFD. (object, core, etc.)  */
  60   bfd_format format;
  61
  62   /* The direction with which the BFD was opened.  */
  63   enum bfd_direction
  64     @{
  65       no_direction = 0,
  66       read_direction = 1,
  67       write_direction = 2,
  68       both_direction = 3
  69     @}
  70   direction;
  71
  72   /* Format_specific flags.  */
  73   flagword flags;
  74
  75   /* Currently my_archive is tested before adding origin to
  76      anything. I believe that this can become always an add of
  77      origin, with origin set to 0 for non archive files.  */
  78   ufile_ptr origin;
  79
  80   /* Remember when output has begun, to stop strange things
  81      from happening.  */
  82   bfd_boolean output_has_begun;
  83
  84   /* A hash table for section names.  */
  85   struct bfd_hash_table section_htab;
  86
  87   /* Pointer to linked list of sections.  */
  88   struct bfd_section *sections;
  89
  90   /* The last section on the section list.  */
  91   struct bfd_section *section_last;
  92
  93   /* The number of sections.  */
  94   unsigned int section_count;
  95
  96   /* Stuff only useful for object files:
  97      The start address.  */
  98   bfd_vma start_address;
  99
 100   /* Used for input and output.  */
 101   unsigned int symcount;
 102
 103   /* Symbol table for output BFD (with symcount entries).  */
 104   struct bfd_symbol  **outsymbols;
 105
 106   /* Used for slurped dynamic symbol tables.  */
 107   unsigned int dynsymcount;
 108
 109   /* Pointer to structure which contains architecture information.  */
 110   const struct bfd_arch_info *arch_info;
 111
 112   /* Flag set if symbols from this BFD should not be exported.  */
 113   bfd_boolean no_export;
 114
 115   /* Stuff only useful for archives.  */
 116   void *arelt_data;
 117   struct bfd *my_archive;      /* The containing archive BFD.  */
 118   struct bfd *next;            /* The next BFD in the archive.  */
 119   struct bfd *archive_head;    /* The first BFD in the archive.  */
 120   bfd_boolean has_armap;
 121
 122   /* A chain of BFD structures involved in a link.  */
 123   struct bfd *link_next;
 124
 125   /* A field used by _bfd_generic_link_add_archive_symbols.  This will
 126      be used only for archive elements.  */
 127   int archive_pass;
 128
 129   /* Used by the back end to hold private data.  */
 130   union
 131     @{
 132       struct aout_data_struct *aout_data;
 133       struct artdata *aout_ar_data;
 134       struct _oasys_data *oasys_obj_data;
 135       struct _oasys_ar_data *oasys_ar_data;
 136       struct coff_tdata *coff_obj_data;
 137       struct pe_tdata *pe_obj_data;
 138       struct xcoff_tdata *xcoff_obj_data;
 139       struct ecoff_tdata *ecoff_obj_data;
 140       struct ieee_data_struct *ieee_data;
 141       struct ieee_ar_data_struct *ieee_ar_data;
 142       struct srec_data_struct *srec_data;
 143       struct ihex_data_struct *ihex_data;
 144       struct tekhex_data_struct *tekhex_data;
 145       struct elf_obj_tdata *elf_obj_data;
 146       struct nlm_obj_tdata *nlm_obj_data;
 147       struct bout_data_struct *bout_data;
 148       struct mmo_data_struct *mmo_data;
 149       struct sun_core_struct *sun_core_data;
 150       struct sco5_core_struct *sco5_core_data;
 151       struct trad_core_struct *trad_core_data;
 152       struct som_data_struct *som_data;
 153       struct hpux_core_struct *hpux_core_data;
 154       struct hppabsd_core_struct *hppabsd_core_data;
 155       struct sgi_core_struct *sgi_core_data;
 156       struct lynx_core_struct *lynx_core_data;
 157       struct osf_core_struct *osf_core_data;
 158       struct cisco_core_struct *cisco_core_data;
 159       struct versados_data_struct *versados_data;
 160       struct netbsd_core_struct *netbsd_core_data;
 161       struct mach_o_data_struct *mach_o_data;
 162       struct mach_o_fat_data_struct *mach_o_fat_data;
 163       struct bfd_pef_data_struct *pef_data;
 164       struct bfd_pef_xlib_data_struct *pef_xlib_data;
 165       struct bfd_sym_data_struct *sym_data;
 166       void *any;
 167     @}
 168   tdata;
 169
 170   /* Used by the application to hold private data.  */
 171   void *usrdata;
 172
 173   /* Where all the allocated stuff under this BFD goes.  This is a
 174      struct objalloc *, but we use void * to avoid requiring the inclusion
 175      of objalloc.h.  */
 176   void *memory;
 177 @};
 178
 179 @end example
 180 @section Error reporting
 181 Most BFD functions return nonzero on success (check their
 182 individual documentation for precise semantics).  On an error,
 183 they call @code{bfd_set_error} to set an error condition that callers
 184 can check by calling @code{bfd_get_error}.
 185 If that returns @code{bfd_error_system_call}, then check
 186 @code{errno}.
 187
 188 The easiest way to report a BFD error to the user is to
 189 use @code{bfd_perror}.
 190
 191 @subsection Type @code{bfd_error_type}
 192 The values returned by @code{bfd_get_error} are defined by the
 193 enumerated type @code{bfd_error_type}.
 194
 195
 196 @example
 197
 198 typedef enum bfd_error
 199 @{
 200   bfd_error_no_error = 0,
 201   bfd_error_system_call,
 202   bfd_error_invalid_target,
 203   bfd_error_wrong_format,
 204   bfd_error_wrong_object_format,
 205   bfd_error_invalid_operation,
 206   bfd_error_no_memory,
 207   bfd_error_no_symbols,
 208   bfd_error_no_armap,
 209   bfd_error_no_more_archived_files,
 210   bfd_error_malformed_archive,
 211   bfd_error_file_not_recognized,
 212   bfd_error_file_ambiguously_recognized,
 213   bfd_error_no_contents,
 214   bfd_error_nonrepresentable_section,
 215   bfd_error_no_debug_section,
 216   bfd_error_bad_value,
 217   bfd_error_file_truncated,
 218   bfd_error_file_too_big,
 219   bfd_error_invalid_error_code
 220 @}
 221 bfd_error_type;
 222
 223 @end example
 224 @findex bfd_get_error
 225 @subsubsection @code{bfd_get_error}
 226 @strong{Synopsis}
 227 @example
 228 bfd_error_type bfd_get_error (void);
 229 @end example
 230 @strong{Description}@*
 231 Return the current BFD error condition.
 232
 233 @findex bfd_set_error
 234 @subsubsection @code{bfd_set_error}
 235 @strong{Synopsis}
 236 @example
 237 void bfd_set_error (bfd_error_type error_tag);
 238 @end example
 239 @strong{Description}@*
 240 Set the BFD error condition to be @var{error_tag}.
 241
 242 @findex bfd_errmsg
 243 @subsubsection @code{bfd_errmsg}
 244 @strong{Synopsis}
 245 @example
 246 const char *bfd_errmsg (bfd_error_type error_tag);
 247 @end example
 248 @strong{Description}@*
 249 Return a string describing the error @var{error_tag}, or
 250 the system error if @var{error_tag} is @code{bfd_error_system_call}.
 251
 252 @findex bfd_perror
 253 @subsubsection @code{bfd_perror}
 254 @strong{Synopsis}
 255 @example
 256 void bfd_perror (const char *message);
 257 @end example
 258 @strong{Description}@*
 259 Print to the standard error stream a string describing the
 260 last BFD error that occurred, or the last system error if
 261 the last BFD error was a system call failure.  If @var{message}
 262 is non-NULL and non-empty, the error string printed is preceded
 263 by @var{message}, a colon, and a space.  It is followed by a newline.
 264
 265 @subsection BFD error handler
 266 Some BFD functions want to print messages describing the
 267 problem.  They call a BFD error handler function.  This
 268 function may be overridden by the program.
 269
 270 The BFD error handler acts like printf.
 271
 272
 273 @example
 274
 275 typedef void (*bfd_error_handler_type) (const char *, ...);
 276
 277 @end example
 278 @findex bfd_set_error_handler
 279 @subsubsection @code{bfd_set_error_handler}
 280 @strong{Synopsis}
 281 @example
 282 bfd_error_handler_type bfd_set_error_handler (bfd_error_handler_type);
 283 @end example
 284 @strong{Description}@*
 285 Set the BFD error handler function.  Returns the previous
 286 function.
 287
 288 @findex bfd_set_error_program_name
 289 @subsubsection @code{bfd_set_error_program_name}
 290 @strong{Synopsis}
 291 @example
 292 void bfd_set_error_program_name (const char *);
 293 @end example
 294 @strong{Description}@*
 295 Set the program name to use when printing a BFD error.  This
 296 is printed before the error message followed by a colon and
 297 space.  The string must not be changed after it is passed to
 298 this function.
 299
 300 @findex bfd_get_error_handler
 301 @subsubsection @code{bfd_get_error_handler}
 302 @strong{Synopsis}
 303 @example
 304 bfd_error_handler_type bfd_get_error_handler (void);
 305 @end example
 306 @strong{Description}@*
 307 Return the BFD error handler function.
 308
 309 @section Miscellaneous
 310
 311
 312 @subsection Miscellaneous functions
 313
 314
 315 @findex bfd_get_reloc_upper_bound
 316 @subsubsection @code{bfd_get_reloc_upper_bound}
 317 @strong{Synopsis}
 318 @example
 319 long bfd_get_reloc_upper_bound (bfd *abfd, asection *sect);
 320 @end example
 321 @strong{Description}@*
 322 Return the number of bytes required to store the
 323 relocation information associated with section @var{sect}
 324 attached to bfd @var{abfd}.  If an error occurs, return -1.
 325
 326 @findex bfd_canonicalize_reloc
 327 @subsubsection @code{bfd_canonicalize_reloc}
 328 @strong{Synopsis}
 329 @example
 330 long bfd_canonicalize_reloc
 331    (bfd *abfd, asection *sec, arelent **loc, asymbol **syms);
 332 @end example
 333 @strong{Description}@*
 334 Call the back end associated with the open BFD
 335 @var{abfd} and translate the external form of the relocation
 336 information attached to @var{sec} into the internal canonical
 337 form.  Place the table into memory at @var{loc}, which has
 338 been preallocated, usually by a call to
 339 @code{bfd_get_reloc_upper_bound}.  Returns the number of relocs, or
 340 -1 on error.
 341
 342 The @var{syms} table is also needed for horrible internal magic
 343 reasons.
 344
 345 @findex bfd_set_reloc
 346 @subsubsection @code{bfd_set_reloc}
 347 @strong{Synopsis}
 348 @example
 349 void bfd_set_reloc
 350    (bfd *abfd, asection *sec, arelent **rel, unsigned int count);
 351 @end example
 352 @strong{Description}@*
 353 Set the relocation pointer and count within
 354 section @var{sec} to the values @var{rel} and @var{count}.
 355 The argument @var{abfd} is ignored.
 356
 357 @findex bfd_set_file_flags
 358 @subsubsection @code{bfd_set_file_flags}
 359 @strong{Synopsis}
 360 @example
 361 bfd_boolean bfd_set_file_flags (bfd *abfd, flagword flags);
 362 @end example
 363 @strong{Description}@*
 364 Set the flag word in the BFD @var{abfd} to the value @var{flags}.
 365
 366 Possible errors are:
 367 @itemize @bullet
 368
 369 @item
 370 @code{bfd_error_wrong_format} - The target bfd was not of object format.
 371 @item
 372 @code{bfd_error_invalid_operation} - The target bfd was open for reading.
 373 @item
 374 @code{bfd_error_invalid_operation} -
 375 The flag word contained a bit which was not applicable to the
 376 type of file.  E.g., an attempt was made to set the @code{D_PAGED} bit
 377 on a BFD format which does not support demand paging.
 378 @end itemize
 379
 380 @findex bfd_get_arch_size
 381 @subsubsection @code{bfd_get_arch_size}
 382 @strong{Synopsis}
 383 @example
 384 int bfd_get_arch_size (bfd *abfd);
 385 @end example
 386 @strong{Description}@*
 387 Returns the architecture address size, in bits, as determined
 388 by the object file's format.  For ELF, this information is
 389 included in the header.
 390
 391 @strong{Returns}@*
 392 Returns the arch size in bits if known, @code{-1} otherwise.
 393
 394 @findex bfd_get_sign_extend_vma
 395 @subsubsection @code{bfd_get_sign_extend_vma}
 396 @strong{Synopsis}
 397 @example
 398 int bfd_get_sign_extend_vma (bfd *abfd);
 399 @end example
 400 @strong{Description}@*
 401 Indicates if the target architecture "naturally" sign extends
 402 an address.  Some architectures implicitly sign extend address
 403 values when they are converted to types larger than the size
 404 of an address.  For instance, bfd_get_start_address() will
 405 return an address sign extended to fill a bfd_vma when this is
 406 the case.
 407
 408 @strong{Returns}@*
 409 Returns @code{1} if the target architecture is known to sign
 410 extend addresses, @code{0} if the target architecture is known to
 411 not sign extend addresses, and @code{-1} otherwise.
 412
 413 @findex bfd_set_start_address
 414 @subsubsection @code{bfd_set_start_address}
 415 @strong{Synopsis}
 416 @example
 417 bfd_boolean bfd_set_start_address (bfd *abfd, bfd_vma vma);
 418 @end example
 419 @strong{Description}@*
 420 Make @var{vma} the entry point of output BFD @var{abfd}.
 421
 422 @strong{Returns}@*
 423 Returns @code{TRUE} on success, @code{FALSE} otherwise.
 424
 425 @findex bfd_get_gp_size
 426 @subsubsection @code{bfd_get_gp_size}
 427 @strong{Synopsis}
 428 @example
 429 unsigned int bfd_get_gp_size (bfd *abfd);
 430 @end example
 431 @strong{Description}@*
 432 Return the maximum size of objects to be optimized using the GP
 433 register under MIPS ECOFF.  This is typically set by the @code{-G}
 434 argument to the compiler, assembler or linker.
 435
 436 @findex bfd_set_gp_size
 437 @subsubsection @code{bfd_set_gp_size}
 438 @strong{Synopsis}
 439 @example
 440 void bfd_set_gp_size (bfd *abfd, unsigned int i);
 441 @end example
 442 @strong{Description}@*
 443 Set the maximum size of objects to be optimized using the GP
 444 register under ECOFF or MIPS ELF.  This is typically set by
 445 the @code{-G} argument to the compiler, assembler or linker.
 446
 447 @findex bfd_scan_vma
 448 @subsubsection @code{bfd_scan_vma}
 449 @strong{Synopsis}
 450 @example
 451 bfd_vma bfd_scan_vma (const char *string, const char **end, int base);
 452 @end example
 453 @strong{Description}@*
 454 Convert, like @code{strtoul}, a numerical expression
 455 @var{string} into a @code{bfd_vma} integer, and return that integer.
 456 (Though without as many bells and whistles as @code{strtoul}.)
 457 The expression is assumed to be unsigned (i.e., positive).
 458 If given a @var{base}, it is used as the base for conversion.
 459 A base of 0 causes the function to interpret the string
 460 in hex if a leading "0x" or "0X" is found, otherwise
 461 in octal if a leading zero is found, otherwise in decimal.
 462
 463 If the value would overflow, the maximum @code{bfd_vma} value is
 464 returned.
 465
 466 @findex bfd_copy_private_header_data
 467 @subsubsection @code{bfd_copy_private_header_data}
 468 @strong{Synopsis}
 469 @example
 470 bfd_boolean bfd_copy_private_header_data (bfd *ibfd, bfd *obfd);
 471 @end example
 472 @strong{Description}@*
 473 Copy private BFD header information from the BFD @var{ibfd} to the
 474 the BFD @var{obfd}.  This copies information that may require
 475 sections to exist, but does not require symbol tables.  Return
 476 @code{true} on success, @code{false} on error.
 477 Possible error returns are:
 478
 479 @itemize @bullet
 480
 481 @item
 482 @code{bfd_error_no_memory} -
 483 Not enough memory exists to create private data for @var{obfd}.
 484 @end itemize
 485 @example
 486 #define bfd_copy_private_header_data(ibfd, obfd) \
 487      BFD_SEND (obfd, _bfd_copy_private_header_data, \
 488                (ibfd, obfd))
 489 @end example
 490
 491 @findex bfd_copy_private_bfd_data
 492 @subsubsection @code{bfd_copy_private_bfd_data}
 493 @strong{Synopsis}
 494 @example
 495 bfd_boolean bfd_copy_private_bfd_data (bfd *ibfd, bfd *obfd);
 496 @end example
 497 @strong{Description}@*
 498 Copy private BFD information from the BFD @var{ibfd} to the
 499 the BFD @var{obfd}.  Return @code{TRUE} on success, @code{FALSE} on error.
 500 Possible error returns are:
 501
 502 @itemize @bullet
 503
 504 @item
 505 @code{bfd_error_no_memory} -
 506 Not enough memory exists to create private data for @var{obfd}.
 507 @end itemize
 508 @example
 509 #define bfd_copy_private_bfd_data(ibfd, obfd) \
 510      BFD_SEND (obfd, _bfd_copy_private_bfd_data, \
 511                (ibfd, obfd))
 512 @end example
 513
 514 @findex bfd_merge_private_bfd_data
 515 @subsubsection @code{bfd_merge_private_bfd_data}
 516 @strong{Synopsis}
 517 @example
 518 bfd_boolean bfd_merge_private_bfd_data (bfd *ibfd, bfd *obfd);
 519 @end example
 520 @strong{Description}@*
 521 Merge private BFD information from the BFD @var{ibfd} to the
 522 the output file BFD @var{obfd} when linking.  Return @code{TRUE}
 523 on success, @code{FALSE} on error.  Possible error returns are:
 524
 525 @itemize @bullet
 526
 527 @item
 528 @code{bfd_error_no_memory} -
 529 Not enough memory exists to create private data for @var{obfd}.
 530 @end itemize
 531 @example
 532 #define bfd_merge_private_bfd_data(ibfd, obfd) \
 533      BFD_SEND (obfd, _bfd_merge_private_bfd_data, \
 534                (ibfd, obfd))
 535 @end example
 536
 537 @findex bfd_set_private_flags
 538 @subsubsection @code{bfd_set_private_flags}
 539 @strong{Synopsis}
 540 @example
 541 bfd_boolean bfd_set_private_flags (bfd *abfd, flagword flags);
 542 @end example
 543 @strong{Description}@*
 544 Set private BFD flag information in the BFD @var{abfd}.
 545 Return @code{TRUE} on success, @code{FALSE} on error.  Possible error
 546 returns are:
 547
 548 @itemize @bullet
 549
 550 @item
 551 @code{bfd_error_no_memory} -
 552 Not enough memory exists to create private data for @var{obfd}.
 553 @end itemize
 554 @example
 555 #define bfd_set_private_flags(abfd, flags) \
 556      BFD_SEND (abfd, _bfd_set_private_flags, (abfd, flags))
 557 @end example
 558
 559 @findex Other functions
 560 @subsubsection @code{Other functions}
 561 @strong{Description}@*
 562 The following functions exist but have not yet been documented.
 563 @example
 564 #define bfd_sizeof_headers(abfd, reloc) \
 565        BFD_SEND (abfd, _bfd_sizeof_headers, (abfd, reloc))
 566
 567 #define bfd_find_nearest_line(abfd, sec, syms, off, file, func, line) \
 568        BFD_SEND (abfd, _bfd_find_nearest_line, \
 569                  (abfd, sec, syms, off, file, func, line))
 570
 571 #define bfd_find_line(abfd, syms, sym, file, line) \
 572        BFD_SEND (abfd, _bfd_find_line, \
 573                  (abfd, syms, sym, file, line))
 574
 575 #define bfd_find_inliner_info(abfd, file, func, line) \
 576        BFD_SEND (abfd, _bfd_find_inliner_info, \
 577                  (abfd, file, func, line))
 578
 579 #define bfd_debug_info_start(abfd) \
 580        BFD_SEND (abfd, _bfd_debug_info_start, (abfd))
 581
 582 #define bfd_debug_info_end(abfd) \
 583        BFD_SEND (abfd, _bfd_debug_info_end, (abfd))
 584
 585 #define bfd_debug_info_accumulate(abfd, section) \
 586        BFD_SEND (abfd, _bfd_debug_info_accumulate, (abfd, section))
 587
 588 #define bfd_stat_arch_elt(abfd, stat) \
 589        BFD_SEND (abfd, _bfd_stat_arch_elt,(abfd, stat))
 590
 591 #define bfd_update_armap_timestamp(abfd) \
 592        BFD_SEND (abfd, _bfd_update_armap_timestamp, (abfd))
 593
 594 #define bfd_set_arch_mach(abfd, arch, mach)\
 595        BFD_SEND ( abfd, _bfd_set_arch_mach, (abfd, arch, mach))
 596
 597 #define bfd_relax_section(abfd, section, link_info, again) \
 598        BFD_SEND (abfd, _bfd_relax_section, (abfd, section, link_info, again))
 599
 600 #define bfd_gc_sections(abfd, link_info) \
 601        BFD_SEND (abfd, _bfd_gc_sections, (abfd, link_info))
 602
 603 #define bfd_merge_sections(abfd, link_info) \
 604        BFD_SEND (abfd, _bfd_merge_sections, (abfd, link_info))
 605
 606 #define bfd_is_group_section(abfd, sec) \
 607        BFD_SEND (abfd, _bfd_is_group_section, (abfd, sec))
 608
 609 #define bfd_discard_group(abfd, sec) \
 610        BFD_SEND (abfd, _bfd_discard_group, (abfd, sec))
 611
 612 #define bfd_link_hash_table_create(abfd) \
 613        BFD_SEND (abfd, _bfd_link_hash_table_create, (abfd))
 614
 615 #define bfd_link_hash_table_free(abfd, hash) \
 616        BFD_SEND (abfd, _bfd_link_hash_table_free, (hash))
 617
 618 #define bfd_link_add_symbols(abfd, info) \
 619        BFD_SEND (abfd, _bfd_link_add_symbols, (abfd, info))
 620
 621 #define bfd_link_just_syms(abfd, sec, info) \
 622        BFD_SEND (abfd, _bfd_link_just_syms, (sec, info))
 623
 624 #define bfd_final_link(abfd, info) \
 625        BFD_SEND (abfd, _bfd_final_link, (abfd, info))
 626
 627 #define bfd_free_cached_info(abfd) \
 628        BFD_SEND (abfd, _bfd_free_cached_info, (abfd))
 629
 630 #define bfd_get_dynamic_symtab_upper_bound(abfd) \
 631        BFD_SEND (abfd, _bfd_get_dynamic_symtab_upper_bound, (abfd))
 632
 633 #define bfd_print_private_bfd_data(abfd, file)\
 634        BFD_SEND (abfd, _bfd_print_private_bfd_data, (abfd, file))
 635
 636 #define bfd_canonicalize_dynamic_symtab(abfd, asymbols) \
 637        BFD_SEND (abfd, _bfd_canonicalize_dynamic_symtab, (abfd, asymbols))
 638
 639 #define bfd_get_synthetic_symtab(abfd, count, syms, dyncount, dynsyms, ret) \
 640        BFD_SEND (abfd, _bfd_get_synthetic_symtab, (abfd, count, syms, \
 641                                                    dyncount, dynsyms, ret))
 642
 643 #define bfd_get_dynamic_reloc_upper_bound(abfd) \
 644        BFD_SEND (abfd, _bfd_get_dynamic_reloc_upper_bound, (abfd))
 645
 646 #define bfd_canonicalize_dynamic_reloc(abfd, arels, asyms) \
 647        BFD_SEND (abfd, _bfd_canonicalize_dynamic_reloc, (abfd, arels, asyms))
 648
 649 extern bfd_byte *bfd_get_relocated_section_contents
 650   (bfd *, struct bfd_link_info *, struct bfd_link_order *, bfd_byte *,
 651    bfd_boolean, asymbol **);
 652
 653 @end example
 654
 655 @findex bfd_alt_mach_code
 656 @subsubsection @code{bfd_alt_mach_code}
 657 @strong{Synopsis}
 658 @example
 659 bfd_boolean bfd_alt_mach_code (bfd *abfd, int alternative);
 660 @end example
 661 @strong{Description}@*
 662 When more than one machine code number is available for the
 663 same machine type, this function can be used to switch between
 664 the preferred one (alternative == 0) and any others.  Currently,
 665 only ELF supports this feature, with up to two alternate
 666 machine codes.
 667
 668
 669 @example
 670 struct bfd_preserve
 671 @{
 672   void *marker;
 673   void *tdata;
 674   flagword flags;
 675   const struct bfd_arch_info *arch_info;
 676   struct bfd_section *sections;
 677   struct bfd_section *section_last;
 678   unsigned int section_count;
 679   struct bfd_hash_table section_htab;
 680 @};
 681
 682 @end example
 683 @findex bfd_preserve_save
 684 @subsubsection @code{bfd_preserve_save}
 685 @strong{Synopsis}
 686 @example
 687 bfd_boolean bfd_preserve_save (bfd *, struct bfd_preserve *);
 688 @end example
 689 @strong{Description}@*
 690 When testing an object for compatibility with a particular
 691 target back-end, the back-end object_p function needs to set
 692 up certain fields in the bfd on successfully recognizing the
 693 object.  This typically happens in a piecemeal fashion, with
 694 failures possible at many points.  On failure, the bfd is
 695 supposed to be restored to its initial state, which is
 696 virtually impossible.  However, restoring a subset of the bfd
 697 state works in practice.  This function stores the subset and
 698 reinitializes the bfd.
 699
 700 @findex bfd_preserve_restore
 701 @subsubsection @code{bfd_preserve_restore}
 702 @strong{Synopsis}
 703 @example
 704 void bfd_preserve_restore (bfd *, struct bfd_preserve *);
 705 @end example
 706 @strong{Description}@*
 707 This function restores bfd state saved by bfd_preserve_save.
 708 If MARKER is non-NULL in struct bfd_preserve then that block
 709 and all subsequently bfd_alloc'd memory is freed.
 710
 711 @findex bfd_preserve_finish
 712 @subsubsection @code{bfd_preserve_finish}
 713 @strong{Synopsis}
 714 @example
 715 void bfd_preserve_finish (bfd *, struct bfd_preserve *);
 716 @end example
 717 @strong{Description}@*
 718 This function should be called when the bfd state saved by
 719 bfd_preserve_save is no longer needed.  ie. when the back-end
 720 object_p function returns with success.
 721