README for utility: ar2

Author: Art S. Kagel, 1990
Version: Features version 1.4, Source revision 1.30
File(s): ar2.c, ar2.mk

Description:

Ar2 was written as a portable ar archiver at a time when GNU ar and GNU tar
were not available or not commonly available so that I could transport
collections of files from UNIX to DOS and back.  Later features were added to
allow me to transport between systems with incompatible versions of ar.  The
main incompatibilities arise from the different handling of long filenames
in BSD and System V derived versions.  BSD systems (notably Ultrix, OSF-1, and
AIX) extended the entry header format to be variable lenght to accomodate
longer names.  System V.4+ systems added a long names table at the beginning of
the file which contains an offset to the actual file entry which has a zero
length name in its actual header.  GNU ar is System V.4 compatible.

Ar2 can both read and write both BSD (-d) and System V (-g) formats although
it cannot append long filename files to an existing System V archive.  In
addition it supports a third long filename scheme of my own, implemented with
the '-i' flag, which is marginally portable to both the other systems.  An
archive created with '-i' can be extracted successfully with ANY ar utility
but the filenames will be truncated (with whatever name clashes that causes)
and a single bogus file named '!' will be left around.  On reading an archive
the header version is automatically detected.

Ar2 does not currently support the initial symbol table entry needed to
support object libraries (ar's primary use) and is intended for source file
transport ONLY.  (Although with the appropriate header option the resulting
library will not be incompatible with OS utilities used to add the symbol
table, ie "ar -s" or ranlib.)  Anyone who feels the need to add this
capability is welcome to do so and feedback the updates to me.


Important:

Note, when compiling, if you do not have getopt on your system simply define
the macro 'nooptarg' to enable another commandline parser built into the source.

Usage:

Since it was originally intended for extraction of archives created elsewhere
extraction is the default operation so that a line like:

ar2 arcfile.ar

will extract the contents of the archive named arcfile.ar.  My archive naming
convention is to use .ar or .ar2 (for -i archives) to distinguish source
archives from object libraries (lib*.a).

The following is the usage report printed by "ar -?" or just "ar":
> ar2

Copyright 1990 through 2011 inclusive
Art S. Kagel
222 Dunhams Corner Rd.
East Brunswick, N.J. 08816

        Written by Art S. Kagel, August 1990.  Portable Version 1.6
        RCS $Revision: 1.37 $
        This program is placed in the public domain for private use only.
        All commercial rights are retained.

Usage:          ./ar2 [-[qmrxtacle]] [-[dgi]] arcname [file1 [file 2 [...]]]

    With no flags ./ar2 extracts files from a UNIX portable archive.

        UNIX "ar" compatible flags (keys), as follows:
        -q      Quick append.  Add file to end.
                (This function will include duplicate copies of files.)
        -m      Move file to archive and remove.
                (This function will include duplicate copies of files.)
        -r      Replace file.  Replace file in archive with another version.
                (Current version replaces all occurances if the file is
                multiply contained in the archive.)
        -x      Extract files.
        -t      List out contents of archive.

        Additional (non-compatible) flags available:
        -a      Append file.  Synonym for -q.
        -e      Extract files.  Synonym for -x.
        -l      List out files.  Synonym for -t.
        -c      Create archive.  CREATE a NEW archive or OVERWRITE an existing
                one!  (q, m, a, & r will also CREATE an archive if none exists.)

        Compatibility options:
        -d      Write archive with BSD compatible headers.  BSD ar handles
                filenames longer than 14 characters by making the file
                header variable length.
        -g      Write archive with System V ar compatible Centralized
                Extended Name table.  Permits names longer than 14 characters.
                Long names cannot be appended to an existing archive in
                this format.
        -i      Write archive with Distributed Extended Name table.
                Permits names longer than 14 characters.  This format extended
                name table may be appended to.
        -A      Write archive in AIX extended name small header format.  Does
                not support files larger than 2GB.
        -B      Write archive in AIX extended name large header format.

BSD, System V, and ar2 Extended format archives are recognized transparently
for listing and extraction.  The -d, -g, and -i options are provided to create
and update such archives.  Only one of these options may be provided.  If none
of -d, -g, -i is provided System V.4 compatibility is assumed.