Jump to content

ar (Unix)

From Wikipedia, the free encyclopedia
ar
Original authorsKen Thompson,
Dennis Ritchie
(AT&T Bell Laboratories)
DevelopersVarious open-source and commercial developers
ReleaseNovember 3, 1971; 54 years ago (1971-11-03)
Written inC
Operating systemUnix, Unix-like, V, Plan 9, Inferno
PlatformCross-platform
TypeCommand
LicensePlan 9: MIT License
archiver format
Filename extension
.a, .lib, .ar[1]
Internet media type
application/x-archive[1]
Magic number!<arch>
Type of formatarchive format
Container forusually object files (.o)
StandardNot standardized, several variants exist
Open format?Yes[2]

ar, short for archiver, is a shell command for maintaining multiple files as a single archive file (i.e. a file archiver). It is often used to create and update static library files that the link editor or linker uses and for generating deb format packages for the Debian Linux distribution. It can be used to create archives for any purpose, but has been largely replaced by tar for purposes other than static libraries.[3]

Originally developed for Unix, the command is widely available on Unix-based systems, and similar commands are available on other platforms. An implementation is included in GNU Binutils.[2]

File format

[edit]
Diagram showing an example file structure of a .deb file

The format of a file that results from using ar has never been standardized, though most variations were documented through the manual page ar(5) or at least the header file ar.h.[4][5]

  1. The first format appeared in the first edition of Unix[6] and was used through Version 6 Unix.[7] It had a magic number of ED FF (0177555).[4] Version 7 Unix had a modified version of that format,[8][4] which was also used in UNIX System III[9] and in UNIX System V on the PDP-11.[10]

A new format was introduced in the first release of System V on processors other than PDP-11s.[11] This format had a magic number of 0177545.[4]

Modern archives are, on most systems, based on a common format with two main variants, BSD[4] (initially used for a.out files) and UNIX System V release 2 and later[12] (initially used for COFF files and later used for ELF files) and used as well by GNU[13][14] and Windows.

AIX has its own formats (small[15] and big[16]), as does Coherent; those formats vary significantly from the common format. In addition to the usual per-entry header, AIX formats include a global header that together enables handling the archive as a doubly-linked list.[17]

Structure

[edit]

An archive file begins with a header that identifies the file type and is followed with a section for each contained file. Each contained file section consists of a header followed by the file content. The headers consist solely of printable ASCII characters and line feeds. In fact, an archive containing only text files is also a text file.

The content of a contained file begins on an even byte boundary. A newline is inserted between files as padding, if necessary. Nevertheless, the size stored reflects the size excluding padding.[18]

Archive header

[edit]

The first header, a.k.a. file signature, is a magic number that encodes the ASCII string !<arch> followed by a single line feed character (0x0A).

Contained file header

[edit]

Each file is preceded by a header that contains information about the file. The common format is as follows. Numeric values are encoded in ASCII and all values are right-padded with spaces (0x20).

Offset Length Content Format
0 16 File identifier ASCII
16 12 File modification timestamp (in seconds) Decimal
28 6 Owner ID Decimal
34 6 Group ID Decimal
40 8 File mode (type and permission) Octal
48 10 File size in bytes Decimal
58 2 Ending characters 0x60 0x0A

Variants

[edit]

Variants of the command were developed to address issues including:

File name length limitation
The BSD and System V/GNU variants devised different methods of storing long or "extended" file names (beyond the 15 or 16-character limit).
Global symbol table
Many implementations include a global symbol table (a.k.a. armap, directory or index) for fast linking without needing to scan the whole archive for a symbol. POSIX recognizes this feature, and requires implementations to have an -s option for updating it. Most implementations put it at the first file entry.[19]
Year 2038 problem
Although the common format is not at risk of this problem, many implementations are vulnerable to failure in that year due to how they parse the time entry. The entry itself would max out at 999,999,999,999, which would implay to a much later year-33658 problem.

BSD

[edit]

With the standard name field, the 4.0BSD implementation stores file names right-padded with ASCII spaces (0x20). Only file names that are up to 16 bytes long and contains no spaces are put in the standard field. For all other file names, it places the string "#1/" followed by the file name length (decimal) in the standard name field, then stores the real file name in front of the data section.[4][14]

The BSD implementation traditionally does not handle the building of a global symbol lookup table, and delegates this task to a separate utility, ranlib,[20] which inserts an architecture-specific[a] file named __.SYMDEF as first archive member.[21] Some descendants put a space and "SORTED" after the name to indicate a sorted version.[22] A 64-bit variant called __.SYMDEF_64 exists on Darwin.

To conform to POSIX, newer BSD implementations support the -s option instead of ranlib. FreeBSD in particular ditched the SYMDEF table format and embraced the System V style table.[14]

SysV/GNU

[edit]

To allow spaces in file names, the System V Revision 2 (SVR2) implementation uses a slash ('/') to mark the end of the file. This limits the file name to 15 chars. Filenames longer than 15 ASCII chars are replaced by an index, represented by a slash ('/') followed by the decimal character offset in the indexfile (also called the "archive stream table), pointing to the location of the start of the name (for example, /768 refers to a name that starts at offset 768 in the index file.) Adopted by many non-BSD Unixes and GNU, this format is called "SVR4/GNU" by BSD documentations.[14]

The index file is named "//". CityPopulation.de. Citing: {{{3}}}. 

and is usually the second entry of the archive, after the symbol table which always is the first. The format of this // file itself is simply a list of the long file names, separated by the sequence /\n LF (0x2F 0x10).[14]

The SVR4/GNU format uses the special file name "/" to denote that the following data entry contains a symbol lookup table, which is used in ar libraries[clarification needed] to speed up access. This symbol table is built in three parts which are recorded together as contiguous data.

  1. A 32-bit big endian integer, giving the number of entries in the table.
  2. A set of 32-bit big endian integers. One for each symbol, recording the position within the archive of the header for the file containing this symbol.
  3. A set of Zero-terminated strings. Each is a symbol name, and occurs in the same order as the list of positions in part 2.

The special file "/" is not terminated with a specific sequence; the end is assumed once the last symbol name has been read, which can be known from either the string count or the ar_size file size entry.

To overcome the 4 GiB table size limit implied by the use of 32-bit integers, some operating system like Solaris 11.2 and GNU use a variant lookup table. Instead of 32-bit integers, 64-bit integers are used in the symbol lookup tables. The string "/SYM64/" instead "/" is used as identifier for this table[23]

Some System V-derived systems do not use the above format. For HP-UX 11.0, this information is stored in a data structure based on the SOM file format (earlier HP-UX are known to use the SVR4 format). For Tru64 Unix, the symbol table is instead a hash table.[17]

Windows

[edit]

The Windows variant is based on the SysV/GNU variant. The first entry "/" has the same layout as the SVR4/GNU symbol table. The second entry is another "/", a Microsoft extension that stores an extended symbol cross-reference table. This one is sorted and uses little-endian integers.[5][24] The third entry is the optional "//" long name data as in SysV/GNU.[25]

The object files within are ordinary PE/COFF object files. The file extension is usually .lib and a LIB.EXE is provided to manipulate these files.

Thin archive

[edit]

The GNU binutils and Elfutils implementations have an additional "thin archive" format with the magic number !<thin>. A thin archive only contains a symbol table and references to the file. The file format is essentially a System V format archive where every file is stored without the data sections. Every file name is stored as a "long" file name and they are to be resolved as if they were symbolic links.[26]

Examples

[edit]

The following command creates an archive libclass.a with object files class1.o, class2.o, class3.o:

ar rcs libclass.a class1.o class2.o class3.o

The linker ld can read object code from an archive file. The following example shows how the archive libclass.a (specified as -lclass) is linked with the object code of main.o.

ld main.o -lclass

See also

[edit]

Notes

[edit]
  1. ↑ In that it is based on the architecture's long data type, which may vary by size and endianness. On most x86 and x86-64 systems, long is 32 bits, which imposes a 2 GiB size limit.

References

[edit]
  1. 1 2 "application/x-archive". Archived from the original on 2019-12-08. Retrieved 2019-03-11.
  2. 1 2 "ar(1) – Linux man page". Archived from the original on 12 February 2019. Retrieved 3 October 2013.
  3. ↑ "Static Libraries". TLDP. Archived from the original on 3 July 2013. Retrieved 3 October 2013.
  4. 1 2 3 4 5 6 "Manual page for NET/2 ar file format". Archived from the original on 2017-08-22. Retrieved 2014-08-23.
  5. 1 2 Levine, John R. (2000) [October 1999]. "Chapter 6: Libraries". Linkers and Loaders. The Morgan Kaufmann Series in Software Engineering and Programming (1 ed.). San Francisco, USA: Morgan Kaufmann. ISBN 1-55860-496-0. OCLC 42413382. Retrieved 2020-01-12.{{cite book}}: CS1 maint: deprecated archival service (link) Code: [dead link] Errata:
  6. ↑ "archive(5) - Unix First Edition Manual Page". Archived from the original on 2025-06-10. Retrieved 2025-11-14.
  7. ↑ "archive page from Section 5 of the unix-6th manual". Archived from the original on 2025-06-10. Retrieved 2025-11-14.
  8. ↑ "V7/usr/include/ar.h". Archived from the original on 2025-12-30. Retrieved 2025-11-14.
  9. ↑ Unix User's Manual, Release 3.0 (PDF). Bell Laboratories. June 1980. AR(5). Archived (PDF) from the original on 2025-11-02. Retrieved 2025-11-14.
  10. ↑ User's Manual, System V (PDF). Western Electric. January 1983. AR(4) (PDP-11 only). Archived (PDF) from the original on 2026-01-07. Retrieved 2025-11-14.
  11. ↑ User's Manual, System V (PDF). Western Electric. January 1983. AR(4) (not on PDP-11). Archived (PDF) from the original on 2026-01-07. Retrieved 2025-11-14.
  12. ↑ UNIX System V Programmer Reference Manual DEC Processors (PDF). AT&T Technogies. April 1984. AR(4) (not on PDP-11). Archived (PDF) from the original on 2026-01-07. Retrieved 2025-11-14.
  13. ↑ "binutils ar.h".
  14. 1 2 3 4 5 ar(5) – FreeBSD File Formats Manual
  15. ↑ "ar File Format (Small)". IBM. Archived from the original on 2025-06-13. Retrieved 2025-08-21.
  16. ↑ "ar File Format (Big)". IBM.
  17. 1 2 "64-bit Archives Needed". www.linker-aliens.org. Archived from the original on 2026-05-13. Retrieved 2026-07-17.
  18. ↑ "ar.h". www.unix.com. The UNIX and Linux Forums.
  19. ↑ ar – Shell and Utilities Reference, The Single UNIX Specification, Version 5 from The Open Group
  20. ↑ "Manual page for NET/2 ranlib utility". Archived from the original on 2021-02-26. Retrieved 2014-08-23.
  21. ↑ "Manual page for NET/2 ranlib file format". Archived from the original on 2021-02-25. Retrieved 2014-08-23.
  22. ↑ "Libc/include/ranlib.h at Libc-320 - apple-oss-distributions/Libc". Github. Retrieved 2020-02-10.
  23. ↑ "ar.h(3HEAD)". docs.oracle.com. Oracle Corporation. 11 November 2014. Archived from the original on 3 March 2021. Retrieved 14 November 2018.
  24. ↑ Pietrek, Matt (April 1998), "Under The Hood", Microsoft Systems Journal, archived from the original on 2007-06-24, retrieved 2014-08-23
  25. ↑ "llvm-mirror/llvm: archive.cpp (format detection)". GitHub. Archived from the original on 28 February 2021. Retrieved 10 February 2020.
  26. ↑ "ar". GNU Binary Utilities. Archived from the original on 2021-04-18. Retrieved 2020-06-29.
[edit]
Retrieved from "https://en.wikipedia.org/w/index.php?title=Ar_(Unix)&oldid=1364631170"