Retro68/binutils/bfd/doc/opncls.texi

@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_1
@subsubsection @code{bfd_get_debug_link_info_1}
@strong{Synopsis}
@example
char *bfd_get_debug_link_info_1 (bfd *abfd, void *crc32_out);
@end example
@strong{Description}@*
Extracts the filename and CRC32 value for any separate debug
information file associated with @var{abfd}.

The @var{crc32_out} parameter is an untyped pointer because
this routine is used as a @code{get_func_type} function, but it
is expected to be an unsigned long pointer.

@strong{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 @var{crc32_out} are updated to hold the corresponding
CRC32 value for the file.

The returned filename is allocated with @code{malloc}; freeing
it is the responsibility of the caller.

@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}@*
Extracts the filename and CRC32 value for any separate debug
information file associated with @var{abfd}.

@strong{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 @var{crc32_out} are updated to hold the corresponding
CRC32 value for the file.

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, void *crc32_p);
@end example
@strong{Description}@*
Checks to see if @var{name} is a file and if its contents
match @var{crc32}, which is a pointer to an @code{unsigned
long} containing a CRC32.

The @var{crc32_p} parameter is an untyped pointer because
this routine is used as a @code{check_func_type} function.

@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, void *unused);
@end example
@strong{Description}@*
Checks to see if @var{name} is a file.

@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, void *data);
@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.

@var{data} is passed unmodified to the @var{get} and @var{check}
functions.  It is generally used to implement build-id-like
matching in the callback functions.

@strong{Returns}@*
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}.

@strong{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.

@findex get_build_id_name
@subsubsection @code{get_build_id_name}
@strong{Synopsis}
@example
char * get_build_id_name (bfd *abfd, void *build_id_out_p)
@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.

@strong{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 @var{build_id_out_p}
parameter (which points to a @code{struct bfd_build_id}
pointer) 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, void *buildid_p);
@end example
@strong{Description}@*
Checks to see if @var{name} is a readable file and if its build-id
matches @var{buildid}.

@strong{Returns}@*
Returns TRUE if the file exists, is readable, and contains a
build-id which matches the build-id pointed at by
@var{build_id_p} (which is really a @code{struct bfd_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.