AR Version 1.9 beta

                          Carl Kreider  71076,76


Ar is a utility modeled loosely after the archive utility in "Software
Tools" the Kernigan & Plauger book.  Its purpose is to gather together
files into a common file to save disk space, keep related files
together, ease the transmission of files by telephone, and other similar
uses.  It preserves file attributes such as last-modify date, creation
date, owner, and permissions.  Ar uses Lempel-Zev compression on text
and binary files, so substantial space savings can result.  Several
versions of the same file can be kept in one archive without file name
contention.  This version runs on OS9 LI and LII, OSK, MSDOS, and UNIX.

The command line syntax is:

  Ar <-command>[options] <archive_name> [file_specification(s)]

The items enclosed in <> are required and those in [] are optional.

The commands operate on the archive in some way:

   d   delete file(s) from the archive
   m   move file(s) to the archive (add and then delete)
   p   print file(s) to standard output
   t   print a table of contents for the archive
   u   update/add file(s) to the archive
   x   extract file(s) from the archive

The options modify the behavior of a command:

   a   include all versions of specified files (affect p,t,x commands)
   bnn set compression to 'nn' bits maximum (affects u command)
   o   make archives compatible with old ar (affects u command)
   s   suppress compression of binaries (affects u command)
   ss  suppress compression of all files (affects u command)
   z   get names of files to process from standard input

Most of these commands and modifiers are obvious, but the detailed operation
is not so obvious.  A version number is kept as part of the header record
associated with each file in the archive.  The current file has a version
number of '0'.  Older versions of files with the same names have succeedingly
greater numbers.  Commands normally operate only on the current version of
each file -- those with a version of '0'. The 'a' option will cause all
versions to be selected.  To avoid name conflicts on extraction, the version
number for all but the current version will be appended to the name of the
created file.

Ar will normally compress binary modules, but these may not compress
well using Lempel-Zev compression.  It is possible for files to actually
grow, although this is less likely as the number of bits used increases.

A file spec can include the meta characters '?' (matches any single character)
and '*' (matches any string of zero or more characters).  Thus the following
examples are valid file specifications:

   *.c    matches ar.c, dir.c, but not dir.h or dir.cc
   ar.?   matches ar.c, ar.h, but not ar.ch
   a*z    matches az, abz, abcz, abcdz, etc.
   *.*    matches anything with at least one dot in it
   *      matches anything and everything

Since the stock OS9 (6809) shell, as well as the MSDOS command.com, does not
expand any meta characters, Ar provides internal expansion of same.  This is
transparent under OSK and UNIX when using Ar for update since it also accepts
a list of files on the command line.  In the case of extraction, deletion, and
printing, we do not want the shell to generate filenames from the current
directory.  In this case, any file specification containing meta characters
must be quoted to protect it from the shell.

Meta characters can be used for files both bound for the archive and for files
to be extracted.  The p, t, and x commands default to '*' if no explicit file
list is given.  The u and d commands MUST have a file spec.  The file
specification can include a path list if it is not absolute.  That is,
'/d0/work/*.c' will not be accepted, but 'work/*.c' will be.  During
extraction, if the directory in the path list of the archived file cannot be
found, it will be created.  Here are some sample command lines:

   ar -pa archfile          print all files, even old versions
   ar -p archfile           print all current files
   ar -p archfile *.c       print all current files with '.c' suffix
   ar -p archfile file.c    print only 'file.c'

The x and t commands would work the same way, but the u command is slightly
different.  Sample command lines follow:

   ar -us archfile *.c      add all files with '.c' suffix without compression
   ar -u archfile *         add ALL files; compress all except modules
   ar -us archfile command  add only 'command', but don't compress it
   ar -u archfile file.c    add only 'file.c'

If a file with the same name as the one to be added exists in the archive
already, the version number of the existing one is incremented and the new
version is added to the end of the archive.  The attribute section of the file
descriptor is saved in the archive and restored to the file (as much as is
possible) on extraction.  OS9 limits this to owner, creation date, last
modified date, and permissions.  Size, of course, will be the same.

Pre-extension is used during extraction to avoid segment table overflow
problems, and will be added to update as soon as the mechanism becomes clear. 

The concatenation of two '.ar' files is still an archive, with certain
limitations.  If a duplicate file with duplicate version appears in both
archives prior to concatenation, only the last one physically in the archive
file will be saved on extraction.  (Both version will actually be extracted,
but the last one will overwrite earlier versions.)  One could, of course,
double the size of Ar with all manner of prompting, perusing, and choosing in
cases like that but I prefer to rely on the inate ability of the user deal
with such problems outside of Ar.

The archive file is opened in update only if necessary, so the last modified
date of the archive is not disturbed by extraction or perusal.  This should go
a long way toward making rational backup of archives possible.

The beta version has been used for a year without bug reports, so I assume
ar v2.00 is now stable.  I do not intend to do a general release of source
code this time, primarily to protect myself from a repeat of the multiple
incompatiple version fiasco of a year to two ago.