When the _bfd_link_add_symbols 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
add_archive_element linker callback, and it must add the
symbols from the object file to the linker hash table.
In most cases the work of looking through the symbols in the
archive should be done by the
_bfd_generic_link_add_archive_symbols 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.
_bfd_generic_link_add_archive_symbols 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.
The function passed to
_bfd_generic_link_add_archive_symbols 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 add_archive_element linker callback
routine must be called with the element as an argument, and
the elements symbols must be added to the linker hash table
just as though the element had itself been passed to the
_bfd_link_add_symbols function.
When the a.out _bfd_link_add_symbols function receives an
archive, it calls _bfd_generic_link_add_archive_symbols
passing aout_link_check_archive_element as the function
argument. aout_link_check_archive_element calls
aout_link_check_ar_symbols. 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 add_archive_element callback and then
aout_link_check_archive_element calls
aout_link_add_symbols to actually add the symbols to the
linker hash table.
The ECOFF back end is unusual in that it does not normally
call _bfd_generic_link_add_archive_symbols, 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.