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. |
- |