598 lines
18 KiB
Plaintext
598 lines
18 KiB
Plaintext
@section @code{typedef bfd}
|
|
A BFD has type @code{bfd}; objects of this type are the
|
|
cornerstone of any application using BFD. Using BFD
|
|
consists of making references though the BFD and to data in the BFD.
|
|
|
|
Here is the structure that defines the type @code{bfd}. It
|
|
contains the major data about the file and pointers
|
|
to the rest of the data.
|
|
|
|
|
|
@example
|
|
|
|
struct _bfd
|
|
@{
|
|
/* The filename the application opened the BFD with. */
|
|
CONST char *filename;
|
|
|
|
/* A pointer to the target jump table. */
|
|
const struct bfd_target *xvec;
|
|
|
|
/* To avoid dragging too many header files into every file that
|
|
includes `@code{bfd.h}', IOSTREAM has been declared as a "char
|
|
*", and MTIME as a "long". Their correct types, to which they
|
|
are cast when used, are "FILE *" and "time_t". The iostream
|
|
is the result of an fopen on the filename. However, if the
|
|
BFD_IN_MEMORY flag is set, then iostream is actually a pointer
|
|
to a bfd_in_memory struct. */
|
|
PTR iostream;
|
|
|
|
/* Is the file descriptor being cached? That is, can it be closed as
|
|
needed, and re-opened when accessed later? */
|
|
|
|
boolean cacheable;
|
|
|
|
/* Marks whether there was a default target specified when the
|
|
BFD was opened. This is used to select which matching algorithm
|
|
to use to choose the back end. */
|
|
|
|
boolean target_defaulted;
|
|
|
|
/* The caching routines use these to maintain a
|
|
least-recently-used list of BFDs */
|
|
|
|
struct _bfd *lru_prev, *lru_next;
|
|
|
|
/* When a file is closed by the caching routines, BFD retains
|
|
state information on the file here: */
|
|
|
|
file_ptr where;
|
|
|
|
/* and here: (``once'' means at least once) */
|
|
|
|
boolean opened_once;
|
|
|
|
/* Set if we have a locally maintained mtime value, rather than
|
|
getting it from the file each time: */
|
|
|
|
boolean mtime_set;
|
|
|
|
/* File modified time, if mtime_set is true: */
|
|
|
|
long mtime;
|
|
|
|
/* Reserved for an unimplemented file locking extension.*/
|
|
|
|
int ifd;
|
|
|
|
/* The format which belongs to the BFD. (object, core, etc.) */
|
|
|
|
bfd_format format;
|
|
|
|
/* The direction the BFD was opened with*/
|
|
|
|
enum bfd_direction @{no_direction = 0,
|
|
read_direction = 1,
|
|
write_direction = 2,
|
|
both_direction = 3@} direction;
|
|
|
|
/* Format_specific flags*/
|
|
|
|
flagword flags;
|
|
|
|
/* Currently my_archive is tested before adding origin to
|
|
anything. I believe that this can become always an add of
|
|
origin, with origin set to 0 for non archive files. */
|
|
|
|
file_ptr origin;
|
|
|
|
/* Remember when output has begun, to stop strange things
|
|
from happening. */
|
|
boolean output_has_begun;
|
|
|
|
/* Pointer to linked list of sections*/
|
|
struct sec *sections;
|
|
|
|
/* The number of sections */
|
|
unsigned int section_count;
|
|
|
|
/* Stuff only useful for object files:
|
|
The start address. */
|
|
bfd_vma start_address;
|
|
|
|
/* Used for input and output*/
|
|
unsigned int symcount;
|
|
|
|
/* Symbol table for output BFD (with symcount entries) */
|
|
struct symbol_cache_entry **outsymbols;
|
|
|
|
/* Pointer to structure which contains architecture information*/
|
|
const struct bfd_arch_info *arch_info;
|
|
|
|
/* Stuff only useful for archives:*/
|
|
PTR arelt_data;
|
|
struct _bfd *my_archive; /* The containing archive BFD. */
|
|
struct _bfd *next; /* The next BFD in the archive. */
|
|
struct _bfd *archive_head; /* The first BFD in the archive. */
|
|
boolean has_armap;
|
|
|
|
/* A chain of BFD structures involved in a link. */
|
|
struct _bfd *link_next;
|
|
|
|
/* A field used by _bfd_generic_link_add_archive_symbols. This will
|
|
be used only for archive elements. */
|
|
int archive_pass;
|
|
|
|
/* Used by the back end to hold private data. */
|
|
|
|
union
|
|
@{
|
|
struct aout_data_struct *aout_data;
|
|
struct artdata *aout_ar_data;
|
|
struct _oasys_data *oasys_obj_data;
|
|
struct _oasys_ar_data *oasys_ar_data;
|
|
struct coff_tdata *coff_obj_data;
|
|
struct pe_tdata *pe_obj_data;
|
|
struct xcoff_tdata *xcoff_obj_data;
|
|
struct ecoff_tdata *ecoff_obj_data;
|
|
struct ieee_data_struct *ieee_data;
|
|
struct ieee_ar_data_struct *ieee_ar_data;
|
|
struct srec_data_struct *srec_data;
|
|
struct ihex_data_struct *ihex_data;
|
|
struct tekhex_data_struct *tekhex_data;
|
|
struct elf_obj_tdata *elf_obj_data;
|
|
struct nlm_obj_tdata *nlm_obj_data;
|
|
struct bout_data_struct *bout_data;
|
|
struct sun_core_struct *sun_core_data;
|
|
struct trad_core_struct *trad_core_data;
|
|
struct som_data_struct *som_data;
|
|
struct hpux_core_struct *hpux_core_data;
|
|
struct hppabsd_core_struct *hppabsd_core_data;
|
|
struct sgi_core_struct *sgi_core_data;
|
|
struct lynx_core_struct *lynx_core_data;
|
|
struct osf_core_struct *osf_core_data;
|
|
struct cisco_core_struct *cisco_core_data;
|
|
struct versados_data_struct *versados_data;
|
|
struct netbsd_core_struct *netbsd_core_data;
|
|
PTR any;
|
|
@} tdata;
|
|
|
|
/* Used by the application to hold private data*/
|
|
PTR usrdata;
|
|
|
|
/* Where all the allocated stuff under this BFD goes. This is a
|
|
struct objalloc *, but we use PTR to avoid requiring the inclusion of
|
|
objalloc.h. */
|
|
PTR memory;
|
|
@};
|
|
|
|
@end example
|
|
@section Error reporting
|
|
Most BFD functions return nonzero on success (check their
|
|
individual documentation for precise semantics). On an error,
|
|
they call @code{bfd_set_error} to set an error condition that callers
|
|
can check by calling @code{bfd_get_error}.
|
|
If that returns @code{bfd_error_system_call}, then check
|
|
@code{errno}.
|
|
|
|
The easiest way to report a BFD error to the user is to
|
|
use @code{bfd_perror}.
|
|
|
|
@subsection Type @code{bfd_error_type}
|
|
The values returned by @code{bfd_get_error} are defined by the
|
|
enumerated type @code{bfd_error_type}.
|
|
|
|
|
|
@example
|
|
|
|
typedef enum bfd_error
|
|
@{
|
|
bfd_error_no_error = 0,
|
|
bfd_error_system_call,
|
|
bfd_error_invalid_target,
|
|
bfd_error_wrong_format,
|
|
bfd_error_invalid_operation,
|
|
bfd_error_no_memory,
|
|
bfd_error_no_symbols,
|
|
bfd_error_no_armap,
|
|
bfd_error_no_more_archived_files,
|
|
bfd_error_malformed_archive,
|
|
bfd_error_file_not_recognized,
|
|
bfd_error_file_ambiguously_recognized,
|
|
bfd_error_no_contents,
|
|
bfd_error_nonrepresentable_section,
|
|
bfd_error_no_debug_section,
|
|
bfd_error_bad_value,
|
|
bfd_error_file_truncated,
|
|
bfd_error_file_too_big,
|
|
bfd_error_invalid_error_code
|
|
@} bfd_error_type;
|
|
|
|
@end example
|
|
@findex bfd_get_error
|
|
@subsubsection @code{bfd_get_error}
|
|
@strong{Synopsis}
|
|
@example
|
|
bfd_error_type bfd_get_error (void);
|
|
@end example
|
|
@strong{Description}@*
|
|
Return the current BFD error condition.
|
|
|
|
@findex bfd_set_error
|
|
@subsubsection @code{bfd_set_error}
|
|
@strong{Synopsis}
|
|
@example
|
|
void bfd_set_error (bfd_error_type error_tag);
|
|
@end example
|
|
@strong{Description}@*
|
|
Set the BFD error condition to be @var{error_tag}.
|
|
|
|
@findex bfd_errmsg
|
|
@subsubsection @code{bfd_errmsg}
|
|
@strong{Synopsis}
|
|
@example
|
|
CONST char *bfd_errmsg (bfd_error_type error_tag);
|
|
@end example
|
|
@strong{Description}@*
|
|
Return a string describing the error @var{error_tag}, or
|
|
the system error if @var{error_tag} is @code{bfd_error_system_call}.
|
|
|
|
@findex bfd_perror
|
|
@subsubsection @code{bfd_perror}
|
|
@strong{Synopsis}
|
|
@example
|
|
void bfd_perror (CONST char *message);
|
|
@end example
|
|
@strong{Description}@*
|
|
Print to the standard error stream a string describing the
|
|
last BFD error that occurred, or the last system error if
|
|
the last BFD error was a system call failure. If @var{message}
|
|
is non-NULL and non-empty, the error string printed is preceded
|
|
by @var{message}, a colon, and a space. It is followed by a newline.
|
|
|
|
@subsection BFD error handler
|
|
Some BFD functions want to print messages describing the
|
|
problem. They call a BFD error handler function. This
|
|
function may be overriden by the program.
|
|
|
|
The BFD error handler acts like printf.
|
|
|
|
|
|
@example
|
|
|
|
typedef void (*bfd_error_handler_type) PARAMS ((const char *, ...));
|
|
|
|
@end example
|
|
@findex bfd_set_error_handler
|
|
@subsubsection @code{bfd_set_error_handler}
|
|
@strong{Synopsis}
|
|
@example
|
|
bfd_error_handler_type bfd_set_error_handler (bfd_error_handler_type);
|
|
@end example
|
|
@strong{Description}@*
|
|
Set the BFD error handler function. Returns the previous
|
|
function.
|
|
|
|
@findex bfd_set_error_program_name
|
|
@subsubsection @code{bfd_set_error_program_name}
|
|
@strong{Synopsis}
|
|
@example
|
|
void bfd_set_error_program_name (const char *);
|
|
@end example
|
|
@strong{Description}@*
|
|
Set the program name to use when printing a BFD error. This
|
|
is printed before the error message followed by a colon and
|
|
space. The string must not be changed after it is passed to
|
|
this function.
|
|
|
|
@findex bfd_get_error_handler
|
|
@subsubsection @code{bfd_get_error_handler}
|
|
@strong{Synopsis}
|
|
@example
|
|
bfd_error_handler_type bfd_get_error_handler (void);
|
|
@end example
|
|
@strong{Description}@*
|
|
Return the BFD error handler function.
|
|
|
|
@section Symbols
|
|
|
|
|
|
@findex bfd_get_reloc_upper_bound
|
|
@subsubsection @code{bfd_get_reloc_upper_bound}
|
|
@strong{Synopsis}
|
|
@example
|
|
long bfd_get_reloc_upper_bound(bfd *abfd, asection *sect);
|
|
@end example
|
|
@strong{Description}@*
|
|
Return the number of bytes required to store the
|
|
relocation information associated with section @var{sect}
|
|
attached to bfd @var{abfd}. If an error occurs, return -1.
|
|
|
|
@findex bfd_canonicalize_reloc
|
|
@subsubsection @code{bfd_canonicalize_reloc}
|
|
@strong{Synopsis}
|
|
@example
|
|
long bfd_canonicalize_reloc
|
|
(bfd *abfd,
|
|
asection *sec,
|
|
arelent **loc,
|
|
asymbol **syms);
|
|
@end example
|
|
@strong{Description}@*
|
|
Call the back end associated with the open BFD
|
|
@var{abfd} and translate the external form of the relocation
|
|
information attached to @var{sec} into the internal canonical
|
|
form. Place the table into memory at @var{loc}, which has
|
|
been preallocated, usually by a call to
|
|
@code{bfd_get_reloc_upper_bound}. Returns the number of relocs, or
|
|
-1 on error.
|
|
|
|
The @var{syms} table is also needed for horrible internal magic
|
|
reasons.
|
|
|
|
@findex bfd_set_reloc
|
|
@subsubsection @code{bfd_set_reloc}
|
|
@strong{Synopsis}
|
|
@example
|
|
void bfd_set_reloc
|
|
(bfd *abfd, asection *sec, arelent **rel, unsigned int count)
|
|
@end example
|
|
@strong{Description}@*
|
|
Set the relocation pointer and count within
|
|
section @var{sec} to the values @var{rel} and @var{count}.
|
|
The argument @var{abfd} is ignored.
|
|
|
|
@findex bfd_set_file_flags
|
|
@subsubsection @code{bfd_set_file_flags}
|
|
@strong{Synopsis}
|
|
@example
|
|
boolean bfd_set_file_flags(bfd *abfd, flagword flags);
|
|
@end example
|
|
@strong{Description}@*
|
|
Set the flag word in the BFD @var{abfd} to the value @var{flags}.
|
|
|
|
Possible errors are:
|
|
@itemize @bullet
|
|
|
|
@item
|
|
@code{bfd_error_wrong_format} - The target bfd was not of object format.
|
|
@item
|
|
@code{bfd_error_invalid_operation} - The target bfd was open for reading.
|
|
@item
|
|
@code{bfd_error_invalid_operation} -
|
|
The flag word contained a bit which was not applicable to the
|
|
type of file. E.g., an attempt was made to set the @code{D_PAGED} bit
|
|
on a BFD format which does not support demand paging.
|
|
@end itemize
|
|
|
|
@findex bfd_set_start_address
|
|
@subsubsection @code{bfd_set_start_address}
|
|
@strong{Synopsis}
|
|
@example
|
|
boolean bfd_set_start_address(bfd *abfd, bfd_vma vma);
|
|
@end example
|
|
@strong{Description}@*
|
|
Make @var{vma} the entry point of output BFD @var{abfd}.
|
|
|
|
@strong{Returns}@*
|
|
Returns @code{true} on success, @code{false} otherwise.
|
|
|
|
@findex bfd_get_mtime
|
|
@subsubsection @code{bfd_get_mtime}
|
|
@strong{Synopsis}
|
|
@example
|
|
long bfd_get_mtime(bfd *abfd);
|
|
@end example
|
|
@strong{Description}@*
|
|
Return the file modification time (as read from the file system, or
|
|
from the archive header for archive members).
|
|
|
|
@findex bfd_get_size
|
|
@subsubsection @code{bfd_get_size}
|
|
@strong{Synopsis}
|
|
@example
|
|
long bfd_get_size(bfd *abfd);
|
|
@end example
|
|
@strong{Description}@*
|
|
Return the file size (as read from file system) for the file
|
|
associated with BFD @var{abfd}.
|
|
|
|
The initial motivation for, and use of, this routine is not
|
|
so we can get the exact size of the object the BFD applies to, since
|
|
that might not be generally possible (archive members for example).
|
|
It would be ideal if someone could eventually modify
|
|
it so that such results were guaranteed.
|
|
|
|
Instead, we want to ask questions like "is this NNN byte sized
|
|
object I'm about to try read from file offset YYY reasonable?"
|
|
As as example of where we might do this, some object formats
|
|
use string tables for which the first @code{sizeof(long)} bytes of the
|
|
table contain the size of the table itself, including the size bytes.
|
|
If an application tries to read what it thinks is one of these
|
|
string tables, without some way to validate the size, and for
|
|
some reason the size is wrong (byte swapping error, wrong location
|
|
for the string table, etc.), the only clue is likely to be a read
|
|
error when it tries to read the table, or a "virtual memory
|
|
exhausted" error when it tries to allocate 15 bazillon bytes
|
|
of space for the 15 bazillon byte table it is about to read.
|
|
This function at least allows us to answer the quesion, "is the
|
|
size reasonable?".
|
|
|
|
@findex bfd_get_gp_size
|
|
@subsubsection @code{bfd_get_gp_size}
|
|
@strong{Synopsis}
|
|
@example
|
|
int bfd_get_gp_size(bfd *abfd);
|
|
@end example
|
|
@strong{Description}@*
|
|
Return the maximum size of objects to be optimized using the GP
|
|
register under MIPS ECOFF. This is typically set by the @code{-G}
|
|
argument to the compiler, assembler or linker.
|
|
|
|
@findex bfd_set_gp_size
|
|
@subsubsection @code{bfd_set_gp_size}
|
|
@strong{Synopsis}
|
|
@example
|
|
void bfd_set_gp_size(bfd *abfd, int i);
|
|
@end example
|
|
@strong{Description}@*
|
|
Set the maximum size of objects to be optimized using the GP
|
|
register under ECOFF or MIPS ELF. This is typically set by
|
|
the @code{-G} argument to the compiler, assembler or linker.
|
|
|
|
@findex bfd_scan_vma
|
|
@subsubsection @code{bfd_scan_vma}
|
|
@strong{Synopsis}
|
|
@example
|
|
bfd_vma bfd_scan_vma(CONST char *string, CONST char **end, int base);
|
|
@end example
|
|
@strong{Description}@*
|
|
Convert, like @code{strtoul}, a numerical expression
|
|
@var{string} into a @code{bfd_vma} integer, and return that integer.
|
|
(Though without as many bells and whistles as @code{strtoul}.)
|
|
The expression is assumed to be unsigned (i.e., positive).
|
|
If given a @var{base}, it is used as the base for conversion.
|
|
A base of 0 causes the function to interpret the string
|
|
in hex if a leading "0x" or "0X" is found, otherwise
|
|
in octal if a leading zero is found, otherwise in decimal.
|
|
|
|
Overflow is not detected.
|
|
|
|
@findex bfd_copy_private_bfd_data
|
|
@subsubsection @code{bfd_copy_private_bfd_data}
|
|
@strong{Synopsis}
|
|
@example
|
|
boolean bfd_copy_private_bfd_data(bfd *ibfd, bfd *obfd);
|
|
@end example
|
|
@strong{Description}@*
|
|
Copy private BFD information from the BFD @var{ibfd} to the
|
|
the BFD @var{obfd}. Return @code{true} on success, @code{false} on error.
|
|
Possible error returns are:
|
|
|
|
@itemize @bullet
|
|
|
|
@item
|
|
@code{bfd_error_no_memory} -
|
|
Not enough memory exists to create private data for @var{obfd}.
|
|
@end itemize
|
|
@example
|
|
#define bfd_copy_private_bfd_data(ibfd, obfd) \
|
|
BFD_SEND (obfd, _bfd_copy_private_bfd_data, \
|
|
(ibfd, obfd))
|
|
@end example
|
|
|
|
@findex bfd_merge_private_bfd_data
|
|
@subsubsection @code{bfd_merge_private_bfd_data}
|
|
@strong{Synopsis}
|
|
@example
|
|
boolean bfd_merge_private_bfd_data(bfd *ibfd, bfd *obfd);
|
|
@end example
|
|
@strong{Description}@*
|
|
Merge private BFD information from the BFD @var{ibfd} to the
|
|
the output file BFD @var{obfd} when linking. Return @code{true}
|
|
on success, @code{false} on error. Possible error returns are:
|
|
|
|
@itemize @bullet
|
|
|
|
@item
|
|
@code{bfd_error_no_memory} -
|
|
Not enough memory exists to create private data for @var{obfd}.
|
|
@end itemize
|
|
@example
|
|
#define bfd_merge_private_bfd_data(ibfd, obfd) \
|
|
BFD_SEND (obfd, _bfd_merge_private_bfd_data, \
|
|
(ibfd, obfd))
|
|
@end example
|
|
|
|
@findex bfd_set_private_flags
|
|
@subsubsection @code{bfd_set_private_flags}
|
|
@strong{Synopsis}
|
|
@example
|
|
boolean bfd_set_private_flags(bfd *abfd, flagword flags);
|
|
@end example
|
|
@strong{Description}@*
|
|
Set private BFD flag information in the BFD @var{abfd}.
|
|
Return @code{true} on success, @code{false} on error. Possible error
|
|
returns are:
|
|
|
|
@itemize @bullet
|
|
|
|
@item
|
|
@code{bfd_error_no_memory} -
|
|
Not enough memory exists to create private data for @var{obfd}.
|
|
@end itemize
|
|
@example
|
|
#define bfd_set_private_flags(abfd, flags) \
|
|
BFD_SEND (abfd, _bfd_set_private_flags, \
|
|
(abfd, flags))
|
|
@end example
|
|
|
|
@findex stuff
|
|
@subsubsection @code{stuff}
|
|
@strong{Description}@*
|
|
Stuff which should be documented:
|
|
@example
|
|
#define bfd_sizeof_headers(abfd, reloc) \
|
|
BFD_SEND (abfd, _bfd_sizeof_headers, (abfd, reloc))
|
|
|
|
#define bfd_find_nearest_line(abfd, sec, syms, off, file, func, line) \
|
|
BFD_SEND (abfd, _bfd_find_nearest_line, (abfd, sec, syms, off, file, func, line))
|
|
|
|
/* Do these three do anything useful at all, for any back end? */
|
|
#define bfd_debug_info_start(abfd) \
|
|
BFD_SEND (abfd, _bfd_debug_info_start, (abfd))
|
|
|
|
#define bfd_debug_info_end(abfd) \
|
|
BFD_SEND (abfd, _bfd_debug_info_end, (abfd))
|
|
|
|
#define bfd_debug_info_accumulate(abfd, section) \
|
|
BFD_SEND (abfd, _bfd_debug_info_accumulate, (abfd, section))
|
|
|
|
|
|
#define bfd_stat_arch_elt(abfd, stat) \
|
|
BFD_SEND (abfd, _bfd_stat_arch_elt,(abfd, stat))
|
|
|
|
#define bfd_update_armap_timestamp(abfd) \
|
|
BFD_SEND (abfd, _bfd_update_armap_timestamp, (abfd))
|
|
|
|
#define bfd_set_arch_mach(abfd, arch, mach)\
|
|
BFD_SEND ( abfd, _bfd_set_arch_mach, (abfd, arch, mach))
|
|
|
|
#define bfd_relax_section(abfd, section, link_info, again) \
|
|
BFD_SEND (abfd, _bfd_relax_section, (abfd, section, link_info, again))
|
|
|
|
#define bfd_link_hash_table_create(abfd) \
|
|
BFD_SEND (abfd, _bfd_link_hash_table_create, (abfd))
|
|
|
|
#define bfd_link_add_symbols(abfd, info) \
|
|
BFD_SEND (abfd, _bfd_link_add_symbols, (abfd, info))
|
|
|
|
#define bfd_final_link(abfd, info) \
|
|
BFD_SEND (abfd, _bfd_final_link, (abfd, info))
|
|
|
|
#define bfd_free_cached_info(abfd) \
|
|
BFD_SEND (abfd, _bfd_free_cached_info, (abfd))
|
|
|
|
#define bfd_get_dynamic_symtab_upper_bound(abfd) \
|
|
BFD_SEND (abfd, _bfd_get_dynamic_symtab_upper_bound, (abfd))
|
|
|
|
#define bfd_print_private_bfd_data(abfd, file)\
|
|
BFD_SEND (abfd, _bfd_print_private_bfd_data, (abfd, file))
|
|
|
|
#define bfd_canonicalize_dynamic_symtab(abfd, asymbols) \
|
|
BFD_SEND (abfd, _bfd_canonicalize_dynamic_symtab, (abfd, asymbols))
|
|
|
|
#define bfd_get_dynamic_reloc_upper_bound(abfd) \
|
|
BFD_SEND (abfd, _bfd_get_dynamic_reloc_upper_bound, (abfd))
|
|
|
|
#define bfd_canonicalize_dynamic_reloc(abfd, arels, asyms) \
|
|
BFD_SEND (abfd, _bfd_canonicalize_dynamic_reloc, (abfd, arels, asyms))
|
|
|
|
extern bfd_byte *bfd_get_relocated_section_contents
|
|
PARAMS ((bfd *, struct bfd_link_info *,
|
|
struct bfd_link_order *, bfd_byte *,
|
|
boolean, asymbol **));
|
|
|
|
@end example
|
|
|