Subversion Repositories openrisc_2011-10-31

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

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

@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}.

@findex bfd_openstreamr

@subsubsection @code{bfd_openstreamr}

@strong{Synopsis}

@example

bfd *bfd_openstreamr (const char *, const char *, void *);

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

@findex bfd_openr_iovec

@subsubsection @code{bfd_openr_iovec}

@strong{Synopsis}

@example

bfd *bfd_openr_iovec (const char *filename, const char *target,

    void *(*open) (struct bfd *nbfd,

    void *open_closure),

    void *open_closure,

    file_ptr (*pread) (struct bfd *nbfd,

    void *stream,

    void *buf,

    file_ptr nbytes,

    file_ptr offset),

    int (*close) (struct bfd *nbfd,

    void *stream),

    int (*stat) (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}, accessed using

@var{pread} and destroyed using @var{close}.

Calls @code{bfd_find_target}, so @var{target} is interpreted as by

that function.

Calls @var{open} (which can call @code{bfd_zalloc} and

@code{bfd_get_filename}) to obtain the read-only stream backing

the BFD.  @var{open} either succeeds returning the

non-@code{NULL} @var{stream}, or fails returning @code{NULL}

(setting @code{bfd_error}).

Calls @var{pread} to request @var{nbytes} of data from

@var{stream} starting at @var{offset} (e.g., via a call to

@code{bfd_read}).  @var{pread} 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} when the BFD is later closed using

@code{bfd_close}.  @var{close} either succeeds returning 0, or

fails returning -1 (setting @code{bfd_error}).

Calls @var{stat} to fill in a stat structure for bfd_stat,

bfd_get_size, and bfd_get_mtime calls.  @var{stat} 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}.

@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}.

@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{template}. The format is always set to @code{bfd_object}.

@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 get_debug_link_info

@subsubsection @code{get_debug_link_info}

@strong{Synopsis}

@example

char *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}.

@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 find_separate_debug_file

@subsubsection @code{find_separate_debug_file}

@strong{Synopsis}

@example

char *find_separate_debug_file (bfd *abfd);

@end example

@strong{Description}@*

Searches @var{abfd} for a reference to separate debugging

information, scans various locations in the filesystem, including

the file tree rooted at @var{debug_file_directory}, and returns a

filename of such debugging information if the file is found and has

matching CRC32.  Returns NULL if no reference to debugging file

exists, or file cannot 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, it will search a default path configured into

libbfd at build time.  [XXX this feature is not currently

implemented].

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