COFF link editor

Using archive libraries

Each member of an archive library is a complete object file. Archive libraries are created with the ar(CP) command from object files generated by cc or as.

Libraries may be searched by the link editor to find definitions for undefined symbols. For a member to be extracted from the library it either must satisfy a reference that is known to be unresolved at the time the library is searched, or has been designated as an undefined symbol through the -u option of ld. Only those members that are required to resolve existing undefined-symbol references are taken from the library for link editing.

Libraries can be placed both inside and outside section definitions. When a library member is included by searching the library inside a SECTIONS directive, all input sections from the library member are included in the output section being defined by that directive. When a library member is included by searching the library outside of a SECTIONS directive, all input sections from the library member are included in an output section with the same name as that input section. If necessary, new output sections are defined to provide a place to put the input sections. Note, however, the following:

specific members of a library cannot be referenced explicitly in an ld directive
the default rules for the placement of members and sections cannot be overridden when they apply to archive library members

The -l option

The -l option to ld is used to link with an input file coming from a predefined set of directories and having a predefined name. Such files are usually archive libraries, however, they don't have to be. Furthermore, archive libraries can be specified without using the -l option by simply giving the full or relative UNIX system file path.

An option of the form -lx, where x is a string of up to nine characters, will cause a library with filename libx.a, located in the directory /lib, to be searched. The effect of this option is the same as if the library file name was substituted for the option on the command line.

The ordering of archive libraries is important since the library must be searched after the unresolved symbol reference is encountered. Archive libraries can be specified more than once, and they are searched every time they are encountered. Archive files have a symbol table at the beginning. If the definition that the library provides for a symbol gives rise to more undefined symbols, ld will cycle through the symbol table until it has determined that it cannot resolve any more references from the current library.

Consider the following example involving two input files, file1.o and file2.o:

The input files file1.o and file2.o each contain a reference to the external function FCN.
Input file1.o contains a reference to symbol ABC.
Input file2.o contains a reference to symbol XYZ.
Library liba.a, member 0, contains a definition of XYZ.
Library libc.a, member 0, contains a definition of ABC.
Both libraries have a member 1 that defines FCN.

The following ld command line will cause the FCN references to be satisfied by liba.a, member 1, ABC to be obtained from libc.a, member 0, and XYZ to remain undefined:

   ld  file1.o  -la  file2.o  -lc

When file1.o is processed by ld, references to ABC and FCN are encountered. The -la option causes liba.a to be searched, and the unresolved references are satisfied by definitions in that library. When file2.o is processed, references to FCN and XYZ are encountered. A definition for FCN has already been found, and hence this definition (from liba.a) resolves the reference. The -lc option causes libc.a to be searched. The reference to XYZ cannot be resolved from libc.a because there is no definition of that symbol in the library. There is a definition of XYZ in liba.a but that definition cannot be obtained at this point, because ld did not know at the time it was searching liba.a that there would be an unresolved reference to XYZ.

The following command line will allow the reference to XYZ to be resolved by the definition of that symbol in member 0 of the library liba.a. This is possible because the -la option appears to the right of the filename file2.o. ld processes the file file2.o and encounters the unresolved reference to XYZ; when it searches the library liba.a it knows that it must resolve that reference and hence obtains the definition from the library. The other references are resolved as in the previous example.

   ld  file1.o  file2.o  -la  -lc

With the following command line, the FCN references are satisfied by libc.a, member 1, ABC is obtained from libc.a, member 0, and XYZ is obtained from liba.a, member 0.

   ld  file1.o  file2.o  -lc  -la

The -u option

The -u option is used to force the linking of a library member that contains a definition of a symbol even if none of the source files contain an unresolved reference to that symbol. As is done in the next example, this option may also be used without any source files to extract a member from a library.

The following command line creates an undefined symbol called rout1 in ld's global symbol table. If any member of library liba.a defines this symbol, that member is extracted. Without the -u option, there would have been no unresolved references or undefined symbols to cause ld to search the archive library. Note that the -u option must appear on the command line before the library that you want to link a member from.

   ld  -u rout1 -la