ar —
archive
file format for ar(1) and
ranlib(1)
#include <ar.h>
ar(1) archives are created and
managed by the
ar(1) and
ranlib(1) utilities. These
archives are typically used during program development to hold libraries of
program objects. An
ar(1)
archive is contained in a single operating system file.
This manual page documents two variants of the
ar(1) archive format: the BSD
archive format, and the SVR4/GNU archive format.
In both variants the archive file starts with an identifying byte sequence of
the seven ASCII characters
‘
!<arch>
’ followed by a ASCII
linefeed character (see the constant “ARMAG” in the header file
<ar.h>).
Archive members follow the initial identifying byte sequence. Each archive
member is prefixed by a fixed size header describing the file attributes
associated with the member.
An archive header describes the file attributes for the archive member that
follows it. The
ar(5) format
only supports a limited number of attributes: the file name, the file creation
time stamp, the uid and gid of the creator, the file mode and the file size.
Archive headers are placed at an even byte offset in the archive file. If the
data for an archive member ends at an odd byte offset, then a padding byte
with value 0x0A is used to position the next archive header on an even byte
offset.
An archive header comprises the following fixed sized fields:
-
-
- ar_name
- (16 bytes) The file name of the archive member. This field
names a leaf file; absolute paths and relative paths containing directory
names are not supported. The format of this field varies between the BSD
and SVR4/GNU formats and is described in more detail in the section
Representing File
Names below.
-
-
- ar_date
- (12 bytes) The file modification time for the member in
seconds since the epoch, encoded as a decimal number.
-
-
- ar_uid
- (6 bytes) The uid associated with the archive member,
encoded as a decimal number.
-
-
- ar_gid
- (6 bytes) The gid associated with the archive member,
encoded as a decimal number.
-
-
- ar_mode
- (8 bytes) The file mode for the archive member, encoded as
an octal number.
-
-
- ar_size
- (10 bytes) In the SVR4/GNU archive format this field holds
the size in bytes of the archive member, encoded as a decimal number. In
the BSD archive format, for short file names, this field holds the size in
bytes of the archive member, encoded as a decimal number. For long file
names (see
Representing File
Names below), the field contains the combined size of the archive
member and its file name, encoded as a decimal number.
-
-
- ar_fmag
- (2 bytes) This field holds 2 bytes with values 0x96 and
0x0A respectively, marking the end of the header.
Unused bytes in the fields of an archive header are set to the value 0x20.
The BSD and SVR4/GNU variants use different schemes for encoding file names for
members.
-
-
- BSD
- File names that are up to 16 bytes long and which do not
contain embedded spaces are stored directly in the
ar_name field of the archive header. File
names that are either longer than 16 bytes or which contain embedded
spaces are stored immediately after the archive header and the
ar_name field of the archive header is
set to the string “#1/” followed by a decimal representation
of the number of bytes needed for the file name. In addition, the
ar_size field of the archive header is
set to the decimal representation of the combined sizes of the archive
member and the file name. The file contents of the member follows the file
name without further padding.
As an example, if the file name for a member was “A B” and its
contents was the string “C D”, then the
ar_name field of the header would contain
“
#1/3
”, the
ar_size field of the header would contain
“6
”, and the bytes immediately
following the header would be 0x41, 0x20, 0x42, 0x43, 0x20 and 0x44 (ASCII
“A BC D”).
-
-
- SVR4/GNU
- File names that are up to 15 characters long are stored
directly in the ar_name field of the
header, terminated by a “
/
”
character.
If the file name is larger than would fit in space for the
ar_name field, then the actual file name
is kept in the archive string table (see
Archive String
Tables below), and the decimal offset of the file name in the string
table is stored in the ar_name field,
prefixed by a “/
” character.
As an example, if the real file name has been stored at offset 768 in the
archive string table, the ar_name field
of the header will contain the string “/768”.
The following archive members are special.
-
-
- “
/
”
- In the SVR4/GNU variant of the archive format, the archive
member with name “
/
” denotes an
archive symbol table. If present, this member will be the very first
member in the archive.
-
-
- “
//
”
- In the SVR4/GNU variant of the archive format, the archive
member with name “
//
” denotes the
archive string table. This special member is used to hold filenames that
do not fit in the file name field of the header (see
Representing File
Names above). If present, this member immediately follows the archive
symbol table if an archive symbol table is present, or is the first member
otherwise.
-
-
- “
__.SYMDEF
”
- This special member contains the archive symbol table in
the BSD variant of the archive format. If present, this member will be the
very first member in the archive.
An archive string table is used in the SVR4/GNU archive format to hold file
names that are too large to fit into the constraints of the
ar_name field of the archive header. An
archive string table contains a sequence of file names. Each file name in the
archive string table is terminated by the byte sequence 0x2F, 0x0A (the ASCII
string “/\n”). No padding is used to separate adjacent file
names.
Archive symbol tables are used to speed up link editing by providing a mapping
between the program symbols defined in the archive and the corresponding
archive members. Archive symbol tables are managed by the
ranlib(1) utility.
The format of archive symbol tables is as follows:
-
-
- BSD
- In the BSD archive format, the archive symbol table
comprises of two parts: a part containing an array of
struct ranlib descriptors, followed by a
part containing a symbol string table. The sizes and layout of the
structures that make up a BSD format archive symbol table are machine
dependent.
The part containing struct ranlib
descriptors begins with a field containing the size in bytes of the array
of struct ranlib descriptors encoded as a
C long value.
The array of struct ranlib descriptors
follows the size field. Each struct
ranlib descriptor describes one symbol.
A struct ranlib descriptor comprises two
fields:
- ran_strx
- (C long) This field
contains the zero-based offset of the symbol name in the symbol string
table.
- ran_off
- (C long) This field is
the file offset to the archive header for the archive member defining
the symbol.
The part containing the symbol string table begins with a field containing
the size in bytes of the string table, encoded as a C
long value. This string table follows the
size field, and contains NUL-terminated strings for the symbols in the
symbol table.
-
-
- SVR4/GNU
- In the SVR4/GNU archive format, the archive symbol table
starts with a 4-byte binary value containing the number of entries
contained in the archive symbol table. This count of entries is stored
most significant byte first.
Next, there are count 4-byte numbers, each
stored most significant byte first. Each number is a binary offset to the
archive header for the member in the archive file for the corresponding
symbol table entry.
After the binary offset values, there are
count NUL-terminated strings in sequence,
holding the symbol names for the corresponding symbol table entries.
The
ar(1) archive format is not
currently specified by a standard.
This manual page documents the
ar(1) archive formats used by
the
4.4BSD and
UNIX SVR4
operating system releases.
ar(1),
ld(1),
ranlib(1),
elf(3),
elf_getarsym(3),
elf_rand(3)