ar(1)ar(1)NAMEar - create and maintain portable archives and libraries
SYNOPSIS
key [modifier ...] [posname] afile [name ...]
DESCRIPTION
The command maintains groups of files combined into a single archive
file. Its main use is to create and update library files as used by
the link editor (see ld(1)). It can be used, however, for any similar
purpose. The magic string and file headers used by consist of print‐
able ASCII characters. If an archive is composed of printable files,
the entire archive is printable.
Individual files are inserted without conversion into the archive file.
When creates an archive, it creates headers in a format that is porta‐
ble across all machines. See ar(4) for a detailed description of the
portable archive format and structure. The archive symbol table
(described in ar(4)) is used by the link editor to search repeatedly
and efficiently through libraries of object files. An archive symbol
table is created and maintained by only when the archive contains at
least one object file. The archive symbol table is in a specially
named file that is always the first file in the archive. This file is
never mentioned or accessible to the user. Whenever is used to create
or update the contents of an archive, the symbol table is rebuilt
(unless the modifier is used). The modifier described below forces the
symbol table to be rebuilt.
One key operation character from the set, is required and can be
optionally preceded by a hyphen (The required key operation character
can be specified with one or more modifier characters from the set pos‐
name is used with the and key operations and the and modifiers to spec‐
ify a position in the archive. afile is the archive file. Constituent
files in the archive file are specified by name arguments.
The following list describes the key operation characters:
Delete the named files from the archive file.
Replace the named files, or add a new file to the archive:
· If the modifier is used with the operation character
only those files with modification dates later than
those of the corresponding member files are replaced.
· If an optional positioning character from the set is
used, the posname argument must be present and speci‐
fies that new files are to be placed after or before
or posname. In the absence of a positioning charac‐
ter, new files are placed at the end.
· creates afile if it does not already exist.
· If no name is specified and:
· the specified archive file does not exist, creates
an empty archive file containing only the archive
header (see ar(4)).
· the archive contains one or more files whose names
match names in the current directory, each matching
archive file is replaced by the corresponding local
file without considering which file may be newer
unless the modifier is also specified.
Quickly append the named files to the end of the archive file.
Positioning characters are invalid. The operation does
not check to determine whether the added members are
already in the archive. creates afile if it does not
already exist.
Print a table of contents of the archive file to the standard
output.
If no names are given, all files in the archive are
described. If names are given, information about only
those files appears.
Print the named files in the archive to the standard output. If
no names
are specified, the contents of all files are printed in
the order that they appear in the archive.
Move the named files.
By default, the files are moved to the end of the ar‐
chive. If a positioning character is present, the pos‐
name argument must be present and, as in the operation,
posname specifies where the files are to be moved. Note
that, when used with a positioning character, the files
are moved in the same order that they currently appear in
the archive, not in the order specified on the command
line. See EXAMPLES.
Extract the named files.
If no names are given, all files in the archive are
extracted. In neither case does alter entries from the
archive file.
The following list describes the optional modifier characters:
Position the files after the existing positioning file specified
by
posname .
Place the new files before the existing positioning file speci‐
fied by
posname .
Suppress the message normally produced when
afile is created. For and operations, normally creates
afile if it does not already exist.
Truncate the named file names to 14 bytes before performing
operations on an archive. This modifier has been pro‐
vided for compatibility with previous releases where file
names up to a maximum of 14 bytes were supported. Longer
file names were truncated. When used with the operation,
the first existing file that matches the truncated file
name is replaced. The modifier can also be used with
other operations to allow the full file names to be spec‐
ified, rather than the truncated file names. Also see the
description of the modifier.
Place the new files before the existing positioning file speci‐
fied by
posname . Identical to the modifier.
Place temporary files in the local current working directory
rather than in the directory specified by the environment
variable or in the default directory Only the and opera‐
tions and the and modifiers use temporary files.
Regenerate the archive symbol table even if
is not invoked with an operation that modifies the ar‐
chive contents. This modifier is useful for restoring
the archive symbol table after the command has been used
on the archive (see strip(1)) or after the archive has
been modified using the modifier.
Update the archive.
operations only) Do not copy the local file to the ar‐
chive unless the local file is newer than the correspond‐
ing existing file in the archive.
Give a verbose file-by-file description
of the creation or modification of an archive file to the
standard output. When used with gives a long listing of
all information about the files. When used with the or
operations, the verbose modifier causes to print each key
operation character and the file name associated with
that operation. For the operation, shows an if it adds a
new file or an if it replaces an existing one. For the
operation, prints the name of the file to the standard
output before the contents of the file are printed.
Suppress the rebuilding of the symbol table when the archive
is modified. This modifier is useful only to avoid long
build times when creating a large archive piece-by-piece.
If an existing archive contains a symbol table, the modi‐
fier will cause it to be invalidated. If a file name
longer than 15 bytes is given the entire archive is
rewritten. To rebuild the symbol table, either use the
command (see ranlib(1)), or invoke again with the modi‐
fier.
Suppress warning messages regarding
optional access control list entries. does not archive
optional access control list entries in a file's access
control list (see acl(5)). Normally, a warning message
is printed for each file having optional access control
list entries.
Prevent extracted files from replacing files with the same name.
The modifier can only be used with the operation.
Truncate the entire archive. The
modifier causes the entire archive to be rewritten such
that all file names within the archive are truncated to
14 bytes, even when does not modify the archive contents.
The long name table will be removed (see ar(4)). This
modifier has been provided for compatibility with previ‐
ous releases where file names up to a maximum of 14 bytes
were supported. Also see the description of the modi‐
fier.
Truncate file names whose archive names are longer than those
supported by
the file system. By default, files with names longer than
those supported by the file system will not be extracted
and will cause an error. The modifier can only be used
with the operation.
Only the following combinations are meaningful; no other combination of
modifiers with operations have any effect on the operation:
and
and
EXTERNAL
INFLU‐
ENCES
Environment Vari‐
ables
The following
international‐
ization vari‐
ables affect
the execution
of
Determines the
locale category
for native lan‐
guage, local
customs and
coded
charac‐
ter set
in the
absence
of and
other
environ‐
ment
vari‐
ables.
If is
not
speci‐
fied or
is set
to the
empty
string,
a
default
of (see
lang(5))
is used
instead
of
Determines the
values for all
locale cate‐
gories and has
precedence over
and
other
environ‐
ment
vari‐
ables.
Determines the
locale category
for character
handling func‐
tions.
Determines the
locale that
should be used
to affect the
format
and con‐
tents of
diagnos‐
tic mes‐
sages
written
to stan‐
dard
error.
Determines the
locale category
for numeric
formatting.
Determines the
format and con‐
tents of date
and time for‐
matting.
Determines the
location of
message cata‐
logues for the
processing
of
If any interna‐
tionalization
variable con‐
tains an
invalid set‐
ting, behaves
as if all
international‐
ization vari‐
ables are set
to See envi‐
ron(5).
In addition,
the following
environment
variable
affects
Specifies a
directory
for tem‐
porary
files
(see
tmp‐
nam(3S)).
The mod‐
ifier
over‐
rides
the
vari‐
able,
and
over‐
rides
the
default
direc‐
tory.
DIAGNOSTICS
The named file
was modified by
another process
while
was
copy‐
ing
it
into
the
ar‐
chive.
When
this
hap‐
pens,
exits
and
the
orig‐
i‐
nal
ar‐
chive
is
left
untouched.
could not write
to a temporary
file or the
final output
file.
If
was
try‐
ing
to
write
the
final
out‐
put
file,
the
orig‐
i‐
nal
ar‐
chive
is
lost.
reports , where
is an archive
file, even if
already exists.
This message is
triggered when
is write-pro‐
tected or inac‐
cessible.
EXAMPLES
Create a new
file (if one
does not
already exist)
in archive for‐
mat with its
constituents
entered in the
order indi‐
cated:
Replace files
and such that
the new copies
follow file and
follows
The archive is
then ordered:
where the sin‐
gle quote marks
indicate
updated files.
The first com‐
mand says "move
and after in
newlib.a", thus
creating the
order:
Note that the
relative order
of and has not
changed. The
second command
says "move
after in
newlib.a", cre‐
ating the
order:
The third com‐
mand then
replaces files
and Since files
and both
already existed
in the archive,
this sequence
of commands
could not be
simply replaced
by:
because the
previous posi‐
tion and rela‐
tive order of
and in the ar‐
chive are pre‐
served (no mat‐
ter how the
files are spec‐
ified on the
command line),
producing the
following ar‐
chive:
WARNINGS
If you are a
user who has
appropriate
privileges, can
alter any ar‐
chive file,
even if it is
write-pro‐
tected.
If the same
file is men‐
tioned twice in
an argument
list, it might
be put in the
archive twice.
If multiple
copies of a
file exist in
an archive,
matches the
first occur‐
rence of the
file in the ar‐
chive.
automatically
creates an ar‐
chive symbol
table, a task
performed in
early HP-UX
versions by Use
of the modifier
either sup‐
presses genera‐
tion of the
symbol table,
or invalidates
it if it
exists. The
command can be
used to rebuild
the symbol ta‐
ble if an ar‐
chive was built
with the modi‐
fier.
FILES
Temporary files
SEE ALSO
System Tools:
ld(1) Invoke
the
link
edi‐
tor
Miscellaneous:
acl(5) Access
con‐
trol
lists
a.out(4) Assem‐
bler,
com‐
piler,
and
linker
out‐
put
ar(4) Ar‐
chive
for‐
mat
lorder(1) Find
the
order‐
ing
rela‐
tion
for
object
files
or
ar‐
chive
libraries
ranlib(1) Regen‐
er‐
ate
an
ar‐
chive
sym‐
bol
ta‐
ble
strip(1) Strip
sym‐
bol
and
line
num‐
ber
infor‐
ma‐
tion
from
an
object
file
tmpnam(3S) Cre‐
ate
a
name
for
a
tem‐
po‐
rary
file
Texts and Tutori‐
als:
(See the option)
(See man‐
u‐
als(5)
for
order‐
ing
infor‐
ma‐
tion)
STANDARDS CONFORMANCEar(1)