Next: Internal, Previous: Architectures, Up: BFD front end
/* Set to N to open the next N BFDs using an alternate id space. */
extern unsigned int bfd_use_reserved_id;
bfd_fopenSynopsis
bfd *bfd_fopen (const char *filename, const char *target,
const char *mode, int fd);
Description
Open the file filename with the target target.
Return a pointer to the created BFD. If fd is not -1,
then fdopen is used to open the file; otherwise, fopen
is used. mode is passed directly to fopen or
fdopen.
Calls bfd_find_target, so target is interpreted as by
that function.
The new BFD is marked as cacheable iff fd is -1.
If NULL is returned then an error has occured. Possible errors
are bfd_error_no_memory, bfd_error_invalid_target or
system_call error.
On error, fd is always closed.
A copy of the filename argument is stored in the newly created BFD. It can be accessed via the bfd_get_filename() macro.
bfd_openrSynopsis
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.
A copy of the filename argument is stored in the newly created BFD. It can be accessed via the bfd_get_filename() macro.
bfd_fdopenrSynopsis
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.
On error, fd is closed.
A copy of the filename argument is stored in the newly created BFD. It can be accessed via the bfd_get_filename() macro.
bfd_openstreamrSynopsis
bfd *bfd_openstreamr (const char * filename, const char * target, void * stream);
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.
A copy of the filename argument is stored in the newly created BFD. It can be accessed via the bfd_get_filename() macro.
bfd_openr_iovecSynopsis
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));
Description
Create and return a BFD backed by a read-only stream.
The stream is created using open_func, accessed using
pread_func and destroyed using close_func.
Calls bfd_find_target, so target is interpreted as by
that function.
Calls open_func (which can call bfd_zalloc and
bfd_get_filename) to obtain the read-only stream backing
the BFD. open_func either succeeds returning the
non-NULL stream, or fails returning NULL
(setting bfd_error).
Calls pread_func to request nbytes of data from
stream starting at offset (e.g., via a call to
bfd_read). pread_func either succeeds returning the
number of bytes read (which can be less than nbytes when
end-of-file), or fails returning -1 (setting bfd_error).
Calls close_func when the BFD is later closed using
bfd_close. close_func either succeeds returning 0, or
fails returning -1 (setting bfd_error).
Calls stat_func to fill in a stat structure for bfd_stat,
bfd_get_size, and bfd_get_mtime calls. stat_func returns 0
on success, or returns -1 on failure (setting bfd_error).
If bfd_openr_iovec returns NULL then an error has
occurred. Possible errors are bfd_error_no_memory,
bfd_error_invalid_target and bfd_error_system_call.
A copy of the filename argument is stored in the newly created BFD. It can be accessed via the bfd_get_filename() macro.
bfd_openwSynopsis
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.
A copy of the filename argument is stored in the newly created BFD. It can be accessed via the bfd_get_filename() macro.
bfd_closeSynopsis
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_doneSynopsis
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_createSynopsis
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 templ. The format is always set to bfd_object.
A copy of the filename argument is stored in the newly created BFD. It can be accessed via the bfd_get_filename() macro.
bfd_make_writableSynopsis
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_readableSynopsis
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_allocSynopsis
void *bfd_alloc (bfd *abfd, bfd_size_type wanted);
Description
Allocate a block of wanted bytes of memory attached to
abfd and return a pointer to it.
bfd_alloc2Synopsis
void *bfd_alloc2 (bfd *abfd, bfd_size_type nmemb, bfd_size_type size);
Description
Allocate a block of nmemb elements of size bytes each
of memory attached to abfd and return a pointer to it.
bfd_zallocSynopsis
void *bfd_zalloc (bfd *abfd, bfd_size_type wanted);
Description
Allocate a block of wanted bytes of zeroed memory
attached to abfd and return a pointer to it.
bfd_zalloc2Synopsis
void *bfd_zalloc2 (bfd *abfd, bfd_size_type nmemb, bfd_size_type size);
Description
Allocate a block of nmemb elements of size bytes each
of zeroed memory attached to abfd and return a pointer to it.
bfd_calc_gnu_debuglink_crc32Synopsis
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.
bfd_get_debug_link_infoSynopsis
char *bfd_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. The
returned filename is allocated with malloc; freeing it
is the responsibility of the caller.
bfd_get_alt_debug_link_infoSynopsis
char *bfd_get_alt_debug_link_info (bfd * abfd,
bfd_size_type *buildid_len,
bfd_byte **buildid_out);
Description
Fetch the filename and BuildID value for any alternate debuginfo
associated with abfd. Return NULL if no such info found,
otherwise return filename and update buildid_len and
buildid_out. The returned filename and build_id are
allocated with malloc; freeing them is the
responsibility of the caller.
separate_debug_file_existsSynopsis
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.
separate_alt_debug_file_existsSynopsis
bfd_boolean separate_alt_debug_file_exists
(char *name, unsigned long crc32);
Description
Checks to see if name is a file and if its BuildID
matches buildid.
find_separate_debug_fileSynopsis
char *find_separate_debug_file (bfd *abfd);
Description
Searches abfd for a section called 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
debug_file_directory, and returns the first matching
filename that it finds. If check_crc is TRUE then the
contents of the file must also match the CRC value contained in
section_name. Returns NULL if no valid file could be found.
bfd_follow_gnu_debuglinkSynopsis
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_follow_gnu_debugaltlinkSynopsis
char *bfd_follow_gnu_debugaltlink (bfd *abfd, const char *dir);
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 dir, and if found returns the
full filename.
If dir is NULL, it will search a default path configured into libbfd at build time. [FIXME: 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_sectionSynopsis
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_sectionSynopsis
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.