bfd: Opening and Closing
/* Set to N to open the next N BFDs using an alternate id space. */
extern unsigned int bfd_use_reserved_id;
2.14 Opening and closing BFDs
=============================
2.14.1 Functions for opening and closing
----------------------------------------
2.14.1.1 'bfd_fopen'
....................
*Synopsis*
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.
2.14.1.2 '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.
A copy of the FILENAME argument is stored in the newly created BFD.
It can be accessed via the bfd_get_filename() macro.
2.14.1.3 '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_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 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.
2.14.1.4 'bfd_openstreamr'
..........................
*Synopsis*
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.
2.14.1.5 'bfd_openr_iovec'
..........................
*Synopsis*
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.
2.14.1.6 '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'.
A copy of the FILENAME argument is stored in the newly created BFD.
It can be accessed via the bfd_get_filename() macro.
2.14.1.7 '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'.
2.14.1.8 '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'.
2.14.1.9 '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 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.
2.14.1.10 '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'.
2.14.1.11 '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'.
2.14.1.12 'bfd_alloc'
.....................
*Synopsis*
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.
2.14.1.13 'bfd_alloc2'
......................
*Synopsis*
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.
2.14.1.14 'bfd_zalloc'
......................
*Synopsis*
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.
2.14.1.15 'bfd_zalloc2'
.......................
*Synopsis*
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.
2.14.1.16 '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.
2.14.1.17 'bfd_get_debug_link_info_1'
.....................................
*Synopsis*
char *bfd_get_debug_link_info_1 (bfd *abfd, void *crc32_out);
*Description*
Extracts the filename and CRC32 value for any separate debug information
file associated with ABFD.
The CRC32_OUT parameter is an untyped pointer because this routine is
used as a 'get_func_type' function, but it is expected to be an unsigned
long pointer.
*Returns*
The filename of the associated debug information file, or NULL if there
is no such file. If the filename was found then the contents of
CRC32_OUT are updated to hold the corresponding CRC32 value for the
file.
The returned filename is allocated with 'malloc'; freeing it is the
responsibility of the caller.
2.14.1.18 'bfd_get_debug_link_info'
...................................
*Synopsis*
char *bfd_get_debug_link_info (bfd *abfd, unsigned long *crc32_out);
*Description*
Extracts the filename and CRC32 value for any separate debug information
file associated with ABFD.
*Returns*
The filename of the associated debug information file, or NULL if there
is no such file. If the filename was found then the contents of
CRC32_OUT are updated to hold the corresponding CRC32 value for the
file.
The returned filename is allocated with 'malloc'; freeing it is the
responsibility of the caller.
2.14.1.19 'bfd_get_alt_debug_link_info'
.......................................
*Synopsis*
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.
2.14.1.20 'separate_debug_file_exists'
......................................
*Synopsis*
bfd_boolean separate_debug_file_exists
(char *name, void *crc32_p);
*Description*
Checks to see if NAME is a file and if its contents match CRC32, which
is a pointer to an 'unsigned long' containing a CRC32.
The CRC32_P parameter is an untyped pointer because this routine is
used as a 'check_func_type' function.
2.14.1.21 'separate_alt_debug_file_exists'
..........................................
*Synopsis*
bfd_boolean separate_alt_debug_file_exists
(char *name, void *unused);
*Description*
Checks to see if NAME is a file.
2.14.1.22 'find_separate_debug_file'
....................................
*Synopsis*
char *find_separate_debug_file
(bfd *abfd, const char *dir, bfd_boolean include_dirs,
get_func_type get, check_func_type check, void *data);
*Description*
Searches for a debug information file corresponding to ABFD.
The name of the separate debug info file is returned by the GET
function. This function scans various fixed locations in the
filesystem, including the file tree rooted at DIR. If the INCLUDE_DIRS
parameter is true then the directory components of ABFD's filename will
be included in the searched locations.
DATA is passed unmodified to the GET and CHECK functions. It is
generally used to implement build-id-like matching in the callback
functions.
*Returns*
Returns the filename of the first file to be found which receives a TRUE
result from the CHECK function. Returns NULL if no valid file could be
found.
2.14.1.23 '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, the search will take place starting at the current
directory.
*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.
2.14.1.24 'bfd_follow_gnu_debugaltlink'
.......................................
*Synopsis*
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, the search will take place starting at the current
directory.
*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.
2.14.1.25 '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.
2.14.1.26 '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.
2.14.1.27 'get_build_id'
........................
*Synopsis*
struct bfd_build_id * get_build_id (bfd *abfd);
*Description*
Finds the build-id associated with ABFD. If the build-id is extracted
from the note section then a build-id structure is built for it, using
memory allocated to ABFD, and this is then attached to the ABFD.
*Returns*
Returns a pointer to the build-id structure if a build-id could be
found. If no build-id is found NULL is returned and error code is set.
2.14.1.28 'get_build_id_name'
.............................
*Synopsis*
char * get_build_id_name (bfd *abfd, void *build_id_out_p)
*Description*
Searches ABFD for a build-id, and then constructs a pathname from it.
The path is computed as .build-id/NN/NN+NN.debug where NNNN+NN is the
build-id value as a hexadecimal string.
*Returns*
Returns the constructed filename or NULL upon error. It is the caller's
responsibility to free the memory used to hold the filename. If a
filename is returned then the BUILD_ID_OUT_P parameter (which points to
a 'struct bfd_build_id' pointer) is set to a pointer to the build_id
structure.
2.14.1.29 'check_build_id_file'
...............................
*Synopsis*
bfd_boolean check_build_id_file (char *name, void *buildid_p);
*Description*
Checks to see if NAME is a readable file and if its build-id matches
BUILDID.
*Returns*
Returns TRUE if the file exists, is readable, and contains a build-id
which matches the build-id pointed at by BUILD_ID_P (which is really a
'struct bfd_build_id **').
2.14.1.30 'bfd_follow_build_id_debuglink'
.........................................
*Synopsis*
char *bfd_follow_build_id_debuglink (bfd *abfd, const char *dir);
*Description*
Takes ABFD and searches it for a .note.gnu.build-id section. If this
section is found, it extracts the value of the NT_GNU_BUILD_ID note,
which should be a hexadecimal value NNNN+NN (for 32+ hex digits). It
then searches the filesystem for a file named .BUILD-ID/NN/NN+NN.DEBUG
in a set of standard locations, including the directory tree rooted at
DIR. The filename of the first matching file to be found is returned.
A matching file should contain a .note.gnu.build-id section with the
same NNNN+NN note as ABFD, although this check is currently not
implemented.
If DIR is NULL, the search will take place starting at the current
directory.
*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.
Info Catalog
bfd: Architectures
bfd: BFD front end
bfd: Internal