A little over a year ago, we received a question from someone who
was trying to build software on Solaris. He was getting errors
from the ar command when creating an archive. At that time, the ar
command on Solaris was a 32-bit command. There was more than
2GB of data, and the ar command was hitting the file size
limit
for a 32-bit process that doesn't use the largefile APIs.
Even in 2011, 2GB is a very large amount of code, so we had not heard
this one before. Most of our toolchain was extended
to handle 64-bit sized data back in the 1990's, but archives were not changed,
presumably because there was no perceived need for it. Since then of course,
programs have continued to get larger, and in 2010, the time had finally come
to investigate the issue and find a way to provide for larger archives.
As part of that process, I had to do a deep dive into the archive
format, and also do some Unix archeology. I'm going to record what I
learned here, to document what Solaris does,
and in the hope that it might help someone else trying to solve the same
problem for their platform.
Archive Format Details
Archives are hardly cutting edge technology. They are still used of
course, but their basic form hasn't changed in decades. Other than to
fix a bug, which is rare, we don't tend to touch that code
much. The archive file format is described in /usr/include/ar.h,
and I won't repeat the
details here. Instead, here is a rough overview of the archive file format,
implemented by System V Release 4 (SVR4) Unix systems such as Solaris:
Every archive starts with a "magic number". This is a sequence
of 8 characters: "!<arch>\n".
The magic number is followed by 1 or more members. A
member starts with a fixed header, defined by the
ar_hdr structure in/usr/include/ar.h.
Immediately following the header comes the
data for the member. Members must be padded at the end with newline
characters so that they have even length.
The requirement to pad members to an even length is a dead giveaway
as to the age of the archive format. It tells you that this format
dates from the 1970's, and more specifically from the era of 16-bit
systems such as the PDP-11 that Unix was originally developed on.
A 32-bit system would have required 4 bytes, and 64-bit systems
such as we use today would probably have required 8 bytes.
2 byte alignment is a poor choice for ELF object archive members.
32-bit objects require 4 byte alignment, and 64-bit objects require
64-bit alignment. The link-editor uses mmap() to process
archives, and if the members have the wrong alignment, we have to
slide (copy) them to the correct alignment
before we can access the ELF data structures inside. The archive
format requires 2 byte padding, but it doesn't prohibit more.
The Solaris ar command takes advantage of this, and pads ELF
object members to 8 byte boundaries. Anything else is padded to 2
as required by the format.
The archive header (ar_hdr) represents all numeric
values using an ASCII text representation rather than as binary
integers. This
means that an archive that contains only text members can be viewed
using tools such as cat, more, or a text
editor. The original designers of this format clearly thought
that archives would be used for many file types, and not just for
objects. Things didn't turn out that way of course
— nearly all
archives contain relocatable objects for a single operating system
and machine, and are used primarily as input to the link-editor (ld).
Archives can have special members that are created by
the ar command rather than being
supplied by the user. These special members
are all distinguished by having a name that starts with the slash (/)
character. This is an unambiguous marker that says that the user could
not have supplied it. The reason for this is that regular archive members
are given the plain name of the file that was inserted to create them,
and any path components are stripped off. Slash is the delimiter
character used by Unix to separate path components, and as such
cannot occur within a plain file name.
The ar command hides
the special members from you when you list the contents of an archive,
so most users don't know that they exist.
There are only two possible special members: A symbol table that maps
ELF symbols to the object
archive member that provides it, and a string table used to hold
member names that exceed 15 characters. The '/' convention for tagging
special members provides room for adding more such members should the
need arise. As I will discuss below, we took advantage of this fact
to add an alternate 64-bit symbol table special member which is used in
archives that are larger than 4GB.
When an archive contains ELF object members, the ar command builds
a special archive member known as the symbol table that
maps all ELF symbols in the object to the archive member that provides
it. The link-editor uses this symbol table to determine which symbols
are provided by the objects in that archive.
If an archive has a symbol table, it will always be the first
member in the archive, immediately following the magic number. Unlike
member headers, symbol tables do use binary integers to represent
offsets. These integers are always stored in big-endian format,
even on a little endian host such as x86.
The archive header (ar_hdr) provides 15 characters for representing
the member name. If any member has a name that is longer than this,
then the real name is written into a special archive member called
the string table, and the member's name field instead
contains a slash (/) character followed by a decimal representation of
the offset of the real name within the string table.
The string table is required to precede all normal archive members,
so it will be the second member if the archive contains a symbol
table, and the first member otherwise.
The archive format is not designed to make finding a given
member easy. Such operations move through the archive from front
to back examining each member in turn, and run in O(n) time. This would be
bad if archives were commonly used in that manner, but in general,
they are not.
Typically, the ar command is used to build an new archive from
scratch, inserting all the objects in one operation, and then the
link-editor accesses the members in the archive in constant time
by using the offsets provided by the symbol table. Both
of these operations are reasonably efficient. However, listing the contents
of a large archive with the ar
command can be rather slow.
Factors That
Limit Solaris Archive Size
As is often the case, there was more than one limiting factor
preventing Solaris archives from growing beyond the 32-bit limits
of 2GB (32-bit signed) and 4GB (32-bit unsigned). These limits are listed
in the order they are hit as archive size grows, so the earlier ones
mask those that follow.
The original Solaris archive file format can handle sizes up to 4GB
without issue. However, the ar command was delivered as a
32-bit executable that did
not use the largefile APIs. As such, the ar command itself could
not create a file larger than 2GB. One can solve this by
building ar with the largefile APIs which would allow it to
reach 4GB, but a simpler and better answer is to deliver a 64-bit
ar, which has the ability to scale well past 4GB.
Symbol table offsets are stored as 32-bit big-endian
binary integers, which limits the maximum archive size
to 4GB. To get around
this
limit requires a different symbol table format, or
an extension mechanism to the current one, similar in nature to
the way member names longer than 15 characters are handled in
member headers.
The size field in the archive member header (ar_hdr)
is an ASCII string capable of representing a 32-bit unsigned
value. This places a 4GB size
limit on the size of any individual
member in an archive.
In considering format extensions to get past these limits, it is
important to remember that very few archives will require
the ability to scale past 4GB for many years. The old format, while
no beauty, continues to be sufficient for its purpose. This argues for
a backward compatible fix that allows newer versions of Solaris to
produce archives that are compatible with older versions of the system
unless the size of the archive exceeds 4GB.
Archive Format Differences Among Unix Variants
While considering how to extend Solaris archives to scale to 64-bits,
I wanted to know how similar archives from other Unix systems
are to those produced by Solaris, and whether they had already
solved the 64-bit issue. I've successfully moved archives between
different Unix systems before with
good luck, so I knew that there was some commonality. If it
turned out that there was already a viable defacto standard for 64-bit archives,
it would obviously be better to adopt that rather than invent something new.
The archive file format is not formally standardized. However, the
ar command and archive format were part of the original Unix
from Bell Labs. Other systems started with that format, extending it in various
often incompatible ways, but usually with the same common shared core. Most of
these systems use the same magic number to identify their archives, despite
the fact that their archives are not always fully compatible with each other.
It is often true that archives can be copied between different
Unix variants, and if the member names are short enough, the ar command from
one system can often read archives produced on another.
In practice,
it is rare to find an archive containing anything other than objects for
a single operating system and machine type. Such an archive is only of
use on the type of system that created it, and is only used on that system.
This is probably why cross platform compatibility of archives between Unix
variants has never been an issue. Otherwise, the use of the same
magic number in archives with incompatible formats would be a problem.
I was able to find information for a number of
Unix variants, described below. These can be divided roughly into three
tribes, SVR4 Unix, BSD Unix, and IBM AIX. Solaris is a SVR4 Unix, and its
archives are completely compatible with those from the other members
of that group (GNU/Linux, HP-UX, and SGI IRIX).
AIX
AIX is an exception to rule that Unix archive formats are all
based on the original Bell labs Unix format. It appears that AIX
supports 2 formats (small and big), both of which differ in
fundamental ways from other Unix systems:
These formats use a different magic number than the standard
one used by Solaris and other Unix variants.
They include support for removing archive members from
a file without reallocating the file, marking dead areas as
unused, and reusing them when new archive items are inserted.
They have a special table of contents member (File Member Header)
which lets you find out everything that's in the archive
without having to actually traverse the entire file. Their symbol
table members are quite similar to those from other systems though.
Their member headers are doubly linked, containing offsets to
both the previous and next members.
Of the Unix systems described here, AIX has the only format I saw
that will have reasonable insert/delete performance for really large
archives. Everyone else has O(n) performance, and are going to be
slow to use with large archives.
BSD
BSD has gone through 4 versions of archive format, which are
described in their
manpage. They use the same member header as SVR4, but their symbol table
format is different, and their scheme for long member
names puts the name directly after the member header rather than into
a string table.
GNU/Linux
The GNU toolchain uses the SVR4 format, and is compatible with
Solaris.
HP-UX
HP-UX seems to follow the SVR4 model, and is compatible with
Solaris.
IRIX
IRIX has 32 and 64-bit archives. The 32-bit format is the
standard SVR4 format, and is compatible with Solaris. The 64-bit format
is the same, except that the symbol table uses
64-bit integers.
IRIX assumes that an archive
contains objects of a single ELFCLASS/MACHINE, and any archive containing
ELFCLASS64 objects receives a 64-bit symbol table. Although they only use
it for 64-bit objects, nothing in the archive format limits it
to ELFCLASS64. It would be perfectly valid to produce a 64-bit
symbol table in an archive containing 32-bit objects, text files, or
anything else.
Tru64 Unix (Digital/Compaq/HP)
Tru64 Unix uses a format much like ours, but their symbol table is
a hash table, making specific symbol lookup much faster. The Solaris
link-editor uses archives by examining the entire
symbol table looking for unsatisfied symbols for the link, and not
by looking up individual symbols, so there would be no benefit to
Solaris from such a hash table. The
Tru64 ld must use a different approach in which the hash table pays
off for them.
Widening the existing SVR4 archive symbol tables rather than inventing something
new is the simplest path forward. There is ample precedent for this
approach in the ELF world. When ELF was extended to support 64-bit objects,
the approach was largely to take the existing data structures, and define
64-bit versions of them. We called the old set ELF32, and the new set ELF64.
My guess is that there was no need to widen the archive format at that time,
but had there been, it seems obvious that this is
how it would have been done.
The Implementation of 64-bit Solaris Archives
As mentioned earlier, there was no desire to improve the fundamental
nature of archives. They have always had O(n) insert/delete behavior, and
for the most part it hasn't mattered. AIX made efforts to improve this,
but those efforts did not find widespread
adoption. For the purposes of link-editing, which is essentially the
only thing that archives
are used for, the existing format is adequate, and issues of backward
compatibility trump the desire to do something technically better.
Widening the existing symbol table format to 64-bits is therefore the
obvious way to proceed. For Solaris 11, I implemented that,
and I also updated the ar command so that a 64-bit
version is run by default. This eliminates the 2 most significant limits
to archive size, leaving only the
limit on an individual archive member.
We only generate
a 64-bit symbol table if the archive exceeds 4GB, or when the new -S
option
to the ar command is used. This maximizes backward compatibility, as an
archive produced by Solaris 11 is highly likely to be less than 4GB in
size, and will therefore employ the same format understood by
older versions of the
system. The main reason for the existence of the -S option is to allow
us to test the 64-bit format without having to construct huge archives to
do so. I don't believe it will find much use outside of that.
Other than the new ability to create and use extremely large archives,
this change is largely invisible to the end user. When reading an
archive, the ar command will transparently accept either form of symbol table.
Similarly, the ELF library (libelf) has been updated to understand
either format. Users of libelf (such as the link-editor ld) do not need
to be modified to use the new format, because these changes are encapsulated
behind the existing functions provided by libelf.
As mentioned above, this work did not lift the
limit on the
maximum size of an individual archive member. That
limit remains fixed
at 4GB for now. This is not because we think objects will never get that
large, for the history of computing says otherwise. Rather, this is based
on an estimation that single relocatable objects of that size will not
appear for a decade or two. A lot can change in that time, and it is better not
to overengineer things by writing code that will sit and rot for years
without being used.
It is not too soon however to have a plan for that eventuality. When
the time comes when this
limit needs to be lifted, I believe that there
is a simple solution that is consistent with the existing format.
The archive member header size field is an ASCII string, like the name,
and as such, the overflow scheme used for long names can also be used to
handle the size. The size string would be placed into the archive string
table, and its offset in the string table would then be written into the
archive header size field using the same format "/ddd" used for overflowed
names.
