Subversion Repositories or1k

@section Opening and closing BFDs

@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 cacheing; 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 *, PTR);

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

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

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

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

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

PTR bfd_alloc (bfd *abfd, size_t wanted);

@end example

@strong{Description}@*

Allocate a block of @var{wanted} bytes of memory attached to

@code{abfd} and return a pointer to it.