bfd: Adding symbols from an archive
2.17.2.3 Adding symbols from an archive
.......................................
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.
(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.)
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.
'_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.
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
element's 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 - possibly those of a
substitute BFD, if the 'add_archive_element' callback avails itself of
that option.
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.