ALF(1)

NAME
alf - create Atari 8-bit ALF archives

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 files 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.

-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.

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

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

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

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

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

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

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

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

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

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

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 mtimes 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)

The git repository for alftools: https://slackware.uk/~urchlay/repos/alftools

Other Atari-related projects by the author, including bw-atari8-tools and unmac65: https://slackware.uk/~urchlay/repos/