1079 lines
39 KiB
Plaintext
1079 lines
39 KiB
Plaintext
This is bfd.info, produced by makeinfo version 4.3 from bfd.texinfo.
|
||
|
||
START-INFO-DIR-ENTRY
|
||
* Bfd: (bfd). The Binary File Descriptor library.
|
||
END-INFO-DIR-ENTRY
|
||
|
||
This file documents the BFD library.
|
||
|
||
Copyright (C) 1991, 2000, 2001 Free Software Foundation, Inc.
|
||
|
||
Permission is granted to copy, distribute and/or modify this document
|
||
under the terms of the GNU Free Documentation License, Version 1.1
|
||
or any later version published by the Free Software Foundation;
|
||
with no Invariant Sections, with no Front-Cover Texts, and with no
|
||
Back-Cover Texts. A copy of the license is included in the
|
||
section entitled "GNU Free Documentation License".
|
||
|
||
|
||
File: bfd.info, Node: Top, Next: Overview, Prev: (dir), Up: (dir)
|
||
|
||
This file documents the binary file descriptor library libbfd.
|
||
|
||
* Menu:
|
||
|
||
* Overview:: Overview of BFD
|
||
* BFD front end:: BFD front end
|
||
* BFD back ends:: BFD back ends
|
||
* GNU Free Documentation License:: GNU Free Documentation License
|
||
* Index:: Index
|
||
|
||
|
||
File: bfd.info, Node: Overview, Next: BFD front end, Prev: Top, Up: Top
|
||
|
||
Introduction
|
||
************
|
||
|
||
BFD is a package which allows applications to use the same routines
|
||
to operate on object files whatever the object file format. A new
|
||
object file format can be supported simply by creating a new BFD back
|
||
end and adding it to the library.
|
||
|
||
BFD is split into two parts: the front end, and the back ends (one
|
||
for each object file format).
|
||
* The front end of BFD provides the interface to the user. It manages
|
||
memory and various canonical data structures. The front end also
|
||
decides which back end to use and when to call back end routines.
|
||
|
||
* The back ends provide BFD its view of the real world. Each back
|
||
end provides a set of calls which the BFD front end can use to
|
||
maintain its canonical form. The back ends also may keep around
|
||
information for their own use, for greater efficiency.
|
||
|
||
* Menu:
|
||
|
||
* History:: History
|
||
* How It Works:: How It Works
|
||
* What BFD Version 2 Can Do:: What BFD Version 2 Can Do
|
||
|
||
|
||
File: bfd.info, Node: History, Next: How It Works, Prev: Overview, Up: Overview
|
||
|
||
History
|
||
=======
|
||
|
||
One spur behind BFD was the desire, on the part of the GNU 960 team
|
||
at Intel Oregon, for interoperability of applications on their COFF and
|
||
b.out file formats. Cygnus was providing GNU support for the team, and
|
||
was contracted to provide the required functionality.
|
||
|
||
The name came from a conversation David Wallace was having with
|
||
Richard Stallman about the library: RMS said that it would be quite
|
||
hard--David said "BFD". Stallman was right, but the name stuck.
|
||
|
||
At the same time, Ready Systems wanted much the same thing, but for
|
||
different object file formats: IEEE-695, Oasys, Srecords, a.out and 68k
|
||
coff.
|
||
|
||
BFD was first implemented by members of Cygnus Support; Steve
|
||
Chamberlain (`sac@cygnus.com'), John Gilmore (`gnu@cygnus.com'), K.
|
||
Richard Pixley (`rich@cygnus.com') and David Henkel-Wallace
|
||
(`gumby@cygnus.com').
|
||
|
||
|
||
File: bfd.info, Node: How It Works, Next: What BFD Version 2 Can Do, Prev: History, Up: Overview
|
||
|
||
How To Use BFD
|
||
==============
|
||
|
||
To use the library, include `bfd.h' and link with `libbfd.a'.
|
||
|
||
BFD provides a common interface to the parts of an object file for a
|
||
calling application.
|
||
|
||
When an application sucessfully opens a target file (object,
|
||
archive, or whatever), a pointer to an internal structure is returned.
|
||
This pointer points to a structure called `bfd', described in `bfd.h'.
|
||
Our convention is to call this pointer a BFD, and instances of it
|
||
within code `abfd'. All operations on the target object file are
|
||
applied as methods to the BFD. The mapping is defined within `bfd.h'
|
||
in a set of macros, all beginning with `bfd_' to reduce namespace
|
||
pollution.
|
||
|
||
For example, this sequence does what you would probably expect:
|
||
return the number of sections in an object file attached to a BFD
|
||
`abfd'.
|
||
|
||
#include "bfd.h"
|
||
|
||
unsigned int number_of_sections(abfd)
|
||
bfd *abfd;
|
||
{
|
||
return bfd_count_sections(abfd);
|
||
}
|
||
|
||
The abstraction used within BFD is that an object file has:
|
||
|
||
* a header,
|
||
|
||
* a number of sections containing raw data (*note Sections::),
|
||
|
||
* a set of relocations (*note Relocations::), and
|
||
|
||
* some symbol information (*note Symbols::).
|
||
|
||
Also, BFDs opened for archives have the additional attribute of an index
|
||
and contain subordinate BFDs. This approach is fine for a.out and coff,
|
||
but loses efficiency when applied to formats such as S-records and
|
||
IEEE-695.
|
||
|
||
|
||
File: bfd.info, Node: What BFD Version 2 Can Do, Prev: How It Works, Up: Overview
|
||
|
||
What BFD Version 2 Can Do
|
||
=========================
|
||
|
||
When an object file is opened, BFD subroutines automatically
|
||
determine the format of the input object file. They then build a
|
||
descriptor in memory with pointers to routines that will be used to
|
||
access elements of the object file's data structures.
|
||
|
||
As different information from the object files is required, BFD
|
||
reads from different sections of the file and processes them. For
|
||
example, a very common operation for the linker is processing symbol
|
||
tables. Each BFD back end provides a routine for converting between
|
||
the object file's representation of symbols and an internal canonical
|
||
format. When the linker asks for the symbol table of an object file, it
|
||
calls through a memory pointer to the routine from the relevant BFD
|
||
back end which reads and converts the table into a canonical form. The
|
||
linker then operates upon the canonical form. When the link is finished
|
||
and the linker writes the output file's symbol table, another BFD back
|
||
end routine is called to take the newly created symbol table and
|
||
convert it into the chosen output format.
|
||
|
||
* Menu:
|
||
|
||
* BFD information loss:: Information Loss
|
||
* Canonical format:: The BFD canonical object-file format
|
||
|
||
|
||
File: bfd.info, Node: BFD information loss, Next: Canonical format, Up: What BFD Version 2 Can Do
|
||
|
||
Information Loss
|
||
----------------
|
||
|
||
_Information can be lost during output._ The output formats
|
||
supported by BFD do not provide identical facilities, and information
|
||
which can be described in one form has nowhere to go in another format.
|
||
One example of this is alignment information in `b.out'. There is
|
||
nowhere in an `a.out' format file to store alignment information on the
|
||
contained data, so when a file is linked from `b.out' and an `a.out'
|
||
image is produced, alignment information will not propagate to the
|
||
output file. (The linker will still use the alignment information
|
||
internally, so the link is performed correctly).
|
||
|
||
Another example is COFF section names. COFF files may contain an
|
||
unlimited number of sections, each one with a textual section name. If
|
||
the target of the link is a format which does not have many sections
|
||
(e.g., `a.out') or has sections without names (e.g., the Oasys format),
|
||
the link cannot be done simply. You can circumvent this problem by
|
||
describing the desired input-to-output section mapping with the linker
|
||
command language.
|
||
|
||
_Information can be lost during canonicalization._ The BFD internal
|
||
canonical form of the external formats is not exhaustive; there are
|
||
structures in input formats for which there is no direct representation
|
||
internally. This means that the BFD back ends cannot maintain all
|
||
possible data richness through the transformation between external to
|
||
internal and back to external formats.
|
||
|
||
This limitation is only a problem when an application reads one
|
||
format and writes another. Each BFD back end is responsible for
|
||
maintaining as much data as possible, and the internal BFD canonical
|
||
form has structures which are opaque to the BFD core, and exported only
|
||
to the back ends. When a file is read in one format, the canonical form
|
||
is generated for BFD and the application. At the same time, the back
|
||
end saves away any information which may otherwise be lost. If the data
|
||
is then written back in the same format, the back end routine will be
|
||
able to use the canonical form provided by the BFD core as well as the
|
||
information it prepared earlier. Since there is a great deal of
|
||
commonality between back ends, there is no information lost when
|
||
linking or copying big endian COFF to little endian COFF, or `a.out' to
|
||
`b.out'. When a mixture of formats is linked, the information is only
|
||
lost from the files whose format differs from the destination.
|
||
|
||
|
||
File: bfd.info, Node: Canonical format, Prev: BFD information loss, Up: What BFD Version 2 Can Do
|
||
|
||
The BFD canonical object-file format
|
||
------------------------------------
|
||
|
||
The greatest potential for loss of information occurs when there is
|
||
the least overlap between the information provided by the source
|
||
format, that stored by the canonical format, and that needed by the
|
||
destination format. A brief description of the canonical form may help
|
||
you understand which kinds of data you can count on preserving across
|
||
conversions.
|
||
|
||
_files_
|
||
Information stored on a per-file basis includes target machine
|
||
architecture, particular implementation format type, a demand
|
||
pageable bit, and a write protected bit. Information like Unix
|
||
magic numbers is not stored here--only the magic numbers' meaning,
|
||
so a `ZMAGIC' file would have both the demand pageable bit and the
|
||
write protected text bit set. The byte order of the target is
|
||
stored on a per-file basis, so that big- and little-endian object
|
||
files may be used with one another.
|
||
|
||
_sections_
|
||
Each section in the input file contains the name of the section,
|
||
the section's original address in the object file, size and
|
||
alignment information, various flags, and pointers into other BFD
|
||
data structures.
|
||
|
||
_symbols_
|
||
Each symbol contains a pointer to the information for the object
|
||
file which originally defined it, its name, its value, and various
|
||
flag bits. When a BFD back end reads in a symbol table, it
|
||
relocates all symbols to make them relative to the base of the
|
||
section where they were defined. Doing this ensures that each
|
||
symbol points to its containing section. Each symbol also has a
|
||
varying amount of hidden private data for the BFD back end. Since
|
||
the symbol points to the original file, the private data format
|
||
for that symbol is accessible. `ld' can operate on a collection
|
||
of symbols of wildly different formats without problems.
|
||
|
||
Normal global and simple local symbols are maintained on output,
|
||
so an output file (no matter its format) will retain symbols
|
||
pointing to functions and to global, static, and common variables.
|
||
Some symbol information is not worth retaining; in `a.out', type
|
||
information is stored in the symbol table as long symbol names.
|
||
This information would be useless to most COFF debuggers; the
|
||
linker has command line switches to allow users to throw it away.
|
||
|
||
There is one word of type information within the symbol, so if the
|
||
format supports symbol type information within symbols (for
|
||
example, COFF, IEEE, Oasys) and the type is simple enough to fit
|
||
within one word (nearly everything but aggregates), the
|
||
information will be preserved.
|
||
|
||
_relocation level_
|
||
Each canonical BFD relocation record contains a pointer to the
|
||
symbol to relocate to, the offset of the data to relocate, the
|
||
section the data is in, and a pointer to a relocation type
|
||
descriptor. Relocation is performed by passing messages through
|
||
the relocation type descriptor and the symbol pointer. Therefore,
|
||
relocations can be performed on output data using a relocation
|
||
method that is only available in one of the input formats. For
|
||
instance, Oasys provides a byte relocation format. A relocation
|
||
record requesting this relocation type would point indirectly to a
|
||
routine to perform this, so the relocation may be performed on a
|
||
byte being written to a 68k COFF file, even though 68k COFF has no
|
||
such relocation type.
|
||
|
||
_line numbers_
|
||
Object formats can contain, for debugging purposes, some form of
|
||
mapping between symbols, source line numbers, and addresses in the
|
||
output file. These addresses have to be relocated along with the
|
||
symbol information. Each symbol with an associated list of line
|
||
number records points to the first record of the list. The head
|
||
of a line number list consists of a pointer to the symbol, which
|
||
allows finding out the address of the function whose line number
|
||
is being described. The rest of the list is made up of pairs:
|
||
offsets into the section and line numbers. Any format which can
|
||
simply derive this information can pass it successfully between
|
||
formats (COFF, IEEE and Oasys).
|
||
|
||
|
||
File: bfd.info, Node: BFD front end, Next: BFD back ends, Prev: Overview, Up: Top
|
||
|
||
BFD front end
|
||
*************
|
||
|
||
`typedef bfd'
|
||
=============
|
||
|
||
A BFD has type `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 `bfd'. It contains the
|
||
major data about the file and pointers to the rest of the data.
|
||
|
||
|
||
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 ``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... */
|
||
ufile_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 with which the BFD was opened. */
|
||
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. */
|
||
ufile_ptr origin;
|
||
|
||
/* Remember when output has begun, to stop strange things
|
||
from happening. */
|
||
boolean output_has_begun;
|
||
|
||
/* A hash table for section names. */
|
||
struct bfd_hash_table section_htab;
|
||
|
||
/* Pointer to linked list of sections. */
|
||
struct sec *sections;
|
||
|
||
/* The place where we add to the section list. */
|
||
struct sec **section_tail;
|
||
|
||
/* 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;
|
||
|
||
/* Used for slurped dynamic symbol tables. */
|
||
unsigned int dynsymcount;
|
||
|
||
/* 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 mmo_data_struct *mmo_data;
|
||
struct sun_core_struct *sun_core_data;
|
||
struct sco5_core_struct *sco5_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;
|
||
};
|
||
|
||
Error reporting
|
||
===============
|
||
|
||
Most BFD functions return nonzero on success (check their individual
|
||
documentation for precise semantics). On an error, they call
|
||
`bfd_set_error' to set an error condition that callers can check by
|
||
calling `bfd_get_error'. If that returns `bfd_error_system_call', then
|
||
check `errno'.
|
||
|
||
The easiest way to report a BFD error to the user is to use
|
||
`bfd_perror'.
|
||
|
||
Type `bfd_error_type'
|
||
---------------------
|
||
|
||
The values returned by `bfd_get_error' are defined by the enumerated
|
||
type `bfd_error_type'.
|
||
|
||
|
||
typedef enum bfd_error
|
||
{
|
||
bfd_error_no_error = 0,
|
||
bfd_error_system_call,
|
||
bfd_error_invalid_target,
|
||
bfd_error_wrong_format,
|
||
bfd_error_wrong_object_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;
|
||
|
||
`bfd_get_error'
|
||
...............
|
||
|
||
*Synopsis*
|
||
bfd_error_type bfd_get_error (void);
|
||
*Description*
|
||
Return the current BFD error condition.
|
||
|
||
`bfd_set_error'
|
||
...............
|
||
|
||
*Synopsis*
|
||
void bfd_set_error (bfd_error_type error_tag);
|
||
*Description*
|
||
Set the BFD error condition to be ERROR_TAG.
|
||
|
||
`bfd_errmsg'
|
||
............
|
||
|
||
*Synopsis*
|
||
const char *bfd_errmsg (bfd_error_type error_tag);
|
||
*Description*
|
||
Return a string describing the error ERROR_TAG, or the system error if
|
||
ERROR_TAG is `bfd_error_system_call'.
|
||
|
||
`bfd_perror'
|
||
............
|
||
|
||
*Synopsis*
|
||
void bfd_perror (const char *message);
|
||
*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 MESSAGE is non-NULL and non-empty, the error
|
||
string printed is preceded by MESSAGE, a colon, and a space. It is
|
||
followed by a newline.
|
||
|
||
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.
|
||
|
||
|
||
typedef void (*bfd_error_handler_type) PARAMS ((const char *, ...));
|
||
|
||
`bfd_set_error_handler'
|
||
.......................
|
||
|
||
*Synopsis*
|
||
bfd_error_handler_type bfd_set_error_handler (bfd_error_handler_type);
|
||
*Description*
|
||
Set the BFD error handler function. Returns the previous function.
|
||
|
||
`bfd_set_error_program_name'
|
||
............................
|
||
|
||
*Synopsis*
|
||
void bfd_set_error_program_name (const char *);
|
||
*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.
|
||
|
||
`bfd_get_error_handler'
|
||
.......................
|
||
|
||
*Synopsis*
|
||
bfd_error_handler_type bfd_get_error_handler (void);
|
||
*Description*
|
||
Return the BFD error handler function.
|
||
|
||
`bfd_archive_filename'
|
||
......................
|
||
|
||
*Synopsis*
|
||
const char *bfd_archive_filename (bfd *);
|
||
*Description*
|
||
For a BFD that is a component of an archive, returns a string with both
|
||
the archive name and file name. For other BFDs, just returns the file
|
||
name.
|
||
|
||
Symbols
|
||
=======
|
||
|
||
`bfd_get_reloc_upper_bound'
|
||
...........................
|
||
|
||
*Synopsis*
|
||
long bfd_get_reloc_upper_bound(bfd *abfd, asection *sect);
|
||
*Description*
|
||
Return the number of bytes required to store the relocation information
|
||
associated with section SECT attached to bfd ABFD. If an error occurs,
|
||
return -1.
|
||
|
||
`bfd_canonicalize_reloc'
|
||
........................
|
||
|
||
*Synopsis*
|
||
long bfd_canonicalize_reloc
|
||
(bfd *abfd,
|
||
asection *sec,
|
||
arelent **loc,
|
||
asymbol **syms);
|
||
*Description*
|
||
Call the back end associated with the open BFD ABFD and translate the
|
||
external form of the relocation information attached to SEC into the
|
||
internal canonical form. Place the table into memory at LOC, which has
|
||
been preallocated, usually by a call to `bfd_get_reloc_upper_bound'.
|
||
Returns the number of relocs, or -1 on error.
|
||
|
||
The SYMS table is also needed for horrible internal magic reasons.
|
||
|
||
`bfd_set_reloc'
|
||
...............
|
||
|
||
*Synopsis*
|
||
void bfd_set_reloc
|
||
(bfd *abfd, asection *sec, arelent **rel, unsigned int count);
|
||
*Description*
|
||
Set the relocation pointer and count within section SEC to the values
|
||
REL and COUNT. The argument ABFD is ignored.
|
||
|
||
`bfd_set_file_flags'
|
||
....................
|
||
|
||
*Synopsis*
|
||
boolean bfd_set_file_flags(bfd *abfd, flagword flags);
|
||
*Description*
|
||
Set the flag word in the BFD ABFD to the value FLAGS.
|
||
|
||
Possible errors are:
|
||
* `bfd_error_wrong_format' - The target bfd was not of object format.
|
||
|
||
* `bfd_error_invalid_operation' - The target bfd was open for
|
||
reading.
|
||
|
||
* `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 `D_PAGED' bit on a BFD format which does not
|
||
support demand paging.
|
||
|
||
`bfd_get_arch_size'
|
||
...................
|
||
|
||
*Synopsis*
|
||
int bfd_get_arch_size (bfd *abfd);
|
||
*Description*
|
||
Returns the architecture address size, in bits, as determined by the
|
||
object file's format. For ELF, this information is included in the
|
||
header.
|
||
|
||
*Returns*
|
||
Returns the arch size in bits if known, `-1' otherwise.
|
||
|
||
`bfd_get_sign_extend_vma'
|
||
.........................
|
||
|
||
*Synopsis*
|
||
int bfd_get_sign_extend_vma (bfd *abfd);
|
||
*Description*
|
||
Indicates if the target architecture "naturally" sign extends an
|
||
address. Some architectures implicitly sign extend address values when
|
||
they are converted to types larger than the size of an address. For
|
||
instance, bfd_get_start_address() will return an address sign extended
|
||
to fill a bfd_vma when this is the case.
|
||
|
||
*Returns*
|
||
Returns `1' if the target architecture is known to sign extend
|
||
addresses, `0' if the target architecture is known to not sign extend
|
||
addresses, and `-1' otherwise.
|
||
|
||
`bfd_set_start_address'
|
||
.......................
|
||
|
||
*Synopsis*
|
||
boolean bfd_set_start_address(bfd *abfd, bfd_vma vma);
|
||
*Description*
|
||
Make VMA the entry point of output BFD ABFD.
|
||
|
||
*Returns*
|
||
Returns `true' on success, `false' otherwise.
|
||
|
||
`bfd_get_mtime'
|
||
...............
|
||
|
||
*Synopsis*
|
||
long bfd_get_mtime(bfd *abfd);
|
||
*Description*
|
||
Return the file modification time (as read from the file system, or
|
||
from the archive header for archive members).
|
||
|
||
`bfd_get_size'
|
||
..............
|
||
|
||
*Synopsis*
|
||
long bfd_get_size(bfd *abfd);
|
||
*Description*
|
||
Return the file size (as read from file system) for the file associated
|
||
with BFD 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 `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?".
|
||
|
||
`bfd_get_gp_size'
|
||
.................
|
||
|
||
*Synopsis*
|
||
unsigned int bfd_get_gp_size(bfd *abfd);
|
||
*Description*
|
||
Return the maximum size of objects to be optimized using the GP
|
||
register under MIPS ECOFF. This is typically set by the `-G' argument
|
||
to the compiler, assembler or linker.
|
||
|
||
`bfd_set_gp_size'
|
||
.................
|
||
|
||
*Synopsis*
|
||
void bfd_set_gp_size(bfd *abfd, unsigned int i);
|
||
*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 `-G' argument to
|
||
the compiler, assembler or linker.
|
||
|
||
`bfd_scan_vma'
|
||
..............
|
||
|
||
*Synopsis*
|
||
bfd_vma bfd_scan_vma(const char *string, const char **end, int base);
|
||
*Description*
|
||
Convert, like `strtoul', a numerical expression STRING into a `bfd_vma'
|
||
integer, and return that integer. (Though without as many bells and
|
||
whistles as `strtoul'.) The expression is assumed to be unsigned
|
||
(i.e., positive). If given a 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.
|
||
|
||
If the value would overflow, the maximum `bfd_vma' value is returned.
|
||
|
||
`bfd_copy_private_bfd_data'
|
||
...........................
|
||
|
||
*Synopsis*
|
||
boolean bfd_copy_private_bfd_data(bfd *ibfd, bfd *obfd);
|
||
*Description*
|
||
Copy private BFD information from the BFD IBFD to the the BFD OBFD.
|
||
Return `true' on success, `false' on error. Possible error returns are:
|
||
|
||
* `bfd_error_no_memory' - Not enough memory exists to create private
|
||
data for OBFD.
|
||
|
||
#define bfd_copy_private_bfd_data(ibfd, obfd) \
|
||
BFD_SEND (obfd, _bfd_copy_private_bfd_data, \
|
||
(ibfd, obfd))
|
||
|
||
`bfd_merge_private_bfd_data'
|
||
............................
|
||
|
||
*Synopsis*
|
||
boolean bfd_merge_private_bfd_data(bfd *ibfd, bfd *obfd);
|
||
*Description*
|
||
Merge private BFD information from the BFD IBFD to the the output file
|
||
BFD OBFD when linking. Return `true' on success, `false' on error.
|
||
Possible error returns are:
|
||
|
||
* `bfd_error_no_memory' - Not enough memory exists to create private
|
||
data for OBFD.
|
||
|
||
#define bfd_merge_private_bfd_data(ibfd, obfd) \
|
||
BFD_SEND (obfd, _bfd_merge_private_bfd_data, \
|
||
(ibfd, obfd))
|
||
|
||
`bfd_set_private_flags'
|
||
.......................
|
||
|
||
*Synopsis*
|
||
boolean bfd_set_private_flags(bfd *abfd, flagword flags);
|
||
*Description*
|
||
Set private BFD flag information in the BFD ABFD. Return `true' on
|
||
success, `false' on error. Possible error returns are:
|
||
|
||
* `bfd_error_no_memory' - Not enough memory exists to create private
|
||
data for OBFD.
|
||
|
||
#define bfd_set_private_flags(abfd, flags) \
|
||
BFD_SEND (abfd, _bfd_set_private_flags, \
|
||
(abfd, flags))
|
||
|
||
`stuff'
|
||
.......
|
||
|
||
*Description*
|
||
Stuff which should be documented:
|
||
#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_gc_sections(abfd, link_info) \
|
||
BFD_SEND (abfd, _bfd_gc_sections, (abfd, link_info))
|
||
|
||
#define bfd_merge_sections(abfd, link_info) \
|
||
BFD_SEND (abfd, _bfd_merge_sections, (abfd, link_info))
|
||
|
||
#define bfd_discard_group(abfd, sec) \
|
||
BFD_SEND (abfd, _bfd_discard_group, (abfd, sec))
|
||
|
||
#define bfd_link_hash_table_create(abfd) \
|
||
BFD_SEND (abfd, _bfd_link_hash_table_create, (abfd))
|
||
|
||
#define bfd_link_hash_table_free(abfd, hash) \
|
||
BFD_SEND (abfd, _bfd_link_hash_table_free, (hash))
|
||
|
||
#define bfd_link_add_symbols(abfd, info) \
|
||
BFD_SEND (abfd, _bfd_link_add_symbols, (abfd, info))
|
||
|
||
#define bfd_link_just_syms(sec, info) \
|
||
BFD_SEND (abfd, _bfd_link_just_syms, (sec, 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 **));
|
||
|
||
`bfd_alt_mach_code'
|
||
...................
|
||
|
||
*Synopsis*
|
||
boolean bfd_alt_mach_code(bfd *abfd, int alternative);
|
||
*Description*
|
||
When more than one machine code number is available for the same
|
||
machine type, this function can be used to switch between the preferred
|
||
one (alternative == 0) and any others. Currently, only ELF supports
|
||
this feature, with up to two alternate machine codes.
|
||
|
||
* Menu:
|
||
|
||
* Memory Usage::
|
||
* Initialization::
|
||
* Sections::
|
||
* Symbols::
|
||
* Archives::
|
||
* Formats::
|
||
* Relocations::
|
||
* Core Files::
|
||
* Targets::
|
||
* Architectures::
|
||
* Opening and Closing::
|
||
* Internal::
|
||
* File Caching::
|
||
* Linker Functions::
|
||
* Hash Tables::
|
||
|
||
|
||
File: bfd.info, Node: Memory Usage, Next: Initialization, Prev: BFD front end, Up: BFD front end
|
||
|
||
Memory usage
|
||
============
|
||
|
||
BFD keeps all of its internal structures in obstacks. There is one
|
||
obstack per open BFD file, into which the current state is stored. When
|
||
a BFD is closed, the obstack is deleted, and so everything which has
|
||
been allocated by BFD for the closing file is thrown away.
|
||
|
||
BFD does not free anything created by an application, but pointers
|
||
into `bfd' structures become invalid on a `bfd_close'; for example,
|
||
after a `bfd_close' the vector passed to `bfd_canonicalize_symtab' is
|
||
still around, since it has been allocated by the application, but the
|
||
data that it pointed to are lost.
|
||
|
||
The general rule is to not close a BFD until all operations dependent
|
||
upon data from the BFD have been completed, or all the data from within
|
||
the file has been copied. To help with the management of memory, there
|
||
is a function (`bfd_alloc_size') which returns the number of bytes in
|
||
obstacks associated with the supplied BFD. This could be used to select
|
||
the greediest open BFD, close it to reclaim the memory, perform some
|
||
operation and reopen the BFD again, to get a fresh copy of the data
|
||
structures.
|
||
|
||
|
||
File: bfd.info, Node: Initialization, Next: Sections, Prev: Memory Usage, Up: BFD front end
|
||
|
||
Initialization
|
||
==============
|
||
|
||
These are the functions that handle initializing a BFD.
|
||
|
||
`bfd_init'
|
||
..........
|
||
|
||
*Synopsis*
|
||
void bfd_init(void);
|
||
*Description*
|
||
This routine must be called before any other BFD function to initialize
|
||
magical internal data structures.
|
||
|
||
|
||
File: bfd.info, Node: Sections, Next: Symbols, Prev: Initialization, Up: BFD front end
|
||
|
||
Sections
|
||
========
|
||
|
||
The raw data contained within a BFD is maintained through the
|
||
section abstraction. A single BFD may have any number of sections. It
|
||
keeps hold of them by pointing to the first; each one points to the
|
||
next in the list.
|
||
|
||
Sections are supported in BFD in `section.c'.
|
||
|
||
* Menu:
|
||
|
||
* Section Input::
|
||
* Section Output::
|
||
* typedef asection::
|
||
* section prototypes::
|
||
|
||
|
||
File: bfd.info, Node: Section Input, Next: Section Output, Prev: Sections, Up: Sections
|
||
|
||
Section input
|
||
-------------
|
||
|
||
When a BFD is opened for reading, the section structures are created
|
||
and attached to the BFD.
|
||
|
||
Each section has a name which describes the section in the outside
|
||
world--for example, `a.out' would contain at least three sections,
|
||
called `.text', `.data' and `.bss'.
|
||
|
||
Names need not be unique; for example a COFF file may have several
|
||
sections named `.data'.
|
||
|
||
Sometimes a BFD will contain more than the "natural" number of
|
||
sections. A back end may attach other sections containing constructor
|
||
data, or an application may add a section (using `bfd_make_section') to
|
||
the sections attached to an already open BFD. For example, the linker
|
||
creates an extra section `COMMON' for each input file's BFD to hold
|
||
information about common storage.
|
||
|
||
The raw data is not necessarily read in when the section descriptor
|
||
is created. Some targets may leave the data in place until a
|
||
`bfd_get_section_contents' call is made. Other back ends may read in
|
||
all the data at once. For example, an S-record file has to be read
|
||
once to determine the size of the data. An IEEE-695 file doesn't
|
||
contain raw data in sections, but data and relocation expressions
|
||
intermixed, so the data area has to be parsed to get out the data and
|
||
relocations.
|
||
|
||
|
||
File: bfd.info, Node: Section Output, Next: typedef asection, Prev: Section Input, Up: Sections
|
||
|
||
Section output
|
||
--------------
|
||
|
||
To write a new object style BFD, the various sections to be written
|
||
have to be created. They are attached to the BFD in the same way as
|
||
input sections; data is written to the sections using
|
||
`bfd_set_section_contents'.
|
||
|
||
Any program that creates or combines sections (e.g., the assembler
|
||
and linker) must use the `asection' fields `output_section' and
|
||
`output_offset' to indicate the file sections to which each section
|
||
must be written. (If the section is being created from scratch,
|
||
`output_section' should probably point to the section itself and
|
||
`output_offset' should probably be zero.)
|
||
|
||
The data to be written comes from input sections attached (via
|
||
`output_section' pointers) to the output sections. The output section
|
||
structure can be considered a filter for the input section: the output
|
||
section determines the vma of the output data and the name, but the
|
||
input section determines the offset into the output section of the data
|
||
to be written.
|
||
|
||
E.g., to create a section "O", starting at 0x100, 0x123 long,
|
||
containing two subsections, "A" at offset 0x0 (i.e., at vma 0x100) and
|
||
"B" at offset 0x20 (i.e., at vma 0x120) the `asection' structures would
|
||
look like:
|
||
|
||
section name "A"
|
||
output_offset 0x00
|
||
size 0x20
|
||
output_section -----------> section name "O"
|
||
| vma 0x100
|
||
section name "B" | size 0x123
|
||
output_offset 0x20 |
|
||
size 0x103 |
|
||
output_section --------|
|
||
|
||
Link orders
|
||
-----------
|
||
|
||
The data within a section is stored in a "link_order". These are
|
||
much like the fixups in `gas'. The link_order abstraction allows a
|
||
section to grow and shrink within itself.
|
||
|
||
A link_order knows how big it is, and which is the next link_order
|
||
and where the raw data for it is; it also points to a list of
|
||
relocations which apply to it.
|
||
|
||
The link_order is used by the linker to perform relaxing on final
|
||
code. The compiler creates code which is as big as necessary to make
|
||
it work without relaxing, and the user can select whether to relax.
|
||
Sometimes relaxing takes a lot of time. The linker runs around the
|
||
relocations to see if any are attached to data which can be shrunk, if
|
||
so it does it on a link_order by link_order basis.
|
||
|