8.6.3 Resolving Symbols with Object Libraries

An object library is a partitioned archive file that contains object files as members. Usually, a group of related modules are grouped together into a library. When you specify an object library as linker input, the linker includes any members of the library that define existing unresolved symbol references. You can use the archiver to build and maintain libraries. Section 7.1 contains more information about the archiver.

Using object libraries can reduce link time and the size of the executable module. Normally, if an object file that contains a function is specified at link time, the file is linked whether the function is used or not; however, if that same function is placed in an archive library, the file is included only if the function is referenced.

The order in which libraries are specified is important, because the linker includes only those members that resolve symbols that are undefined at the time the library is searched. The same library can be specified as often as necessary; it is searched each time it is included. Alternatively, you can use the --reread_libs option to reread libraries until no more references can be resolved (see Section 8.4.15.3). A library has a table that lists all external symbols defined in the library; the linker searches through the table until it determines that it cannot use the library to resolve any more references.

The following examples link several files and libraries, using these assumptions:

• Input files f1.c.obj and f2.c.obj both reference an external function named clrscr.
• Input file f1.c.obj references the symbol origin.
• Input file f2.c.obj references the symbol fillclr.
• Member 0 of library libc.lib contains a definition of origin.
• Member 3 of library liba.lib contains a definition of fillclr.
• Member 1 of both libraries defines clrscr.

If you enter:

then:

• Member 1 of liba.lib satisfies the f1.c.obj and f2.c.obj references to clrscr because the library is searched and the definition of clrscr is found.
• Member 0 of libc.lib satisfies the reference to origin.
• Member 3 of liba.lib satisfies the reference to fillclr.

If, however, you enter:

then the references to clrscr are satisfied by member 1 of libc.lib.

If none of the linked files reference symbols defined in a library, you can use the --undef_sym option to force the linker to include a library member. (See Section 8.4.31.) The next example creates an undefined symbol rout1 in the linker's global symbol table:

If any member of libc.lib defines rout1, the linker includes that member.

Library members are allocated according to the SECTIONS directive default allocation algorithm; see Section 8.5.5.

Section 8.4.15 describes methods for specifying directories that contain object libraries.