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