Node: Opening and Closing, Next: , Previous: Architectures, Up: BFD front end


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 caching; 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 *, void *);
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 

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

bfd_calc_gnu_debuglink_crc32

Synopsis 

     unsigned long bfd_calc_gnu_debuglink_crc32
        (unsigned long crc, const unsigned char *buf, bfd_size_type len);
Description
Computes a CRC value as used in the .gnu_debuglink section. Advances the previously computed crc value by computing and adding in the crc32 for len bytes of buf.

Returns
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, 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 dir, and if found returns the full filename.

If dir is NULL, it will search a default path configured into libbfd at build time. [XXX this feature is not currently implemented].

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.

bfd_create_gnu_debuglink_section

Synopsis 

     struct bfd_section *bfd_create_gnu_debuglink_section
        (bfd *abfd, const char *filename);
Description
Takes a BFD and adds a .gnu_debuglink section to it. The section is sized to be big enough to contain a link to the specified filename.

Returns
A pointer to the new section is returned if all is ok. Otherwise NULL is returned and bfd_error is set.

bfd_fill_in_gnu_debuglink_section

Synopsis 

     bfd_boolean bfd_fill_in_gnu_debuglink_section
        (bfd *abfd, struct bfd_section *sect, const char *filename);
Description
Takes a BFD and containing a .gnu_debuglink section SECT and fills in the contents of the section to contain a link to the specified filename. The filename should be relative to the current directory.

Returns
TRUE is returned if all is ok. Otherwise FALSE is returned and bfd_error is set.