1021 lines
39 KiB
HTML
1021 lines
39 KiB
HTML
<html lang="en">
|
|
<head>
|
|
<title>BFD front end - Untitled</title>
|
|
<meta http-equiv="Content-Type" content="text/html">
|
|
<meta name="description" content="Untitled">
|
|
<meta name="generator" content="makeinfo 4.7">
|
|
<link title="Top" rel="start" href="index.html#Top">
|
|
<link rel="prev" href="Overview.html#Overview" title="Overview">
|
|
<link rel="next" href="BFD-back-ends.html#BFD-back-ends" title="BFD back ends">
|
|
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
|
|
<!--
|
|
This file documents the BFD library.
|
|
|
|
Copyright (C) 1991, 2000, 2001, 2003, 2006, 2007 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 the
|
|
Invariant Sections being ``GNU General Public License'' and ``Funding
|
|
Free Software'', the Front-Cover texts being (a) (see below), and with
|
|
the Back-Cover Texts being (b) (see below). A copy of the license is
|
|
included in the section entitled ``GNU Free Documentation License''.
|
|
|
|
(a) The FSF's Front-Cover Text is:
|
|
|
|
A GNU Manual
|
|
|
|
(b) The FSF's Back-Cover Text is:
|
|
|
|
You have freedom to copy and modify this GNU Manual, like GNU
|
|
software. Copies published by the Free Software Foundation raise
|
|
funds for GNU development.-->
|
|
<meta http-equiv="Content-Style-Type" content="text/css">
|
|
<style type="text/css"><!--
|
|
pre.display { font-family:inherit }
|
|
pre.format { font-family:inherit }
|
|
pre.smalldisplay { font-family:inherit; font-size:smaller }
|
|
pre.smallformat { font-family:inherit; font-size:smaller }
|
|
pre.smallexample { font-size:smaller }
|
|
pre.smalllisp { font-size:smaller }
|
|
span.sc { font-variant:small-caps }
|
|
span.roman { font-family: serif; font-weight: normal; }
|
|
--></style>
|
|
</head>
|
|
<body>
|
|
<div class="node">
|
|
<p>
|
|
<a name="BFD-front-end"></a>Next: <a rel="next" accesskey="n" href="BFD-back-ends.html#BFD-back-ends">BFD back ends</a>,
|
|
Previous: <a rel="previous" accesskey="p" href="Overview.html#Overview">Overview</a>,
|
|
Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
|
|
<hr><br>
|
|
</div>
|
|
|
|
<h2 class="chapter">2 BFD Front End</h2>
|
|
|
|
<h3 class="section">2.1 <code>typedef bfd</code></h3>
|
|
|
|
<p>A BFD has type <code>bfd</code>; 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.
|
|
|
|
<p>Here is the structure that defines the type <code>bfd</code>. It
|
|
contains the major data about the file and pointers
|
|
to the rest of the data.
|
|
|
|
<pre class="example">
|
|
struct bfd
|
|
{
|
|
/* A unique identifier of the BFD */
|
|
unsigned int id;
|
|
|
|
/* The filename the application opened the BFD with. */
|
|
const char *filename;
|
|
|
|
/* A pointer to the target jump table. */
|
|
const struct bfd_target *xvec;
|
|
|
|
/* The IOSTREAM, and corresponding IO vector that provide access
|
|
to the file backing the BFD. */
|
|
void *iostream;
|
|
const struct bfd_iovec *iovec;
|
|
|
|
/* 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;
|
|
|
|
/* 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;
|
|
|
|
/* Values that may appear in the flags field of a BFD. These also
|
|
appear in the object_flags field of the bfd_target structure, where
|
|
they indicate the set of flags used by that backend (not all flags
|
|
are meaningful for all object file formats) (FIXME: at the moment,
|
|
the object_flags values have mostly just been copied from backend
|
|
to another, and are not necessarily correct). */
|
|
|
|
#define BFD_NO_FLAGS 0x00
|
|
|
|
/* BFD contains relocation entries. */
|
|
#define HAS_RELOC 0x01
|
|
|
|
/* BFD is directly executable. */
|
|
#define EXEC_P 0x02
|
|
|
|
/* BFD has line number information (basically used for F_LNNO in a
|
|
COFF header). */
|
|
#define HAS_LINENO 0x04
|
|
|
|
/* BFD has debugging information. */
|
|
#define HAS_DEBUG 0x08
|
|
|
|
/* BFD has symbols. */
|
|
#define HAS_SYMS 0x10
|
|
|
|
/* BFD has local symbols (basically used for F_LSYMS in a COFF
|
|
header). */
|
|
#define HAS_LOCALS 0x20
|
|
|
|
/* BFD is a dynamic object. */
|
|
#define DYNAMIC 0x40
|
|
|
|
/* Text section is write protected (if D_PAGED is not set, this is
|
|
like an a.out NMAGIC file) (the linker sets this by default, but
|
|
clears it for -r or -N). */
|
|
#define WP_TEXT 0x80
|
|
|
|
/* BFD is dynamically paged (this is like an a.out ZMAGIC file) (the
|
|
linker sets this by default, but clears it for -r or -n or -N). */
|
|
#define D_PAGED 0x100
|
|
|
|
/* BFD is relaxable (this means that bfd_relax_section may be able to
|
|
do something) (sometimes bfd_relax_section can do something even if
|
|
this is not set). */
|
|
#define BFD_IS_RELAXABLE 0x200
|
|
|
|
/* This may be set before writing out a BFD to request using a
|
|
traditional format. For example, this is used to request that when
|
|
writing out an a.out object the symbols not be hashed to eliminate
|
|
duplicates. */
|
|
#define BFD_TRADITIONAL_FORMAT 0x400
|
|
|
|
/* This flag indicates that the BFD contents are actually cached
|
|
in memory. If this is set, iostream points to a bfd_in_memory
|
|
struct. */
|
|
#define BFD_IN_MEMORY 0x800
|
|
|
|
/* The sections in this BFD specify a memory page. */
|
|
#define HAS_LOAD_PAGE 0x1000
|
|
|
|
/* This BFD has been created by the linker and doesn't correspond
|
|
to any input file. */
|
|
#define BFD_LINKER_CREATED 0x2000
|
|
|
|
/* 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;
|
|
|
|
/* The origin in the archive of the proxy entry. This will
|
|
normally be the same as origin, except for thin archives,
|
|
when it will contain the current offset of the proxy in the
|
|
thin archive rather than the offset of the bfd in its actual
|
|
container. */
|
|
ufile_ptr proxy_origin;
|
|
|
|
/* A hash table for section names. */
|
|
struct bfd_hash_table section_htab;
|
|
|
|
/* Pointer to linked list of sections. */
|
|
struct bfd_section *sections;
|
|
|
|
/* The last section on the section list. */
|
|
struct bfd_section *section_last;
|
|
|
|
/* 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).
|
|
Also used by the linker to cache input BFD symbols. */
|
|
struct bfd_symbol **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. */
|
|
void *arelt_data;
|
|
struct bfd *my_archive; /* The containing archive BFD. */
|
|
struct bfd *archive_next; /* The next BFD in the archive. */
|
|
struct bfd *archive_head; /* The first BFD in the archive. */
|
|
struct bfd *nested_archives; /* List of nested archive in a flattened
|
|
thin archive. */
|
|
|
|
/* 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;
|
|
struct mach_o_data_struct *mach_o_data;
|
|
struct mach_o_fat_data_struct *mach_o_fat_data;
|
|
struct bfd_pef_data_struct *pef_data;
|
|
struct bfd_pef_xlib_data_struct *pef_xlib_data;
|
|
struct bfd_sym_data_struct *sym_data;
|
|
void *any;
|
|
}
|
|
tdata;
|
|
|
|
/* Used by the application to hold private data. */
|
|
void *usrdata;
|
|
|
|
/* Where all the allocated stuff under this BFD goes. This is a
|
|
struct objalloc *, but we use void * to avoid requiring the inclusion
|
|
of objalloc.h. */
|
|
void *memory;
|
|
|
|
/* Is the file descriptor being cached? That is, can it be closed as
|
|
needed, and re-opened when accessed later? */
|
|
unsigned int cacheable : 1;
|
|
|
|
/* 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. */
|
|
unsigned int target_defaulted : 1;
|
|
|
|
/* ... and here: (``once'' means at least once). */
|
|
unsigned int opened_once : 1;
|
|
|
|
/* Set if we have a locally maintained mtime value, rather than
|
|
getting it from the file each time. */
|
|
unsigned int mtime_set : 1;
|
|
|
|
/* Flag set if symbols from this BFD should not be exported. */
|
|
unsigned int no_export : 1;
|
|
|
|
/* Remember when output has begun, to stop strange things
|
|
from happening. */
|
|
unsigned int output_has_begun : 1;
|
|
|
|
/* Have archive map. */
|
|
unsigned int has_armap : 1;
|
|
|
|
/* Set if this is a thin archive. */
|
|
unsigned int is_thin_archive : 1;
|
|
};
|
|
|
|
</pre>
|
|
<h3 class="section">2.2 Error reporting</h3>
|
|
|
|
<p>Most BFD functions return nonzero on success (check their
|
|
individual documentation for precise semantics). On an error,
|
|
they call <code>bfd_set_error</code> to set an error condition that callers
|
|
can check by calling <code>bfd_get_error</code>.
|
|
If that returns <code>bfd_error_system_call</code>, then check
|
|
<code>errno</code>.
|
|
|
|
<p>The easiest way to report a BFD error to the user is to
|
|
use <code>bfd_perror</code>.
|
|
|
|
<h4 class="subsection">2.2.1 Type <code>bfd_error_type</code></h4>
|
|
|
|
<p>The values returned by <code>bfd_get_error</code> are defined by the
|
|
enumerated type <code>bfd_error_type</code>.
|
|
|
|
<pre class="example">
|
|
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_on_input,
|
|
bfd_error_invalid_error_code
|
|
}
|
|
bfd_error_type;
|
|
|
|
</pre>
|
|
<p><a name="index-bfd_005fget_005ferror-5"></a>
|
|
|
|
<h5 class="subsubsection">2.2.1.1 <code>bfd_get_error</code></h5>
|
|
|
|
<p><strong>Synopsis</strong>
|
|
<pre class="example"> bfd_error_type bfd_get_error (void);
|
|
</pre>
|
|
<p><strong>Description</strong><br>
|
|
Return the current BFD error condition.
|
|
|
|
<p><a name="index-bfd_005fset_005ferror-6"></a>
|
|
|
|
<h5 class="subsubsection">2.2.1.2 <code>bfd_set_error</code></h5>
|
|
|
|
<p><strong>Synopsis</strong>
|
|
<pre class="example"> void bfd_set_error (bfd_error_type error_tag, ...);
|
|
</pre>
|
|
<p><strong>Description</strong><br>
|
|
Set the BFD error condition to be <var>error_tag</var>.
|
|
If <var>error_tag</var> is bfd_error_on_input, then this function
|
|
takes two more parameters, the input bfd where the error
|
|
occurred, and the bfd_error_type error.
|
|
|
|
<p><a name="index-bfd_005ferrmsg-7"></a>
|
|
|
|
<h5 class="subsubsection">2.2.1.3 <code>bfd_errmsg</code></h5>
|
|
|
|
<p><strong>Synopsis</strong>
|
|
<pre class="example"> const char *bfd_errmsg (bfd_error_type error_tag);
|
|
</pre>
|
|
<p><strong>Description</strong><br>
|
|
Return a string describing the error <var>error_tag</var>, or
|
|
the system error if <var>error_tag</var> is <code>bfd_error_system_call</code>.
|
|
|
|
<p><a name="index-bfd_005fperror-8"></a>
|
|
|
|
<h5 class="subsubsection">2.2.1.4 <code>bfd_perror</code></h5>
|
|
|
|
<p><strong>Synopsis</strong>
|
|
<pre class="example"> void bfd_perror (const char *message);
|
|
</pre>
|
|
<p><strong>Description</strong><br>
|
|
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</var>
|
|
is non-NULL and non-empty, the error string printed is preceded
|
|
by <var>message</var>, a colon, and a space. It is followed by a newline.
|
|
|
|
<h4 class="subsection">2.2.2 BFD error handler</h4>
|
|
|
|
<p>Some BFD functions want to print messages describing the
|
|
problem. They call a BFD error handler function. This
|
|
function may be overridden by the program.
|
|
|
|
<p>The BFD error handler acts like printf.
|
|
|
|
<pre class="example">
|
|
typedef void (*bfd_error_handler_type) (const char *, ...);
|
|
|
|
</pre>
|
|
<p><a name="index-bfd_005fset_005ferror_005fhandler-9"></a>
|
|
|
|
<h5 class="subsubsection">2.2.2.1 <code>bfd_set_error_handler</code></h5>
|
|
|
|
<p><strong>Synopsis</strong>
|
|
<pre class="example"> bfd_error_handler_type bfd_set_error_handler (bfd_error_handler_type);
|
|
</pre>
|
|
<p><strong>Description</strong><br>
|
|
Set the BFD error handler function. Returns the previous
|
|
function.
|
|
|
|
<p><a name="index-bfd_005fset_005ferror_005fprogram_005fname-10"></a>
|
|
|
|
<h5 class="subsubsection">2.2.2.2 <code>bfd_set_error_program_name</code></h5>
|
|
|
|
<p><strong>Synopsis</strong>
|
|
<pre class="example"> void bfd_set_error_program_name (const char *);
|
|
</pre>
|
|
<p><strong>Description</strong><br>
|
|
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.
|
|
|
|
<p><a name="index-bfd_005fget_005ferror_005fhandler-11"></a>
|
|
|
|
<h5 class="subsubsection">2.2.2.3 <code>bfd_get_error_handler</code></h5>
|
|
|
|
<p><strong>Synopsis</strong>
|
|
<pre class="example"> bfd_error_handler_type bfd_get_error_handler (void);
|
|
</pre>
|
|
<p><strong>Description</strong><br>
|
|
Return the BFD error handler function.
|
|
|
|
<h3 class="section">2.3 Miscellaneous</h3>
|
|
|
|
<h4 class="subsection">2.3.1 Miscellaneous functions</h4>
|
|
|
|
<p><a name="index-bfd_005fget_005freloc_005fupper_005fbound-12"></a>
|
|
|
|
<h5 class="subsubsection">2.3.1.1 <code>bfd_get_reloc_upper_bound</code></h5>
|
|
|
|
<p><strong>Synopsis</strong>
|
|
<pre class="example"> long bfd_get_reloc_upper_bound (bfd *abfd, asection *sect);
|
|
</pre>
|
|
<p><strong>Description</strong><br>
|
|
Return the number of bytes required to store the
|
|
relocation information associated with section <var>sect</var>
|
|
attached to bfd <var>abfd</var>. If an error occurs, return -1.
|
|
|
|
<p><a name="index-bfd_005fcanonicalize_005freloc-13"></a>
|
|
|
|
<h5 class="subsubsection">2.3.1.2 <code>bfd_canonicalize_reloc</code></h5>
|
|
|
|
<p><strong>Synopsis</strong>
|
|
<pre class="example"> long bfd_canonicalize_reloc
|
|
(bfd *abfd, asection *sec, arelent **loc, asymbol **syms);
|
|
</pre>
|
|
<p><strong>Description</strong><br>
|
|
Call the back end associated with the open BFD
|
|
<var>abfd</var> and translate the external form of the relocation
|
|
information attached to <var>sec</var> into the internal canonical
|
|
form. Place the table into memory at <var>loc</var>, which has
|
|
been preallocated, usually by a call to
|
|
<code>bfd_get_reloc_upper_bound</code>. Returns the number of relocs, or
|
|
-1 on error.
|
|
|
|
<p>The <var>syms</var> table is also needed for horrible internal magic
|
|
reasons.
|
|
|
|
<p><a name="index-bfd_005fset_005freloc-14"></a>
|
|
|
|
<h5 class="subsubsection">2.3.1.3 <code>bfd_set_reloc</code></h5>
|
|
|
|
<p><strong>Synopsis</strong>
|
|
<pre class="example"> void bfd_set_reloc
|
|
(bfd *abfd, asection *sec, arelent **rel, unsigned int count);
|
|
</pre>
|
|
<p><strong>Description</strong><br>
|
|
Set the relocation pointer and count within
|
|
section <var>sec</var> to the values <var>rel</var> and <var>count</var>.
|
|
The argument <var>abfd</var> is ignored.
|
|
|
|
<p><a name="index-bfd_005fset_005ffile_005fflags-15"></a>
|
|
|
|
<h5 class="subsubsection">2.3.1.4 <code>bfd_set_file_flags</code></h5>
|
|
|
|
<p><strong>Synopsis</strong>
|
|
<pre class="example"> bfd_boolean bfd_set_file_flags (bfd *abfd, flagword flags);
|
|
</pre>
|
|
<p><strong>Description</strong><br>
|
|
Set the flag word in the BFD <var>abfd</var> to the value <var>flags</var>.
|
|
|
|
<p>Possible errors are:
|
|
<ul>
|
|
<li><code>bfd_error_wrong_format</code> - The target bfd was not of object format.
|
|
<li><code>bfd_error_invalid_operation</code> - The target bfd was open for reading.
|
|
<li><code>bfd_error_invalid_operation</code> -
|
|
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</code> bit
|
|
on a BFD format which does not support demand paging.
|
|
</ul>
|
|
|
|
<p><a name="index-bfd_005fget_005farch_005fsize-16"></a>
|
|
|
|
<h5 class="subsubsection">2.3.1.5 <code>bfd_get_arch_size</code></h5>
|
|
|
|
<p><strong>Synopsis</strong>
|
|
<pre class="example"> int bfd_get_arch_size (bfd *abfd);
|
|
</pre>
|
|
<p><strong>Description</strong><br>
|
|
Returns the architecture address size, in bits, as determined
|
|
by the object file's format. For ELF, this information is
|
|
included in the header.
|
|
|
|
<p><strong>Returns</strong><br>
|
|
Returns the arch size in bits if known, <code>-1</code> otherwise.
|
|
|
|
<p><a name="index-bfd_005fget_005fsign_005fextend_005fvma-17"></a>
|
|
|
|
<h5 class="subsubsection">2.3.1.6 <code>bfd_get_sign_extend_vma</code></h5>
|
|
|
|
<p><strong>Synopsis</strong>
|
|
<pre class="example"> int bfd_get_sign_extend_vma (bfd *abfd);
|
|
</pre>
|
|
<p><strong>Description</strong><br>
|
|
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.
|
|
|
|
<p><strong>Returns</strong><br>
|
|
Returns <code>1</code> if the target architecture is known to sign
|
|
extend addresses, <code>0</code> if the target architecture is known to
|
|
not sign extend addresses, and <code>-1</code> otherwise.
|
|
|
|
<p><a name="index-bfd_005fset_005fstart_005faddress-18"></a>
|
|
|
|
<h5 class="subsubsection">2.3.1.7 <code>bfd_set_start_address</code></h5>
|
|
|
|
<p><strong>Synopsis</strong>
|
|
<pre class="example"> bfd_boolean bfd_set_start_address (bfd *abfd, bfd_vma vma);
|
|
</pre>
|
|
<p><strong>Description</strong><br>
|
|
Make <var>vma</var> the entry point of output BFD <var>abfd</var>.
|
|
|
|
<p><strong>Returns</strong><br>
|
|
Returns <code>TRUE</code> on success, <code>FALSE</code> otherwise.
|
|
|
|
<p><a name="index-bfd_005fget_005fgp_005fsize-19"></a>
|
|
|
|
<h5 class="subsubsection">2.3.1.8 <code>bfd_get_gp_size</code></h5>
|
|
|
|
<p><strong>Synopsis</strong>
|
|
<pre class="example"> unsigned int bfd_get_gp_size (bfd *abfd);
|
|
</pre>
|
|
<p><strong>Description</strong><br>
|
|
Return the maximum size of objects to be optimized using the GP
|
|
register under MIPS ECOFF. This is typically set by the <code>-G</code>
|
|
argument to the compiler, assembler or linker.
|
|
|
|
<p><a name="index-bfd_005fset_005fgp_005fsize-20"></a>
|
|
|
|
<h5 class="subsubsection">2.3.1.9 <code>bfd_set_gp_size</code></h5>
|
|
|
|
<p><strong>Synopsis</strong>
|
|
<pre class="example"> void bfd_set_gp_size (bfd *abfd, unsigned int i);
|
|
</pre>
|
|
<p><strong>Description</strong><br>
|
|
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</code> argument to the compiler, assembler or linker.
|
|
|
|
<p><a name="index-bfd_005fscan_005fvma-21"></a>
|
|
|
|
<h5 class="subsubsection">2.3.1.10 <code>bfd_scan_vma</code></h5>
|
|
|
|
<p><strong>Synopsis</strong>
|
|
<pre class="example"> bfd_vma bfd_scan_vma (const char *string, const char **end, int base);
|
|
</pre>
|
|
<p><strong>Description</strong><br>
|
|
Convert, like <code>strtoul</code>, a numerical expression
|
|
<var>string</var> into a <code>bfd_vma</code> integer, and return that integer.
|
|
(Though without as many bells and whistles as <code>strtoul</code>.)
|
|
The expression is assumed to be unsigned (i.e., positive).
|
|
If given a <var>base</var>, 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.
|
|
|
|
<p>If the value would overflow, the maximum <code>bfd_vma</code> value is
|
|
returned.
|
|
|
|
<p><a name="index-bfd_005fcopy_005fprivate_005fheader_005fdata-22"></a>
|
|
|
|
<h5 class="subsubsection">2.3.1.11 <code>bfd_copy_private_header_data</code></h5>
|
|
|
|
<p><strong>Synopsis</strong>
|
|
<pre class="example"> bfd_boolean bfd_copy_private_header_data (bfd *ibfd, bfd *obfd);
|
|
</pre>
|
|
<p><strong>Description</strong><br>
|
|
Copy private BFD header information from the BFD <var>ibfd</var> to the
|
|
the BFD <var>obfd</var>. This copies information that may require
|
|
sections to exist, but does not require symbol tables. Return
|
|
<code>true</code> on success, <code>false</code> on error.
|
|
Possible error returns are:
|
|
|
|
<ul>
|
|
<li><code>bfd_error_no_memory</code> -
|
|
Not enough memory exists to create private data for <var>obfd</var>.
|
|
</ul>
|
|
|
|
<pre class="example"> #define bfd_copy_private_header_data(ibfd, obfd) \
|
|
BFD_SEND (obfd, _bfd_copy_private_header_data, \
|
|
(ibfd, obfd))
|
|
</pre>
|
|
<p><a name="index-bfd_005fcopy_005fprivate_005fbfd_005fdata-23"></a>
|
|
|
|
<h5 class="subsubsection">2.3.1.12 <code>bfd_copy_private_bfd_data</code></h5>
|
|
|
|
<p><strong>Synopsis</strong>
|
|
<pre class="example"> bfd_boolean bfd_copy_private_bfd_data (bfd *ibfd, bfd *obfd);
|
|
</pre>
|
|
<p><strong>Description</strong><br>
|
|
Copy private BFD information from the BFD <var>ibfd</var> to the
|
|
the BFD <var>obfd</var>. Return <code>TRUE</code> on success, <code>FALSE</code> on error.
|
|
Possible error returns are:
|
|
|
|
<ul>
|
|
<li><code>bfd_error_no_memory</code> -
|
|
Not enough memory exists to create private data for <var>obfd</var>.
|
|
</ul>
|
|
|
|
<pre class="example"> #define bfd_copy_private_bfd_data(ibfd, obfd) \
|
|
BFD_SEND (obfd, _bfd_copy_private_bfd_data, \
|
|
(ibfd, obfd))
|
|
</pre>
|
|
<p><a name="index-bfd_005fmerge_005fprivate_005fbfd_005fdata-24"></a>
|
|
|
|
<h5 class="subsubsection">2.3.1.13 <code>bfd_merge_private_bfd_data</code></h5>
|
|
|
|
<p><strong>Synopsis</strong>
|
|
<pre class="example"> bfd_boolean bfd_merge_private_bfd_data (bfd *ibfd, bfd *obfd);
|
|
</pre>
|
|
<p><strong>Description</strong><br>
|
|
Merge private BFD information from the BFD <var>ibfd</var> to the
|
|
the output file BFD <var>obfd</var> when linking. Return <code>TRUE</code>
|
|
on success, <code>FALSE</code> on error. Possible error returns are:
|
|
|
|
<ul>
|
|
<li><code>bfd_error_no_memory</code> -
|
|
Not enough memory exists to create private data for <var>obfd</var>.
|
|
</ul>
|
|
|
|
<pre class="example"> #define bfd_merge_private_bfd_data(ibfd, obfd) \
|
|
BFD_SEND (obfd, _bfd_merge_private_bfd_data, \
|
|
(ibfd, obfd))
|
|
</pre>
|
|
<p><a name="index-bfd_005fset_005fprivate_005fflags-25"></a>
|
|
|
|
<h5 class="subsubsection">2.3.1.14 <code>bfd_set_private_flags</code></h5>
|
|
|
|
<p><strong>Synopsis</strong>
|
|
<pre class="example"> bfd_boolean bfd_set_private_flags (bfd *abfd, flagword flags);
|
|
</pre>
|
|
<p><strong>Description</strong><br>
|
|
Set private BFD flag information in the BFD <var>abfd</var>.
|
|
Return <code>TRUE</code> on success, <code>FALSE</code> on error. Possible error
|
|
returns are:
|
|
|
|
<ul>
|
|
<li><code>bfd_error_no_memory</code> -
|
|
Not enough memory exists to create private data for <var>obfd</var>.
|
|
</ul>
|
|
|
|
<pre class="example"> #define bfd_set_private_flags(abfd, flags) \
|
|
BFD_SEND (abfd, _bfd_set_private_flags, (abfd, flags))
|
|
</pre>
|
|
<p><a name="index-Other-functions-26"></a>
|
|
|
|
<h5 class="subsubsection">2.3.1.15 <code>Other functions</code></h5>
|
|
|
|
<p><strong>Description</strong><br>
|
|
The following functions exist but have not yet been documented.
|
|
<pre class="example"> #define bfd_sizeof_headers(abfd, info) \
|
|
BFD_SEND (abfd, _bfd_sizeof_headers, (abfd, info))
|
|
|
|
#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))
|
|
|
|
#define bfd_find_line(abfd, syms, sym, file, line) \
|
|
BFD_SEND (abfd, _bfd_find_line, \
|
|
(abfd, syms, sym, file, line))
|
|
|
|
#define bfd_find_inliner_info(abfd, file, func, line) \
|
|
BFD_SEND (abfd, _bfd_find_inliner_info, \
|
|
(abfd, file, func, line))
|
|
|
|
#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_is_group_section(abfd, sec) \
|
|
BFD_SEND (abfd, _bfd_is_group_section, (abfd, sec))
|
|
|
|
#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(abfd, 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_synthetic_symtab(abfd, count, syms, dyncount, dynsyms, ret) \
|
|
BFD_SEND (abfd, _bfd_get_synthetic_symtab, (abfd, count, syms, \
|
|
dyncount, dynsyms, ret))
|
|
|
|
#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
|
|
(bfd *, struct bfd_link_info *, struct bfd_link_order *, bfd_byte *,
|
|
bfd_boolean, asymbol **);
|
|
|
|
</pre>
|
|
<p><a name="index-bfd_005falt_005fmach_005fcode-27"></a>
|
|
|
|
<h5 class="subsubsection">2.3.1.16 <code>bfd_alt_mach_code</code></h5>
|
|
|
|
<p><strong>Synopsis</strong>
|
|
<pre class="example"> bfd_boolean bfd_alt_mach_code (bfd *abfd, int alternative);
|
|
</pre>
|
|
<p><strong>Description</strong><br>
|
|
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.
|
|
|
|
<pre class="example"> struct bfd_preserve
|
|
{
|
|
void *marker;
|
|
void *tdata;
|
|
flagword flags;
|
|
const struct bfd_arch_info *arch_info;
|
|
struct bfd_section *sections;
|
|
struct bfd_section *section_last;
|
|
unsigned int section_count;
|
|
struct bfd_hash_table section_htab;
|
|
};
|
|
|
|
</pre>
|
|
<p><a name="index-bfd_005fpreserve_005fsave-28"></a>
|
|
|
|
<h5 class="subsubsection">2.3.1.17 <code>bfd_preserve_save</code></h5>
|
|
|
|
<p><strong>Synopsis</strong>
|
|
<pre class="example"> bfd_boolean bfd_preserve_save (bfd *, struct bfd_preserve *);
|
|
</pre>
|
|
<p><strong>Description</strong><br>
|
|
When testing an object for compatibility with a particular
|
|
target back-end, the back-end object_p function needs to set
|
|
up certain fields in the bfd on successfully recognizing the
|
|
object. This typically happens in a piecemeal fashion, with
|
|
failures possible at many points. On failure, the bfd is
|
|
supposed to be restored to its initial state, which is
|
|
virtually impossible. However, restoring a subset of the bfd
|
|
state works in practice. This function stores the subset and
|
|
reinitializes the bfd.
|
|
|
|
<p><a name="index-bfd_005fpreserve_005frestore-29"></a>
|
|
|
|
<h5 class="subsubsection">2.3.1.18 <code>bfd_preserve_restore</code></h5>
|
|
|
|
<p><strong>Synopsis</strong>
|
|
<pre class="example"> void bfd_preserve_restore (bfd *, struct bfd_preserve *);
|
|
</pre>
|
|
<p><strong>Description</strong><br>
|
|
This function restores bfd state saved by bfd_preserve_save.
|
|
If MARKER is non-NULL in struct bfd_preserve then that block
|
|
and all subsequently bfd_alloc'd memory is freed.
|
|
|
|
<p><a name="index-bfd_005fpreserve_005ffinish-30"></a>
|
|
|
|
<h5 class="subsubsection">2.3.1.19 <code>bfd_preserve_finish</code></h5>
|
|
|
|
<p><strong>Synopsis</strong>
|
|
<pre class="example"> void bfd_preserve_finish (bfd *, struct bfd_preserve *);
|
|
</pre>
|
|
<p><strong>Description</strong><br>
|
|
This function should be called when the bfd state saved by
|
|
bfd_preserve_save is no longer needed. ie. when the back-end
|
|
object_p function returns with success.
|
|
|
|
<p><a name="index-bfd_005femul_005fget_005fmaxpagesize-31"></a>
|
|
|
|
<h5 class="subsubsection">2.3.1.20 <code>bfd_emul_get_maxpagesize</code></h5>
|
|
|
|
<p><strong>Synopsis</strong>
|
|
<pre class="example"> bfd_vma bfd_emul_get_maxpagesize (const char *);
|
|
</pre>
|
|
<p><strong>Description</strong><br>
|
|
Returns the maximum page size, in bytes, as determined by
|
|
emulation.
|
|
|
|
<p><strong>Returns</strong><br>
|
|
Returns the maximum page size in bytes for ELF, abort
|
|
otherwise.
|
|
|
|
<p><a name="index-bfd_005femul_005fset_005fmaxpagesize-32"></a>
|
|
|
|
<h5 class="subsubsection">2.3.1.21 <code>bfd_emul_set_maxpagesize</code></h5>
|
|
|
|
<p><strong>Synopsis</strong>
|
|
<pre class="example"> void bfd_emul_set_maxpagesize (const char *, bfd_vma);
|
|
</pre>
|
|
<p><strong>Description</strong><br>
|
|
For ELF, set the maximum page size for the emulation. It is
|
|
a no-op for other formats.
|
|
|
|
<p><a name="index-bfd_005femul_005fget_005fcommonpagesize-33"></a>
|
|
|
|
<h5 class="subsubsection">2.3.1.22 <code>bfd_emul_get_commonpagesize</code></h5>
|
|
|
|
<p><strong>Synopsis</strong>
|
|
<pre class="example"> bfd_vma bfd_emul_get_commonpagesize (const char *);
|
|
</pre>
|
|
<p><strong>Description</strong><br>
|
|
Returns the common page size, in bytes, as determined by
|
|
emulation.
|
|
|
|
<p><strong>Returns</strong><br>
|
|
Returns the common page size in bytes for ELF, abort otherwise.
|
|
|
|
<p><a name="index-bfd_005femul_005fset_005fcommonpagesize-34"></a>
|
|
|
|
<h5 class="subsubsection">2.3.1.23 <code>bfd_emul_set_commonpagesize</code></h5>
|
|
|
|
<p><strong>Synopsis</strong>
|
|
<pre class="example"> void bfd_emul_set_commonpagesize (const char *, bfd_vma);
|
|
</pre>
|
|
<p><strong>Description</strong><br>
|
|
For ELF, set the common page size for the emulation. It is
|
|
a no-op for other formats.
|
|
|
|
<p><a name="index-bfd_005fdemangle-35"></a>
|
|
|
|
<h5 class="subsubsection">2.3.1.24 <code>bfd_demangle</code></h5>
|
|
|
|
<p><strong>Synopsis</strong>
|
|
<pre class="example"> char *bfd_demangle (bfd *, const char *, int);
|
|
</pre>
|
|
<p><strong>Description</strong><br>
|
|
Wrapper around cplus_demangle. Strips leading underscores and
|
|
other such chars that would otherwise confuse the demangler.
|
|
If passed a g++ v3 ABI mangled name, returns a buffer allocated
|
|
with malloc holding the demangled name. Returns NULL otherwise
|
|
and on memory alloc failure.
|
|
|
|
<p><a name="index-struct-bfd_005fiovec-36"></a>
|
|
|
|
<h5 class="subsubsection">2.3.1.25 <code>struct bfd_iovec</code></h5>
|
|
|
|
<p><strong>Description</strong><br>
|
|
The <code>struct bfd_iovec</code> contains the internal file I/O class.
|
|
Each <code>BFD</code> has an instance of this class and all file I/O is
|
|
routed through it (it is assumed that the instance implements
|
|
all methods listed below).
|
|
<pre class="example"> struct bfd_iovec
|
|
{
|
|
/* To avoid problems with macros, a "b" rather than "f"
|
|
prefix is prepended to each method name. */
|
|
/* Attempt to read/write NBYTES on ABFD's IOSTREAM storing/fetching
|
|
bytes starting at PTR. Return the number of bytes actually
|
|
transfered (a read past end-of-file returns less than NBYTES),
|
|
or -1 (setting <code>bfd_error</code>) if an error occurs. */
|
|
file_ptr (*bread) (struct bfd *abfd, void *ptr, file_ptr nbytes);
|
|
file_ptr (*bwrite) (struct bfd *abfd, const void *ptr,
|
|
file_ptr nbytes);
|
|
/* Return the current IOSTREAM file offset, or -1 (setting <code>bfd_error</code>
|
|
if an error occurs. */
|
|
file_ptr (*btell) (struct bfd *abfd);
|
|
/* For the following, on successful completion a value of 0 is returned.
|
|
Otherwise, a value of -1 is returned (and <code>bfd_error</code> is set). */
|
|
int (*bseek) (struct bfd *abfd, file_ptr offset, int whence);
|
|
int (*bclose) (struct bfd *abfd);
|
|
int (*bflush) (struct bfd *abfd);
|
|
int (*bstat) (struct bfd *abfd, struct stat *sb);
|
|
};
|
|
</pre>
|
|
<p><a name="index-bfd_005fget_005fmtime-37"></a>
|
|
|
|
<h5 class="subsubsection">2.3.1.26 <code>bfd_get_mtime</code></h5>
|
|
|
|
<p><strong>Synopsis</strong>
|
|
<pre class="example"> long bfd_get_mtime (bfd *abfd);
|
|
</pre>
|
|
<p><strong>Description</strong><br>
|
|
Return the file modification time (as read from the file system, or
|
|
from the archive header for archive members).
|
|
|
|
<p><a name="index-bfd_005fget_005fsize-38"></a>
|
|
|
|
<h5 class="subsubsection">2.3.1.27 <code>bfd_get_size</code></h5>
|
|
|
|
<p><strong>Synopsis</strong>
|
|
<pre class="example"> file_ptr bfd_get_size (bfd *abfd);
|
|
</pre>
|
|
<p><strong>Description</strong><br>
|
|
Return the file size (as read from file system) for the file
|
|
associated with BFD <var>abfd</var>.
|
|
|
|
<p>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.
|
|
|
|
<p>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)</code> 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 question, "is the
|
|
size reasonable?".
|
|
|
|
<ul class="menu">
|
|
<li><a accesskey="1" href="Memory-Usage.html#Memory-Usage">Memory Usage</a>
|
|
<li><a accesskey="2" href="Initialization.html#Initialization">Initialization</a>
|
|
<li><a accesskey="3" href="Sections.html#Sections">Sections</a>
|
|
<li><a accesskey="4" href="Symbols.html#Symbols">Symbols</a>
|
|
<li><a accesskey="5" href="Archives.html#Archives">Archives</a>
|
|
<li><a accesskey="6" href="Formats.html#Formats">Formats</a>
|
|
<li><a accesskey="7" href="Relocations.html#Relocations">Relocations</a>
|
|
<li><a accesskey="8" href="Core-Files.html#Core-Files">Core Files</a>
|
|
<li><a accesskey="9" href="Targets.html#Targets">Targets</a>
|
|
<li><a href="Architectures.html#Architectures">Architectures</a>
|
|
<li><a href="Opening-and-Closing.html#Opening-and-Closing">Opening and Closing</a>
|
|
<li><a href="Internal.html#Internal">Internal</a>
|
|
<li><a href="File-Caching.html#File-Caching">File Caching</a>
|
|
<li><a href="Linker-Functions.html#Linker-Functions">Linker Functions</a>
|
|
<li><a href="Hash-Tables.html#Hash-Tables">Hash Tables</a>
|
|
</ul>
|
|
|
|
</body></html>
|
|
|