vendor/binutils/2.15.NOTHING

1 files changed, 0 insertions, 690 deletions

diff --git a/contrib/binutils/bfd/doc/bfdt.texi b/contrib/binutils/bfd/doc/bfdt.texi
deleted file mode 100644
index 74cace4a60a5..000000000000
--- a/contrib/binutils/bfd/doc/bfdt.texi
+++ /dev/null
@@ -1,690 +0,0 @@
-@section @code{typedef bfd}
-A BFD has type @code{bfd}; objects of this type are the
-cornerstone of any application using BFD. Using BFD
-consists of making references though the BFD and to data in the BFD.
-
-Here is the structure that defines the type @code{bfd}.  It
-contains the major data about the file and pointers
-to the rest of the data.
-
-
-@example
-
-struct bfd
-@{
-  /* A unique identifier of the BFD  */
-  unsigned int id;
-
-  /* The filename the application opened the BFD with.  */
-  const char *filename;
-
-  /* A pointer to the target jump table.  */
-  const struct bfd_target *xvec;
-
-  /* To avoid dragging too many header files into every file that
-     includes `@code{bfd.h}', IOSTREAM has been declared as a "char *",
-     and MTIME as a "long".  Their correct types, to which they
-     are cast when used, are "FILE *" and "time_t".    The iostream
-     is the result of an fopen on the filename.  However, if the
-     BFD_IN_MEMORY flag is set, then iostream is actually a pointer
-     to a bfd_in_memory struct.  */
-  void *iostream;
-
-  /* Is the file descriptor being cached?  That is, can it be closed as
-     needed, and re-opened when accessed later?  */
-  bfd_boolean cacheable;
-
-  /* Marks whether there was a default target specified when the
-     BFD was opened. This is used to select which matching algorithm
-     to use to choose the back end.  */
-  bfd_boolean target_defaulted;
-
-  /* The caching routines use these to maintain a
-     least-recently-used list of BFDs.  */
-  struct bfd *lru_prev, *lru_next;
-
-  /* When a file is closed by the caching routines, BFD retains
-     state information on the file here...  */
-  ufile_ptr where;
-
-  /* ... and here: (``once'' means at least once).  */
-  bfd_boolean opened_once;
-
-  /* Set if we have a locally maintained mtime value, rather than
-     getting it from the file each time.  */
-  bfd_boolean mtime_set;
-
-  /* File modified time, if mtime_set is TRUE.  */
-  long mtime;
-
-  /* Reserved for an unimplemented file locking extension.  */
-  int ifd;
-
-  /* The format which belongs to the BFD. (object, core, etc.)  */
-  bfd_format format;
-
-  /* The direction with which the BFD was opened.  */
-  enum bfd_direction
-    @{
-      no_direction = 0,
-      read_direction = 1,
-      write_direction = 2,
-      both_direction = 3
-    @}
-  direction;
-
-  /* Format_specific flags.  */
-  flagword flags;
-
-  /* Currently my_archive is tested before adding origin to
-     anything. I believe that this can become always an add of
-     origin, with origin set to 0 for non archive files.  */
-  ufile_ptr origin;
-
-  /* Remember when output has begun, to stop strange things
-     from happening.  */
-  bfd_boolean output_has_begun;
-
-  /* A hash table for section names.  */
-  struct bfd_hash_table section_htab;
-
-  /* Pointer to linked list of sections.  */
-  struct bfd_section *sections;
-
-  /* The place where we add to the section list.  */
-  struct bfd_section **section_tail;
-
-  /* The number of sections.  */
-  unsigned int section_count;
-
-  /* Stuff only useful for object files:
-     The start address.  */
-  bfd_vma start_address;
-
-  /* Used for input and output.  */
-  unsigned int symcount;
-
-  /* Symbol table for output BFD (with symcount entries).  */
-  struct bfd_symbol  **outsymbols;
-
-  /* Used for slurped dynamic symbol tables.  */
-  unsigned int dynsymcount;
-
-  /* Pointer to structure which contains architecture information.  */
-  const struct bfd_arch_info *arch_info;
-
-  /* Stuff only useful for archives.  */
-  void *arelt_data;
-  struct bfd *my_archive;      /* The containing archive BFD.  */
-  struct bfd *next;            /* The next BFD in the archive.  */
-  struct bfd *archive_head;    /* The first BFD in the archive.  */
-  bfd_boolean has_armap;
-
-  /* A chain of BFD structures involved in a link.  */
-  struct bfd *link_next;
-
-  /* A field used by _bfd_generic_link_add_archive_symbols.  This will
-     be used only for archive elements.  */
-  int archive_pass;
-
-  /* Used by the back end to hold private data.  */
-  union
-    @{
-      struct aout_data_struct *aout_data;
-      struct artdata *aout_ar_data;
-      struct _oasys_data *oasys_obj_data;
-      struct _oasys_ar_data *oasys_ar_data;
-      struct coff_tdata *coff_obj_data;
-      struct pe_tdata *pe_obj_data;
-      struct xcoff_tdata *xcoff_obj_data;
-      struct ecoff_tdata *ecoff_obj_data;
-      struct ieee_data_struct *ieee_data;
-      struct ieee_ar_data_struct *ieee_ar_data;
-      struct srec_data_struct *srec_data;
-      struct ihex_data_struct *ihex_data;
-      struct tekhex_data_struct *tekhex_data;
-      struct elf_obj_tdata *elf_obj_data;
-      struct nlm_obj_tdata *nlm_obj_data;
-      struct bout_data_struct *bout_data;
-      struct mmo_data_struct *mmo_data;
-      struct sun_core_struct *sun_core_data;
-      struct sco5_core_struct *sco5_core_data;
-      struct trad_core_struct *trad_core_data;
-      struct som_data_struct *som_data;
-      struct hpux_core_struct *hpux_core_data;
-      struct hppabsd_core_struct *hppabsd_core_data;
-      struct sgi_core_struct *sgi_core_data;
-      struct lynx_core_struct *lynx_core_data;
-      struct osf_core_struct *osf_core_data;
-      struct cisco_core_struct *cisco_core_data;
-      struct versados_data_struct *versados_data;
-      struct netbsd_core_struct *netbsd_core_data;
-      struct mach_o_data_struct *mach_o_data;
-      struct mach_o_fat_data_struct *mach_o_fat_data;
-      struct bfd_pef_data_struct *pef_data;
-      struct bfd_pef_xlib_data_struct *pef_xlib_data;
-      struct bfd_sym_data_struct *sym_data;
-      void *any;
-    @}
-  tdata;
-
-  /* Used by the application to hold private data.  */
-  void *usrdata;
-
-  /* Where all the allocated stuff under this BFD goes.  This is a
-     struct objalloc *, but we use void * to avoid requiring the inclusion
-     of objalloc.h.  */
-  void *memory;
-@};
-
-@end example
-@section Error reporting
-Most BFD functions return nonzero on success (check their
-individual documentation for precise semantics).  On an error,
-they call @code{bfd_set_error} to set an error condition that callers
-can check by calling @code{bfd_get_error}.
-If that returns @code{bfd_error_system_call}, then check
-@code{errno}.
-
-The easiest way to report a BFD error to the user is to
-use @code{bfd_perror}.
-
-@subsection Type @code{bfd_error_type}
-The values returned by @code{bfd_get_error} are defined by the
-enumerated type @code{bfd_error_type}.
-
-
-@example
-
-typedef enum bfd_error
-@{
-  bfd_error_no_error = 0,
-  bfd_error_system_call,
-  bfd_error_invalid_target,
-  bfd_error_wrong_format,
-  bfd_error_wrong_object_format,
-  bfd_error_invalid_operation,
-  bfd_error_no_memory,
-  bfd_error_no_symbols,
-  bfd_error_no_armap,
-  bfd_error_no_more_archived_files,
-  bfd_error_malformed_archive,
-  bfd_error_file_not_recognized,
-  bfd_error_file_ambiguously_recognized,
-  bfd_error_no_contents,
-  bfd_error_nonrepresentable_section,
-  bfd_error_no_debug_section,
-  bfd_error_bad_value,
-  bfd_error_file_truncated,
-  bfd_error_file_too_big,
-  bfd_error_invalid_error_code
-@}
-bfd_error_type;
-
-@end example
-@findex bfd_get_error
-@subsubsection @code{bfd_get_error}
-@strong{Synopsis}
-@example
-bfd_error_type bfd_get_error (void);
-@end example
-@strong{Description}@*
-Return the current BFD error condition.
-
-@findex bfd_set_error
-@subsubsection @code{bfd_set_error}
-@strong{Synopsis}
-@example
-void bfd_set_error (bfd_error_type error_tag);
-@end example
-@strong{Description}@*
-Set the BFD error condition to be @var{error_tag}.
-
-@findex bfd_errmsg
-@subsubsection @code{bfd_errmsg}
-@strong{Synopsis}
-@example
-const char *bfd_errmsg (bfd_error_type error_tag);
-@end example
-@strong{Description}@*
-Return a string describing the error @var{error_tag}, or
-the system error if @var{error_tag} is @code{bfd_error_system_call}.
-
-@findex bfd_perror
-@subsubsection @code{bfd_perror}
-@strong{Synopsis}
-@example
-void bfd_perror (const char *message);
-@end example
-@strong{Description}@*
-Print to the standard error stream a string describing the
-last BFD error that occurred, or the last system error if
-the last BFD error was a system call failure.  If @var{message}
-is non-NULL and non-empty, the error string printed is preceded
-by @var{message}, a colon, and a space.  It is followed by a newline.
-
-@subsection BFD error handler
-Some BFD functions want to print messages describing the
-problem.  They call a BFD error handler function.  This
-function may be overridden by the program.
-
-The BFD error handler acts like printf.
-
-
-@example
-
-typedef void (*bfd_error_handler_type) (const char *, ...);
-
-@end example
-@findex bfd_set_error_handler
-@subsubsection @code{bfd_set_error_handler}
-@strong{Synopsis}
-@example
-bfd_error_handler_type bfd_set_error_handler (bfd_error_handler_type);
-@end example
-@strong{Description}@*
-Set the BFD error handler function.  Returns the previous
-function.
-
-@findex bfd_set_error_program_name
-@subsubsection @code{bfd_set_error_program_name}
-@strong{Synopsis}
-@example
-void bfd_set_error_program_name (const char *);
-@end example
-@strong{Description}@*
-Set the program name to use when printing a BFD error.  This
-is printed before the error message followed by a colon and
-space.  The string must not be changed after it is passed to
-this function.
-
-@findex bfd_get_error_handler
-@subsubsection @code{bfd_get_error_handler}
-@strong{Synopsis}
-@example
-bfd_error_handler_type bfd_get_error_handler (void);
-@end example
-@strong{Description}@*
-Return the BFD error handler function.
-
-@findex bfd_archive_filename
-@subsubsection @code{bfd_archive_filename}
-@strong{Synopsis}
-@example
-const char *bfd_archive_filename (bfd *);
-@end example
-@strong{Description}@*
-For a BFD that is a component of an archive, returns a string
-with both the archive name and file name.  For other BFDs, just
-returns the file name.
-
-@section Symbols
-
-
-@findex bfd_get_reloc_upper_bound
-@subsubsection @code{bfd_get_reloc_upper_bound}
-@strong{Synopsis}
-@example
-long bfd_get_reloc_upper_bound (bfd *abfd, asection *sect);
-@end example
-@strong{Description}@*
-Return the number of bytes required to store the
-relocation information associated with section @var{sect}
-attached to bfd @var{abfd}.  If an error occurs, return -1.
-
-@findex bfd_canonicalize_reloc
-@subsubsection @code{bfd_canonicalize_reloc}
-@strong{Synopsis}
-@example
-long bfd_canonicalize_reloc
-   (bfd *abfd, asection *sec, arelent **loc, asymbol **syms);
-@end example
-@strong{Description}@*
-Call the back end associated with the open BFD
-@var{abfd} and translate the external form of the relocation
-information attached to @var{sec} into the internal canonical
-form.  Place the table into memory at @var{loc}, which has
-been preallocated, usually by a call to
-@code{bfd_get_reloc_upper_bound}.  Returns the number of relocs, or
--1 on error.
-
-The @var{syms} table is also needed for horrible internal magic
-reasons.
-
-@findex bfd_set_reloc
-@subsubsection @code{bfd_set_reloc}
-@strong{Synopsis}
-@example
-void bfd_set_reloc
-   (bfd *abfd, asection *sec, arelent **rel, unsigned int count);
-@end example
-@strong{Description}@*
-Set the relocation pointer and count within
-section @var{sec} to the values @var{rel} and @var{count}.
-The argument @var{abfd} is ignored.
-
-@findex bfd_set_file_flags
-@subsubsection @code{bfd_set_file_flags}
-@strong{Synopsis}
-@example
-bfd_boolean bfd_set_file_flags (bfd *abfd, flagword flags);
-@end example
-@strong{Description}@*
-Set the flag word in the BFD @var{abfd} to the value @var{flags}.
-
-Possible errors are:
-@itemize @bullet
-
-@item
-@code{bfd_error_wrong_format} - The target bfd was not of object format.
-@item
-@code{bfd_error_invalid_operation} - The target bfd was open for reading.
-@item
-@code{bfd_error_invalid_operation} -
-The flag word contained a bit which was not applicable to the
-type of file.  E.g., an attempt was made to set the @code{D_PAGED} bit
-on a BFD format which does not support demand paging.
-@end itemize
-
-@findex bfd_get_arch_size
-@subsubsection @code{bfd_get_arch_size}
-@strong{Synopsis}
-@example
-int bfd_get_arch_size (bfd *abfd);
-@end example
-@strong{Description}@*
-Returns the architecture address size, in bits, as determined
-by the object file's format.  For ELF, this information is
-included in the header.
-
-@strong{Returns}@*
-Returns the arch size in bits if known, @code{-1} otherwise.
-
-@findex bfd_get_sign_extend_vma
-@subsubsection @code{bfd_get_sign_extend_vma}
-@strong{Synopsis}
-@example
-int bfd_get_sign_extend_vma (bfd *abfd);
-@end example
-@strong{Description}@*
-Indicates if the target architecture "naturally" sign extends
-an address.  Some architectures implicitly sign extend address
-values when they are converted to types larger than the size
-of an address.  For instance, bfd_get_start_address() will
-return an address sign extended to fill a bfd_vma when this is
-the case.
-
-@strong{Returns}@*
-Returns @code{1} if the target architecture is known to sign
-extend addresses, @code{0} if the target architecture is known to
-not sign extend addresses, and @code{-1} otherwise.
-
-@findex bfd_set_start_address
-@subsubsection @code{bfd_set_start_address}
-@strong{Synopsis}
-@example
-bfd_boolean bfd_set_start_address (bfd *abfd, bfd_vma vma);
-@end example
-@strong{Description}@*
-Make @var{vma} the entry point of output BFD @var{abfd}.
-
-@strong{Returns}@*
-Returns @code{TRUE} on success, @code{FALSE} otherwise.
-
-@findex bfd_get_gp_size
-@subsubsection @code{bfd_get_gp_size}
-@strong{Synopsis}
-@example
-unsigned int bfd_get_gp_size (bfd *abfd);
-@end example
-@strong{Description}@*
-Return the maximum size of objects to be optimized using the GP
-register under MIPS ECOFF.  This is typically set by the @code{-G}
-argument to the compiler, assembler or linker.
-
-@findex bfd_set_gp_size
-@subsubsection @code{bfd_set_gp_size}
-@strong{Synopsis}
-@example
-void bfd_set_gp_size (bfd *abfd, unsigned int i);
-@end example
-@strong{Description}@*
-Set the maximum size of objects to be optimized using the GP
-register under ECOFF or MIPS ELF.  This is typically set by
-the @code{-G} argument to the compiler, assembler or linker.
-
-@findex bfd_scan_vma
-@subsubsection @code{bfd_scan_vma}
-@strong{Synopsis}
-@example
-bfd_vma bfd_scan_vma (const char *string, const char **end, int base);
-@end example
-@strong{Description}@*
-Convert, like @code{strtoul}, a numerical expression
-@var{string} into a @code{bfd_vma} integer, and return that integer.
-(Though without as many bells and whistles as @code{strtoul}.)
-The expression is assumed to be unsigned (i.e., positive).
-If given a @var{base}, it is used as the base for conversion.
-A base of 0 causes the function to interpret the string
-in hex if a leading "0x" or "0X" is found, otherwise
-in octal if a leading zero is found, otherwise in decimal.
-
-If the value would overflow, the maximum @code{bfd_vma} value is
-returned.
-
-@findex bfd_copy_private_bfd_data
-@subsubsection @code{bfd_copy_private_bfd_data}
-@strong{Synopsis}
-@example
-bfd_boolean bfd_copy_private_bfd_data (bfd *ibfd, bfd *obfd);
-@end example
-@strong{Description}@*
-Copy private BFD information from the BFD @var{ibfd} to the
-the BFD @var{obfd}.  Return @code{TRUE} on success, @code{FALSE} on error.
-Possible error returns are:
-
-@itemize @bullet
-
-@item
-@code{bfd_error_no_memory} -
-Not enough memory exists to create private data for @var{obfd}.
-@end itemize
-@example
-#define bfd_copy_private_bfd_data(ibfd, obfd) \
-     BFD_SEND (obfd, _bfd_copy_private_bfd_data, \
-               (ibfd, obfd))
-@end example
-
-@findex bfd_merge_private_bfd_data
-@subsubsection @code{bfd_merge_private_bfd_data}
-@strong{Synopsis}
-@example
-bfd_boolean bfd_merge_private_bfd_data (bfd *ibfd, bfd *obfd);
-@end example
-@strong{Description}@*
-Merge private BFD information from the BFD @var{ibfd} to the
-the output file BFD @var{obfd} when linking.  Return @code{TRUE}
-on success, @code{FALSE} on error.  Possible error returns are:
-
-@itemize @bullet
-
-@item
-@code{bfd_error_no_memory} -
-Not enough memory exists to create private data for @var{obfd}.
-@end itemize
-@example
-#define bfd_merge_private_bfd_data(ibfd, obfd) \
-     BFD_SEND (obfd, _bfd_merge_private_bfd_data, \
-               (ibfd, obfd))
-@end example
-
-@findex bfd_set_private_flags
-@subsubsection @code{bfd_set_private_flags}
-@strong{Synopsis}
-@example
-bfd_boolean bfd_set_private_flags (bfd *abfd, flagword flags);
-@end example
-@strong{Description}@*
-Set private BFD flag information in the BFD @var{abfd}.
-Return @code{TRUE} on success, @code{FALSE} on error.  Possible error
-returns are:
-
-@itemize @bullet
-
-@item
-@code{bfd_error_no_memory} -
-Not enough memory exists to create private data for @var{obfd}.
-@end itemize
-@example
-#define bfd_set_private_flags(abfd, flags) \
-     BFD_SEND (abfd, _bfd_set_private_flags, (abfd, flags))
-@end example
-
-@findex Other functions
-@subsubsection @code{Other functions}
-@strong{Description}@*
-The following functions exist but have not yet been documented.
-@example
-#define bfd_sizeof_headers(abfd, reloc) \
-       BFD_SEND (abfd, _bfd_sizeof_headers, (abfd, reloc))
-
-#define bfd_find_nearest_line(abfd, sec, syms, off, file, func, line) \
-       BFD_SEND (abfd, _bfd_find_nearest_line, \
-                 (abfd, sec, syms, off, file, func, line))
-
-#define bfd_debug_info_start(abfd) \
-       BFD_SEND (abfd, _bfd_debug_info_start, (abfd))
-
-#define bfd_debug_info_end(abfd) \
-       BFD_SEND (abfd, _bfd_debug_info_end, (abfd))
-
-#define bfd_debug_info_accumulate(abfd, section) \
-       BFD_SEND (abfd, _bfd_debug_info_accumulate, (abfd, section))
-
-#define bfd_stat_arch_elt(abfd, stat) \
-       BFD_SEND (abfd, _bfd_stat_arch_elt,(abfd, stat))
-
-#define bfd_update_armap_timestamp(abfd) \
-       BFD_SEND (abfd, _bfd_update_armap_timestamp, (abfd))
-
-#define bfd_set_arch_mach(abfd, arch, mach)\
-       BFD_SEND ( abfd, _bfd_set_arch_mach, (abfd, arch, mach))
-
-#define bfd_relax_section(abfd, section, link_info, again) \
-       BFD_SEND (abfd, _bfd_relax_section, (abfd, section, link_info, again))
-
-#define bfd_gc_sections(abfd, link_info) \
-       BFD_SEND (abfd, _bfd_gc_sections, (abfd, link_info))
-
-#define bfd_merge_sections(abfd, link_info) \
-       BFD_SEND (abfd, _bfd_merge_sections, (abfd, link_info))
-
-#define bfd_discard_group(abfd, sec) \
-       BFD_SEND (abfd, _bfd_discard_group, (abfd, sec))
-
-#define bfd_link_hash_table_create(abfd) \
-       BFD_SEND (abfd, _bfd_link_hash_table_create, (abfd))
-
-#define bfd_link_hash_table_free(abfd, hash) \
-       BFD_SEND (abfd, _bfd_link_hash_table_free, (hash))
-
-#define bfd_link_add_symbols(abfd, info) \
-       BFD_SEND (abfd, _bfd_link_add_symbols, (abfd, info))
-
-#define bfd_link_just_syms(sec, info) \
-       BFD_SEND (abfd, _bfd_link_just_syms, (sec, info))
-
-#define bfd_final_link(abfd, info) \
-       BFD_SEND (abfd, _bfd_final_link, (abfd, info))
-
-#define bfd_free_cached_info(abfd) \
-       BFD_SEND (abfd, _bfd_free_cached_info, (abfd))
-
-#define bfd_get_dynamic_symtab_upper_bound(abfd) \
-       BFD_SEND (abfd, _bfd_get_dynamic_symtab_upper_bound, (abfd))
-
-#define bfd_print_private_bfd_data(abfd, file)\
-       BFD_SEND (abfd, _bfd_print_private_bfd_data, (abfd, file))
-
-#define bfd_canonicalize_dynamic_symtab(abfd, asymbols) \
-       BFD_SEND (abfd, _bfd_canonicalize_dynamic_symtab, (abfd, asymbols))
-
-#define bfd_get_dynamic_reloc_upper_bound(abfd) \
-       BFD_SEND (abfd, _bfd_get_dynamic_reloc_upper_bound, (abfd))
-
-#define bfd_canonicalize_dynamic_reloc(abfd, arels, asyms) \
-       BFD_SEND (abfd, _bfd_canonicalize_dynamic_reloc, (abfd, arels, asyms))
-
-extern bfd_byte *bfd_get_relocated_section_contents
-  (bfd *, struct bfd_link_info *, struct bfd_link_order *, bfd_byte *,
-   bfd_boolean, asymbol **);
-
-@end example
-
-@findex bfd_alt_mach_code
-@subsubsection @code{bfd_alt_mach_code}
-@strong{Synopsis}
-@example
-bfd_boolean bfd_alt_mach_code (bfd *abfd, int alternative);
-@end example
-@strong{Description}@*
-When more than one machine code number is available for the
-same machine type, this function can be used to switch between
-the preferred one (alternative == 0) and any others.  Currently,
-only ELF supports this feature, with up to two alternate
-machine codes.
-
-
-@example
-struct bfd_preserve
-@{
-  void *marker;
-  void *tdata;
-  flagword flags;
-  const struct bfd_arch_info *arch_info;
-  struct bfd_section *sections;
-  struct bfd_section **section_tail;
-  unsigned int section_count;
-  struct bfd_hash_table section_htab;
-@};
-
-@end example
-@findex bfd_preserve_save
-@subsubsection @code{bfd_preserve_save}
-@strong{Synopsis}
-@example
-bfd_boolean bfd_preserve_save (bfd *, struct bfd_preserve *);
-@end example
-@strong{Description}@*
-When testing an object for compatibility with a particular
-target back-end, the back-end object_p function needs to set
-up certain fields in the bfd on successfully recognizing the
-object.  This typically happens in a piecemeal fashion, with
-failures possible at many points.  On failure, the bfd is
-supposed to be restored to its initial state, which is
-virtually impossible.  However, restoring a subset of the bfd
-state works in practice.  This function stores the subset and
-reinitializes the bfd.
-
-@findex bfd_preserve_restore
-@subsubsection @code{bfd_preserve_restore}
-@strong{Synopsis}
-@example
-void bfd_preserve_restore (bfd *, struct bfd_preserve *);
-@end example
-@strong{Description}@*
-This function restores bfd state saved by bfd_preserve_save.
-If MARKER is non-NULL in struct bfd_preserve then that block
-and all subsequently bfd_alloc'd memory is freed.
-
-@findex bfd_preserve_finish
-@subsubsection @code{bfd_preserve_finish}
-@strong{Synopsis}
-@example
-void bfd_preserve_finish (bfd *, struct bfd_preserve *);
-@end example
-@strong{Description}@*
-This function should be called when the bfd state saved by
-bfd_preserve_save is no longer needed.  ie. when the back-end
-object_p function returns with success.
-