<!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 - 2013 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: Adding symbols from an archive</title>

<meta name="description" content="Untitled Document: Adding symbols from an archive">
<meta name="keywords" content="Untitled Document: Adding symbols from an archive">
<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="Adding-Symbols-to-the-Hash-Table.html#Adding-Symbols-to-the-Hash-Table" rel="up" title="Adding Symbols to the Hash Table">
<link href="Performing-the-Final-Link.html#Performing-the-Final-Link" rel="next" title="Performing the Final Link">
<link href="Adding-symbols-from-an-object-file.html#Adding-symbols-from-an-object-file" rel="prev" title="Adding symbols from an object file">
<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="Adding-symbols-from-an-archive"></a>
<div class="header">
<p>
Previous: <a href="Adding-symbols-from-an-object-file.html#Adding-symbols-from-an-object-file" accesskey="p" rel="prev">Adding symbols from an object file</a>, Up: <a href="Adding-Symbols-to-the-Hash-Table.html#Adding-Symbols-to-the-Hash-Table" accesskey="u" rel="up">Adding Symbols to the Hash Table</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="Adding-symbols-from-an-archive-1"></a>
<h4 class="subsubsection">2.17.2.3 Adding symbols from an archive</h4>
<p>When the <code>_bfd_link_add_symbols</code> routine is passed an
archive, it must look through the symbols defined by the
archive and decide which elements of the archive should be
included in the link.  For each such element it must call the
<code>add_archive_element</code> linker callback, and it must add the
symbols from the object file to the linker hash table.  (The
callback may in fact indicate that a replacement BFD should be
used, in which case the symbols from that BFD should be added
to the linker hash table instead.)
</p>
<a name="index-_005fbfd_005fgeneric_005flink_005fadd_005farchive_005fsymbols"></a>
<p>In most cases the work of looking through the symbols in the
archive should be done by the
<code>_bfd_generic_link_add_archive_symbols</code> function.  This
function builds a hash table from the archive symbol table and
looks through the list of undefined symbols to see which
elements should be included.
<code>_bfd_generic_link_add_archive_symbols</code> is passed a function
to call to make the final decision about adding an archive
element to the link and to do the actual work of adding the
symbols to the linker hash table.
</p>
<p>The function passed to
<code>_bfd_generic_link_add_archive_symbols</code> must read the
symbols of the archive element and decide whether the archive
element should be included in the link.  If the element is to
be included, the <code>add_archive_element</code> linker callback
routine must be called with the element as an argument, and
the element&rsquo;s symbols must be added to the linker hash table
just as though the element had itself been passed to the
<code>_bfd_link_add_symbols</code> function.  The <code>add_archive_element</code>
callback has the option to indicate that it would like to
replace the element archive with a substitute BFD, in which
case it is the symbols of that substitute BFD that must be
added to the linker hash table instead.
</p>
<p>When the a.out <code>_bfd_link_add_symbols</code> function receives an
archive, it calls <code>_bfd_generic_link_add_archive_symbols</code>
passing <code>aout_link_check_archive_element</code> as the function
argument. <code>aout_link_check_archive_element</code> calls
<code>aout_link_check_ar_symbols</code>.  If the latter decides to add
the element (an element is only added if it provides a real,
non-common, definition for a previously undefined or common
symbol) it calls the <code>add_archive_element</code> callback and then
<code>aout_link_check_archive_element</code> calls
<code>aout_link_add_symbols</code> to actually add the symbols to the
linker hash table - possibly those of a substitute BFD, if the
<code>add_archive_element</code> callback avails itself of that option.
</p>
<p>The ECOFF back end is unusual in that it does not normally
call <code>_bfd_generic_link_add_archive_symbols</code>, because ECOFF
archives already contain a hash table of symbols.  The ECOFF
back end searches the archive itself to avoid the overhead of
creating a new hash table.
</p>
<hr>
<div class="header">
<p>
Previous: <a href="Adding-symbols-from-an-object-file.html#Adding-symbols-from-an-object-file" accesskey="p" rel="prev">Adding symbols from an object file</a>, Up: <a href="Adding-Symbols-to-the-Hash-Table.html#Adding-Symbols-to-the-Hash-Table" accesskey="u" rel="up">Adding Symbols to the Hash Table</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>