blob: 9bd9852c7cf37edea839a51baa5a8ec92f295f0f [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- This file documents the BFD library.
Copyright (C) 1991-2015 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.3 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. -->
<!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
<head>
<title>Untitled Document: aout</title>
<meta name="description" content="Untitled Document: aout">
<meta name="keywords" content="Untitled Document: aout">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="BFD-Index.html#BFD-Index" rel="index" title="BFD Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="BFD-back-ends.html#BFD-back-ends" rel="up" title="BFD back ends">
<link href="coff.html#coff" rel="next" title="coff">
<link href="What-to-Put-Where.html#What-to-Put-Where" rel="prev" title="What to Put Where">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
div.smalllisp {margin-left: 3.2em}
kbd {font-style:oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
-->
</style>
</head>
<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="aout"></a>
<div class="header">
<p>
Next: <a href="coff.html#coff" accesskey="n" rel="next">coff</a>, Previous: <a href="What-to-Put-Where.html#What-to-Put-Where" accesskey="p" rel="prev">What to Put Where</a>, Up: <a href="BFD-back-ends.html#BFD-back-ends" accesskey="u" rel="up">BFD back ends</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="BFD-Index.html#BFD-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="a_002eout-backends"></a>
<h3 class="section">3.2 a.out backends</h3>
<p><strong>Description</strong><br>
BFD supports a number of different flavours of a.out format,
though the major differences are only the sizes of the
structures on disk, and the shape of the relocation
information.
</p>
<p>The support is split into a basic support file <samp>aoutx.h</samp>
and other files which derive functions from the base. One
derivation file is <samp>aoutf1.h</samp> (for a.out flavour 1), and
adds to the basic a.out functions support for sun3, sun4, 386
and 29k a.out files, to create a target jump vector for a
specific target.
</p>
<p>This information is further split out into more specific files
for each machine, including <samp>sunos.c</samp> for sun3 and sun4,
<samp>newsos3.c</samp> for the Sony NEWS, and <samp>demo64.c</samp> for a
demonstration of a 64 bit a.out format.
</p>
<p>The base file <samp>aoutx.h</samp> defines general mechanisms for
reading and writing records to and from disk and various
other methods which BFD requires. It is included by
<samp>aout32.c</samp> and <samp>aout64.c</samp> to form the names
<code>aout_32_swap_exec_header_in</code>, <code>aout_64_swap_exec_header_in</code>, etc.
</p>
<p>As an example, this is what goes on to make the back end for a
sun4, from <samp>aout32.c</samp>:
</p>
<div class="example">
<pre class="example"> #define ARCH_SIZE 32
#include &quot;aoutx.h&quot;
</pre></div>
<p>Which exports names:
</p>
<div class="example">
<pre class="example"> ...
aout_32_canonicalize_reloc
aout_32_find_nearest_line
aout_32_get_lineno
aout_32_get_reloc_upper_bound
...
</pre></div>
<p>from <samp>sunos.c</samp>:
</p>
<div class="example">
<pre class="example"> #define TARGET_NAME &quot;a.out-sunos-big&quot;
#define VECNAME sparc_aout_sunos_be_vec
#include &quot;aoutf1.h&quot;
</pre></div>
<p>requires all the names from <samp>aout32.c</samp>, and produces the jump vector
</p>
<div class="example">
<pre class="example"> sparc_aout_sunos_be_vec
</pre></div>
<p>The file <samp>host-aout.c</samp> is a special case. It is for a large set
of hosts that use &ldquo;more or less standard&rdquo; a.out files, and
for which cross-debugging is not interesting. It uses the
standard 32-bit a.out support routines, but determines the
file offsets and addresses of the text, data, and BSS
sections, the machine architecture and machine type, and the
entry point address, in a host-dependent manner. Once these
values have been determined, generic code is used to handle
the object file.
</p>
<p>When porting it to run on a new system, you must supply:
</p>
<div class="example">
<pre class="example"> HOST_PAGE_SIZE
HOST_SEGMENT_SIZE
HOST_MACHINE_ARCH (optional)
HOST_MACHINE_MACHINE (optional)
HOST_TEXT_START_ADDR
HOST_STACK_END_ADDR
</pre></div>
<p>in the file <samp>../include/sys/h-<var>XXX</var>.h</samp> (for your host). These
values, plus the structures and macros defined in <samp>a.out.h</samp> on
your host system, will produce a BFD target that will access
ordinary a.out files on your host. To configure a new machine
to use <samp>host-aout.c</samp>, specify:
</p>
<div class="example">
<pre class="example"> TDEFAULTS = -DDEFAULT_VECTOR=host_aout_big_vec
TDEPFILES= host-aout.o trad-core.o
</pre></div>
<p>in the <samp>config/<var>XXX</var>.mt</samp> file, and modify <samp>configure.ac</samp>
to use the
<samp><var>XXX</var>.mt</samp> file (by setting &quot;<code>bfd_target=XXX</code>&quot;) when your
configuration is selected.
</p>
<a name="Relocations-2"></a>
<h4 class="subsection">3.2.1 Relocations</h4>
<p><strong>Description</strong><br>
The file <samp>aoutx.h</samp> provides for both the <em>standard</em>
and <em>extended</em> forms of a.out relocation records.
</p>
<p>The standard records contain only an
address, a symbol index, and a type field. The extended records
(used on 29ks and sparcs) also have a full integer for an
addend.
</p>
<a name="Internal-entry-points"></a>
<h4 class="subsection">3.2.2 Internal entry points</h4>
<p><strong>Description</strong><br>
<samp>aoutx.h</samp> exports several routines for accessing the
contents of an a.out file, which are gathered and exported in
turn by various format specific files (eg sunos.c).
</p>
<a name="index-aout_005fsize_005fswap_005fexec_005fheader_005fin"></a>
<a name="aout_005fsize_005fswap_005fexec_005fheader_005fin"></a>
<h4 class="subsubsection">3.2.2.1 <code>aout_<var>size</var>_swap_exec_header_in</code></h4>
<p><strong>Synopsis</strong>
</p><div class="example">
<pre class="example">void aout_<var>size</var>_swap_exec_header_in,
(bfd *abfd,
struct external_exec *bytes,
struct internal_exec *execp);
</pre></div>
<p><strong>Description</strong><br>
Swap the information in an executable header <var>raw_bytes</var> taken
from a raw byte stream memory image into the internal exec header
structure <var>execp</var>.
</p>
<a name="index-aout_005fsize_005fswap_005fexec_005fheader_005fout"></a>
<a name="aout_005fsize_005fswap_005fexec_005fheader_005fout"></a>
<h4 class="subsubsection">3.2.2.2 <code>aout_<var>size</var>_swap_exec_header_out</code></h4>
<p><strong>Synopsis</strong>
</p><div class="example">
<pre class="example">void aout_<var>size</var>_swap_exec_header_out
(bfd *abfd,
struct internal_exec *execp,
struct external_exec *raw_bytes);
</pre></div>
<p><strong>Description</strong><br>
Swap the information in an internal exec header structure
<var>execp</var> into the buffer <var>raw_bytes</var> ready for writing to disk.
</p>
<a name="index-aout_005fsize_005fsome_005faout_005fobject_005fp"></a>
<a name="aout_005fsize_005fsome_005faout_005fobject_005fp"></a>
<h4 class="subsubsection">3.2.2.3 <code>aout_<var>size</var>_some_aout_object_p</code></h4>
<p><strong>Synopsis</strong>
</p><div class="example">
<pre class="example">const bfd_target *aout_<var>size</var>_some_aout_object_p
(bfd *abfd,
struct internal_exec *execp,
const bfd_target *(*callback_to_real_object_p) (bfd *));
</pre></div>
<p><strong>Description</strong><br>
Some a.out variant thinks that the file open in <var>abfd</var>
checking is an a.out file. Do some more checking, and set up
for access if it really is. Call back to the calling
environment&rsquo;s &quot;finish up&quot; function just before returning, to
handle any last-minute setup.
</p>
<a name="index-aout_005fsize_005fmkobject"></a>
<a name="aout_005fsize_005fmkobject"></a>
<h4 class="subsubsection">3.2.2.4 <code>aout_<var>size</var>_mkobject</code></h4>
<p><strong>Synopsis</strong>
</p><div class="example">
<pre class="example">bfd_boolean aout_<var>size</var>_mkobject, (bfd *abfd);
</pre></div>
<p><strong>Description</strong><br>
Initialize BFD <var>abfd</var> for use with a.out files.
</p>
<a name="index-aout_005fsize_005fmachine_005ftype"></a>
<a name="aout_005fsize_005fmachine_005ftype"></a>
<h4 class="subsubsection">3.2.2.5 <code>aout_<var>size</var>_machine_type</code></h4>
<p><strong>Synopsis</strong>
</p><div class="example">
<pre class="example">enum machine_type aout_<var>size</var>_machine_type
(enum bfd_architecture arch,
unsigned long machine,
bfd_boolean *unknown);
</pre></div>
<p><strong>Description</strong><br>
Keep track of machine architecture and machine type for
a.out&rsquo;s. Return the <code>machine_type</code> for a particular
architecture and machine, or <code>M_UNKNOWN</code> if that exact architecture
and machine can&rsquo;t be represented in a.out format.
</p>
<p>If the architecture is understood, machine type 0 (default)
is always understood.
</p>
<a name="index-aout_005fsize_005fset_005farch_005fmach"></a>
<a name="aout_005fsize_005fset_005farch_005fmach"></a>
<h4 class="subsubsection">3.2.2.6 <code>aout_<var>size</var>_set_arch_mach</code></h4>
<p><strong>Synopsis</strong>
</p><div class="example">
<pre class="example">bfd_boolean aout_<var>size</var>_set_arch_mach,
(bfd *,
enum bfd_architecture arch,
unsigned long machine);
</pre></div>
<p><strong>Description</strong><br>
Set the architecture and the machine of the BFD <var>abfd</var> to the
values <var>arch</var> and <var>machine</var>. Verify that <var>abfd</var>&rsquo;s format
can support the architecture required.
</p>
<a name="index-aout_005fsize_005fnew_005fsection_005fhook"></a>
<a name="aout_005fsize_005fnew_005fsection_005fhook"></a>
<h4 class="subsubsection">3.2.2.7 <code>aout_<var>size</var>_new_section_hook</code></h4>
<p><strong>Synopsis</strong>
</p><div class="example">
<pre class="example">bfd_boolean aout_<var>size</var>_new_section_hook,
(bfd *abfd,
asection *newsect);
</pre></div>
<p><strong>Description</strong><br>
Called by the BFD in response to a <code>bfd_make_section</code>
request.
</p>
<hr>
<div class="header">
<p>
Next: <a href="coff.html#coff" accesskey="n" rel="next">coff</a>, Previous: <a href="What-to-Put-Where.html#What-to-Put-Where" accesskey="p" rel="prev">What to Put Where</a>, Up: <a href="BFD-back-ends.html#BFD-back-ends" accesskey="u" rel="up">BFD back ends</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="BFD-Index.html#BFD-Index" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>