diff options
Diffstat (limited to 'src/unalf.1')
| -rw-r--r-- | src/unalf.1 | 412 |
1 files changed, 0 insertions, 412 deletions
diff --git a/src/unalf.1 b/src/unalf.1 deleted file mode 100644 index 3343162..0000000 --- a/src/unalf.1 +++ /dev/null @@ -1,412 +0,0 @@ -.\" 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-28" "0.2.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, extracts, or tests 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. The Atari executables are \fBLZ.COM\fP -for the compressor and \fBDZ.COM\fP for the decompressor. \fBunalf\fP is a -port of \fBDZ.COM\fP for modern operating systems, with added features. -.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. -.sp -Only one \fIalf\-file\fP argument is allowed. It\(aqs impossible to process -multiple ALF files per run of \fBunalf\fP\&. If you need bulk extraction, -use e.g. a \fBfor\fP loop in a shell script. -.sp -\fBunalf\fP can\(aqt read an ALF file on standard input; \fIalf\-file\fP must be -a real file. -.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 \-f -Fix (remove) junk at EOF. This option truncates the \fIalf\-file\fP\&. -It is the only \fBunalf\fP option that writes to the input file. No -backup is made. -.UNINDENT -.\" fix (remove) junk at EOF. -. -.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 <wildcard>. may be given multiple times. -. -.\" ENDOPTS -. -.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": -.SS Fatal errors -.sp -\fBunalf\fP will exit with status 1 immediately after these errors: -.INDENT 0.0 -.TP -.B \fBfatal: this is an ARC file, not ALF\fP -Self\-explanatory. Use the \fBarc\fP(1) utility for this file. -.TP -.B \fBfatal: not 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 \fBfatal: stack underrun/overrun\fP -Generally means the archive is corrupt. Valid ALF files should never -cause these errors. -.TP -.B \fBfatal: compressed data is truncated, EOF before end marker\fP -Self\-explanatory. The ALF file ends before the compressed data does. -.UNINDENT -.SS Warnings -.sp -\fBunalf\fP will continue after these messages occur. -.INDENT 0.0 -.TP -.B \fBjunk at EOF (ignoring)\fP -Mostly harmless: does \fInot\fP imply data corruption. -.sp -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 -This message means you can\(aqt append to the ALF file with \fBalf \-a\fP -or \fBLZ.COM\fP\&. You can, however, use \fBunalf \-f\fP to remove the junk. -.TP -.B \fBchecksum error on\fP \fI<file>\fP -The archive is corrupt. If \fI<file>\fP is a text file, it may be -partially readable. If it\(aqs an executable or other binary file, it\(aqs -probably unrecoverable. \fBunalf\fP will try to extract the rest of -the archive, but will exit with status 2 when it\(aqs done. -.sp -If you have an ALF file that does this, try it with the Atari -\fBDZ.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 \fI<file>\fP \fBshould be\fP \fI<size>\fP \fBbytes, but extracted to\fP \fI<size>\fP -The archive is corrupt. If this happens on the last (or only) file, it -probably means the ALF file was truncated. You\(aqll almost certainly -get a checksum error for \fI<file>\fP, too. -.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). -.TP -.B \fBheader #<n> (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. -.TP -.B \fBALF files don\(aqt normally contain other ALF files, are you trying to extract/list multiple ALF files at once?\fP -You gave a \fIwildcard\fP argument that ends with \fI\&.alf\fP\&. This is OK if -your \fIALF\fP file actually contains another \fIALF\fP file, but that would -be a pathological case. Most likely, you\(aqre trying to extract multiple -\fIALF\fP files with one command, which doesn\(aqt work. Use one \fBunalf\fP -command per file. -.UNINDENT -.SH NOTES -.sp -This \fBunalf\fP is 100% compatible with the original Atari \fBDZ.COM\fP -aka \fBUNALF.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 \fBDZ.COM\fP actually use the dates/times -stored in the archive. Extracted files will have their timestamps set -to the current date/time. -.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 \fBunalf\fP and the Atari one. -.SH BUGS -.sp -A minor one: \fBunalf\fP can\(aqt correctly extract files larger than about -15MB. This could be a problem in \fBalf\fP (though the archives look -OK to me), or it could be a bug I introduced when porting \fBunalf\fP, -or it could be a bug in the original \fBDZ.COM\fP\&. Files this large are -a pathological case for \fIALF\fP, anyway, since nobody ever used them on -the Atari 8\-bit. -.SH COPYRIGHT -.sp -The original AlfCrunch (\fBDZ.COM\fP and \fBLZ.COM\fP) for the Atari -8\-bit was released into the Public Domain. Portions of the \fBDZ.COM\fP -code are included in \fBunalf\fP, converted from 6502 instructions to -C macros. -.sp -\fBunalf\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 \fBunalf\fP was written by B. Watson <\fI\%urchlay@slackware.uk\fP>. -.SH SEE ALSO -.sp -\fBalf\fP(1), \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. -. |