Opening and closing BFDs
========================

bfd_openr
.........

Synopsis

     bfd *bfd_openr(const char *filename, const char *target);

Description

Open the file FILENAME (using fopen) with the target TARGET.  Return a pointer to the created BFD.

Calls bfd_find_target, so TARGET is interpreted as by that function.

If NULL is returned then an error has occured.   Possible errors are bfd_error_no_memory, bfd_error_invalid_target or system_call error.

bfd_fdopenr
...........

Synopsis

     bfd *bfd_fdopenr(const char *filename, const char *target, int fd);

Description

bfd_fdopenr is to bfd_fopenr much like fdopen is to fopen.  It opens a BFD on a file already described by the FD supplied.

When the file is later bfd_closed, 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 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 cacheing; the file descriptor will remain open until bfd_close, and will not be affected by BFD operations on other files.

Possible errors are bfd_error_no_memory, bfd_error_invalid_target and bfd_error_system_call.

bfd_openstreamr
...............

Synopsis

     bfd *bfd_openstreamr(const char *, const char *, PTR);

Description

Open a BFD for read access on an existing stdio stream.  When the BFD is passed to bfd_close, the stream will be closed.

bfd_openw
.........

Synopsis

     bfd *bfd_openw(const char *filename, const char *target);

Description

Create a BFD, associated with file FILENAME, using the file format TARGET, and return a pointer to it.

Possible errors are bfd_error_system_call, bfd_error_no_memory, bfd_error_invalid_target.

bfd_close
.........

Synopsis

     bfd_boolean bfd_close (bfd *abfd);

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

Returns

TRUE is returned if all is ok, otherwise FALSE.

bfd_close_all_done
..................

Synopsis

     bfd_boolean bfd_close_all_done (bfd *);

Description

Close a BFD.  Differs from 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 chmod is called to mark it as such.

All memory attached to the BFD is released.

Returns

TRUE is returned if all is ok, otherwise FALSE.

bfd_create
..........

Synopsis

     bfd *bfd_create(const char *filename, bfd *templ);

Description

Create a new BFD in the manner of bfd_openw, but without opening a file. The new BFD takes the target from the target used by TEMPLATE. The format is always set to bfd_object.

bfd_make_writable
.................

Synopsis

     bfd_boolean bfd_make_writable (bfd *abfd);

Description

Takes a BFD as created by bfd_create and converts it into one like as returned by bfd_openw.  It does this by converting the BFD to BFD_IN_MEMORY.  It's assumed that you will call bfd_make_readable on this bfd later.

Returns

TRUE is returned if all is ok, otherwise FALSE.

bfd_make_readable
.................

Synopsis

     bfd_boolean bfd_make_readable (bfd *abfd);

Description

Takes a BFD as created by bfd_create and bfd_make_writable and converts it into one like as returned by bfd_openr.  It does this by writing the contents out to the memory buffer, then reversing the direction.

Returns

TRUE is returned if all is ok, otherwise FALSE.

bfd_alloc
.........

Synopsis

     PTR bfd_alloc (bfd *abfd, size_t wanted);

Description

Allocate a block of WANTED bytes of memory attached to abfd and return a pointer to it.

calc_crc32
..........

Synopsis

     unsigned long calc_crc32 (unsigned long crc, const unsigned char *buf, size_t len);

Description

Advance the CRC32 given by CRC through LEN bytes of BUF. Return the updated CRC32 value.

get_debug_link_info
...................

Synopsis

     char *get_debug_link_info (bfd *abfd, unsigned long *crc32_out)

Description

fetch the filename and CRC32 value for any separate debuginfo associated with ABFD. Return NULL if no such info found, otherwise return filename and update CRC32_OUT.

separate_debug_file_exists
..........................

Synopsis

     bfd_boolean separate_debug_file_exists (char * name, unsigned long crc32)

Description

Checks to see if NAME is a file and if its contents match CRC32.

find_separate_debug_file
........................

Synopsis

     char * find_separate_debug_file (bfd *abfd)

Description

Searches ABFD for a reference to separate debugging information, scans various locations in the filesystem, including the file tree rooted at 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.

bfd_follow_gnu_debuglink
........................

Synopsis

     char * bfd_follow_gnu_debuglink(bfd *abfd, const char *dir);

Description

Takes a BFD and searches it for a .gnu_debuglink section.  If this section is found, examines the section for the name and checksum of a '.debug' file containing auxiliary debugging information. Searches filesystem for .debug file in some standard locations, including the directory tree rooted at DIR, and if found returns the full filename. If DIR is NULL, will search default path configured into libbfd at build time.

Returns

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.