NAME

ar - archive file maintainer


SYNOPSIS

ar [-](d|p|t|u|x)[v] arcname [files]


DESCRIPTION

Ar collects sets of arbitrary files into one big file and
maintains that file as an 'archive'.
Files can be extracted from the archive, new ones can be added,
old ones can be deleted or replaced by updated versions, and
data about the contents can be listed.

If a minus sign ('-') is given as a file name, further file names
are read from the standard input, one file name per line.

Files that are to be added to an archive must exist as
files with the name given.  Files that are extracted from
an archive will be put onto files with the name given.
Files that are added to archives can, of course, be archive files
themselves.  There is no (theoretical) limit to the number
of files that can be nested this way.
Thus AR provides the utility necessary to maintain tree-structured
file directories.

AR is invoked by the command line



AR command archname [optional filenames]

where 'command' is any one of 'dptux', optionally concatenated
with 'v', specifying what operation to perform on the
archive file named 'archname'.
The possible commands are:



u - Update named archive by replacing existing files or adding new
ones at end.
If the 'v' option is used, file names will be printed on the
standard output as files are written to the new archived file.

x - Extract named files from archive.  Put onto file of the
same name.
If the 'v' option is added, file names will be printed on the
standard output as files are extracted.

d - Delete named files from archive.
If the 'v' option is used, file names will be printed on
the standard output as they are deleted from the archive.

p - Print named files on standard output.
Using the 'v' option will cause the file name to precede the file.

t - Print table of archive contents.
Normally, the table will contain only the file name.
If the 'v' option is used, the table will also contain
the file's length, type, and date and time of last change.

v - Verbose.  This command may be concatenated to any of the above
commands,
and will cause the archiver to print additional information,
generally file names, on the standard output.
Its specific action for each command has already been described.



The optional filenames in the command line specify individual
files that may participate in the action.
If no files are named, the action is done on ALL files in the archive,
but if any files are explicitly named, they are the ONLY ones that
take part in the action.
(The 'd' command is an exception--files may be deleted only by
specifying their names.)






FILES

A file 'arctemp' is created and subsequently deleted for each run.


SEE ALSO

The Unix commands 'ar' and 'ls' in the Unix manual


DIAGNOSTICS

archive not in proper format


The basic problem is that archive didn't find a header
line where one was expected.
Typical reasons include misspelling the file name,
using an existing file (not in archive format)
on a creation run, and
referencing an archive file that has been modified
directly (say with the editor).



archive integrity in doubt - missing trailer


Each file in an archive is terminated by a special line called a
"trailer," which must be present.
The message is caused by the lack of a trailer line when one was
expected.




delete by name only


For user protection, files are allowed to be deleted from an archive
only by specifying each file name.



duplicate file name


A file was listed more than once when calling the archiver



fatal errors-archive not altered


This message is generated whenever one or more of the other
errors have been detected.  An archive is never altered unless
EVERYTHING has run properly.



too many file names


At the present the user may call the archiver with no more than
25 files at a time.



usage:  ar [-](dptux)[v] arcname [files]


The command line passed to the archiver is in error.
Possibly the command is wrong or the archive file name
has not been given.



'filename': can't add


The file specified by 'filename' doesn't exist or can't be
opened (e. g. is locked).



'filename': can't create


The archiver could not generate a local file by the name
of 'filename'.  Probably the archiver's internal file
buffer space has been exceeded.



'filename': not in archive


The archiver could not locate the file specified by 'filename' in
the archived file.





AUTHORS

Original code from Kernighan and Plauger's 'Software Tools',
with rewrites by Allen Akin (Georgia Institute of Technology)
and minor changes suggested by David Hanson (University
of Arizona).


BUGS/DEFICIENCIES

On some systems only text files can be archived.

When the update and print commands are used, the files are
updated or printed
in the order they appear on the
archived file, NOT the order listed on
the command line.

The Unix archiver allows files to be positioned in the
archive, rather than simply added at the end as AR does.
This is done by adding the following commands:



m - Move specified files to end of archive

ma posname - Move specified files to position after file 'posname'

mb posname - Move specified files to position before file 'posname'

r - Replace specified files and place at end of archive

ra posname - Replace files and place after file 'posname'

rb posname - Replace files and place before file 'posname'



There are some discrepancies between the Unix version of AR and
this version.  Unix uses 'r'--replace instead of 'u'--update.
Unix also requires the user to specify an additional command 'n'
when creating a new archive.