AR(5) FreeBSD File Formats Manual AR(5)
NAME
ar - archive file format for ar(1) and ranlib(1)
SYNOPSIS
#include <ar.h>
DESCRIPTION
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.
Archive Headers
An archive header describes the file attributes for the archive member
that follows it. The ar 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. 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.
Representing File Names
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".
Special Archive Members
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.
Archive String Tables
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
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.
STANDARDS COMPLIANCE
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.
SEE ALSO
ar(1), ld(1), ranlib(1), elf(3), elf_getarsym(3), elf_rand(3)
FreeBSD 13.1-RELEASE-p6 November 28, 2010 FreeBSD 13.1-RELEASE-p6
man2web Home...