mirror of
https://github.com/autc04/Retro68.git
synced 2024-11-30 19:53:46 +00:00
534 lines
18 KiB
Plaintext
534 lines
18 KiB
Plaintext
|
|
@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 buildid);
|
|
@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, const char *dir, bfd_boolean include_dirs,
|
|
get_func_type get, check_func_type check);
|
|
@end example
|
|
@strong{Description}@*
|
|
Searches for a debug information file corresponding to @var{abfd}.
|
|
The name of the separate debug info file is returned by the @var{get}
|
|
function. This function scans various fixed locations in the
|
|
filesystem, including the file tree rooted at @var{dir}. If the
|
|
@var{include_dirs} parameter is true then the directory components of
|
|
@var{abfd}'s filename will be included in the searched locations.
|
|
|
|
Returns the filename of the first file to be found which receives a
|
|
TRUE result from the @var{check} function. 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, the search will take place starting at
|
|
the current directory.
|
|
|
|
@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, the search will take place starting at
|
|
the current directory.
|
|
|
|
@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.
|
|
|
|
@findex get_build_id
|
|
@subsubsection @code{get_build_id}
|
|
@strong{Synopsis}
|
|
@example
|
|
struct bfd_build_id * get_build_id
|
|
(bfd *abfd);
|
|
@end example
|
|
@strong{Description}@*
|
|
Finds the build-id associated with @var{abfd}. If the build-id is
|
|
extracted from the note section then a build-id structure is built
|
|
for it, using memory allocated to @var{abfd}, and this is then
|
|
attached to the @var{abfd}.
|
|
|
|
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.
|
|
|
|
@findex get_build_id_name
|
|
@subsubsection @code{get_build_id_name}
|
|
@strong{Synopsis}
|
|
@example
|
|
char * get_build_id_name
|
|
(bfd *abfd, unsigned long *build_id_out)
|
|
@end example
|
|
@strong{Description}@*
|
|
Searches @var{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 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 @var{build_id_out} parameter is
|
|
set to a pointer to the build_id structure.
|
|
|
|
@findex check_build_id_file
|
|
@subsubsection @code{check_build_id_file}
|
|
@strong{Synopsis}
|
|
@example
|
|
bfd_boolean check_build_id_file
|
|
(char *name, unsigned long buildid);
|
|
@end example
|
|
@strong{Description}@*
|
|
Checks to see if @var{name} is a readable file and if its build-id
|
|
matches @var{buildid}.
|
|
|
|
Returns TRUE if the file exists, is readable, and contains a build-id
|
|
which matches @var{build-id}.
|
|
|
|
@findex bfd_follow_build_id_debuglink
|
|
@subsubsection @code{bfd_follow_build_id_debuglink}
|
|
@strong{Synopsis}
|
|
@example
|
|
char *bfd_follow_build_id_debuglink (bfd *abfd, const char *dir);
|
|
@end example
|
|
@strong{Description}@*
|
|
Takes @var{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 @var{NNNN+NN} (for
|
|
32+ hex digits). It then searches the filesystem for a file named
|
|
@var{.build-id/NN/NN+NN.debug} in a set of standard locations,
|
|
including the directory tree rooted at @var{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
|
|
@var{NNNN+NN} note as @var{abfd}, although this check is currently
|
|
not implemented.
|
|
|
|
If @var{dir} is NULL, the search will take place starting at
|
|
the current directory.
|
|
|
|
@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.
|
|
|