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 *archive_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_on_input,
 220   bfd_error_invalid_error_code
 221 @}
 222 bfd_error_type;
 223
 224 @end example
 225 @findex bfd_get_error
 226 @subsubsection @code{bfd_get_error}
 227 @strong{Synopsis}
 228 @example
 229 bfd_error_type bfd_get_error (void);
 230 @end example
 231 @strong{Description}@*
 232 Return the current BFD error condition.
 233
 234 @findex bfd_set_error
 235 @subsubsection @code{bfd_set_error}
 236 @strong{Synopsis}
 237 @example
 238 void bfd_set_error (bfd_error_type error_tag, ...);
 239 @end example
 240 @strong{Description}@*
 241 Set the BFD error condition to be @var{error_tag}.
 242 If @var{error_tag} is bfd_error_on_input, then this function
 243 takes two more parameters, the input bfd where the error
 244 occurred, and the bfd_error_type error.
 245
 246 @findex bfd_errmsg
 247 @subsubsection @code{bfd_errmsg}
 248 @strong{Synopsis}
 249 @example
 250 const char *bfd_errmsg (bfd_error_type error_tag);
 251 @end example
 252 @strong{Description}@*
 253 Return a string describing the error @var{error_tag}, or
 254 the system error if @var{error_tag} is @code{bfd_error_system_call}.
 255
 256 @findex bfd_perror
 257 @subsubsection @code{bfd_perror}
 258 @strong{Synopsis}
 259 @example
 260 void bfd_perror (const char *message);
 261 @end example
 262 @strong{Description}@*
 263 Print to the standard error stream a string describing the
 264 last BFD error that occurred, or the last system error if
 265 the last BFD error was a system call failure.  If @var{message}
 266 is non-NULL and non-empty, the error string printed is preceded
 267 by @var{message}, a colon, and a space.  It is followed by a newline.
 268
 269 @subsection BFD error handler
 270 Some BFD functions want to print messages describing the
 271 problem.  They call a BFD error handler function.  This
 272 function may be overridden by the program.
 273
 274 The BFD error handler acts like printf.
 275
 276
 277 @example
 278
 279 typedef void (*bfd_error_handler_type) (const char *, ...);
 280
 281 @end example
 282 @findex bfd_set_error_handler
 283 @subsubsection @code{bfd_set_error_handler}
 284 @strong{Synopsis}
 285 @example
 286 bfd_error_handler_type bfd_set_error_handler (bfd_error_handler_type);
 287 @end example
 288 @strong{Description}@*
 289 Set the BFD error handler function.  Returns the previous
 290 function.
 291
 292 @findex bfd_set_error_program_name
 293 @subsubsection @code{bfd_set_error_program_name}
 294 @strong{Synopsis}
 295 @example
 296 void bfd_set_error_program_name (const char *);
 297 @end example
 298 @strong{Description}@*
 299 Set the program name to use when printing a BFD error.  This
 300 is printed before the error message followed by a colon and
 301 space.  The string must not be changed after it is passed to
 302 this function.
 303
 304 @findex bfd_get_error_handler
 305 @subsubsection @code{bfd_get_error_handler}
 306 @strong{Synopsis}
 307 @example
 308 bfd_error_handler_type bfd_get_error_handler (void);
 309 @end example
 310 @strong{Description}@*
 311 Return the BFD error handler function.
 312
 313 @section Miscellaneous
 314
 315
 316 @subsection Miscellaneous functions
 317
 318
 319 @findex bfd_get_reloc_upper_bound
 320 @subsubsection @code{bfd_get_reloc_upper_bound}
 321 @strong{Synopsis}
 322 @example
 323 long bfd_get_reloc_upper_bound (bfd *abfd, asection *sect);
 324 @end example
 325 @strong{Description}@*
 326 Return the number of bytes required to store the
 327 relocation information associated with section @var{sect}
 328 attached to bfd @var{abfd}.  If an error occurs, return -1.
 329
 330 @findex bfd_canonicalize_reloc
 331 @subsubsection @code{bfd_canonicalize_reloc}
 332 @strong{Synopsis}
 333 @example
 334 long bfd_canonicalize_reloc
 335    (bfd *abfd, asection *sec, arelent **loc, asymbol **syms);
 336 @end example
 337 @strong{Description}@*
 338 Call the back end associated with the open BFD
 339 @var{abfd} and translate the external form of the relocation
 340 information attached to @var{sec} into the internal canonical
 341 form.  Place the table into memory at @var{loc}, which has
 342 been preallocated, usually by a call to
 343 @code{bfd_get_reloc_upper_bound}.  Returns the number of relocs, or
 344 -1 on error.
 345
 346 The @var{syms} table is also needed for horrible internal magic
 347 reasons.
 348
 349 @findex bfd_set_reloc
 350 @subsubsection @code{bfd_set_reloc}
 351 @strong{Synopsis}
 352 @example
 353 void bfd_set_reloc
 354    (bfd *abfd, asection *sec, arelent **rel, unsigned int count);
 355 @end example
 356 @strong{Description}@*
 357 Set the relocation pointer and count within
 358 section @var{sec} to the values @var{rel} and @var{count}.
 359 The argument @var{abfd} is ignored.
 360
 361 @findex bfd_set_file_flags
 362 @subsubsection @code{bfd_set_file_flags}
 363 @strong{Synopsis}
 364 @example
 365 bfd_boolean bfd_set_file_flags (bfd *abfd, flagword flags);
 366 @end example
 367 @strong{Description}@*
 368 Set the flag word in the BFD @var{abfd} to the value @var{flags}.
 369
 370 Possible errors are:
 371 @itemize @bullet
 372
 373 @item
 374 @code{bfd_error_wrong_format} - The target bfd was not of object format.
 375 @item
 376 @code{bfd_error_invalid_operation} - The target bfd was open for reading.
 377 @item
 378 @code{bfd_error_invalid_operation} -
 379 The flag word contained a bit which was not applicable to the
 380 type of file.  E.g., an attempt was made to set the @code{D_PAGED} bit
 381 on a BFD format which does not support demand paging.
 382 @end itemize
 383
 384 @findex bfd_get_arch_size
 385 @subsubsection @code{bfd_get_arch_size}
 386 @strong{Synopsis}
 387 @example
 388 int bfd_get_arch_size (bfd *abfd);
 389 @end example
 390 @strong{Description}@*
 391 Returns the architecture address size, in bits, as determined
 392 by the object file's format.  For ELF, this information is
 393 included in the header.
 394
 395 @strong{Returns}@*
 396 Returns the arch size in bits if known, @code{-1} otherwise.
 397
 398 @findex bfd_get_sign_extend_vma
 399 @subsubsection @code{bfd_get_sign_extend_vma}
 400 @strong{Synopsis}
 401 @example
 402 int bfd_get_sign_extend_vma (bfd *abfd);
 403 @end example
 404 @strong{Description}@*
 405 Indicates if the target architecture "naturally" sign extends
 406 an address.  Some architectures implicitly sign extend address
 407 values when they are converted to types larger than the size
 408 of an address.  For instance, bfd_get_start_address() will
 409 return an address sign extended to fill a bfd_vma when this is
 410 the case.
 411
 412 @strong{Returns}@*
 413 Returns @code{1} if the target architecture is known to sign
 414 extend addresses, @code{0} if the target architecture is known to
 415 not sign extend addresses, and @code{-1} otherwise.
 416
 417 @findex bfd_set_start_address
 418 @subsubsection @code{bfd_set_start_address}
 419 @strong{Synopsis}
 420 @example
 421 bfd_boolean bfd_set_start_address (bfd *abfd, bfd_vma vma);
 422 @end example
 423 @strong{Description}@*
 424 Make @var{vma} the entry point of output BFD @var{abfd}.
 425
 426 @strong{Returns}@*
 427 Returns @code{TRUE} on success, @code{FALSE} otherwise.
 428
 429 @findex bfd_get_gp_size
 430 @subsubsection @code{bfd_get_gp_size}
 431 @strong{Synopsis}
 432 @example
 433 unsigned int bfd_get_gp_size (bfd *abfd);
 434 @end example
 435 @strong{Description}@*
 436 Return the maximum size of objects to be optimized using the GP
 437 register under MIPS ECOFF.  This is typically set by the @code{-G}
 438 argument to the compiler, assembler or linker.
 439
 440 @findex bfd_set_gp_size
 441 @subsubsection @code{bfd_set_gp_size}
 442 @strong{Synopsis}
 443 @example
 444 void bfd_set_gp_size (bfd *abfd, unsigned int i);
 445 @end example
 446 @strong{Description}@*
 447 Set the maximum size of objects to be optimized using the GP
 448 register under ECOFF or MIPS ELF.  This is typically set by
 449 the @code{-G} argument to the compiler, assembler or linker.
 450
 451 @findex bfd_scan_vma
 452 @subsubsection @code{bfd_scan_vma}
 453 @strong{Synopsis}
 454 @example
 455 bfd_vma bfd_scan_vma (const char *string, const char **end, int base);
 456 @end example
 457 @strong{Description}@*
 458 Convert, like @code{strtoul}, a numerical expression
 459 @var{string} into a @code{bfd_vma} integer, and return that integer.
 460 (Though without as many bells and whistles as @code{strtoul}.)
 461 The expression is assumed to be unsigned (i.e., positive).
 462 If given a @var{base}, it is used as the base for conversion.
 463 A base of 0 causes the function to interpret the string
 464 in hex if a leading "0x" or "0X" is found, otherwise
 465 in octal if a leading zero is found, otherwise in decimal.
 466
 467 If the value would overflow, the maximum @code{bfd_vma} value is
 468 returned.
 469
 470 @findex bfd_copy_private_header_data
 471 @subsubsection @code{bfd_copy_private_header_data}
 472 @strong{Synopsis}
 473 @example
 474 bfd_boolean bfd_copy_private_header_data (bfd *ibfd, bfd *obfd);
 475 @end example
 476 @strong{Description}@*
 477 Copy private BFD header information from the BFD @var{ibfd} to the
 478 the BFD @var{obfd}.  This copies information that may require
 479 sections to exist, but does not require symbol tables.  Return
 480 @code{true} on success, @code{false} on error.
 481 Possible error returns are:
 482
 483 @itemize @bullet
 484
 485 @item
 486 @code{bfd_error_no_memory} -
 487 Not enough memory exists to create private data for @var{obfd}.
 488 @end itemize
 489 @example
 490 #define bfd_copy_private_header_data(ibfd, obfd) \
 491      BFD_SEND (obfd, _bfd_copy_private_header_data, \
 492                (ibfd, obfd))
 493 @end example
 494
 495 @findex bfd_copy_private_bfd_data
 496 @subsubsection @code{bfd_copy_private_bfd_data}
 497 @strong{Synopsis}
 498 @example
 499 bfd_boolean bfd_copy_private_bfd_data (bfd *ibfd, bfd *obfd);
 500 @end example
 501 @strong{Description}@*
 502 Copy private BFD information from the BFD @var{ibfd} to the
 503 the BFD @var{obfd}.  Return @code{TRUE} on success, @code{FALSE} on error.
 504 Possible error returns are:
 505
 506 @itemize @bullet
 507
 508 @item
 509 @code{bfd_error_no_memory} -
 510 Not enough memory exists to create private data for @var{obfd}.
 511 @end itemize
 512 @example
 513 #define bfd_copy_private_bfd_data(ibfd, obfd) \
 514      BFD_SEND (obfd, _bfd_copy_private_bfd_data, \
 515                (ibfd, obfd))
 516 @end example
 517
 518 @findex bfd_merge_private_bfd_data
 519 @subsubsection @code{bfd_merge_private_bfd_data}
 520 @strong{Synopsis}
 521 @example
 522 bfd_boolean bfd_merge_private_bfd_data (bfd *ibfd, bfd *obfd);
 523 @end example
 524 @strong{Description}@*
 525 Merge private BFD information from the BFD @var{ibfd} to the
 526 the output file BFD @var{obfd} when linking.  Return @code{TRUE}
 527 on success, @code{FALSE} on error.  Possible error returns are:
 528
 529 @itemize @bullet
 530
 531 @item
 532 @code{bfd_error_no_memory} -
 533 Not enough memory exists to create private data for @var{obfd}.
 534 @end itemize
 535 @example
 536 #define bfd_merge_private_bfd_data(ibfd, obfd) \
 537      BFD_SEND (obfd, _bfd_merge_private_bfd_data, \
 538                (ibfd, obfd))
 539 @end example
 540
 541 @findex bfd_set_private_flags
 542 @subsubsection @code{bfd_set_private_flags}
 543 @strong{Synopsis}
 544 @example
 545 bfd_boolean bfd_set_private_flags (bfd *abfd, flagword flags);
 546 @end example
 547 @strong{Description}@*
 548 Set private BFD flag information in the BFD @var{abfd}.
 549 Return @code{TRUE} on success, @code{FALSE} on error.  Possible error
 550 returns are:
 551
 552 @itemize @bullet
 553
 554 @item
 555 @code{bfd_error_no_memory} -
 556 Not enough memory exists to create private data for @var{obfd}.
 557 @end itemize
 558 @example
 559 #define bfd_set_private_flags(abfd, flags) \
 560      BFD_SEND (abfd, _bfd_set_private_flags, (abfd, flags))
 561 @end example
 562
 563 @findex Other functions
 564 @subsubsection @code{Other functions}
 565 @strong{Description}@*
 566 The following functions exist but have not yet been documented.
 567 @example
 568 #define bfd_sizeof_headers(abfd, info) \
 569        BFD_SEND (abfd, _bfd_sizeof_headers, (abfd, info))
 570
 571 #define bfd_find_nearest_line(abfd, sec, syms, off, file, func, line) \
 572        BFD_SEND (abfd, _bfd_find_nearest_line, \
 573                  (abfd, sec, syms, off, file, func, line))
 574
 575 #define bfd_find_line(abfd, syms, sym, file, line) \
 576        BFD_SEND (abfd, _bfd_find_line, \
 577                  (abfd, syms, sym, file, line))
 578
 579 #define bfd_find_inliner_info(abfd, file, func, line) \
 580        BFD_SEND (abfd, _bfd_find_inliner_info, \
 581                  (abfd, file, func, line))
 582
 583 #define bfd_debug_info_start(abfd) \
 584        BFD_SEND (abfd, _bfd_debug_info_start, (abfd))
 585
 586 #define bfd_debug_info_end(abfd) \
 587        BFD_SEND (abfd, _bfd_debug_info_end, (abfd))
 588
 589 #define bfd_debug_info_accumulate(abfd, section) \
 590        BFD_SEND (abfd, _bfd_debug_info_accumulate, (abfd, section))
 591
 592 #define bfd_stat_arch_elt(abfd, stat) \
 593        BFD_SEND (abfd, _bfd_stat_arch_elt,(abfd, stat))
 594
 595 #define bfd_update_armap_timestamp(abfd) \
 596        BFD_SEND (abfd, _bfd_update_armap_timestamp, (abfd))
 597
 598 #define bfd_set_arch_mach(abfd, arch, mach)\
 599        BFD_SEND ( abfd, _bfd_set_arch_mach, (abfd, arch, mach))
 600
 601 #define bfd_relax_section(abfd, section, link_info, again) \
 602        BFD_SEND (abfd, _bfd_relax_section, (abfd, section, link_info, again))
 603
 604 #define bfd_gc_sections(abfd, link_info) \
 605        BFD_SEND (abfd, _bfd_gc_sections, (abfd, link_info))
 606
 607 #define bfd_merge_sections(abfd, link_info) \
 608        BFD_SEND (abfd, _bfd_merge_sections, (abfd, link_info))
 609
 610 #define bfd_is_group_section(abfd, sec) \
 611        BFD_SEND (abfd, _bfd_is_group_section, (abfd, sec))
 612
 613 #define bfd_discard_group(abfd, sec) \
 614        BFD_SEND (abfd, _bfd_discard_group, (abfd, sec))
 615
 616 #define bfd_link_hash_table_create(abfd) \
 617        BFD_SEND (abfd, _bfd_link_hash_table_create, (abfd))
 618
 619 #define bfd_link_hash_table_free(abfd, hash) \
 620        BFD_SEND (abfd, _bfd_link_hash_table_free, (hash))
 621
 622 #define bfd_link_add_symbols(abfd, info) \
 623        BFD_SEND (abfd, _bfd_link_add_symbols, (abfd, info))
 624
 625 #define bfd_link_just_syms(abfd, sec, info) \
 626        BFD_SEND (abfd, _bfd_link_just_syms, (sec, info))
 627
 628 #define bfd_final_link(abfd, info) \
 629        BFD_SEND (abfd, _bfd_final_link, (abfd, info))
 630
 631 #define bfd_free_cached_info(abfd) \
 632        BFD_SEND (abfd, _bfd_free_cached_info, (abfd))
 633
 634 #define bfd_get_dynamic_symtab_upper_bound(abfd) \
 635        BFD_SEND (abfd, _bfd_get_dynamic_symtab_upper_bound, (abfd))
 636
 637 #define bfd_print_private_bfd_data(abfd, file)\
 638        BFD_SEND (abfd, _bfd_print_private_bfd_data, (abfd, file))
 639
 640 #define bfd_canonicalize_dynamic_symtab(abfd, asymbols) \
 641        BFD_SEND (abfd, _bfd_canonicalize_dynamic_symtab, (abfd, asymbols))
 642
 643 #define bfd_get_synthetic_symtab(abfd, count, syms, dyncount, dynsyms, ret) \
 644        BFD_SEND (abfd, _bfd_get_synthetic_symtab, (abfd, count, syms, \
 645                                                    dyncount, dynsyms, ret))
 646
 647 #define bfd_get_dynamic_reloc_upper_bound(abfd) \
 648        BFD_SEND (abfd, _bfd_get_dynamic_reloc_upper_bound, (abfd))
 649
 650 #define bfd_canonicalize_dynamic_reloc(abfd, arels, asyms) \
 651        BFD_SEND (abfd, _bfd_canonicalize_dynamic_reloc, (abfd, arels, asyms))
 652
 653 extern bfd_byte *bfd_get_relocated_section_contents
 654   (bfd *, struct bfd_link_info *, struct bfd_link_order *, bfd_byte *,
 655    bfd_boolean, asymbol **);
 656
 657 @end example
 658
 659 @findex bfd_alt_mach_code
 660 @subsubsection @code{bfd_alt_mach_code}
 661 @strong{Synopsis}
 662 @example
 663 bfd_boolean bfd_alt_mach_code (bfd *abfd, int alternative);
 664 @end example
 665 @strong{Description}@*
 666 When more than one machine code number is available for the
 667 same machine type, this function can be used to switch between
 668 the preferred one (alternative == 0) and any others.  Currently,
 669 only ELF supports this feature, with up to two alternate
 670 machine codes.
 671
 672
 673 @example
 674 struct bfd_preserve
 675 @{
 676   void *marker;
 677   void *tdata;
 678   flagword flags;
 679   const struct bfd_arch_info *arch_info;
 680   struct bfd_section *sections;
 681   struct bfd_section *section_last;
 682   unsigned int section_count;
 683   struct bfd_hash_table section_htab;
 684 @};
 685
 686 @end example
 687 @findex bfd_preserve_save
 688 @subsubsection @code{bfd_preserve_save}
 689 @strong{Synopsis}
 690 @example
 691 bfd_boolean bfd_preserve_save (bfd *, struct bfd_preserve *);
 692 @end example
 693 @strong{Description}@*
 694 When testing an object for compatibility with a particular
 695 target back-end, the back-end object_p function needs to set
 696 up certain fields in the bfd on successfully recognizing the
 697 object.  This typically happens in a piecemeal fashion, with
 698 failures possible at many points.  On failure, the bfd is
 699 supposed to be restored to its initial state, which is
 700 virtually impossible.  However, restoring a subset of the bfd
 701 state works in practice.  This function stores the subset and
 702 reinitializes the bfd.
 703
 704 @findex bfd_preserve_restore
 705 @subsubsection @code{bfd_preserve_restore}
 706 @strong{Synopsis}
 707 @example
 708 void bfd_preserve_restore (bfd *, struct bfd_preserve *);
 709 @end example
 710 @strong{Description}@*
 711 This function restores bfd state saved by bfd_preserve_save.
 712 If MARKER is non-NULL in struct bfd_preserve then that block
 713 and all subsequently bfd_alloc'd memory is freed.
 714
 715 @findex bfd_preserve_finish
 716 @subsubsection @code{bfd_preserve_finish}
 717 @strong{Synopsis}
 718 @example
 719 void bfd_preserve_finish (bfd *, struct bfd_preserve *);
 720 @end example
 721 @strong{Description}@*
 722 This function should be called when the bfd state saved by
 723 bfd_preserve_save is no longer needed.  ie. when the back-end
 724 object_p function returns with success.
 725
 726 @findex bfd_emul_get_maxpagesize
 727 @subsubsection @code{bfd_emul_get_maxpagesize}
 728 @strong{Synopsis}
 729 @example
 730 bfd_vma bfd_emul_get_maxpagesize (const char *);
 731 @end example
 732 @strong{Description}@*
 733 Returns the maximum page size, in bytes, as determined by
 734 emulation.
 735
 736 @strong{Returns}@*
 737 Returns the maximum page size in bytes for ELF, abort
 738 otherwise.
 739
 740 @findex bfd_emul_set_maxpagesize
 741 @subsubsection @code{bfd_emul_set_maxpagesize}
 742 @strong{Synopsis}
 743 @example
 744 void bfd_emul_set_maxpagesize (const char *, bfd_vma);
 745 @end example
 746 @strong{Description}@*
 747 For ELF, set the maximum page size for the emulation.  It is
 748 a no-op for other formats.
 749
 750 @findex bfd_emul_get_commonpagesize
 751 @subsubsection @code{bfd_emul_get_commonpagesize}
 752 @strong{Synopsis}
 753 @example
 754 bfd_vma bfd_emul_get_commonpagesize (const char *);
 755 @end example
 756 @strong{Description}@*
 757 Returns the common page size, in bytes, as determined by
 758 emulation.
 759
 760 @strong{Returns}@*
 761 Returns the common page size in bytes for ELF, abort otherwise.
 762
 763 @findex bfd_emul_set_commonpagesize
 764 @subsubsection @code{bfd_emul_set_commonpagesize}
 765 @strong{Synopsis}
 766 @example
 767 void bfd_emul_set_commonpagesize (const char *, bfd_vma);
 768 @end example
 769 @strong{Description}@*
 770 For ELF, set the common page size for the emulation.  It is
 771 a no-op for other formats.
 772
 773 @findex bfd_demangle
 774 @subsubsection @code{bfd_demangle}
 775 @strong{Synopsis}
 776 @example
 777 char *bfd_demangle (bfd *, const char *, int);
 778 @end example
 779 @strong{Description}@*
 780 Wrapper around cplus_demangle.  Strips leading underscores and
 781 other such chars that would otherwise confuse the demangler.
 782 If passed a g++ v3 ABI mangled name, returns a buffer allocated
 783 with malloc holding the demangled name.  Returns NULL otherwise
 784 and on memory alloc failure.
 785