NAME

ar - create and maintain library archives

 SYNOPSIS

ar -d[-v][-l] archive file ...

ar -m[-abilv][posname] archive file ...

ar -p[-v][-s]archive [file ...]

ar -q[-clv] archive file ...

ar -r[-cuv][-abil][posname]archive file ...

ar -t[-v][-s]archive [file ...]

ar -x[-v][-sCT]archive [file ...]

 DESCRIPTION

The ar utility can be used to create and maintain groups of files combined into an archive. Once an archive has been created, new files can be added, and existing files can be extracted, deleted or replaced. When an archive consists entirely of valid object files, the implementation will format the archive so that it is usable as a library for link editing (see c89, cc and fort77). When some of the archived files are not valid object files, the suitability of the archive for library use is undefined. If an archive file consists entirely of printable files, the entire archive file is printable.

When ar creates an archive file, it creates administrative information in a format that is portable across all machines. When there is at least one object file that ar recognises as such in the archive, an archive symbol table is created in the archive file and maintained by ar; it is used by the link editor to search the archive file. Whenever the ar utility is used to create or update the contents of such an archive, the symbol table is rebuilt. The -s option forces the symbol table to be rebuilt.

All file operands can be pathnames. However, files within archives are named by a filename, which is the last component of the pathname used when the file was entered into the archive. The comparison of file operands to the names of files in archives is performed by comparing the last component of the operand to the name of the archive file.

It is unspecified whether multiple files in the archive may be identically named. In the case of such files, however, each file and posname operand will match only the first archive file having a name that is the same as the last component of the operand.

 OPTIONS

The ar utility supports the XBD specification, Utility Syntax Guidelines  .

The following options are supported:

-a

Position new files in the archive after the file named by the posname operand.

-b

Position new files in the archive before the file named by the posname operand.

-c

Suppress the diagnostic message that is written to standard error by default when the archive file archive is created.

-C

Prevent extracted files from replacing like-named files in the file system. This option is useful when -T is also used, to prevent truncated filenames from replacing files with the same prefix.

-d

Delete one or more files from archive.

-i

Position new files in the archive before the file named by the posname operand (equivalent to -b).

-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. (LEGACY)

-m

Move the named files. The -a, -b or -i options with the posname operand indicate the position; otherwise, move the files to the end of the archive.

-p

Write the contents of the files from archive to the standard output. If no files are specified, the contents of all files in the archive will be written in the order of the archive.

-q

Quickly append the named files to the end of the archive file. In this case ar does not check whether the added members are already in the archive. This is useful to bypass the searching otherwise done when creating a large archive piece by piece.

-r

Replace or add files to archive. If the archive named by archive does not exist, a new archive file will be created and a diagnostic message will be written to standard error (unless the -c option is specified). If no files are specified and the archive exists, the results are undefined. Files that replace existing files will not change the order of the archive. Files that do not replace existing files will be appended to the archive.

-s

Force the regeneration of the archive symbol table even if ar is not invoked with an option that will modify the archive file contents. This option is useful to restore the archive symbol table after it has been stripped; see strip.

-t

Write a table of contents of archive to the standard output. The files specified by the file operands will be included in the written list. If no file operands are specified, all files in archive will be included in the order of the archive.

-T

Allow filename truncation of extracted files whose archive names are longer than the file system can support. By default, extracting a file with a name that is too long is an error; a diagnostic message will be written and the file will not be extracted.

-u

Update older files. When used with the -r option, files within the archive will be replaced only if the corresponding file has a modification time that is at least as new as the modification time of the file within the archive.

-v

Give verbose output. When used with the option characters -d, -r or -x, write a detailed file-by-file description of the archive creation and maintenance activity, as described in the STDOUT section. When used with -p, write the name of the file to the standard output before writing the file itself to the standard output, as described in the STDOUT section. When used with -t, include a long listing of information about the files within the archive, as described in the STDOUT section.

-x

Extract the files named by the file operands from archive. The contents of the archive file will not be changed. If no file operands are given, all files in the archive will be extracted. If the filename of a file extracted from the archive is longer than that supported in the directory to which it is being extracted, the results are undefined. The modification time of each file extracted will be set to the time the file is extracted from the archive.

 OPERANDS

The following operands are supported:

archive

A pathname of the archive file.

file

A pathname. Only the last component will be used when comparing against the names of files in the archive. If two or more file operands have the same last pathname component (basename), the results are unspecified. The implementation's archive format will not truncate valid filenames of files added to or replaced in the archive.

posname

The name of a file in the archive file, used for relative positioning; see options -m and -r.

 STDIN

Not used.

 INPUT FILES

The input file named by archive must be a file in the format created by ar -r.

 ENVIRONMENT VARIABLES

The following environment variables affect the execution of ar:

LANG

Provide a default value for the internationalisation variables that are unset or null. If LANG is unset or null, the corresponding value from the implementation-dependent default locale will be used. If any of the internationalisation 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 internationalisation variables.

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.

LC_TIME

Determine the format and content for date and time strings written by ar -tv.

NLSPATH

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

TMPDIR

Determine the pathname that overrides the default directory for temporary files, if any.

 ASYNCHRONOUS EVENTS

Default.

 STDOUT

If the -d option is used with the -v option, the standard output format is:

"d - %s\n", <file> where <file> is the operand specified on the command line.

If the -p option is used with the -v option, ar will precede the contents of each file with:

"\n<%s>\n\n", <file>

where <file> is the operand specified on the command line, if file operands were specified, and the name of the file in the archive if they were not.

If the -r option is used with the -v option, and file is already in the archive, the standard output format is:

"r - %s\n", <file> where <file> is the operand specified on the command line.

If file is being added to the archive with the -r option, the standard output format is:

"a - %s\n", <file> where <file> is the operand specified on the command line.

If the -t option is used, ar writes the names of the files to the standard output in the format:

"%s\n", <file> where <file> is the operand specified on the command line, if file operands were specified, or the name of the file in the archive if they were not.

If the -t option is used with the -v option, the standard output format is:

"%s %u/%u %u %s %d %d:%d %d %s\n", <member mode>, <user ID>, <group ID>, <number of bytes in member>, <abbreviated month>, <day-of-month>, <hour>, <minute>, <year>, <file>

Where:

<file>

is the operand specified on the command line, if file operands were specified, or the name of the file in the archive if they were not.

<member mode>

is formatted the same as the <file mode> string defined in the STDOUT section of ls, except that the first character, the <entry type>, is not used; the string represents the file mode of the archive member at the time it was added to or replaced in the archive.

The following represent the last-modification time of a file when it was most recently added to or replaced in the archive:

<abbreviated month>

is equivalent to the %b format in date.

<day-of-month>

is equivalent to the %e format in date.

<hour>

is equivalent to the %H format in date.

<minute>

is equivalent to the %M format in date.

<year>

is equivalent to the %Y format in date.

When LC_TIME does not specify the POSIX locale, a different format and order of presentation of these fields relative to each other may be used in a format appropriate in the specified locale.

If the -x option is used with the -v option, the standard output format is:

"x - %s\n", <file> where <file> is the operand specified on the command line, if file operands were specified, or the name of the file in the archive if they were not.

 STDERR

Used only for diagnostic messages. The diagnostic message about creating a new archive when -c is not specified will not modify the exit status.

 OUTPUT FILES

Archives are files with unspecified formats.

 EXTENDED DESCRIPTION

None.

 EXIT STATUS

The following exit values are returned:

0

Successful completion.

>0

An error occurred.

 CONSEQUENCES OF ERRORS

Default.

 APPLICATION USAGE

None.

 EXAMPLES

None.

 FUTURE DIRECTIONS

The IEEE PASC 1003.2 Interpretations Committee has forwarded concerns about parts of this interface definition to the IEEE PASC Shell and Utilities Working Group which is identifying the corrections. A future revision of this specification will align with IEEE Std. 1003.2b when finalised.

 SEE ALSO

c89, cc, cpio, pax, strip. the XSH specification <unistd.h> description of {POSIX_NO_TRUNC}.