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;

### 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`

Synopsis

         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.

##### 2.14.1.18 `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.19 `separate_debug_file_exists`

Synopsis

         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.

##### 2.14.1.20 `separate_alt_debug_file_exists`

Synopsis

         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.

##### 2.14.1.21 `find_separate_debug_file`

Synopsis

         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.

##### 2.14.1.22 `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, 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.

##### 2.14.1.23 `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, 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.

##### 2.14.1.24 `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.25 `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.