 |
» |
|
|
|
NAMEar — create and maintain portable archives and libraries SYNOPSISar
[-]key
[-][modifier ...] [posname]
afile
[name ...] DESCRIPTIONThe
ar
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
ar
consist of printable 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
ar
creates an archive, it creates headers in a format
that is portable 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
ar
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
ar
is used to create or update the contents of an archive,
the symbol table is rebuilt (unless the
z
modifier is used).
The
s
modifier described below forces the symbol table to be rebuilt. One
key
operation character from the set,
drqtpmx,
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
abcfFilsuvzACT.
posname
is used with the
r
and
m
key operations and the
a,
b,
and
i
modifiers to specify 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:
- d
Delete the named files from the archive file. - r
Replace the named files, or add a new file to the archive:
If the
u
modifier is used with
the operation character
r,
only those files with modification dates
later than those of the corresponding member files are replaced. If an optional positioning character from the set
abi
is used, the
posname
argument must be present and specifies that new files
are to be placed after
(a)
or before
(b
or
i)
posname.
In the absence of a positioning character, new files are placed at the end. ar
creates
afile
if it does not already exist. If no
name
is specified and:
the specified archive file does not exist,
ar
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
u
modifier is also specified.
- q
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.
ar
creates
afile
if it does not already exist. - t
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. - p
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. - m
Move the named files.
By default, the files are moved to the end of the archive.
If a positioning character is present, the
posname
argument must be present and, as in the
r
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. - x
Extract the named files.
If no names are given, all files in the archive are extracted.
In neither case does
x
alter entries from the archive file.
The following list describes the optional
modifier
characters:
- a
Position the files after the existing positioning file specified by
posname . - b
Place the new files before the existing positioning file specified by
posname . - c
Suppress the message normally produced when
afile
is created.
For
r
and
q
operations,
ar
normally creates
afile
if it does not already exist. - f
Truncate the named file names to 14 bytes before performing
operations on an archive.
This modifier has been provided 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
r
operation,
the first existing file that matches the truncated file name
is replaced.
The
f
modifier can also be used with other operations
to allow the full file names to be specified,
rather than the truncated file names. Also see the description of the
F
modifier. - i
Place the new files before the existing positioning file specified by
posname .
Identical to the
b
modifier. - l
Place temporary files in the local current working directory
rather than in the directory specified by the environment variable
TMPDIR
or in the default directory
/var/tmp.
Only the
d,
m,
q,
and
r
operations and the
s
and
F
modifiers use temporary files. - s
Regenerate the archive symbol table even if
ar
is not invoked with an operation
that modifies the archive contents.
This modifier is useful for restoring the archive symbol table after the
strip
command has been used on the archive (see
strip(1))
or after the archive has been modified using the
z
modifier. - u
Update the archive.
(r
operations only)
Do not copy the local file to the archive
unless the local file is newer
than the corresponding existing file in the archive. - v
Give a verbose file-by-file description
of the creation or modification of an archive file to the standard output.
When used with
t,
v
gives a long listing of all information about the files.
When used with the
d,
m,
p,
q,
or
x
operations, the verbose modifier causes
ar
to print each
key
operation character and the file name associated with that operation.
For the
r
operation,
ar
shows an
a
if it adds a new file or an
r
if it replaces an existing one. For the
p
operation,
ar
prints the name of the file to the standard output before the contents of
the file are printed. - z
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
z
modifier 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
ranlib
command (see
ranlib(1)),
or invoke
ar
again with the
s
modifier. - A
Suppress warning messages regarding
optional access control list entries.
ar
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. - C
Prevent extracted files from replacing files with the same name.
The
C
modifier can only be used with the
x
operation. - F
Truncate the entire archive. The
F
modifier causes the entire archive to be rewritten such that all file names
within the archive are truncated to 14 bytes, even when
ar
does not modify the archive contents. The long name table will be removed (see
ar(4)).
This modifier has been provided for compatibility
with previous releases where file names up to a maximum of 14 bytes were supported.
Also see the description of the
f
modifier. - T
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
T
modifier can only be used with the
x
operation.
Only the following combinations are meaningful;
no other combination of modifiers with operations
have any effect on the operation:
- d:
v,
f,
F,
l - m:
v,
f,
F,
l,
and
a | b | i - r:
v,
f,
F,
l,
c,
A,
u,
and
a | b | i - q:
v,
f,
F,
l,
c,
A,
z,
s - t:
v,
f,
F,
s - p:
v,
f,
F,
s - x:
v,
f,
F,
s,
C,
T
EXTERNAL INFLUENCESEnvironment VariablesThe following internationalization variables affect the execution of
ar:
- LANG
Determines the locale category for native language, local customs and
coded character set in the absence of
LC_ALL
and other
LC_*
environment variables.
If
LANG
is not specified or is set to the empty string,
a default of
C
(see
lang(5))
is used instead of
LANG. - LC_ALL
Determines the values for all locale categories and has precedence over
LANG
and other
LC_*
environment variables. - LC_CTYPE
Determines the locale category for character handling functions. - LC_MESSAGES
Determines the locale that should be used to affect the format
and contents of diagnostic messages written to standard error. - LC_NUMERIC
Determines the locale category for numeric formatting. - LC_TIME
Determines the format and contents of date and time formatting. - NLSPATH
Determines the location of message catalogues for the processing
of
LC_MESSAGES.
If any internationalization variable
contains an invalid setting,
ar
behaves as if all internationalization variables are set to
C.
See
environ(5). In addition, the following environment variable affects
ar:
- TMPDIR
Specifies a directory
for temporary files (see
tmpnam(3S)).
The
l
modifier overrides the
TMPDIR
variable, and
TMPDIR
overrides
/var/tmp,
the default directory.
DIAGNOSTICS- phase error on file name
The named file was modified by another process while
ar
was copying it into the archive.
When this happens,
ar
exits and the original archive is left untouched. - ar write error: file system error message
ar
could not write to a temporary file or the final output file.
If
ar
was trying to write the final output file,
the original archive is lost.
ar
reports
cannot create
file.a
, where
file.a
is an
ar-format
archive file, even if
file.a
already exists.
This message is triggered when
file.a
is write-protected or inaccessible. EXAMPLESCreate a new file (if one does not already exist)
in archive format with its constituents entered
in the order indicated:
ar r newlib.a f3 f2 f1 f4 Replace files
f2
and
f3
such that the new copies follow file
f1,
and
f3
follows
f2:
ar ma f1 newlib.a f2 f3
ar ma f2 newlib.a f3
ar r newlib.a f2 f3 The archive is then ordered:
where the single quote marks indicate updated files.
The first command says "move
f2
and
f3
after
f1
in
newlib.a", thus creating the order:
Note that the relative order of
f2
and
f3
has not changed.
The second command says "move
f3
after
f2
in
newlib.a
", creating the order:
The third command then replaces files
f2
and
f3.
Since files
f2
and
f3
both already existed in the archive,
this sequence of commands could not be simply replaced by:
because the previous position and relative order of
f2
and
f3
in the archive are preserved
(no matter how the files are specified on the command line),
producing the following archive:
WARNINGSIf you are a user who has appropriate privileges,
ar
can alter any archive file, even if it is write-protected. If the same file is mentioned twice in an argument list,
it might be put in the archive twice. If multiple copies of a file exist in an archive,
ar
matches the first occurrence of the file in the archive. ar
automatically creates an archive symbol table,
a task performed in early HP-UX versions by
ranlib.
Use of the
z
modifier either suppresses generation of the symbol table, or invalidates
it if it exists. The
ranlib
command can be used to rebuild the symbol table if an
archive was built with the
z
modifier.
FILES- /var/tmp/ar*
Temporary files
SEE ALSOSystem Tools:- ld(1)
Invoke the link editor
Miscellaneous:- acl(5)
Access control lists - a.out(4)
Assembler, compiler, and linker output - ar(4)
Archive format - lorder(1)
Find the ordering relation for object files or archive libraries - ranlib(1)
Regenerate an archive symbol table - strip(1)
Strip symbol and line number information from an object file - tmpnam(3S)
Create a name for a temporary file
Texts and Tutorials:- HP-UX Linker and Libraries Online User Guide
(See the
+help
option) - HP-UX Linker and Libraries User's Guide
(See
manuals(5)
for ordering information)
STANDARDS CONFORMANCEar: SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2 |
Printable version
