path: root/src/alf.1

.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "ALF" 1 "2025-11-29" "0.2.1" "Urchlay's Atari 8-bit Tools"
.SH NAME
alf \- create Atari 8-bit ALF archives
.\" RST source for alf(1) man page. Convert with:
.
.\" rst2man.py alf.rst > alf.1
.
.SH SYNOPSIS
.sp
alf [\fB\-\-help\fP] | [\fB\-a\fP | \fB\-o\fP ] [\fB\-t[dgz]\fP] \fIalf\-file\fP \fIfile\fP [\fIfile\fP ...]
.SH DESCRIPTION
.sp
\fBalf\fP creates \fIALF\fP archives.
.sp
\fIALF\fP is a compressed archive format similar to \fBarc\fP(1), though
not compatible with it. It was used on the Atari 8\-bit platform
beginning in the late 1980s. The Atari executables are \fBLZ.COM\fP
for the compressor and \fBDZ.COM\fP for the decompressor. \fBalf\fP is a
rewrite of \fBLZ.COM\fP for modern operating systems, with added features.
.sp
By default, the \fIalf\-file\fP is created, and the \fIfile\fPs are compressed
and added to it. If \fIalf\-file\fP already existed, it is backed up by adding
a \fB~\fP to the filename.
.sp
The \fBALF\fP 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 \fBALF\fP file uppercased
and truncated to fit the 8.3 scheme. This could result in duplicate
filenames in the archive, if you\(aqre not careful.
.SH OPTIONS
.INDENT 0.0
.TP
.B  \-a
Append to \fIalf\-file\fP\&. 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 \fIalf\-file\fP doesn\(aqt exist, it will be created. No backup
is made with \fB\-a\fP\&.
.UNINDENT
.\" append to alf file.
.
.INDENT 0.0
.TP
.B  \-A
Convert line endings and tabs from ASCII to ATASCII in all input
files. This will corrupt any executables or non\-text data files,
so use with caution. There is no way to autodetect text files,
unlike \fBunalf\fP\&.
.UNINDENT
.\" convert EOLs and tabs in all input files.
.
.INDENT 0.0
.TP
.B  \-h\fP,\fB  \-\-help
Show built\-in help message.
.UNINDENT
.\" show this help message.
.
.INDENT 0.0
.TP
.B  \-o
Overwrite \fIalf\-file\fP if it exists; do not make a \fB~\fP backup.
.UNINDENT
.\" overwrite alf file if exists (do not create file~ backup).
.
.INDENT 0.0
.TP
.B \fB\-td\fP
Use default \fBLZ.COM\fP timestamps (8 Dec 82  12:24).
.UNINDENT
.\" use default LZ.COM timestamps.
.
.INDENT 0.0
.TP
.B \fB\-tu\fP
Use UTC for timestamps (default is local timezone).
.UNINDENT
.\" use UTC timestamps.
.
.INDENT 0.0
.TP
.B \fB\-tz\fP
Use zero for timestamps (0 ??? 80  12:00a).
.UNINDENT
.\" use zero timestamps.
.
.INDENT 0.0
.TP
.B  \-V\fP,\fB  \-\-version
Show \fBunalf\fP version number and exit.
.UNINDENT
.\" show version number.
.
.\" ENDOPTS
.
.SH EXIT STATUS
.INDENT 0.0
.TP
.B 0
Success.
.TP
.B 1
Fatal error (I/O or bad command\-line arguments).
.UNINDENT
.SH DIAGNOSTICS
.sp
Besides the standard error messages such as "no such file or directory", \fBalf\fP
can generate warnings about the filenames it\(aqs compressing:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B \fBfilename has underscore, OK on Sparta/MyDOS, not Atari DOS 2.x\fP
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\(aqt
allow underscores in filenames.
.TP
.B \fBbad Atari filename\fP \fI<filename>\fP \fI<reason>\fP
The filename stored in the ALF header doesn\(aqt follow the rules for
Atari DOS filenames. \fI<reason>\fP will be something like "doesn\(aqt start
with A\-Z" or "invalid character". The filename will be printed with
any unprintable characters as hex values (e.g. \fB$01\fP).
.UNINDENT
.UNINDENT
.UNINDENT
.sp
The resulting \fIALF\fP archive will extract with \fBunalf\fP, but will have
problems with \fBDZ.COM\fP running on an Atari. Or you can just rename
the files so they comply with Atari DOS filename restrictions.
.SH NOTES
.SS Compatibility
.sp
This \fBalf\fP is \fIintended\fP to be 100% compatible with the original
Atari \fBLZ.COM\fP aka \fBALF.COM\fP, with the following differences:
.INDENT 0.0
.IP \(bu 2
There is no interactive mode. The file to create and the files to add
must be given as command\-line arguments.
.IP \(bu 2
\fBLZ.COM\fP always appends to a file that already exists. This \fBalf\fP
overwrites (making a backup) by default, and can append with the \fB\-a\fP
option.
.IP \(bu 2
\fBLZ.COM\fP doesn\(aqt handle 0\-byte (empty) files correctly, but \fBalf\fP
does. Not that this is very useful.
.IP \(bu 2
Turning the screen off for speed makes no sense on modern operating
systems, so there\(aqs no option for that.
.UNINDENT
.sp
Note that \fBalf\fP is a complete reverse\-engineered rewrite in C, \fInot\fP
a port of the original 6502 code as \fBunalf\fP is. It\(aqs still being
tested, and may still contain bugs.
.sp
A note about the Atari filenames: \fBDZ.COM\fP is sometimes found on
old disk images as \fBUNALF.COM\fP, and \fBLZ.COM\fP is sometimes called
\fBALF.COM\fP or \fBALFER.COM\fP\&. I\(aqve used the original names partly
out of respect for the original author, and partly to avoid confusion
between my \fBalf\fP/\fBunalf\fP and his Atari ones.
.SS File Size Limits
.sp
\fBalf\fP (and \fBLZ.COM\fP) have a 16MB file size limit. \fBuanlf\fP
actually can\(aqt handle files above about 15MB, if you compress one with
\fBalf\fP\&. Real Atari 8\-bit files are never this large anyway, so it\(aqs
a pathological case. A real Atari would take hours or even days to
compress/decompress such files, and you\(aqd have to have a hard disk and
a DOS capable of handling multi\-megabyte files...
.SS Performance
.sp
Performance is \fIhorrible\fP\&. This shouldn\(aqt be a real problem on
modern multi\-GHz CPU, especially since most Atari 8\-bit files are
small (usually under 64KB). Interestingly, it\(aqs not O(n^2), it scales
linearly, O(1): Compressing a 1.3MB text file takes 0.7 seconds on the
author\(aqs (rather modest) Intel i7 workstation, and a file 10x as large
takes approximately 10x as long (7 seconds). A 50KB file is almost
instantaneous, 0.05 seconds, which is more typical of the files you\(aqd
actually use this with.
.SS Timestamps
.sp
The date/time stamps stored in the archive are the \fBmtime\fPs of the
files (which is the same time \fBls\fP(1) shows, by default), and your
local timezone is assumed (but see the \fB\-td\fP, \fB\-tu\fP, \fB\-tz\fP
options above). There\(aqs no way to store timezone or daylight savings
info in the \fIALF\fP file.
.sp
The year stored in the \fIALF\fP file doesn\(aqt have a Y2K problem. It does,
however, have a Y2108 problem: the range is from 1980 to 2107.
.sp
The timestamp only has 2\-second resolution. Files with odd\-numbered
seconds in the \fImtime\fP will have the number before that (1 => 0, 31 =>
30, etc). This is a limitation of the \fIALF\fP file format. Also of the
\fIARC\fP format (I didn\(aqt know that, did you?)
.SH COPYRIGHT
.sp
The original AlfCrunch (\fBDZ.COM\fP and \fBLZ.COM\fP) for the Atari 8\-bit
was released into the Public Domain. \fBalf\fP contains no code from
AlfCrunch.
.sp
\fBalf\fP is released under the WTPFL: Do WTF you want with this.
.SH AUTHOR
.sp
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".
.sp
This \fBalf\fP was written by B. Watson <\fI\%urchlay@slackware.uk\fP>.
.SH SEE ALSO
.sp
\fBunalf\fP(1), \fBalfls\fP(1)
.sp
The git repository for \fBalftools\fP:
.INDENT 0.0
.INDENT 3.5
\fI\%https://slackware.uk/~urchlay/repos/alftools\fP
.UNINDENT
.UNINDENT
.sp
Other Atari\-related projects by the author, including \fBbw\-atari8\-tools\fP
and \fBunmac65\fP:
.INDENT 0.0
.INDENT 3.5
\fI\%https://slackware.uk/~urchlay/repos/\fP
.UNINDENT
.UNINDENT
.\" Generated by docutils manpage writer.
.