ar [-]p[mod [relpos]] archive [member...] ar -M [ <mri-script ]
ar program creates, modifies, and extracts from
archives. An archive is a single file holding a collection of
other files in a structure that makes it possible to retrieve
the original individual files (called members of the archive).
The original files' contents, mode (permissions), timestamp, owner, and group are preserved in the archive, and can be restored on extraction.
ar can maintain archives whose members have names of any
length; however, depending on how
ar is configured on your
system, a limit on member-name length may be imposed for compatibility
with archive formats maintained with other tools. If it exists, the
limit is often 15 characters (typical of formats related to a.out) or 16
characters (typical of formats related to coff).
ar is considered a binary utility because archives of this sort
are most often used as libraries holding commonly needed
ar creates an index to the symbols defined in relocatable
object modules in the archive when you specify the modifier `s'.
Once created, this index is updated in the archive whenever
makes a change to its contents (save for the `q' update operation).
An archive with such an index speeds up linking to the library, and
allows routines in the library to call each other without regard to
their placement in the archive.
You may use `nm -s' or `nm --print-armap' to list this index
table. If an archive lacks the table, another form of
ranlib can be used to add just the table.
ar is designed to be compatible with two different
facilities. You can control its activity using command-line options,
like the different varieties of
ar on Unix systems; or, if you
specify the single command-line option `-M', you can control it
with a script supplied via standard input, like the MRI "librarian"
aron the command line
ar [-]p[mod [relpos]] archive [member...]
When you use
ar in the Unix style,
ar insists on at least two
arguments to execute: one keyletter specifying the operation
(optionally accompanied by other keyletters specifying
modifiers), and the archive name to act on.
Most operations can also accept further member arguments, specifying particular files to operate on.
ar allows you to mix the operation code p and modifier
flags mod in any order, within the first command-line argument.
If you wish, you may begin the first command-line argument with a dash.
The p keyletter specifies what operation to execute; it may be any of the following, but you must specify only one of them:
arlists each module as it is deleted.
m, any members you name in the member arguments are moved to the end of the archive; you can use the `a', `b', or `i' modifiers to move them to a specified place instead.
arlist each file as it is appended. Since the point of this operation is speed, the archive's symbol table index is not updated, even if it already existed; you can use `ar s' or
ranlibexplicitly to update the symbol table index. However, too many different systems assume quick append rebuilds the index, so GNU ar implements
qas a synonym for
ardisplays an error message, and leaves undisturbed any existing members of the archive matching that name. By default, new members are added at the end of the file; but you may use one of the modifiers `a', `b', or `i' to request placement relative to some existing member. The modifier `v' used with this operation elicits a line of output for each file inserted, along with one of the letters `a' or `r' to indicate whether the file was appended (no old member deleted) or replaced.
arlist each name as it extracts it. If you do not specify a member, all files in the archive are extracted.
A number of modifiers (mod) may immediately follow the p keyletter, to specify variations on an operation's behavior:
arwill normally permit file names of any length. This will cause it to create archives which are not compatible with the native
arprogram on some systems. If this is a concern, the `f' modifier may be used to truncate file names when putting them in the archive.
arwith a script
ar -M [ <script ]
If you use the single command-line option `-M' with
can control its operation with a rudimentary command language. This
ar operates interactively if standard input is coming
directly from a terminal. During interactive use,
ar prompts for
input (the prompt is `AR >'), and continues executing even after
errors. If you redirect standard input to a script file, no prompts are
ar abandons execution (with a nonzero exit code)
on any error.
ar command language is not designed to be equivalent
to the command-line options; in fact, it provides somewhat less control
over archives. The only purpose of the command language is to ease the
transition to GNU
ar for developers who already have scripts
written for the MRI "librarian" program.
The syntax for the
ar command language is straightforward:
LISTis the same as
list. In the following descriptions, commands are shown in upper case for clarity.
arcommand, you can separate the individual names with either commas or blanks. Commas are shown in the explanations below, for clarity.
Here are the commands you can use in
ar scripts, or when using
ar interactively. Three of them have special significance:
CREATE specify a current archive, which is
a temporary file required for most of the other commands.
SAVE commits the changes so far specified by the script. Prior
SAVE, commands affect only the temporary copy of the current
ADDLIB archive (module, module, ... module)
ADDMOD member, member, ... member
SAVE. May be executed (with no effect) even if no current archive is specified.
SAVE. You can overwrite existing archives; similarly, the contents of any existing file named archive will not be destroyed until
DELETE module, module, ... module
DIRECTORY archive (module, ... module)
DIRECTORY archive (module, ... module) outputfile
VERBOSEspecifies the form of the output: when verbose output is off, output is like that of `ar -t archive module...'. When verbose output is on, the listing is like `ar -tv archive module...'. Output normally goes to the standard output stream; however, if you specify outputfile as a final argument,
ardirects the output to that file.
ar, with a
0exit code to indicate successful completion. This command does not save the output file; if you have changed the current archive since the last
SAVEcommand, those changes are lost.
EXTRACT module, module, ... module
VERBOSE. The effect is like `ar tv archive'). (This single command is a GNU
ldenhancement, rather than present for MRI compatibility.) Requires prior use of
REPLACE module, module, ... module
REPLACEarguments) from files in the current working directory. To execute this command without errors, both the file, and the module in the current archive, must exist. Requires prior use of
DIRECTORY. When the flag is on,
DIRECTORYoutput matches output from `ar -tv '....
OPENcommand. Requires prior use of
Go to the first, previous, next, last section, table of contents.