NAME

ranlib − add or update the table of contents of archive libraries

SYNOPSIS

ranlib [ −s ] [ −a ] [ −c ] [ −t ] archive ... 

DESCRIPTION

Ranlib adds or updates the table of contents to each archive so it can be linked by the link editor.  The table of contents is a file at the beginning of the archive that indicates which symbols are defined in which library members.  Ranlib rewrites the archive, so that sufficient temporary file space must be available in the file system which contains the current directory. 

The name for a table of contents begins with “__.SYMDEF”. Currently there are two types of table of contents produced by ranlib and understood by the link editor, ld(1).

−s Produced the preferred type of table of contents which results in faster link editing when linking with the archive.  The order of the table of contents is sorted by symbol name.  The library member name of this type of table of contents is “__.SYMDEF SORTED”. This type of table of contents can only be produced when the library does not have multiple members that define the same symbol.  This is the default. 

−a Produce the original type of table of contents who’s order is based on the order of the members in the archive.  The library member name of this type of table of contents is “__.SYMDEF”. This type of table of contents must be used when the library has multiple members that define the same symbol. 

−c Include common symbols as definitions with respect to the table of contents.  This is seldom ever the behavior that is intended for linking from a library as it will force the linking of a library member just because it uses an uninitialized global that is undefined at that point in the linking.  This is only included as an option because this was the original behavior of ranlib.  This is not the default. 

−t Only “touch” the archives and do not modify them.  This is useful after copying an archive or using the −t option of make(1) in order to avoid having ld(1) complain about an “out of date” symbol table.

SEE ALSO

ld(1), ar(1), otool(1), lorder(1), make(1)

BUGS

Because generation of a library by ar and randomization of the library by ranlib are separate processes, phase errors are possible.  The link editor, ld, warns when the modification date of a library is more recent than the creation date of its dictionary;  but this means that you get the warning even if you only copy the library.

The old (NeXT 1.0) version of ranlib will not correctly place the table of contents member “__.SYMDEF” at the beginning of the archive if the archive has had it’s table of contents built with the new ranlib −s option.  This results in the link editor continuing to think the table of contents is out of date no matter how many times the old ranlib is run.  The fix is to remove the “__SYMDEF SORTED” table of contents with ar(1) directly or rebuild the archive. What happens is the table of contents built by ranlib −s is not replaced by the member “__.SYMDEF” because it’s name is “__SYMDEF SORTED” and ranlib uses a different method to detect that the member name is the table of contents than ar(1) which ranlib calls to do the replacement.  This is only a backwards compatibility problem in using an old ranlib on an archive that was processed by the new ranlib. 

7th Edition  —  March 13, 1990