GDB 7.6.50

bfd/doc/opncls.texi

Index: bfd/doc/opncls.texi
diff --git a/bfd/doc/opncls.texi b/bfd/doc/opncls.texi
deleted file mode 100644
index 1562ea57efe989e9a3f8fb253c58dd95c0d779cb..0000000000000000000000000000000000000000
--- a/bfd/doc/opncls.texi
+++ /dev/null
@@ -1,381 +0,0 @@
-
-@example
-/* Set to N to open the next N BFDs using an alternate id space.  */
-extern unsigned int bfd_use_reserved_id;
-@end example
-@section Opening and closing BFDs
-
-
-@subsection Functions for opening and closing
-
-
-@findex bfd_fopen
-@subsubsection @code{bfd_fopen}
-@strong{Synopsis}
-@example
-bfd *bfd_fopen (const char *filename, const char *target,
-    const char *mode, int fd);
-@end example
-@strong{Description}@*
-Open the file @var{filename} with the target @var{target}.
-Return a pointer to the created BFD.  If @var{fd} is not -1,
-then @code{fdopen} is used to open the file; otherwise, @code{fopen}
-is used.  @var{mode} is passed directly to @code{fopen} or
-@code{fdopen}. 
-
-Calls @code{bfd_find_target}, so @var{target} is interpreted as by
-that function.
-
-The new BFD is marked as cacheable iff @var{fd} is -1.
-
-If @code{NULL} is returned then an error has occured.   Possible errors
-are @code{bfd_error_no_memory}, @code{bfd_error_invalid_target} or
-@code{system_call} error.
-
-On error, @var{fd} is always closed.
-
-@findex bfd_openr
-@subsubsection @code{bfd_openr}
-@strong{Synopsis}
-@example
-bfd *bfd_openr (const char *filename, const char *target);
-@end example
-@strong{Description}@*
-Open the file @var{filename} (using @code{fopen}) with the target
-@var{target}.  Return a pointer to the created BFD.
-
-Calls @code{bfd_find_target}, so @var{target} is interpreted as by
-that function.
-
-If @code{NULL} is returned then an error has occured.   Possible errors
-are @code{bfd_error_no_memory}, @code{bfd_error_invalid_target} or
-@code{system_call} error.
-
-@findex bfd_fdopenr
-@subsubsection @code{bfd_fdopenr}
-@strong{Synopsis}
-@example
-bfd *bfd_fdopenr (const char *filename, const char *target, int fd);
-@end example
-@strong{Description}@*
-@code{bfd_fdopenr} is to @code{bfd_fopenr} much like @code{fdopen} is to
-@code{fopen}.  It opens a BFD on a file already described by the
-@var{fd} supplied.
-
-When the file is later @code{bfd_close}d, the file descriptor will
-be closed.  If the caller desires that this file descriptor be
-cached by BFD (opened as needed, closed as needed to free
-descriptors for other opens), with the supplied @var{fd} used as
-an initial file descriptor (but subject to closure at any time),
-call bfd_set_cacheable(bfd, 1) on the returned BFD.  The default
-is to assume no caching; the file descriptor will remain open
-until @code{bfd_close}, and will not be affected by BFD operations
-on other files.
-
-Possible errors are @code{bfd_error_no_memory},
-@code{bfd_error_invalid_target} and @code{bfd_error_system_call}.
-
-On error, @var{fd} is closed.
-
-@findex bfd_openstreamr
-@subsubsection @code{bfd_openstreamr}
-@strong{Synopsis}
-@example
-bfd *bfd_openstreamr (const char *, const char *, void *);
-@end example
-@strong{Description}@*
-Open a BFD for read access on an existing stdio stream.  When
-the BFD is passed to @code{bfd_close}, the stream will be closed.
-
-@findex bfd_openr_iovec
-@subsubsection @code{bfd_openr_iovec}
-@strong{Synopsis}
-@example
-bfd *bfd_openr_iovec (const char *filename, const char *target,
-    void *(*open_func) (struct bfd *nbfd,
-    void *open_closure),
-    void *open_closure,
-    file_ptr (*pread_func) (struct bfd *nbfd,
-    void *stream,
-    void *buf,
-    file_ptr nbytes,
-    file_ptr offset),
-    int (*close_func) (struct bfd *nbfd,
-    void *stream),
-    int (*stat_func) (struct bfd *abfd,
-    void *stream,
-    struct stat *sb));
-@end example
-@strong{Description}@*
-Create and return a BFD backed by a read-only @var{stream}.
-The @var{stream} is created using @var{open_func}, accessed using
-@var{pread_func} and destroyed using @var{close_func}.
-
-Calls @code{bfd_find_target}, so @var{target} is interpreted as by
-that function.
-
-Calls @var{open_func} (which can call @code{bfd_zalloc} and
-@code{bfd_get_filename}) to obtain the read-only stream backing
-the BFD.  @var{open_func} either succeeds returning the
-non-@code{NULL} @var{stream}, or fails returning @code{NULL}
-(setting @code{bfd_error}).
-
-Calls @var{pread_func} to request @var{nbytes} of data from
-@var{stream} starting at @var{offset} (e.g., via a call to
-@code{bfd_read}).  @var{pread_func} either succeeds returning the
-number of bytes read (which can be less than @var{nbytes} when
-end-of-file), or fails returning -1 (setting @code{bfd_error}).
-
-Calls @var{close_func} when the BFD is later closed using
-@code{bfd_close}.  @var{close_func} either succeeds returning 0, or
-fails returning -1 (setting @code{bfd_error}).
-
-Calls @var{stat_func} to fill in a stat structure for bfd_stat,
-bfd_get_size, and bfd_get_mtime calls.  @var{stat_func} returns 0
-on success, or returns -1 on failure (setting @code{bfd_error}).
-
-If @code{bfd_openr_iovec} returns @code{NULL} then an error has
-occurred.  Possible errors are @code{bfd_error_no_memory},
-@code{bfd_error_invalid_target} and @code{bfd_error_system_call}.
-
-@findex bfd_openw
-@subsubsection @code{bfd_openw}
-@strong{Synopsis}
-@example
-bfd *bfd_openw (const char *filename, const char *target);
-@end example
-@strong{Description}@*
-Create a BFD, associated with file @var{filename}, using the
-file format @var{target}, and return a pointer to it.
-
-Possible errors are @code{bfd_error_system_call}, @code{bfd_error_no_memory},
-@code{bfd_error_invalid_target}.
-
-@findex bfd_close
-@subsubsection @code{bfd_close}
-@strong{Synopsis}
-@example
-bfd_boolean bfd_close (bfd *abfd);
-@end example
-@strong{Description}@*
-Close a BFD. If the BFD was open for writing, then pending
-operations are completed and the file written out and closed.
-If the created file is executable, then @code{chmod} is called
-to mark it as such.
-
-All memory attached to the BFD is released.
-
-The file descriptor associated with the BFD is closed (even
-if it was passed in to BFD by @code{bfd_fdopenr}).
-
-@strong{Returns}@*
-@code{TRUE} is returned if all is ok, otherwise @code{FALSE}.
-
-@findex bfd_close_all_done
-@subsubsection @code{bfd_close_all_done}
-@strong{Synopsis}
-@example
-bfd_boolean bfd_close_all_done (bfd *);
-@end example
-@strong{Description}@*
-Close a BFD.  Differs from @code{bfd_close} since it does not
-complete any pending operations.  This routine would be used
-if the application had just used BFD for swapping and didn't
-want to use any of the writing code.
-
-If the created file is executable, then @code{chmod} is called
-to mark it as such.
-
-All memory attached to the BFD is released.
-
-@strong{Returns}@*
-@code{TRUE} is returned if all is ok, otherwise @code{FALSE}.
-
-@findex bfd_create
-@subsubsection @code{bfd_create}
-@strong{Synopsis}
-@example
-bfd *bfd_create (const char *filename, bfd *templ);
-@end example
-@strong{Description}@*
-Create a new BFD in the manner of @code{bfd_openw}, but without
-opening a file. The new BFD takes the target from the target
-used by @var{templ}. The format is always set to @code{bfd_object}.
-
-@findex bfd_make_writable
-@subsubsection @code{bfd_make_writable}
-@strong{Synopsis}
-@example
-bfd_boolean bfd_make_writable (bfd *abfd);
-@end example
-@strong{Description}@*
-Takes a BFD as created by @code{bfd_create} and converts it
-into one like as returned by @code{bfd_openw}.  It does this
-by converting the BFD to BFD_IN_MEMORY.  It's assumed that
-you will call @code{bfd_make_readable} on this bfd later.
-
-@strong{Returns}@*
-@code{TRUE} is returned if all is ok, otherwise @code{FALSE}.
-
-@findex bfd_make_readable
-@subsubsection @code{bfd_make_readable}
-@strong{Synopsis}
-@example
-bfd_boolean bfd_make_readable (bfd *abfd);
-@end example
-@strong{Description}@*
-Takes a BFD as created by @code{bfd_create} and
-@code{bfd_make_writable} and converts it into one like as
-returned by @code{bfd_openr}.  It does this by writing the
-contents out to the memory buffer, then reversing the
-direction.
-
-@strong{Returns}@*
-@code{TRUE} is returned if all is ok, otherwise @code{FALSE}.
-
-@findex bfd_alloc
-@subsubsection @code{bfd_alloc}
-@strong{Synopsis}
-@example
-void *bfd_alloc (bfd *abfd, bfd_size_type wanted);
-@end example
-@strong{Description}@*
-Allocate a block of @var{wanted} bytes of memory attached to
-@code{abfd} and return a pointer to it.
-
-@findex bfd_alloc2
-@subsubsection @code{bfd_alloc2}
-@strong{Synopsis}
-@example
-void *bfd_alloc2 (bfd *abfd, bfd_size_type nmemb, bfd_size_type size);
-@end example
-@strong{Description}@*
-Allocate a block of @var{nmemb} elements of @var{size} bytes each
-of memory attached to @code{abfd} and return a pointer to it.
-
-@findex bfd_zalloc
-@subsubsection @code{bfd_zalloc}
-@strong{Synopsis}
-@example
-void *bfd_zalloc (bfd *abfd, bfd_size_type wanted);
-@end example
-@strong{Description}@*
-Allocate a block of @var{wanted} bytes of zeroed memory
-attached to @code{abfd} and return a pointer to it.
-
-@findex bfd_zalloc2
-@subsubsection @code{bfd_zalloc2}
-@strong{Synopsis}
-@example
-void *bfd_zalloc2 (bfd *abfd, bfd_size_type nmemb, bfd_size_type size);
-@end example
-@strong{Description}@*
-Allocate a block of @var{nmemb} elements of @var{size} bytes each
-of zeroed memory attached to @code{abfd} and return a pointer to it.
-
-@findex bfd_calc_gnu_debuglink_crc32
-@subsubsection @code{bfd_calc_gnu_debuglink_crc32}
-@strong{Synopsis}
-@example
-unsigned long bfd_calc_gnu_debuglink_crc32
-   (unsigned long crc, const unsigned char *buf, bfd_size_type len);
-@end example
-@strong{Description}@*
-Computes a CRC value as used in the .gnu_debuglink section.
-Advances the previously computed @var{crc} value by computing
-and adding in the crc32 for @var{len} bytes of @var{buf}.
-
-@strong{Returns}@*
-Return the updated CRC32 value.
-
-@findex get_debug_link_info
-@subsubsection @code{get_debug_link_info}
-@strong{Synopsis}
-@example
-char *get_debug_link_info (bfd *abfd, unsigned long *crc32_out);
-@end example
-@strong{Description}@*
-fetch the filename and CRC32 value for any separate debuginfo
-associated with @var{abfd}. Return NULL if no such info found,
-otherwise return filename and update @var{crc32_out}.
-
-@findex separate_debug_file_exists
-@subsubsection @code{separate_debug_file_exists}
-@strong{Synopsis}
-@example
-bfd_boolean separate_debug_file_exists
-   (char *name, unsigned long crc32);
-@end example
-@strong{Description}@*
-Checks to see if @var{name} is a file and if its contents
-match @var{crc32}.
-
-@findex find_separate_debug_file
-@subsubsection @code{find_separate_debug_file}
-@strong{Synopsis}
-@example
-char *find_separate_debug_file (bfd *abfd);
-@end example
-@strong{Description}@*
-Searches @var{abfd} for a reference to separate debugging
-information, scans various locations in the filesystem, including
-the file tree rooted at @var{debug_file_directory}, and returns a
-filename of such debugging information if the file is found and has
-matching CRC32.  Returns NULL if no reference to debugging file
-exists, or file cannot be found.
-
-@findex bfd_follow_gnu_debuglink
-@subsubsection @code{bfd_follow_gnu_debuglink}
-@strong{Synopsis}
-@example
-char *bfd_follow_gnu_debuglink (bfd *abfd, const char *dir);
-@end example
-@strong{Description}@*
-Takes a BFD and searches it for a .gnu_debuglink section.  If this
-section is found, it examines the section for the name and checksum
-of a '.debug' file containing auxiliary debugging information.  It
-then searches the filesystem for this .debug file in some standard
-locations, including the directory tree rooted at @var{dir}, and if
-found returns the full filename.
-
-If @var{dir} is NULL, it will search a default path configured into
-libbfd at build time.  [XXX this feature is not currently
-implemented].
-
-@strong{Returns}@*
-@code{NULL} on any errors or failure to locate the .debug file,
-otherwise a pointer to a heap-allocated string containing the
-filename.  The caller is responsible for freeing this string.
-
-@findex bfd_create_gnu_debuglink_section
-@subsubsection @code{bfd_create_gnu_debuglink_section}
-@strong{Synopsis}
-@example
-struct bfd_section *bfd_create_gnu_debuglink_section
-   (bfd *abfd, const char *filename);
-@end example
-@strong{Description}@*
-Takes a @var{BFD} and adds a .gnu_debuglink section to it.  The section is sized
-to be big enough to contain a link to the specified @var{filename}.
-
-@strong{Returns}@*
-A pointer to the new section is returned if all is ok.  Otherwise @code{NULL} is
-returned and bfd_error is set.
-
-@findex bfd_fill_in_gnu_debuglink_section
-@subsubsection @code{bfd_fill_in_gnu_debuglink_section}
-@strong{Synopsis}
-@example
-bfd_boolean bfd_fill_in_gnu_debuglink_section
-   (bfd *abfd, struct bfd_section *sect, const char *filename);
-@end example
-@strong{Description}@*
-Takes a @var{BFD} and containing a .gnu_debuglink section @var{SECT}
-and fills in the contents of the section to contain a link to the
-specified @var{filename}.  The filename should be relative to the
-current directory.
-
-@strong{Returns}@*
-@code{TRUE} is returned if all is ok.  Otherwise @code{FALSE} is returned
-and bfd_error is set.
-