1 files changed, 456 insertions, 0 deletions
diff --git a/bfd/doc/opncls.texi b/bfd/doc/opncls.texi
new file mode 100644
index 0000000..a7a57a6
--- /dev/null
+++ b/bfd/doc/opncls.texi
@@ -0,0 +1,456 @@
+
+@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.
+
+A copy of the @var{filename} argument is stored in the newly created
+BFD.  It can be accessed via the bfd_get_filename() macro.
+
+@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.
+
+A copy of the @var{filename} argument is stored in the newly created
+BFD.  It can be accessed via the bfd_get_filename() macro.
+
+@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.
+
+A copy of the @var{filename} argument is stored in the newly created
+BFD.  It can be accessed via the bfd_get_filename() macro.
+
+@findex bfd_openstreamr
+@subsubsection @code{bfd_openstreamr}
+@strong{Synopsis}
+@example
+bfd *bfd_openstreamr (const char * filename, const char * target, void * stream);
+@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.
+
+A copy of the @var{filename} argument is stored in the newly created
+BFD.  It can be accessed via the bfd_get_filename() macro.
+
+@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}.
+
+A copy of the @var{filename} argument is stored in the newly created
+BFD.  It can be accessed via the bfd_get_filename() macro.
+
+@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}.
+
+A copy of the @var{filename} argument is stored in the newly created
+BFD.  It can be accessed via the bfd_get_filename() macro.
+
+@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}.
+
+A copy of the @var{filename} argument is stored in the newly created
+BFD.  It can be accessed via the bfd_get_filename() macro.
+
+@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 bfd_get_debug_link_info
+@subsubsection @code{bfd_get_debug_link_info}
+@strong{Synopsis}
+@example
+char *bfd_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}.  The
+returned filename is allocated with @code{malloc}; freeing it
+is the responsibility of the caller.
+
+@findex bfd_get_alt_debug_link_info
+@subsubsection @code{bfd_get_alt_debug_link_info}
+@strong{Synopsis}
+@example
+char *bfd_get_alt_debug_link_info (bfd * abfd,
+    bfd_size_type *buildid_len,
+    bfd_byte **buildid_out);
+@end example
+@strong{Description}@*
+Fetch the filename and BuildID value for any alternate debuginfo
+associated with @var{abfd}.  Return NULL if no such info found,
+otherwise return filename and update @var{buildid_len} and
+@var{buildid_out}.  The returned filename and build_id are
+allocated with @code{malloc}; freeing them is the
+responsibility of the caller.
+
+@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 separate_alt_debug_file_exists
+@subsubsection @code{separate_alt_debug_file_exists}
+@strong{Synopsis}
+@example
+bfd_boolean separate_alt_debug_file_exists
+   (char *name, unsigned long crc32);
+@end example
+@strong{Description}@*
+Checks to see if @var{name} is a file and if its BuildID
+matches @var{buildid}.
+
+@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 section called @var{section_name} which
+is expected to contain a reference to a file containing separate
+debugging information.  The function scans various locations in
+the filesystem, including the file tree rooted at
+@var{debug_file_directory}, and returns the first matching
+filename that it finds.  If @var{check_crc} is TRUE then the
+contents of the file must also match the CRC value contained in
+@var{section_name}.  Returns NULL if no valid file could 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_follow_gnu_debugaltlink
+@subsubsection @code{bfd_follow_gnu_debugaltlink}
+@strong{Synopsis}
+@example
+char *bfd_follow_gnu_debugaltlink (bfd *abfd, const char *dir);
+@end example
+@strong{Description}@*
+Takes a BFD and searches it for a .gnu_debugaltlink section.  If this
+section is found, it examines the section for the name of a file
+containing auxiliary debugging information.  It then searches the
+filesystem for this file in a set of 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.  [FIXME: 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.
+