.. RST source for alf(1) man page. Convert with:
..   rst2man.py alf.rst > alf.1

.. include:: ver.rst

.. |date| date::

===
alf
===

-------------------------------
create Atari 8-bit ALF archives
-------------------------------

:Manual section: 1
:Manual group: Urchlay's Atari 8-bit Tools
:Date: |date|
:Version: |version|

SYNOPSIS
========

alf [**--help**] | [**--version** | **-V** | [**-a** | **-o** ] [**-t[dgz]**] [**-v**] *alf-file* *file[=NAME]* [*file[=NAME]* ...]

DESCRIPTION
===========

**alf** creates *ALF* archives.

*ALF* is a compressed archive format similar to **arc**\(1), though
not compatible with it. It was used on the Atari 8-bit platform
beginning in the late 1980s. The Atari executables are **LZ.COM**
for the compressor and **DZ.COM** for the decompressor. **alf** is a
rewrite of **LZ.COM** for modern operating systems, with added features.

By default, the *alf-file* is created, and the *file*\s are compressed
and added to it. If *alf-file* already existed, it is backed up by adding
a **~** to the filename.

The **ALF** file format only supports uppercase "8.3" filenames
(Atari DOS or MS-DOS style), and does not support subdirectories. The
filenames you give will be stored in the **ALF** file uppercased
and truncated to fit the 8.3 scheme. This could result in duplicate
filenames in the archive, if you're not careful.

Filenames in the archive can be explicitly set. Each *file* can be
given as *file=NAME*, where *NAME* will be the file's name in the
*ALF* archive. The *NAME* is still uppercased and truncated to 8.3.

OPTIONS
=======

Options can be combined (e.g. **-ov** means **-o** **-v**), though the
**-td**, **-tu**, **-tz** options must appear last (**-tdv** would be
an error; **-vtd** is OK).

-A
  Append to *alf-file*. The files are added to the end of the archive. Be
  careful not to add a file with the same name as as existing member of
  the archive. If *alf-file* doesn't exist, it will be created. No backup
  is made with **-a**.

.. append to ALF file.

-a
  Convert text file line endings and tabs from ASCII to ATASCII. Text
  files are detected by looking at the first 2 bytes of the file. If both
  are printable ASCII, the file is considered text.

.. convert EOLs and tabs in text files.

-aa
  Convert line endings and tabs in *all* input files. This will
  corrupt any executables or non-text data files, so use with caution.

.. convert EOLs and tabs in all input files.

-h, --help
   Show built-in help message.

.. show this help message.

-o
  Overwrite *alf-file* if it exists; do not make a **~** backup.

.. overwrite ALF file if it exists (don't create file~ backup).

-q
  Quiet operation. **alf** won't print any messages on standard
  output. Errors and warnings will still be printed to standard
  error.

.. quiet.

**-td**
  Use default **LZ.COM** timestamps (8 Dec 82  12:24).

.. use default LZ.COM timestamps.

**-tu**
  Use UTC for timestamps (default is local timezone).

.. use UTC timestamps.

**-tz**
  Use zero for timestamps. **unalf** will display *<none>* for the
  date and midnight for the time.

.. use zero timestamps.

-v
  Verbose operation. Shows more information about what **alf**
  is doing. Can be given twice to dump the token tables (*lots* of
  output; for debugging only).

.. verbose (-vv: debug).

-V, --version
  Show **alf** version number and exit.

.. show version number.

--
  End of options. The next argument is treated as the *alf-file* and
  any further options are files to add to the archive.

.. end of options (next arg is alf-file).

.. ENDOPTS

EXIT STATUS
===========

0
  Success.

1
  Fatal error (I/O or bad command-line arguments).

DIAGNOSTICS
===========

Besides the standard error messages such as "no such file or
directory":

Filenames
---------

**filename has underscore, OK on Sparta/MyDOS, not Atari DOS 2.x**
  Not an actual problem, unless you try to extract this ALF file on
  an Atari running Atari DOS 2.0/2.5, or any other DOS that doesn't
  allow underscores in filenames.

**bad Atari filename** *<filename>* *<reason>*
  The filename stored in the ALF header doesn't follow the rules for
  Atari DOS filenames. *<reason>* will be something like "doesn't start
  with A-Z" or "invalid character". The filename will be printed with
  any unprintable characters as hex values (e.g. **$01**).

With either of the above, the resulting *ALF* archive will extract
with **unalf**, but will have problems with **DZ.COM** running on an
Atari. Or you can just rename the files so they comply with Atari DOS
filename restrictions.

**duplicate Atari filename** *<filename>*
  You gave the same filename twice, or you gave two (or more) filenames that
  convert to the same "8.3" Atari filename. Example: *foo.bar* and *foo.barf*
  both get stored as *FOO.BAR*. You can avoid this by using the *file=NAME*
  syntax, e.g.::

    $ alf ARCHIVE.ALF foo.bar foo.barf=FOO.BRF

File Size
---------

**this file is too large; only compressing the first 16MB.**
  The *ALF* file format doesn't support files larger than
  16MB. Actually the *file format* does, but the decompressor
  (either **DZ.COM** or **unalf**) does not.

NOTES
=====

Compatibility
-------------

This **alf** is *intended* to be 100% compatible with the original
Atari **LZ.COM** aka **ALF.COM**, with the following differences:

- There is no interactive mode. The file to create and the files to add
  must be given as command-line arguments.

- **LZ.COM** always appends to a file that already exists. This **alf**
  overwrites (making a backup) by default, and can append with the **-a**
  option.

- **LZ.COM** doesn't handle 0-byte (empty) files correctly, but **alf**
  does. Not that this is very useful.

- Turning the screen off for speed makes no sense on modern operating
  systems, so there's no option for that.

Note that **alf** is a complete reverse-engineered rewrite in C, *not*
a port of the original 6502 code as **unalf** is. It's still being
tested, and may still contain bugs.

A note about the Atari filenames: **DZ.COM** is sometimes found on
old disk images as **UNALF.COM**, and **LZ.COM** is sometimes called
**ALF.COM** or **ALFER.COM**. I've used the original names partly
out of respect for the original author, and partly to avoid confusion
between my **alf**\/**unalf** and his Atari ones.

Compression Characteristics
---------------------------

Larger files compress better than smaller ones. Very small files
will get larger when compressed. Files with lots of entropy (random
garbage, files that are already compressed) will also get larger.

For text files, compression is usually around 45% to 50%, which
is comparable with **arc**. For SAVEd Atari BASIC, the average is
a little worse: 35% to 40%. For executables, it seems to average
around 30%... unless the executables are already compressed (e.g.
self-decompressing), in which case they'll get bigger when compressed
with **alf**.

File Size Limits
----------------

**alf** (and **LZ.COM**) have a 16MB file size limit. This applies to
both the input file size, and the compressed size (in case of files
that grow when compressed, e.g. random data).

Real Atari 8-bit files are never this large anyway, so it's a
pathological case. A real Atari would take hours or even days to
compress/decompress such files, and you'd have to have a hard disk and
a DOS capable of handling multi-megabyte files...

Performance
-----------

Performance is pretty good, as of alftools-0.4.0. For small files
like you'd use on an Atari (up to 50KB), it's basically instantaneous
(0.008 seconds) on the author's modest i7 workstation. For a 1MB text
file, it takes 0.022 sec (faster than **arc**\!). For 1MB of random
garbage, it's 0.03 sec (and the resulting ALF file is 36% larger than
the garbage).

By comparison, **zip** takes 0.06 seconds to compress the 1MB text file,
and 0.03 sec for the 1MB randomness (and the compressed file is still
larger than the input, but only by 312 bytes). **arc**
compresses the text file in 0.03s, and it's smart enough to *not*
compress the random garbage (it uses the 'store' method, which **alf**
doesn't have).

Timestamps
----------

The date/time stamps stored in the archive are the **mtime**\s of the
files (which is the same time **ls**\(1) shows, by default), and your
local timezone is assumed (but see the **-td**\, **-tu**\, **-tz**
options above). There's no way to store timezone or daylight savings
info in the *ALF* file.

The year stored in the *ALF* file doesn't have a Y2K problem. It does,
however, have a Y2108 problem: the range is from 1980 to 2107. Files
with timestamps outside this range will have a zero (invalid) date in the
*ALF* header, and **unalf** will display the date as *<none>*.

The timestamp only has 2-second resolution. Files with odd-numbered
seconds in the *mtime* will have the number before that (1 => 0, 31 =>
30, etc). This is a limitation of the *ALF* file format. Also of the
*ARC* format (I didn't know that, did you?)

COPYRIGHT
=========

The original AlfCrunch (**DZ.COM** and **LZ.COM**) for the Atari 8-bit
was released into the Public Domain. **alf** contains no code from
AlfCrunch.

**alf** is released under the WTPFL: Do WTF you want with this.

AUTHOR
======

The original AlfCrunch for the Atari 8-bit was written by Alfred, who
can be reached via the AtariAge.com forums with the username "Alfred".

This **alf** was written by B. Watson <urchlay@slackware.uk>.

SEE ALSO
========

**unalf**\(1), **alfsum**\(1)

.. include:: manftr.rst
