.\" 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 "UNALF" 1 "2025-11-19" "0.1.0" "Urchlay's Atari 8-bit Tools" .SH NAME unalf \- extract Atari 8-bit ALF archives .\" RST source for unalf(1) man page. Convert with: . .\" rst2man.py unalf.rst > unalf.1 . .SH SYNOPSIS .sp unalf [\fB\-\-help\fP] [\fB\-aehtklLopqtv\fP] [\fB\-d\fP \fIdir\fP] [\fB\-x\fP \fIwildcard\fP] \fIalf\-file\fP [\fIwildcard\fP ...] .SH DESCRIPTION .sp \fBunalf\fP lists or extracts the contents of an \fIALF\fP archive. .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. .sp Extracted files are written to the current directory by default. Existing files are backed up by default (by adding a \fB~\fP suffix to the filename). .sp If one or more \fIwildcard\fP arguments are provided, files will only be listed or extracted if they match one of the wildcards. See \fBWILDCARDS\fP below for details. .SH OPTIONS .INDENT 0.0 .TP .B \-a Convert text file line endings and tabs from ATASCII to ASCII. Text files are detected by looking at the first 2 bytes of the extracted file. If both are printable ASCII (including ATASCII EOL, aka \fB$9B\fP), the file is considered text. .sp Note that \fIonly\fP line\-endings and tabs are converted. Other ATASCII characters are left alone. If you need anything more in\-depth, use \fBa8cat\fP(1). .UNINDENT .\" convert EOLs and tabs in text files. . .INDENT 0.0 .TP .B \fB\-aa\fP Convert line endings and tabs in \fIall\fP extracted files. This will corrupt any executables or non\-text data files, so use with caution. .UNINDENT .\" convert EOLs and tabs in ALL files. . .INDENT 0.0 .TP .BI \-d \ output\-dir Write extracted files to this directory, which will be created if it does not exist. The default is the current directory. .UNINDENT .\" set output directory (created if needed). . .INDENT 0.0 .TP .B \-e Extract files. This is actually a no\-op, as extraction is the default action. .UNINDENT .\" extract files (redundant; this is the default action). . .INDENT 0.0 .TP .B \-h\fP,\fB \-\-help Show built\-in help message. .UNINDENT .\" show this help message. . .INDENT 0.0 .TP .B \-k Keep trailing periods. In most (all?) ALF files, filenames that have no extension are stored with a trailing period, e.g. \(aq\fBFOO\fP\(aq would be stored as \(aq\fBFOO.\fP\(aq. On the Atari, the extracted file would be named \(aq\fBFOO\fP\(aq, so \fBunalf\fP does the same by default. With \fB\-k\fP, the file will be named \(aq\fBFOO.\fP\(aq. .UNINDENT .\" keep trailing periods (dots) in filenames. . .INDENT 0.0 .TP .B \-l List filenames in archive, one per line, but do not extract. Use \fB\-v\fP for more information (file size, etc). Obeys \fIwildcards\fP and the \fB\-x\fP, \fB\-L\fP, \fB\-k\fP options. .UNINDENT .\" list files in archive (filenames only). . .INDENT 0.0 .TP .B \-L Lowercase filenames. Example: \fBFOO.TXT\fP will extract to \fBfoo.txt\fP\&. .UNINDENT .\" use lowercase filenames. . .INDENT 0.0 .TP .B \-o Overwrite files, if they already exist. The default is to rename existing files, adding a \fB~\fP suffix. Note that renaming \fBfile\fP to \fBfile~\fP \fIwill\fP overwrite \fBfile~\fP if it already exists. .UNINDENT .\" overwrite files (do not create file~ backups). . .INDENT 0.0 .TP .B \-p Extract to standard output. All the files that get extracted will be printed to stdout with no delimiters, so this is most useful when only extracting one file. \fB\-q\fP is automatically enabled by this option. .sp \fIWarning:\fP No checking is done to see whether stdout is a terminal. Printing binary files to a terminal is a good way to make a mess. Even text files with the EOLs translated can still contain ATASCII formatting/graphics codes that can confuse your terminal. You have been warned. .UNINDENT .\" extract to stdout (enables -q). . .INDENT 0.0 .TP .B \-q Quiet extraction or testing: do not print "Uncrunching \fIfile\fP" or "Testing \fIfile\fP" messages. Errors and warnings will still be printed. This is the default when \fB\-p\fP is used. This option doesn\(aqt do anything when used with \fB\-l\fP or \fB\-v\fP\&. .UNINDENT .\" quiet: don't print filenames during extraction/testing. . .INDENT 0.0 .TP .B \-t Test archive. Same as extraction, except the files are not written anywhere. .UNINDENT .\" test archive. . .INDENT 0.0 .TP .B \-v Verbose listing of archive contents, with compressed and original sizes, compression ration, date/time stamps, and checksum. The output format is similar to that of \fBarc \-v\fP, minus the \fIStowage\fP column, since \fIALF\fP doesn\(aqt support multiple compression types. The date and time are displayed, but in most .alf files these are the default values of "8 Jan 82 12:24a". .sp Unlike \fB\-l\fP, the \fB\-v\fP listing shows the filenames exactly as stored in the archive (ignores \fB\-L\fP, enables \fB\-k\fP), and always shows all the files (ignores \fIwildcards\fP and \fB\-x\fP). .UNINDENT .\" verbose listing of archive contents. . .INDENT 0.0 .TP .B \-V\fP,\fB \-\-version Show \fBunalf\fP version number and exit. .UNINDENT .\" show version number. . .INDENT 0.0 .TP .BI \-x \ wildcard Exclude (do not list or extract) files matching \fIwildcard\fP\&. See \fBWILDCARDS\fP below. This option can be given multiple times to exclude multiple patterns. .UNINDENT .\" exclude . may be given multiple times. . .SH WILDCARDS .sp Wildcard (aka glob) matching works like it does on the Atari: \fI*.*\fP matches any filename (whether or not it has an extension), and \fI*\fP or \fI*.\fP only match filenames with no extension. .sp A \fI*\fP matches any number of characters (including zero). A \fI?\fP matches a single character. All other characters match themselves, so a wildcard with no \fI*\fP or \fI?\fP must match exactly. .sp Like the Atari, anything in the name or extension following a \fI*\fP is ignored: \fBFOO*BAR.TXT\fP is equivalent to \fBFOO*.TXT\fP, and \fBFOO.T*T\fP is equivalent to \fBFOO.T*\fP\&. \fBFOO*TXT\fP is equivalent to \fBFOO*\fP, and \fIwill not\fP match the file \fBFOO.TXT\fP\&. .sp Unlike the Atari, matching is case\-insensitive. .sp To avoid your shell trying to expand the wildcards, always quote them! Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C unalf filename.alf \(aq*.txt\(aq .ft P .fi .UNINDENT .UNINDENT .SH EXIT STATUS .INDENT 0.0 .TP .B 0 Success. .TP .B 1 Fatal error (I/O or bad command\-line arguments, stack under/overrun). .TP .B 2 Processing completed OK, but at least one file in the archive has a bad checksum. .UNINDENT .SH DIAGNOSTICS .sp Besides the standard error messages such as "no such file or directory": .INDENT 0.0 .TP .B \fBthis is an ARC file, not ALF\fP Self\-explanatory. Use the \fBarc\fP(1) utility for this file. .TP .B \fBnot an ALF file\fP Self\-explanatory. Either the file is too small (less than 29 bytes) or its first two bytes don\(aqt match the \fIALF\fP signature \fB0x1a\fP \fB0x0f\fP\&. .TP .B \fBjunk at EOF (ignored)\fP Usually this is caused by the .alf file being stored on a CP/M disk at some time, or by a dumb file transfer protocol. Either way, the file gets padded to the block size of the filesystem or protocol. Usually, the padding characters are \fB0x1a\fP, aka ASCII control\-Z. .sp If you see this message, you can ignore it. It\(aqs intended to let you know that this .alf file can\(aqt be appended to by the \fBALF.COM\fP aka \fBLZ.COM\fP Atari utility. .TP .B \fBchecksum error on\fP \fI\fP The archive is corrupt. If \fI\fP is a text file, it may be partially readable. If it\(aqs an executable or other binary file, it\(aqs probably unrecoverable. .TP .B \fBstack underrun/overrun\fP Generally means the archive is corrupt. Valid ALF files should never cause these errors. .sp If you have an ALF file that does this, try it with the Atari \fBUNALF14.COM\fP and see if it has the same problem. If it doesn\(aqt, you\(aqve found a bug in \fBunalf\fP, please send me the .alf file via email (see \fBAUTHOR\fP, below). Actually, I\(aqd be interested to see the .alf file even if it doesn\(aqt work on the Atari either. .TP .B \fBbad Atari filename\fP \fI\fP \fI\fP The filename stored in the ALF header doesn\(aqt follow the rules for Atari DOS filenames. \fI\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). .TP .B \fBheader # (compressed|original) size is...\fP Followed by "impossibly large", "suspiciously large", or "too large to fit on a floppy disk". May indicate a corrupt archive, or someone really might have created an ALF file with files this big... though "impossibly large" means >=16MB. \fBunalf\fP can\(aqt extract a file that big. .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. .UNINDENT .SH NOTES .sp This \fBunalf\fP is 100% compatible with the original Atari \fBUNALF14.COM\fP aka \fBDZ.COM\fP, with the following differences: .INDENT 0.0 .IP \(bu 2 There is no interactive mode. The file to extract must be given as a command\-line argument, and the output directory must be given with the \fB\-d\fP option. .IP \(bu 2 This \fBunalf\fP is capable of listing or testing the contents of an archive without extracting it, plus other handy features such as extracting to standard output and text file EOL conversion. .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 Neither this \fBunalf\fP nor \fBUNALF14.COM\fP actually use the dates/times stored in the archive. Extracted files will have their timestamps set to the current date/time. .SH COPYRIGHT .sp \fBunalf\fP is released under the WTPFL: Do WTF you want with this. .SH AUTHOR .INDENT 0.0 .IP B. 3 Watson <\fI\%urchlay@slackware.uk\fP> .UNINDENT .SH SEE ALSO .sp \fBalfls\fP(1) .sp The git repository for \fBunalf\fP: .INDENT 0.0 .INDENT 3.5 \fI\%https://slackware.uk/~urchlay/repos/unalf\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. .