##### 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. 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 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. The `add_archive_element` 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.

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.