     /* Set to N to open the next N BFDs using an alternate id space.  */
     extern unsigned int bfd_use_reserved_id;

Opening and closing BFDs
========================

Functions for opening and closing
---------------------------------

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.

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.

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.

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_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.

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.

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.

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 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_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, bfd_size_type wanted);

Description

Allocate a block of WANTED bytes of memory attached to abfd and return a pointer to it.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

bfd_set_filename
................

Synopsis

     const char *bfd_set_filename (bfd *abfd, const char *filename);

Description

Set the filename of ABFD, copying the FILENAME parameter to bfd_alloc'd memory owned by ABFD.  Returns a pointer the newly allocated name, or NULL if the allocation failed.