ar - archive maintainer

ar is used to maintain archives (libraries).

In specific terms, you can use ar to perform the following file management functions. For
each file management function the corresponding main key(s) is/are specified in the list:

• Create an archive file: -q or -r

• Quickly append a file to the end of the archive: -q

• Place/replace a file in the archive: -r

• Delete a file from the archive: -d

• Move a file within the archive: -m

• Print the contents of a file: -p

• List the files in the archive: -t

• Copy (extract) a file from the archive: -x

• Output symbols: -S

Syntax

ar[ -V] mainkey[modifier]...[posmname] afile[ filename]...

-V

ar prints its version number to standard error output.

Main keys

When you call ar, you must specify precisely one main key (-d, -m, -p, -q, -r, -t, -x or -S), optionally followed by one or more arguments.

-d

(d - delete)

ar deletes the specified files from the archive. If no files are specified, no action is taken.

-m

(m - move)

ar moves the specified files within the archive.

With posname:
The files are placed after (a) or before (b or i) the file named posname (see posname).

Without posname:
The files are appended to the end of the archive.

-p

(p - print)

ar prints the contents of the specified files. If no files are specified, the contents of all files are printed.

-q

(q - quickly)

ar adds the specified files to the archive "quickly", i.e.:

If the archive already exists, ar appends the named files to it without checking whether they are already present in the archive. If the archive does not yet exist, it is created.

No posname arguments are permitted.

The -q option is useful when creating a large archive step by step.

-r

(r - replace)

This option has three different effects, depending on whether the specified archive exists and whether it contains the named files:

If the archive exists and contains the files, ar replaces the named files. If the archive exists but is missing one or more of the named files, ar adds the missing files to the archive. If the archive does not exist, ar creates the archive from the named files.

With modifier u:

ar replaces a file in the archive only if the named file has a later date of last modification than the version already in the archive.

With posname:
Files not yet in the archive are placed after (a) or before (b or i) the file posfile (see “posname”).

Without posname:
Files not yet in the archive are appended to the end of the archive.

-t

(t - table)

ar prints a table of contents of the archive file. If no files are specified, all files in the archive are listed; otherwise, only the named files.

-x

(x - extract)

ar copies (extracts) files from the archive. If no files are specified, all files in the archive are extracted. The archive itself remains unaltered.

-S

(S – Symbols)

ar lists all symbols of the specified files. If no files are specified, ar lists all symbols which are contained in the library. The library is not changed by this.

Key modifiers

c

(c - create)

The message that ar usually issues when creating an archive is suppressed.

C

(C - Create)

Extracted files are prevented from being overwritten by files of the same name in the file system. This option is useful when -T is also used, to prevent truncated filenames from replacing files with the same prefix in the file system.

T

(T - truncate)

Truncates the names of extracted files. When files are extracted from an archive, their archive names may be longer than the file system can support. By default an error message will be output and the file will not be extracted if the filename is too long.

l

(l - local)

Can be specified, but is ignored.

s

(s - symbol table)

ar regenerates the archive symbol table, but only if new objects are included in the library or existing objects are replaced.

u

(u - update)

See main key -r.

v

(v - verbose)

ar reports each action it takes (adding files to the archive, moving them within the archive, extracting them from the archive, etc.). If v is used with the -t key, ar displays a detailed listing similar to that produced by the ls -l command (see ls).

posname

The posname argument specifies the position at which a file is inserted into the archive. posname may be:

a posfile

ar inserts the file before the named posfile.

b posfile
i posfilei

ar inserts the file before the named posfile.

posfile is the name of a file already in the archive.

afile

Name of the archive to be created or processed.

file

Name of the file to be listed, printed out, added to, extracted from, or moved within the archive.
More than one file may be named on the command line. If you specify the same file more than once when calling ar with the -q or -r key, ar will enter the named file into the archive as often as specified. If a number of identically named files are contained in the archive, and you use ar without specifying a position, the first file with the given name will be accessed (rather than the most recent or oldest file, for example).

Structure of an archive

An archive is a single file that combines several files into one. By convention, the name of an archive file ends with the suffix .a. The purpose of an archive file is to enable the collective maintenance of a group of related files. Archives make it easier to maintain files, since you will often only need to specify the archive file instead of individually listing all its elements.
The constituents of an archive are typically object modules that usually form part of the same program or suite of programs.

The magic string and the file headers used by ar consist of printable ASCII characters. If an archive is entirely composed of printable files, the entire archive is printable.

When ar creates an archive, it creates headers in a format that is portable across all machines.

If the archive contains at least one object file, ar creates and maintains an archive symbol table. This symbol table is used by the link editor ld to effect multiple passes over the archive in an efficient manner. The archive symbol table is stored in a specially named file that is always the first file in the archive. This file is never listed or printed out like other archive files and is not accessible to the user. Whenever the ar command is used to create or update the contents of an archive, the symbol table is rebuilt. The symbol table can also be rebuilt by calling ar with the -s option.

As far as possible the virtual main memory is used and the export of elements to temporary files is avoided. If this is not successful, temporary files are created, but this is only necessary in the case of the main option –m. The following priorities then apply for the storage location of the temporary files:

1. the current directory

2. the directory specified in the TMPDIR variable

3. the /tmp directory

Locale

The following environment variables affect the execution of ar:

LANG

Provide a default value for the internationalization variables that are unset or null. If LANG is unset of null, the corresponding value from the implementation-specific default locale will be used. If any of the internationalization variables contains an invalid setting, the utility will behave as if none of the variables had been defined.

LC_ALL

If set to a non-empty string value, override the values of all the other internationalization variables.

LC_TIME

Determine the format of date and time strings in archive content listings produced in conjunction with the v modifier.

LC_CTYPE

Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single- as opposed to multi-byte characters in arguments and input files).

LC_MESSAGES

Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.

NLSPATH

Determine the location of message catalogs for the processing of LC_MESSAGES.

Example 1

Quickly creating an archive file:

$ ar -qv afile.a atoi.o itoa.o
ar: creating afile.a
a - atoi.o
a - itoa.o

ar creates the archive afile.a from the files atoi.o and itoa.o. The v modifier tells ar to display the names of the files as they are added. 

Example 2

Placing a new file at a specified position in an archive:

$ ar -rvb atoi.o afile.a atof.o
a - atof.o

ar copies atof.o into the archive file afile.a, placing it before atoi.o.

Example 3

Printing the table of contents of an archive:

$ ar -tv archiv.a
rw-r--r-- 104/     1      2276 Jul 13 12:17 2008 atof.o
rw-r--r-- 104/     1       759 Jul 13 12:17 2008 atoi.o
rw-r--r-- 104/     1      1280 Jul 13 12:17 2008 itoa.o

Example 4

Extracting (copying) a file from an archive:

$ ar -xv archiv.a atoi.o
x - atoi.o

The file atoi.o is copied from the archive afile.a into the working directory. The copy is also called atoi.o.

See also

cpio, pax, tar