LhA User's Guide Version 1.10 - January 1992 /~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\ /~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\ /~~\___________________________________________/~~\ /~~\___________________________________________/~~\ /~~\__/~~\_________/~~\___________/~~~~~~~~\___/~~\ /~~\__/~~\_________/~~\__________/~~~~~~~~~~\__/~~\ /~~\__/~~\_________/~~\__________/~~\____/~~\__/~~\ /~~\__/~~\_________/~~\__________/~~\____/~~\__/~~\ /~~\__/~~\_________/~~~~~~~~~\___/~~~~~~~~~~\__/~~\ /~~\__/~~\_________/~~~~~~~~~~\__/~~~~~~~~~~\__/~~\ /~~\__/~~\_________/~~\____/~~\__/~~\____/~~\__/~~\ /~~\__/~~\_________/~~\____/~~\__/~~\____/~~\__/~~\ /~~\__/~~~~~~~~~\__/~~\____/~~\__/~~\____/~~\__/~~\ /~~\__/~~~~~~~~~\__/~~\____/~~\__/~~\____/~~\__/~~\ /~~\___________________________________________/~~\ /~~\___________________________________________/~~\ /~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\ /~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\ Written by Stefan Boberg Copyright (c) 1991,92 by Stefan Boberg V1.10 LhA User's Guide Page 1 1 - Introduction LhA is a new and powerful archiver for the Commodore-Amiga computer. It is fully compatible with LHA for MSDOS systems and LhArc for MSDOS, Amiga and *NIX. It is also compatible with LZ, LhArc and LhArcA for the Amiga. LhA sports fast compression and decompression and has several commands and options not found in any other archiver currently available archiver for the Amiga. 1.1 About the manual The manual is divided into three sections, the first section (this one) contains some information related to the program and how it compares to other similar products. The second section is a reference section, where all features, commands and options are explained thoroughly. The last section contains the license agreement, registration details and disclaimers. 1.2 System requirements LhA will run on any Amiga system with at least 512KB RAM and one diskdrive, though 1MB RAM and two diskdrives or harddrive is recommended to get the most out of LhA. LhA will run on any KickStart from version 1.2 and up. If LhA is used on a system with the new KickStart 2.x it will adapt to this and utilize features new to this release. Special care has been taken in the program design to make the program execute as fast as possible on 68020, 030 and 040-processors without sacrificing 68000 compatibility. Currently, LhA requires `arp.library'. 1.4 Terminology ARCHIVE - An archive is a file containing one or more files in a compressed or non-compressed state and related information like file names, last modification date/time, filenotes etc. COMPRESSION - The process of encoding redundant information into data requiring less storage space. There are a multitude of ways you can do this in. LhA uses a modified version of Lempel-Ziv compression with block-adaptive Huffman coding and a dictionary size of 4096 or 8192 characters. COMPRESSION RATIO - The compression ratio figures reported by LhA are calculated as follows: ratio = (1 - (CompressedSize) / (OriginalSize)) * 100. I.e how many percent of the file that was GAINED. Other archivers may use other methods. LHA and ARJ for MS-DOS, for example, calculates the ratio as: ratio = (CompressedSize) / (OriginalSize), i.e. how large the compressed V1.10 LhA User's Guide Page 2 file is compared to the original file. (MSDOSratio = 1-(ADOSratio/100)). The higher the LhA compression ratio is, the better the compression. Most Amiga archivers use the same ratio calculation method as I use. EXTRACTION or DECOMPRESSION - The process of recreating the exact information that was previously compressed (file contents, modification date, filenotes, protection flags, directory structure etc.) SELF-EXTRACTION MODULE (SFX-Module) - This is an archive that is an executable file capable of extracting self-contained files. 1.5 LhA - what is it? LhA is a file archiving program written especially for the Commodore Amiga computer. The primary goal is to provide the Amiga community with a fast, efficient and reliable file archiver. LhA creates and processes archive files with the '.LZH' suffix, and is fully compatible with both MSDOS LhArc and MSDOS LhA, as well as the Amiga LhArc, LZ, and LhArcA. It handles both the old LhArc-style compression (-lh1-, -lh0-) and the new LHA-style (-lh5-, -lh4-). LhA is at the time of release by far the fastest LhArc archive handler, and is more reliable and robust than both LZ and LhArc. Neither LZ nor LhArc even comes close to the speed of LhA. The compression and decompression routines are written entirely in what I'd call very optimized 68000 assembly language. The routines were written directly from scratch in pure 68000 assembler, and did not, as in the other Amiga LZH-archivers, start as a compiled C-program. Because of this, the routines are both smaller and, more importantly, faster than they would have been if I'd used compiler output as source material. You can get an idea of how fast LhA is compared to other archivers by looking at the speed test results in section 1.7.1 of this manual. An even better way to see how fast LhA is, is to try it yourself! Before writing this program I used LhArc a lot, to archive my source codes automatically for example. But since LhArc often behaved in a very weird way when updating archives, sometimes adding files twice, and sometimes not adding files at all, I decided to write an archiver of my own. And this is the result... LZ was no alternative since it did not have the commands I needed (u,f) and was very unreliable at the time. 1.6 What is a file archiver anyway? A file archiver, as the name implies, archives files. It collects the files you specify and stores them all in a single archive-file. Almost all file archivers (including LhA) also V1.10 LhA User's Guide Page 3 compress the files before putting them in the archive-file, so that they occupy less diskspace. When you wish to retrieve some file from the archive, the archiver decompresses the file and restores it's file attributes (Last modification date, time, file comments, protection status etc.). A file archiver can usually also process archive files in different ways, for instance delete files, freshen files, print files etc. See the 'ARCHIVER COMMANDS' section of this manual for an explanation of the different actions LhA is capable of performing. The most common use for a file archiver is for transferring several related files via modem. It would be a very tedious and cumbersome task to transfer for instance every single source file of a big project separately, so why not put them all into one single file? This is where the file archiver comes in, we simply feed the archiver with all the files we wish to transmit, and then just transfer the single archive-file the achiver then creates! Then the receiver just use the archiver to extract all files from the archive-file onto his harddisk (or floppy). Also, if the files were compressed by the archiver, it would take less time to transfer the files as well, which means the phonecall will cost us less. There are of course other uses for a file archiver, you can use it as a harddisk-backup program for example (if you have another harddisk to put the archive file on..), and you can use it to stuff away files you don't use very often, and then when you want to use them you simply extract the files from the archive, and then delete them when you're finished (saves disk space). Personally I use LhA a lot to make automatic backups of my source codes for various projects. The file compression methods vary from very simple, less effective, and fast (Run-Length Encoding, RLE, for instance), to complex, effective and relatively time-consuming methods (Lempel-Ziv-Huffman, LZHUF, as used in LhA). The method used in LZH-Archivers (LZHUF) is to date probably the best algorithm used in an archiver. There are other similar methods, like ZIP, but they are not as good. Even though the files become smaller you don't lose any information when compressing them, the information is just stored in a different way. Basically, redundant (repeated) information is replaced with a pointer to some other part of the file, where this information is located. For example in this text the word 'archive' appears at several places, this is an example of redundant data. Simply put, if a file compressor was to compress this file it would let the first occurence of 'archive' remain unchanged, and then it would replace all other occurences of 'archive' with a pointer to the first one. When decompressing the file, the archiver uses these pointers to restore the file to its original state. Files which have already been compressed with one technique can generally not be compressed any further by feeding them to the same file compressing program again (If that had been V1.10 LhA User's Guide Page 4 possible, modem transfers would have been a lot cheaper :), since the redundant information has already been eliminated. It is possible though to compress files output by certain compressors (RunLength-Encoders for example) further by feeding them to a program that uses another method (like LZHUF), since they eliminate different kinds of redundant information. 1.7 Why should I use LhA? There are several reasons why you should use LhA instead of other archivers for the Amiga; here are some examples: 1) It extracts files faster than any other popular archiver, including LZ, Zoo, LhArcA, PkAZip, Pkax, Arc, and Ape. 2) It compresses files faster than any other archiver, with the exception for Zoo V2.01, which has much looser compression ratio and thus produces much larger archives. 3) It produces smaller archives than any other archiver. Both LZ V1.92 and Zoo V2.10 produces archives which are approximately the same size, but are much slower than LhA on both extraction and compression. 4) LhA has a number of features that no other archiver for the Amiga has, for example the ability to create and maintain multiple-volume archives. 1.7.1 How fast is it? The following tables compares LhA's compression and decompression with several other archivers. The T field shows compression or decompression time in seconds and T(archiver) Q=----------- i.e. how much longer the archiver takes compared T(LhA_lh5) to LhA in -lh5- mode. For example, A Q value of 2 means that the archiver in question takes twice as long as LhA in -lh5- mode to extract/compress all files. The tests were made with a A3000/25Mhz/4M SCRAM/2M CHIP and with all files in RAM:. A special program (`time') was used to measure execution time with the `timer.device'. The times exclude loading and unloading time to more accurately reflect the actual program speed. All tests were made with the programs in their default mode of operation, except for LhA `max' where the optimal command line parameters for the files were chosen by hand (-v0 -Qh64). Extraction speed Archive: `the brown corpus' V1.10 LhA User's Guide Page 5 Type: 3.2MB of text, binary and graphics data in 21 files +-----+-----+-----+-----+-----+-----+-----+-----+------+------+ | LhA | LZ | LhA | LZ |LhArc| Zoo |Zoo | Zoo |PkAZip| Pkax | | |V1.92| |V1.92| |V2.01|V2.1 |V2.1 |V1.02 | V1.0 | |-lh5-|-lh5-|-lh1-|-lh1-|-lh1-| old |old |-lh5-| imp. |crunch| +--+-----+-----+-----+-----+-----+-----+-----+-----+------+------+ |T |13.3 |27.0 |36.0 |51.2 |90.5 |24.2 |76.1 |57.5 | 45.0 | 51.1 | +--+-----+-----+-----+-----+-----+-----+-----+-----+------+------+ |Q | 1.00| 2.03| 2.71| 3.85| 6.80| 1.82| 5.72| 4.32| 3.38| 3.84| +--+-----+-----+-----+-----+-----+-----+-----+-----+------+------+ Archive: `dlgmsgs.lha' Type: 760K text file. +-----+-----+-----+-----+-----+-----+-----+-----+------+------+ | LhA | LZ | LhA | LZ |LhArc| Zoo |Zoo | Zoo |PkAZip| Pkax | | |V1.92| |V1.92| |V2.01|V2.1 |V2.1 |V1.02 | V1.0 | |-lh5-|-lh5-|-lh1-|-lh1-|-lh1-| old |old |-lh5-|impld.|crunch| +--+-----+-----+-----+-----+-----+-----+-----+-----+------+------+ |T | 3.1 | 6.4 | 9.2 |13.1 |21.8 | 5.9 |19.3 |14.1 | 11.2 | 13.8 | +--+-----+-----+-----+-----+-----+-----+-----+-----+------+------+ |Q | 1.00| 2.07| 2.97| 4.23| 7.03| 1.90| 6.22| 4.54| 3.61| 4.45| +--+-----+-----+-----+-----+-----+-----+-----+-----+------+------+ Compression speed Archive: `the brown corpus' Type: 3.2MB of text, binary and graphics data in 21 files +-----+-----+-----+-----+-----+-----+-----+------+------+------+ | LhA | LZ | LhA | LZ |LhArc| Zoo | Zoo |PkAZip|LhArcA| LhA | | |V1.92| |V1.92| |V2.01|V2.1 |V1.02 |V1.01 | V1.0 | |-lh5-|-lh5-|-lh1-|-lh1-|-lh1-| old |-lh5-| imp. |-lh1- | max | +--+-----+-----+-----+-----+-----+-----+-----+------+------+------+ |T | 208 | 396 | 205 | 285 | 571 | 76 | 512 | 394 | 386 | 206 | +--+-----+-----+-----+-----+-----+-----+-----+------+------+------+ |Q | 1.00| 1.90| 0.99| 1.37| 2.75| 0.37| 2.46| 1.89| 1.86| 0.99| +--+-----+-----+-----+-----+-----+-----+-----+------+------+------+ Resulting sizes : LhA -lh5- 1139622 1.0000 LZ -lh5- 1139178 0.9996 LhA -lh1- 1199680 1.0527 LZ -lh1- 1199209 1.0523 LhArc -lh1- 1248729 1.0957 LhArcA -lh1- 1248729 1.0957 PkAZip Impl. 1196698 1.0501 Zoo -lh5- 1140114 1.0004 Zoo old 1491922 1.3091 LhA max 1136244 0.9970 (-Qh64) Archive: `dlgmsgs.lha' Type: 760K text file. V1.10 LhA User's Guide Page 6 +-----+-----+-----+-----+------+-----+------+------+------+ | LhA | LZ | LhA | LZ |LhArc | Zoo | Zoo |PkAZip|LhArcA| | |V1.92| |V1.92| |V2.01|V2.1 |V1.02 |V1.01 | |-lh5-|-lh5-|-lh1-|-lh1-|-lh1- | old |-lh5- |impld.|-lh1- | +--+-----+-----+-----+-----+------+-----+------+------+------+ |T |30.5 |78.0 |39.8 |63.4 |115.4 |15.8 |120.8 | 45.3 | 84.1 | +--+-----+-----+-----+-----+------+-----+------+------+------+ |Q | 1.00| 2.56| 1.30| 2.07| 3.78| 0.52| 3.96| 1.49| 2.76| +--+-----+-----+-----+-----+------+-----+------+-------------+ Resulting sizes : LhA -lh5- 274648 1.0000 LZ -lh5- 274635 1.0000 LhA -lh1- 293076 1.0671 LZ -lh1- 293084 1.0671 LhArc -lh1- 303100 1.1036 LhArcA -lh1- 303100 1.0957 PkAZip Impl. 278837 1.0153 Zoo -lh5- 274839 1.0001 Zoo old 420212 1.5300 LhA max 273383 0.9954 (-Qh64) 1.8 Compatibility and Amiga-specific features LhA is aimed at full compatibility with LHA V2.12 for MS-DOS, which is an improvement of the original LhArc V1.13. LhA is also compatible with LhArc, LhArcA and LZ for the Commodore Amiga computer. However, LhArc and LhArcA cannot process any archives with headers of level 1 or 2, or files compressed with the new LHA compression (-lh5-). LZ 1.92 cannot process archives with headers of level 2. LHA V2.12 can process all archives created by LhA. The OS-ID stored in level 1 and level 2 headers is `A' for Amiga. The only OS-IDs I know of currently are: ID Operating system --- ---------------- `A' AMIGA `F' OS-9 / FLEX `H' Human68K `K' OS-9 / M68K `M' MS-DOS `m' Mac OS `U' UNIX `2' OS/2 `3' OS-386 `9' OS-9 V1.10 LhA User's Guide Page 7 The OS-ID indicates on what operating system the archive was created. If an entry in an archive has an OS-ID other that `A', LhA will ignore the file attributes and other OS-specific fields and use the default attribute / whatever. If LhA encounters an extended data-field it does not recognize it issues a warning and continues processing. The warning does not generate any return code (if nothing goes wrong LhA returns 0 as the return code). The LhA-specific extended data structures in the level 2 and level 1 headers are laid out as follows: +------------------+ | DISPLAY FILE | |------------------| | 0x0003 [Length] | | 0x70 [ID Byte] | +------------------+ This extension is used to flag files that should be displayed upon extraction. +------------------+ | FILENOTE | +------------------+ | WORD [Length] | | 0x71 [ID Byte] | | char[] [Notestr] | +------------------+ Obviously, this extension is used to store filenotes in level 1 and level 2 headers.. In level 0 headers the filenote is stored in another way. NOTE The evaluation version of LhA is currently only able to create archives with headers of level 0. 1.9 About the author program history and future I, Stefan Boberg - the author of the programs in the LhA family, am 19 years old and studying `applied physics and electrical engineering', first year, at the Linköping Institute of Technology. I started working on LhA mainly because I thought there was no real good archiver for the Amiga, the ones that existed at the time (June 1991) I began work on it were either too slow, had loose compression ratios or were bugged/crippled so that they could not do what I needed an archiver to do. I use archivers mainly to back up sources for my various programming projects automatically, and I also use it a lot to just V1.10 LhA User's Guide Page 8 decompress archives from bulletin board systems and computer networks. Another reason for doing it was to earn a little extra money, which I badly need, being a poor student with a _small_ allowance.. :) Anyway, I intend to continue developing LhA and the related programs as long as I can, and will release other, related, programs as well, like an intuition- driven archiver called `LhI' for instance. A file system to enable you to treat archives as directories is also in the pipeline and will be released sometime in 1992. Other archive formats than LhA-style archives will also be supported in the filesystem and intuition driven archiver by means of special resident libraries and handlers. When these will be finished depends on how much time I can devote to developing the programs (have to take care of my studies you know). But this all depends on YOU, if I get a good response and people register I will continue work on the program. If not, well, then I might as well drop it for other projects, and just make minor bugfixes to it instead of continuing development... It's your choice! If you would like to express your opinions about the program, or have an idea for a feature you'd like to see in the next version, please drop me a line via EMail (see section 3 for addresses) or write a letter. I would really appreciate it! You MUST report any bugs you find (though I hope you won't find any), so I can fix it right away! V1.10 LhA User's Guide Page 9 2 Reference guide This section of the manual is intended to be used mostly as a reference guide when you want to know exactly how a certain option or command works. If you haven't used LhA before (but used other archivers), you should at least glance through the descriptions of all the commands and options to get an idea of what LhA can do. 2.1 Command line syntax The command line syntax is as follows: LhA [-options] [[HomeDir] FileSpec] [@file] [destdir] The items in square brackets are optional, and the items in angle brackets are mandatory. Read the following sections for exact information on the various items. 2.1.1 Specifying options Unlike other archivers, LhA lets you specify options anywhere on the command line. The option specifier is `-' (dash), any items on the command line that begins with this character are considered to be option switches. If you want to specify a filename or something else that begins with a `-' character, enclose the name in double quotes or use double dashes. For example, to specify a filename of `-minus', you could write either `"-minus"' or `--minus'. If you write `-o' the option `o' is enabled regardless of its initial state. If you want to disable an option, append a `0' (zero) after the option, like in `-o0'. If an option is followed by any other numeric character than `0', the option is enabled. You can specify multiple options without having a dash in front of every option character. An example would be `-ox0m', which would enable option `o', disable option `x' and enable option `m'. The only exception is options taking multi-digit numeric arguments, which must be followed by whitespace and another dash if you want to specify more options (like in `-b32 -ox0m'). 2.1.2 Specifying commands The first non-option argument on the command line MUST be the command specifier. The commands are case-insensitive (`l' means the same thing as `L'), and only the first character of the argument is considered (except for the `vv', `mb' and `mf' commands), so you may use verbose commands such as `list' or V1.10 LhA User's Guide Page 10 `add' instead of `l' and `a', respectively. 2.1.3 Specifying archives The archive specification must be the second non-option argument (the first being the command specification). In most cases you can specify a pattern here. The exception being the `m' (move files to archive) command. 2.1.4 Specifying action files The action files are specified after the archive specification. The action file specifications may include pattern matching tokens. Note that, as all other file specifications in LhA, action file specifications may contain wildcards for directory names as well - `hd:*/*/dir/*.h' is valid, for example. NOTE If you do not specify any action files, LhA assumes that you wish to act upon all files in the archive or in the current directory. 2.1.5 Home directories Home directories is a new concept introduced with LhA, it provides an easy way of specifying what parts of pathnames that should be preserved in the archive. It can also be used to simplify specifications of mutiple files in the same directory. It is perhaps best explained with a couple of examples: EXAMPLE Example 1: lha -x a newarc dh0:files/ file1 dir1/file2 dir2/file3 dh0:files2/ *.c This would add the following files to `newarc.lha': Added file(s) Stored as ----------------- -------------- dh0:files/file1 file1 dh0:files/dir1/file2 dir1/file2 dh0:files/dir2/file3 dir2/file3 dh0:files2/*.c *.c Example 2: lha -r a newarc hd:tmp/ *.c *.h hd:px/ *.s *.snd *.iff V1.10 LhA User's Guide Page 11 This would add all `.c' and `.h' files in `hd:tmp' and it's subdirectories, storing pathnames, but excluding the `hd:tmp' part. For instance, the file `hd:tmp/src/foo/arargh.c' would be stored in the archive with the name `src/foo/arargh.c'. Additionally, all `.s', `.snd' and `.iff' files in `hd:px' and its subdirectories will be added, excluding the `hd:px/' part of the name. Homedir specifications must end in `/' or `:', otherwise they won't be recognized as such. Homedir specifications may contain wildcards and other pattern matching tokens. NOTE You are not supposed to include the home directory name in the action file specifications after the home directory spec. I.e. you should not enter `devs:printers/ devs:printers/*HP*', but `devs:printers/ *HP*' is correct. The home directory remains active for the rest of the command line or until the next home directory specification. If you want to set the home directory to the current directory (as it is from the beginning), use a single slash (`/') as a home directory specification. This means you cannot use a single slash to specify the parent directory, to do this you will have to add an additional slash (`//' means parent directory, `///' the parent's parent directory and so on). 2.1.6 Recursive file collection When collecting files recursively (by using the -r option with a or u commands), action file specs are treated somewhat differently. Home directories work the same way as usual. In recursive file collection mode, the last node of the action file specification (i.e. the file name part) is used as a pattern that is compared to all files in the specified directory and its subdirectories. Some examples to hopefully clarify the somewhat fuzzy description: EXAMPLE Example 1: lha -r a myarc * V1.10 LhA User's Guide Page 12 This will add all files in the current directory and its subdirectories to `myarc.lha'. Example 2: lha -r a myarc *.c *.cpp Will add all `.c' and `.cpp' files in the current directory and its subdirectories to `myarc.lha'. Example 3: lha -r a myarc ram:work/* hd:tmp/*.c Will add all files in `ram:work' and its subdirectories - as well as all `.c' files in `hd:tmp' and its subdirectories - to `myarc.lha'. The full pathnames will be stored (excluding the device specification of course). Example 4: lha -r a myarc ram:work/ * hd:tmp/ *.c Will do exactly the same as example 3, but LhA will not store the `ram:work/' and `hd:tmp/' parts of the filenames in the archive. (Because of the home directory specifications). Example 5: lha -r a myarc ram:dir1 ram:makefile Will archive all files in the directory `dir1' and its subdirectories, as well as the file `ram:makefile'. Example 6: lha -r a myarc ram:dir1 ram:(makefile) Will do almost the same as example 5, but will archive ALL `makefile's in ram: and all it's subdirectories (because of the parentheses - see note below). NOTE Explicitly specified directories (explicitly = without pattern matching) will be treated as `dirname/*', i.e. all files in the directory and it's subdirs will be archived. Explicitly specified files will only be looked for in the current home directory, unless the filename is enclosed in parentheses, in which case the file will be looked for recursively. I have chosen to V1.10 LhA User's Guide Page 13 implement it this way because LhA can then be used better together with directory utilities such as Browser or DirectoryOpus. 2.1.7 Specifying destination directory You can optionally specify a destination directory for the files written by the extract commands by writing the desired directory name anywhere after the archive name on the command line. If no destination directory is specified, LhA will use the current directory as the destination. The destination directory specification must end in `:' or `/', just like home directory specifications, or LhA would not be able to distinguish directory names from action file specs. EXAMPLE `lha x corpus ram:' would extract the contents of `corpus.lzh' to ram:. `lha x project *.c dl:tmp/' would extract the contents of `project.lzh' to the `dl:tmp' directory. and so would `lha x project dl:tmp/ *.c'. NOTE You can specify a directory that does not already exist as the destination, LhA will automatically create the directory for you. 2.1.8 `@'-files `@'-files are files that are treated as if their contents were written on the command line. They can be used to specify files, options commands and anything else can be specified on the command line. An example would be the command `lha -r e arc.lzh *.[chas] @filelist ram:', which would extract all files matching `*.[chas]' or the files listed in `filelist' to ram:. Carriage returns and linefeeds in `@'-files are treated as whitespace. 2.1.9 LhA limitations LhA has been written to be as flexible as possible, but there are some limitations that you should be aware of as a user: o LhA pathnames are currently limited to 255 characters. o When headers of level 0 are used, filenotes may not be longer than 230-{filename length (including path)} characters. With V1.10 LhA User's Guide Page 14 header level 1 or 2 filenotes may be up to 255 characters (AmigaDOS currently only supports filenotes of max 80 characters so this should not be any problem except with exceptionally long filenames and paths). o The number of files in an archive files are only limited by available disk space. o The number of arguments on the command line is only limited by available RAM memory and the used shell. o The allowed number of wildcard-matched files is only limited by available RAM memory. Any number of files may be extracted or added to an archive in one go. o Level 2 headers must not be longer than 256 characters, or LhA will not be able to process them. V1.10 LhA User's Guide Page 15 2.3 Pattern matching This section describes how LhA handles pattern matching and file collection. For a discussion on what commands will accept file patterns, please refer to section 2.1 (Command line syntax). Pattern matching in LhA is always case-insensitive. (i.e. it doesn't matter if you write names in upper- or lowercase, `a' will match both `a' and `A'. 2.3.0 Exactly what is pattern matching anyway? Pattern matching is a means of specifying several files in an elegant and relatively straightforward manner. Instead of just lining up all the file names you would like to work on on the command line (which can be very tedious when a lot of files are involved) you can use a technique called `pattern matching'. With this technique you - as the name implies - use the fact that the names of the files you wish to work on often share certain characteristics. For example, the names of files containing C-source almost always end in `.c', so if you would like to add all C-source files in the current directory you could take advantage of this fact by specifying a pattern to that matches these files (in this case such a pattern would be `*.c'). Exactly how these patterns are built up are explained in section 2.3.1 forward. Also read the sections explaining `how to specify action files' and `how to specify archive files'. 2.3.1 Accepted pattern tokens LhA accepts all valid KickStart 2.x and 1.x pattern tokens, it also accepts all ARP tokens (works more or less the same way as KS2.x). In the explanations that follow, the term `expression' means either a single token or character (such as `x' or `?'), or an alternation (such as `(ab|cd|ef)'), or a character class (such as `[a-z,A-Z]'). 2.3.1.1 Question mark (?) The question mark matches any one _single_ character. The question mark is sometimes also referred to as the `wildchar'. EXAMPLE `d?' : matches all two-letter names beginning with a `d' character. For example `dm' or 'd8'. `ab?d' : matches all four-letter names beginning with `ab' and ending in `d'. For example `abcd', `abad' and `ab_d' V1.10 LhA User's Guide Page 16 but not `abd' or `acid'. `f??' : matches all three-letter names beginning in `f'. For example `foo', `fel', `fan' but not `ab', `f18' or `fini' 2.3.1.2 Star/Asterisk (*) The star matches any sequence of any length, including sequences with length zero (i.e. the null string). The `*' character is often called the `wildcard' character. EXAMPLE `a*' : matches all names starting with an `a', for example `abba', `anette'. `a*z' : matches `auugaz', `awacz' and `az' and any other names starting with an `a' and ending in `z'. `s*f*n' : matches `stefan', `staffan', `steffen', `sfn' or any other name starting with an `s', followed by any number (including zero) of arbitrary characters, followed by an `f', and ending in `n'. `*.lzh' : matches all names ending in `.lzh' 2.3.1.3 Hash mark (#) The hash mark matches a subsequent expression (pattern) 0 or more times. The simplest example of this is `#?' which will match any filename. EXAMPLE `#a' : matches any name consisting of the `a' character only. For example `aaaa' and `a'. `b#ad' : matches any name beginning in `b', followed by any number (including 0) of `a' characters, and ending in `d'. For example `bad', `bd' and `baaaad'. 2.3.1.4 Square brackets ([]) The square brackets enclose a set of characters to match. They are a bit like the parentheses but match single-characters only. You can either specify just the letters you would like the expression to match, as in `[abcx]' (this would match `a', `b', V1.10 LhA User's Guide Page 17 `c' and `x'), or you can specify ranges, like `[a-c,x-z]' (which would match `a', `b', `c' and `x', `y', `z'). EXAMPLE `prg.[1-9]' : matches any five-letter name beginning with `prg.', followed by a non-zero digit. For example `prg.1', 'Prg.8'. `Ver_[1-2].[0-9].[a-z]' : matches any nine-letter name beginning with `ver_' followed by either a `1' or a `2' character, followed by a dot (`.'), a digit and finally a character between `a' and `z' (i.e. all letters in the english alphabet). For example `Ver_1.2.a', `Ver_2.9.d'. `#[a-z 0-9]' matches any name containing any number of alphanumeric characters (i.e. either in the alphabet or numeric). For example `ados' or `PDP11'. It does not match `AXE.dat' however, since it contains a `.' which is not in the specified character range. `*.[chas]' : matches any name ending in `.c', `.h', `.a' or `.s'. 2.3.1.5 Parentheses and the vertical bar Parentheses can be used to achieve several things. The first way of using them is just like in mathematics - to group several individual expressions into one single expression. The other way is to provide a list of acceptable expressions separated with `|' chars. The entire parenthesized expression is treated as one token by other tokens (like `#' and `~'). These two are actually the same, since the first is just a special case of the second use. This is easier to explain with a couple of examples: EXAMPLE `(abc|def|xyz)' : will match names `abc', `def' and `xyz' and no other. `*.(doc|prf|man)' : will match all names ending in `.doc', `.prf' or `.man'. `~(pfile)' : will match all names except `pfile'. (NB: this expression is NOT the same thing as `~pfile', see section 2.3.1.6 for details) `(*.c|*.h|*.doc|ab*)' : will match all files ending in `.c', `.h' or `.doc' and all files beginning with `ab'. V1.10 LhA User's Guide Page 18 Typing an action-file spec of `(xxx|yyy|zzz)' is functionally equivalent to writing `xxx yyy zzz' (xxx, yyy, zzz can be any valid patterns, including patterns with parentheses). Parentheses can be nested. 2.3.1.6 Tilde (~) The tilde negates the immediately following expression. It negates ONLY the immediately following token or paranthesized expressiom, not the entire following expression as some people think. EXAMPLE `~x?' : matches any two-letter name except those starting with `x'. For example `ah', `ko' or 'ba' but not 'x0' or 'xi'. `~(x?)' : matches anything except two-letter names starting with `x'. For example `xaa' or `ab' but not `xa' or 'x9'. `~(#?)' : matches nothing at all. (The tilde negates the `#?', which matches all names). `~lha' : matches all strings that doesn't begin with `l', and ends in 'ha'. For example `uha', `why_lha' but not 'lumbha' or 'lha'. 2.3.1.7 Percent sign (%) The percent sign represents the empty string. i.e. it matches 0 characters always. It is only useful in parenthesized expressions and must not follow a the `#' token (`#%' would be a rather pointless pattern, since the % always matches exactly 0 characters). EXAMPLE `lha(.doc|.man|%)' : matches `lha.doc', `lha.man' and `lha'. `l%u%a' : matches `lua' only; the percent signs are totally irrelevant here and can just as well be removed. V1.10 LhA User's Guide Page 19 2.4 Commands This section describes the commands for archive manipulation and maintenance LhA offers to you. See section 2.1.2 (Specifying commands) for details on how to specify commands on the command line. 2.4.1 `a' Add files to archive Obviously, this command adds a number of files to one or more archives. If the specified archive does not already exist, then it will be created. You cannot add files to an archive if these already exist in the archive. If you attempt to do so, a warning will be issued, but LhA will continue adding the other files you have specified. Only the filenames are stored by default, if you want to preserve some disk structure and directory names, you will have to use the -x option to turn path preservation on. If you want to archive entire subdirectories recursively you can use the -r option, which will turn on the -x option automatically. These options are explained in section 2.5. EXAMPLE `LhA a myarchive dict.txt' would add the file `dict.txt' to the archive `myarchive.lha'. `LhA a arc.lzh *.c *.h' would cause all files in the current directory ending in `.c' or `.h' to be added to the archive `arc.lzh' `LhA -r -0 arch *.c' would cause all `.c' files in the current directory and all it's subdirectories to be added to the archive `arch.lzh' using the -lh1- (LhArc 1.x) compression method. `LhA -r archive src:(lharca|lha)/*.[cha] asrc:*.asm' would cause all `.c', `.h' and `.a' files in the `src:lharca' and `src:lha' directories and subdirectories, as well as all `.asm' files in the `asrc:' directory, to be added to the archive `archive.lha'. 2.4.3 `d' Delete files from archive This command removes one or more files from an archive. NOTE V1.10 LhA User's Guide Page 20 Files deleted with the `d' command cannot be recovered from the archive file in any way. Once a file is deleted from an archive it is gone forever. 2.4.4 `e' Extract files from archive This command is used to extract files from an archive. It works just like the `x' command, except this command takes the `-x' option into consideration (the `x' command assumes it is set). If the `-x' option is disabled, files are extracted without their pathnames, and if it's enabled LhA will extract all files with the pathnames and create the needed directories if they do not already exist. EXAMPLE `lha -x0 e foo.lzh ram:' will extract all files from the archive `foo.lzh' to ram:, without paths (all files will be put in the ram: root directory). `lha x foo.lzh *.c ram:' will extract all files ending in `.c' to ram:, with paths - i.e. it will recreate the original directory structure. See the tutorial section for more examples 2.4.5 `f' Freshen files in archive This command is used to freshen files in an archive. I.e. replace older files in the archive with new files from the current directory. Pathnames are considered unless the `-x' option is disabled explicitly (with `-x0'). This command never adds any files to an archive, it just replaces those files that have older modification dates than the corresponding files in the current directory. EXAMPLE `lha f /aab/lha' will freshen all files in the archive '/aab/lha.lha'. `lha f /aab/fsys *.[ch]' will freshen all `.c' and `.h' files in the archive '/aab/fsys.lha'. This command automatically enables the `-x' option unless it is explicitly disabled on the command line with `-x0'. 2.4.8 `l' List archive contents (terse) V1.10 LhA User's Guide Page 21 This command gives a terse list of the contents of an archive file, including file names (without paths), original and compressed length, last modification date and compression ratio. Files with pathnames are indicated by having a `+' character in front of the name. See example below. Filenotes are NOT displayed when using this command, use the `v' or `vv' command to display those. The action file specification is used to determine what files to list. If no filespecs are given, all files will be listed. EXAMPLE 1> lha -N l dl:c64new Listing of archive 'dl:c64new.lzh': Original Packed Ratio Date Time Name -------- ------- ----- --------- -------- ------------- 36098 26979 25.2% 20-Oct-91 22:40:16 +Stormlord 482 293 39.2% 20-Oct-91 22:41:36 +Stormlord.info 23016 12100 47.4% 21-Oct-91 08:28:18 PlaySID -------- ------- ----- --------- -------- 59596 39372 33.9% 25-Oct-91 21:22:48 3 files The `+' (plus) signs in front of the first two names indicate that the file has a path which is not displayed with the `l' command (use the `v' or `vv' command to display pathnames as well). The `-N' suppresses the copyright notice. 2.4.9 `m' Move files to archive This command works just like the `a' command, but the source files are deleted after successfully adding them to the archive. EXAMPLE `lha m includes.lzh src:*.[hi]' will move all files in directory `src:' having filenames ending in `.h' or `.i' to the archive `includes.lzh'. `lha m myarc.lzh lhb_log.911012 lhb_idx.911012' will move the two specified files (`lhb_log.911012' and `lhb_idx.911012') to the archive `myarc.lzh'. 2.4.14 `p' Print files to stdout This command works just like the extract (`e', `x') commands, but sends the extracted output to stdout (normally the console or V1.10 LhA User's Guide Page 22 output redirection file). 2.4.17 `t' Test archive integrity This command tests the specified archives integrity by extracting the files they contain to nowhereland, i.e. the data is decompressed only, not written to any file. This command only works on entire archives, i.e. you cannot just test one file in an archive. If this command fails, the archive is corrupted, and a warning return code is returned. EXAMPLE `lha t work:arcs/*' will check the integrity of all archives in directory `work:arcs'. `lha t s:envarc.lzh' will check the integrity of `s:envarc.lzh' `lha -R t dh0:*' will check the integrity of all archives on the `dh0' volume (`-R' = Collect archives recursively). 2.4.18 `u' Update archive As the command name implies, this command updates archives. It adds files that are not yet in the archive and replaces existing but older files. The last modification date for files are used to determine which file is the newest one. EXAMPLE `lha u /aab/lha.lzh *.c' will update archive `/aab/lha.lzh' with all `.c' files in the current directory. 2.4.19 `v' List archive (verbose) This command works just like the `l' command, but displays the full pathname of the file, while `l' only displays the name node without path. Another difference between `l' and the `v'/`vv' commands is that the `l' command does not show filenotes. Filenotes are displayed on a separate line with a colon (`:') in front of it, just like the AmigaDOS `list' command. The action file specification is used to determine what files to list. If no filespecs are given, all files will be listed. EXAMPLE 1> lha -N v dl:c64new V1.10 LhA User's Guide Page 23 Listing of archive 'dl:c64new.lzh': Original Packed Ratio Date Time Name -------- ------- ----- --------- -------- ------------- 36098 26979 25.2% 20-Oct-91 22:40:16 S/Stormlord 482 293 39.2% 20-Oct-91 22:41:36 S/Stormlord.info 23016 12100 47.4% 21-Oct-91 08:28:18 PlaySID : New version with `equalizers' -------- ------- ----- --------- -------- 59596 39372 33.9% 25-Oct-91 21:22:48 3 files The `-N' suppresses the copyright notice. 2.4.20 `vv' List archive (full) This command is just like the `v' command, but displays all available information in a slightly different format. The original and packed size, last modification date and compression ratio is listed just as with the `v' command, plus file attributes (`Atts'), compression method, file CRC and DOS ID for the OS the files were compressed on. If no DOS ID is given in the archive (header level < 1), a question mark is displayed. The currently known DOS IDs are `A' and `M', where `A' is for AmigaDOS and `M' is for MS-DOS. The filename including path is displayed on a separate line. File notes are displayed in the same way as the `v' command does it, on a separate line after the filename. The action file specification is used to determine what files to list. If no filespecs are given, all files will be listed. EXAMPLE 1> lha -N vv dl:c64new Listing of archive 'dl:c64new.lzh': Original Packed Ratio Date Time Atts Method CRC DOS -------- ------- ----- --------- -------- -------- ------ ---- --- S/Stormlord 36098 26979 25.2% 20-Oct-91 22:40:16 ----rwed -lh1- 2093 ? S/Stormlord.info 482 293 39.2% 20-Oct-91 22:41:36 ----rwed -lh1- 710E ? PlaySID 23016 12100 47.4% 21-Oct-91 08:28:18 ----rwed -lh5- 89FF ? : New version with `equalizers' -------- ------- ----- --------- -------- 59596 39372 33.9% 25-Oct-91 21:22:48 3 files The `-N' option suppresses the copyright notice. V1.10 LhA User's Guide Page 24 2.4.21 `x' Extract files with path This command is exactly the same as the `e' command, but it always extracts files with paths (i.e. same as using the `e' command with `-x' option on), regardless of the state of the `-x' option. V1.10 LhA User's Guide Page 25 2.5 Options This section describes the various options that are available to you when using LhA. For a detailed explanation on how to enable/disable specific options and where you can specify options, see section 2.1.1. The letters in parantheses indicate what commands the options affect. Code Commands ----- ------------ (add) a,u,f (all) all commands (ext) e,x (upx) a,u,f,e,x (upd) a,u,f,d 2.5.1 `-a' (upx) Preserve file attributes This option, when enabled, will make LhA store and restore file protection flags. The eight attributes are listed below: r: Read - This flag is set for files which are readable (a file is read-protected if the flag is unset). w: Write - This flag is set for files which are writeable (a file is write-protected if the flag is unset). e: Execute - This flag is set for files which are executable (binary load files or shell scripts must have this bit set). d: Delete - This flag is set for files which are deleteable (a file is protected from deletion if this flag is unset). a: Archived - This flag is used by harddisk-backup programs (and optionally LhA) to indicate what files have been changed since the last backup. If this flag is set it indicates that the file is unchanged, and if it is unset the file has changed since the last backup. The bit is cleared whenever a write is made to the file. p: Pure - This flag is set for binary load files which are pure (i.e. multitasking reentrant), and can be made resident with the AmigaDOS 'resident' or equivalent command. s: Script - This flag is set for shell script files. h: Hidden - This flag is set for files that should not V1.10 LhA User's Guide Page 26 show up on directory listings. It is not supported by the current release of the AmigaDOS shell/CLI commands, and should thus not be used. Please refer to an AmigaDOS manual for more detailed explanation of the various file protection flags. If the option is disabled (by issuing `-a0' on the command line), the protection flags are set to '----RWED' for all extracted and archived files. Important: You MUST have this option enabled both when archiving and extracting to preserve file attributes correctly. NOTE Use this option only if you know that the archive has been compressed or will be decompressed with an Amiga archiver, since the attribute field format is different on different operating systems. If you use archive headers of level 1 or higher you need not care about this since the archiver then detects what OS the archive was created on and only uses the protection flags if it is the native OS. Always leave this option enabled when using archive headers of level 1 and higher! This option is enabled by default when archiving (a,f,u,m) and disabled by default for all other commands. 2.5.2 `-A' (upd) Set archive attributes When this option is active, LhA will set the file protection flags of all archives it updates to `----RW-D'. This option is OFF by default. 2.5.3 `-b' (all) Set I/O buffer size This option will set the size of the I/O buffers LhA uses when reading and writing to archive files. You can set the buffer size to anything from 8KB to 64 KB. Larger buffers normally makes LhA operate slightly faster (depends on the nature of the archive and what files are selected). EXAMPLE 'lha -b64 a archive.lzh hubba' : Will add file `hubba' to `archive.lzh' using an I/O buffer of 64K. NOTE V1.10 LhA User's Guide Page 27 Running LhA with a small I/O buffer on an accelerated (68020 and up) Amiga will degrade compression / decompression performance significantly! The default buffer size of 32KB is enough in most cases, and works well on an unaccelerated Amiga as well. Also note that when running LhA and doing all work on some ram disk, the I/O buffer size is less important, and it is unnecessary to run with a large buffer. The default buffer size of 32K is OK for most purposes. The default buffer size is 32K (32768 bytes) 2.5.5 `-c' (all) Confirm files When this option is active LhA will ask you for confirmation on all files and archives that are acted upon. This option is OFF by default. 2.5.6 `-C' (ext) Clear arc-bit on extract When this option is active LhA will mask the A-protection bit for all files it extracts. This is useful when extracting files from archives to a harddisk, since the extracted files would not be recognized as new or changed files by the backup program if the A-bit was set. This option is ON by default. 2.5.8 `-D' (all) Alternate progress display This switch is used to change the look of the byte progress indicator that LhA displays when it is compressing or decompressing files. There are several different types of progress indicators, you can specify which one you want with a digit after the '-D' string. 0: This is the default progress indicator, it displays how many bytes of the file LhA has processed, and how many bytes there is in the file like this: (xxxxxxx/yyyyyyy) where x = bytes processed, and y = total bytes in the file. 1: This progress indicator simply shows a `rotating line' that is rotated 45 degrees every time the progress indicator display is updated). V1.10 LhA User's Guide Page 28 2: This progress indicator shows how many percent of the file LhA has processed. 3: This progress indicator displays a growing bar that indicates how much of the file that has been processed. EXAMPLE `lha -D2 a src *.asm' will add files to the archive `src.lha' with a percentage indicator (type 2). The default progress indication type is 0. 2.5.11 `-f' (all) Ignore filenotes When this option is enabled, LhA will not store or restore any filenotes. There is no real need to do this, since it does not cause any compatibility problems with other systems because of the way the filenotes are stored. If problems should arise anyway, try enabling this option or use headers of level 1 or higher if the target system supports it. See the section about compatibility (1.7) for a discussion about this and other compatibility issues. This option is OFF by default (filenotes are stored and restored) 2.5.12 `-F' (all) Use fast progress display In this mode LhA uses a different method of display progress for the extract and test commands. Normally, LhA emits a linefeed (LF) after each file has been processed, thus advancing/scrolling the display one line. In this mode LhA only emits a LF when an error occurs. This is useful if you are testing or extracting files with a lot of small files, and the scrolling takes more time than the actual decompression! NOTE If you use the default style progress display on a very fast Amiga system (68020+), beware that the scrolling of the screen may actually take more time than the actual decompression! This is especially true for archives with many small files. So don't use it unless you really _have_ to see what files have been processed. LhA scrolls the display whenever an error occurs on a file, so you still can see when an error occurs (better, even, since the V1.10 LhA User's Guide Page 29 only filenames that remain on screen after the action is complete are those that failed!). This option is OFF by default (use old style progress indication). 2.5.16 `-i' (all) Read filelist from file With this option you can include an action file list from a file instead of specifying all action files on a command line. EXAMPLE If the file `ArcFList' contains the following lines: ---> Start of ArcFList data (this line is NOT in the file) LhA.c ArcList.c FSys/*.(c|h|i|asm|prf|man|doc|txt) ---> End of ArcFList data (this line is NOT in the file) The following command line: `lha -iArcFList u /aab/lha.lzh' Will do the same thing as this command: `lha u /aab/lha.lzh LhA.c ArcList.c FSys/*.(c|h|i|asm|prf|man|doc|txt)' NOTE This command works almost exactly like entering the following command line: LhA ? ???? @file Thus you can include options in your -i file. The only difference is that the -i file cannot contain a destination directory specification while you can do this with the @file method. The destination directory will always be taken from the command line when using the -i option. See the section about `@'(include)-files for an alternate way of doing this. 2.5.17 `-k' (all) Keep partial files V1.10 LhA User's Guide Page 30 This option will, if it's enabled, prevent LhA from deleting temporary files when an error occurs. Normally temporary files that fail the CRC check, cause I/O errors or are interrupted with CTRL-C are deleted before exiting LhA with an error message, with this option you can force LhA to keep those (often) partial files. This can be useful when trying to recover data from corrupted archives - LhA will attempt to extract the data from the erraneous archive file and put a special filenote on the file to indicate that it failed the CRC check and probably is corrupted. NOTE Please that in the current release, for certain errors all data that has been extracted may not be in the partially extracted file, because of internal I/O buffering. In this case, set the I/O buffer to the smallest value possible (8KB) to recover as much as possible. Because of this, small files may not be recovered at all. This only applies to LHA (-lh5-) compression, LhArc compressed files will always have all extracted data in the partially extracted file. This option is OFF by default (partial files are deleted). 2.5.18 `-l' (ALL) Make filenames lowercase This option, when active, will cause LhA to convert all filenames to lowercase. This is useful when extracting files from archives created on MSDOS systems, whose filenames are all uppercase, which look completely braindead (IMHO). Use this option to make them look nicer! EXAMPLE `LhA -l x myarc' will extract all files from `myarc.(lzh|lha)', making all filenames lowercase. This option if OFF by default 2.5.19 `-L' (ALL) Create filelist When this option is enabled, it will cause LhA to create a list of the files it has acted upon (i.e. what files in the last operation that matched the action file specification you gave on the command line). The name of the list file must follow immediately after the `-L' string. If you need spaces in the filename, enclose the name in double quotes. EXAMPLE V1.10 LhA User's Guide Page 31 `lha -Lram:ListFile d src.lzh *.asm' will delete all files in `src.lzh' with names ending in `.asm' and create a list of the deleted files in the file `ram:ListFile'. `lha -L"ram:List File" u src.lzh *.asm' will update `src.lzh', and create a list of the files that were added/replaced in the file `ram:List File'. NOTE The file that this option creates is a plain ASCII file with every name on a separate line. The files created by this option are suitable for use as action or exclude lists for LhA using the `@' or `-i' options. This option is OFF by default (no filelist created). 2.5.20 `-m' (ALL) No messages for query When this option is active LhA will suppress all queries that normally are issued before overwriting existing files for example. Enabling this option will also cause LhA to ignore TelOps (autoshow files). When this option is on you LhA will behave like you choose the default action in response to all the queries (yes). This option is automatically enabled if the standard input is not interactive (if run in the background for example). This option if OFF by default. 2.5.21 `-M' (ext) No autoshow files When this option is enabled, LhA will suppress the display of autoshow files (files with names ending in `.displayme'). NOTE Autoshow files are also suppressed if one or more of the `-N', `-q' or `-m' options are enabled. This option is OFF by default (autoshow files are displayed). 2.5.22 `-n' (upx) No byte progress indicator When this option is enabled, the byte progress indicator is disabled. LhA will still display what file it is working on however, use `-N' to disable all progress indication. V1.10 LhA User's Guide Page 32 This option is OFF by default. 2.5.23 `-N' (all) No progress indicator This option is similar to the `-n' option, but supresses higher-level progress indication (i.e. the display of what file LhA is bashing). It also disables the short copyright banner that is printed at each invokation otherwise. This option is off by default (file progress indication ON). 2.5.25 `-p' (ALL) Pause after loading When selected, this option will cause LhA to pause and wait for the user to press any key before executing a command. This is useful for users with floppies, who can then swap disks after LhA has been loaded and is waiting for a keypress. This option is OFF by default. 2.5.26 `-P' (ALL) Set task priority This option is used to set the LhA process priority. The priority may be set to any value in the range -5 to +5, including 0. The higher priority you give LhA, the more CPU time it will grab (processes with lower priority will almost never get the chance to run since LhA is very processor-intensive). Setting it to a low value (like -5) will make LhA only use the processor time that nobody else wants (nice when running LhA as a background task while running a comm program). The priority must be specified with a single (optionally prefixed with a minus sign for negative priority) digit immediately after the P as in: EXAMPLE `lha -P-1 a nonsense.lzh bogus.txt' will make LhA add the file `bogus.txt' to the archive `nonsense.lzh', running at priority -1. The default priority is inherited from the calling process (i.e. the CLI or program that called Execute()/RunCommand() ). This is usually zero (0). 2.5.27 `-q' (ALL) Be quiet This option will supress ALL messages from LhA. This option is OFF by default V1.10 LhA User's Guide Page 33 2.5.28 `-Q' (ALL) Alternate option set This option character (`Q') will cause all following option characters until next space character to be interpreted as extended options. These are documented at the end of this section. 2.5.29 `-r' (add) Collect action files recursively When this option is used, LhA will recursively collect files from subdirectories. EXAMPLE `lha -r a ram:disk1 df0:' will archive all files on the disk in drive 0 to `ram:disk1.lha'. `lha -r a ram:disk2src df0:*.c' will archive all `.c' files on df0: to `ram:disk2src.lha'. `lha -r a ram:exthup hd:prg/src/ lha/*.[chasi] lhi/*.[chasi]' will add all `.c', `.h', `.a', `.s', `.i' files in `hd:prg/src/lha' and `hd:prg/src/lhi' and their subdirectories. The `hd:prg/src/' part of the names will not be stored in the archive (home directory `hd:prg/src/' was specified). NOTE Files that are specified explicitly (i.e. without any pattern matching) are looked for only in the current (home) directory, while patterns are used for matching in all subdirectories. If a directory is specified explicitly without any following file pattern (like in `lha -r a ram:test sys:l') it will be treated as if a `/*' was appended to the directory name - i.e. all files in the directory and it's subdirectories will be archived. This option is OFF by default. Note that the `-x' option is automatically enabled when the -r option is used. If you do not want to store pathnames simply specify `-x0' on the command line. 2.5.30 `-R' (ALL) Collect archive files recursively When this option is enabled LhA will search for archive files recursively using the archive file specification given at the command line. This works like the `-r' option but for archive files. EXAMPLE `lha -R l dh0:files/a*' will list the contents of all archive files whose names begin in `a' in directory V1.10 LhA User's Guide Page 34 `dh0:files' and its subdirectories. `lha -R l *' will list the contents of all archive files in the current directory and its subdirectories. `lha -R l myarc' will list the contents of all archives called 'myarc.lzh' or `myarc.lha' in the current directory and its subdirectories. This option is OFF by default. 2.5.32 `-S' (add) Set A-flag on archived files When this option is on, LhA will set the A (for Archived) file protection flag on all files that are added to an archive. This can be used to simplify automatic backups when used together with the -O (Add files without A-flag only). See section 2.5.24 for more details. This option is OFF by default. 2.5.33 `-t' (ext) Only new files When this option is active, LhA will not overwrite or replace any files. NOTE This option overrides the `-T' option. This option is OFF by default. 2.5.34 `-T' (upx) New and newer files When this option is active, LhA will overwrite or replace files that already exists and are older than the current file, and create files that does not already exist. NOTE This option overrides the `-t' option. This option is OFF by default. 2.5.35 `-u' (ALL) Make filenames uppercase This option, when active, will force LhA to convert all filenames to uppercase. This can be useful when making archives that are supposed to be used on MSDOS-Systems running LhArc/LHA. While these have no problems with extracting files V1.10 LhA User's Guide Page 35 with mixed-case filenames, the pattern matching routines will not work correctly. This option is OFF by default. 2.5.36 `-U' (upx) Set update interval This option is used to set the interval (in bytes) at which LhA updates the byte progress indicator. The desired interval must be expressed in kilobytes, and must immediately follow the `U' character. EXAMPLE `LhA -U4096 a bar.lzh *.c' will add all c-source files in the current directory to `bar.lzh' with a progress indicator interval of 4096 (4K) bytes. `LhA -U32768 a bar.lzh *.c' will do the same as the example above, but with a update interval of 32768 bytes (32K). NOTE This option does currently not affect the update rate of the LHA decompression (`-lh5-' compression mode). When LhA decompresses files with this compression mode, the update rate will be whatever I/O buffer size is used (set with the `-b' option). The reason of this behaviour is that the normal progress indication would slow down decompression. The default update interval is 8192 (8K) bytes for -lh1- and -lh5- compression and 4096 (4K) bytes for -lh1- decompression. The update rate for -lh5- decompression is determined by the I/O buffer size setting (see note above). 2.5.37 `-v' (add) Set compression speed This option can be used to increase or decrease the compression speed. -v0 is the slowest, and -v9 is the fastest. As usual you can't get anything for free, so compression performance is slightly looser with -v9 than with -v0 but the difference in speed can be significant (especially with some binary graphics data). Higher compression speed is attained by using less statistics in the compression phase. The default compression speed is 5 - best in 99% of all cases. 2.5.38 `-w' (upd) Set work directory This option is used to specify what directory LhA should use V1.10 LhA User's Guide Page 36 to store temporary files. Temporary files are created when adding files to archives, or when updating an archive in some way (like deleting or freshening files). The work directory name must be specified immediately after the `-w' string. EXAMPLE `LhA -wrad:tmp a MyArc.lzh *' will use the directory `rad:tmp' as temporary storage location when adding all files in the current directory to the archive `MyArc.lzh'. By default LhA uses the `T:' directory for temporary files, if this assign or device does not exist, LhA will use the current directory. 2.5.39 `-x' (all) Preserve and use pathnames When this option is enabled, LhA will use and preserve pathnames when extracting and archiving files. When extracting, LhA will create the directories that does not already exist. Use this option when you want to preserve some directory structure. This option is automatically enabled when the `-r' option is used. This option is disabled by default for update operations and enabled by default for extract operations. 2.5.40 `-X' (ALL) Do not append suffix When this option is enabled, LhA will not append an `.lzh' or `.lha' suffix to the given archive name. The default behaviour is to append a suffix of `.lha' or `.lzh' (suffix is chosen depending on compression mode) if the name does not already have an extension. This option is OFF by default (suffixes are appended). 2.5.41 `-Y' (add) Store big files with ratio When this option is enabled, LhA will store big files (>32KB) without compression if compression ratio is lower than 3%. This is because extraction times of these files are long on slower machines. This option is OFF by default (all files are compressed). 2.5.42 `-z' (add) Do not compress files This option, when active, will force LhA to store all updated or added files in the archive without attempting to compress them. Useful for making fast backups where archive size is of no importance. It is not advisable to use this option when making archives for distribution via modem or V1.10 LhA User's Guide Page 37 networks since the archive will end up much larger than if it was compressed. EXAMPLE `lha -z a foo.lha *.bmp' Will store all files in the current directory with a suffix of `.bmp' in the archive file `foo.lha' without compressing them. This option is OFF by default. 2.5.43 `-Z' (add) Compress archives This option will cause LhA to attempt compressing already compressed files. By default, LhA will not attempt to compress files which are already compressed (typically archive files or picture files in GIF or JPEG format). The file type is determined from the suffix, and files with names ending in `.lzh', `.lha', `.zoo', `.zip', `arj', `.arc', `.dms', `.wrp', `.lhw', `.zap', `.pak', `.pp', `.gif', or `.jpg'. The reason why already compressed files should not be compressed is that the number of bytes gained by this is so small that it is not worth the time spent compressing/decompressing it. This option is OFF by default. 2.5.45 `-0' (add) Use LhArc 1.x compression This option causes LhA to use the old -lh1- compression method when updating archives. This compression method is slightly faster than the normal -lh5- compression but has looser compression and is much slower to decompress. When this compression mode is used, LhA defaults to appending a suffix of `.lzh' when creating archives. When this option is specified, option `-2' is automatically deactivated. By default the -lh5- compression is used. 2.5.46 `-2' (add) Use LhA compression This option causes LhA to use the new -lh5- compression method when updating archives. This compression method is slightly slower then the old -lh1- compression but has tighter compression and is much faster to decompress. When this compression mode is used, LhA defaults to V1.10 LhA User's Guide Page 38 appending a suffix of `.lha' when creating archives. When this option is specified, option `-0' is automatically deactivated. This is the default compression mode. 2.5.49 `-Qh' (add) Set Huffman buffer size This option can be used to set the size of the buffer used in LHA compression (default or selected with the `-2' option) for collecting statistics. The size of this buffer affects the compression ratio in unpredictable ways. As a general rule, keep this at the default, but if you are compressing homogenous data with a relatively fixed relative frequency of symbols (like text files), setting this to a large value will improve compression. Binaries generally compress best with the default setting. The Huffman buffer may be of any size between 4K and 64K and must be specified immediately following the `-Qh' string, in kilobytes. EXAMPLE `LhA -Qh32 -2 a foo.lha *' will compress all files in the current directory using a Huffman buffer size of 32768 (32K) bytes. `LhA -Qh4 -2 a foo.lha *' will compress all files in the current directory using a Huffman buffer size of 4096 (4K) bytes. The default Huffman buffer size is 16K. 2.6 Autoshow files Autoshow files are files that are displayed automatically to the user when extracting the file from an archive. LhA determines if a file should be displayed by looking at the filename; if the filename ends in `.displayme' then the file is displayed unless autoshow files have been disabled (with the `-M' option). Apart from being displayed on-screen, autoshow files are extracted just like normal files, without stripping off the `.displayme' part (AmigaDOS LhArc 1.30 does this). V1.10 LhA User's Guide Page 39 4 Politics 4.1 Registration LhA is a copyrighted product that has been made available to you under the concept of "Shareware". It has never been, nor will it ever be in the "Public Domain". You are granted a limited license in order to evaluate these programs. If, after a 3 or 4 week period of evaluation, you find that LhA suits your archiving needs, please register. By cooperating with this concept you help to ensure continued development of this product. Registered users will be shipped a disk with the latest release version of LhA together with a keyfile. This keyfile, once copied to your system, will disable the ShareWare reminders that always open when you start or quit the Intuition driven programs in the LhA family. The registered-user version of LhA has all the features of the evaluation version, as well as several additional commands, options and features. Among these are multi-volume archive handling and creation, faster and better compression, commands to repair, split and sort archives, and several other new useful options. Site license information for commercial and government use can be obtained directly from the author. No person(s) or businesses other than the author are authorized to accept any registration or distribution fees in any form whatsoever, except as specified by the author. The only people who will be acknowledged as registered users are those who have sent SEK 100, US, 20 IRC's or more to: Stefan Boberg Rydsvägen 242 A:25 S-58251 Linköping Sweden / Europe For residents in Sweden, the easiest and cheapest way of transferring money to the author is by `PostGiro' # 629 22 84-4 This only costs 8 crowns and you can write the registration info on the giro-form. For your own sake, make sure that the giro number found in this manual really is mine, by calling me on 013-175992, or ask at the post office (it's free). As one of the safest and easiest ways to send in your registration fee from other countries, I would suggest an international postal money order -- your local post office will be happy to provide you with more information about this. It also has the advantage that the exchange of currencies is handled automatically and the surcharge is negligible. V1.10 LhA User's Guide Page 40 Should the above not work out satisfyingly, you can either send a cheque or money order payable to Stefan Boberg in Swedish Crowns or have your bank transfer the registration fee to the "Svenska Handelsbanken" account 145.587.932 "Stefan Boberg". Beware: International transfers via banks are quite expensive. In any case, be sure to provide me with your name, address, fido-nodenumber/InterNet address and international phone number for filing purposes. You can send this information via electronic mail, if you wish. If you don't mind, this data will be stored and processed in electronic form. There is a sample registration form you can fill in in the file "OrderForm". Please allow two to eight weeks for delivery. 4.2 Distribution Basically, LhA may be distributed freely as long as the following conditions are met: The distributor may only charge a fee up to the costs of obtaining a public domain diskette from Fred Fish. The distributor agrees to cease distributing the programs and data involved if requested to do so by the author. The distributor may only distribute an unmodified copy of the original program, with all the supplied documentation and copyright notices left intact. For more details, see the chapter called "License". 4.3 Support If you have any suggestions, bug reports or questions, please contact the author of LhA at the address given in section 4.1 or at one of the electronic mail addresses below: InterNet: boberg@lysator.liu.se or : lha@augs.se or : stefan_boberg@augs.se FIDONet : "Stefan Boberg" at node 2:204/404 When sending in bug reports, please state exactly under what circumstances the bug occurred, what equipment was used and what happened. If possible also try to give me enough information to reproduce the bug. It is very difficult to find bugs when you don't know exactly what happened. Please don't just send messages like "it can't extract files from archives sometimes", that really doesn't help me. If possible, submit V1.10 LhA User's Guide Page 41 the offending file/archive to me so I can test it myself. 4.4 Program availability The latest version of LhA is always available for anonymous FTP at lysator.liu.se, in `/pub/amiga/LhAEval.run' - it is a self-extracting archive that should be executed from CLI or WB2.0 to extract the contents. It will also be available for FidoNet FReq from AUGS BBS in Linköping, Sweden, under the magic filename `LHA', the node number is 2:204.404. 4.5 License 1. This license applies to the product called "LhA", a set of programs for the Commodore-Amiga computer, published by Stefan Boberg under the concepts of ShareWare, and the accompanying documentation, example files and anything else that comes with the original distribution. The terms "Programs" and "LhA" below, refer to this product. The licensee is addressed as "you". 2. You may copy and distribute verbatim copies of the programs' executable code and documentation as you receive it, in any medium, provided that you conspicuosly and appropriately publish only the original, unmodified programs, with all copyright notices and disclaimers of warranty intact and including all the accompanying documentation, example files and anything else that came with the original. 3. You may not copy and/or distribute these programs without the accompanying documentation and other additional files that came with the original. You may not copy and/or distribute modified versions of these programs. 4. You may not copy, modify, sublicense, distribute or transfer the programs except as expressly provided under this license. Any attempt otherwise to copy, modify, sublicense, distribute or transfer the programs is void, and will automatically terminate your rights to use the programs under this license. However, parties who have received copies, or rights to use copies, from you under this license will not have their licenses terminated so long as such parties remain in full compliance. 5. By copying, distributing and/or using the programs you indicate your acceptance of this license to do so, and all its terms and conditions. 6. Each time you redistribute the programs, the recipient automatically receives a license from the original licensor to copy, distribute and/or use the programs subject to these V1.10 LhA User's Guide Page 42 terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. 7. You may not disassemble, decompile, re-source or otherwise reverse engineer the programs. 8. You may use the programs for a period of up to 30 days for evaluation. After that, you have to register. 9. If you wish to incorporate parts of the programs into other programs, write to the author to ask for permission. 10. You agree to cease distributing the programs and data involved if requested to do so by author. 11. You may charge a fee to recover distribution costs. The fee for diskette distribution may not be more than the cost to obtain a public domain diskette from Fred Fish. 4.6 Disclaimer THERE IS NO WARRANTY FOR THE PROGRAMS, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAMS "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAMS IS WITH YOU. SHOULD THE PROGRAMS PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY REDISTRIBUTE THE PROGRAMS AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAMS (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAMS TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. V1.10 LhA User's Guide Page 43 5 Acknowledgements Haruyasu Yoshizaki For releasing the source of the original LHA for MSDOS. The source was used as a reference when writing this program. No actual code was copied from this source, rather LhA was written from scratch for the Amiga. Haruhiko Okumura For devising the -lh5- and -lh4- compression algorithms, and for releasing the C source for these to the public domain. These sources were used as a reference when writing the 680x0 assembler versions of the compression and decompression code. Some algorithms were replaced with my own, faster ones. Robert K.Jung For making the feature-packed ARJ for MSDOS, from which several ideas for commands and features was included in LhA. Paolo Zibetti For making the first LhArc-style archiver for the Amiga, which made me interested in file archivers and advanced data compression techniques. Jonathan Forbes For making the -lh1- compression routines of LZ slightly faster than those of my previous (unfinished) program `LhArcA'. This was one of the reasons that made me start writing this program. Another reason for writing LhA was that LZ had some misfeatures and did not work as intended. Ron Birk For digging out the source codes I needed before I gained access to InterNet myself - Thanks! LhArcA users Big thanks to all of you who registered for LhArcA and LhA even before the programs were finished (LhArcA never was, but those who registered will receive LhI/LhA when it's finished). LhA users Big thanks to all who registered for LhA V1.00, and even bigger thanks to those who reported bugs and problems with the previous releases - without you this program would never be what it is now. The license agreement was heavily inspired by the TrapDoor V1.10 LhA User's Guide Page 44 license, which in turn was inspired by Jack Radigan and the GNU General public License. The manual was formatted with a modified version of `proff' (originally written for VAX/VMS/MSDOS by Ozan S. Yigit and Steven Tress). The program was developed using the Lattice C Compiler and Assembler on a 25MHz Amiga 3000. Great compiler, great computer! Inspiration provided (in order of significance) by Linda, Depeche Mode, Pet Shop Boys, Erasure, OMD, Electronic, The KLF/JAMS, Yazoo, Tears for Fears, Simple Minds and Kraftwerk. ... Post aspera grata ... Table Of Contents LhA V1.10 1 - Introduction ..................................... 1 1.1 About the manual ............................... 1 1.2 System requirements ........................... 1 1.4 Terminology .................................. 1 1.5 LhA - what is it? ................................ 2 1.6 What is a file archiver anyway? ................... 2 1.7 Why should I use LhA? ............................ 4 1.7.1 How fast is it? ............................ 4 1.8 Compatibility and Amiga-specific features ....... 6 1.9 About the author program history and future........ 7 2 Reference guide .................................... 9 2.1 Command line syntax ............................ 9 2.1.1 Specifying options ....................... 9 2.1.2 Specifying commands ...................... 9 2.1.3 Specifying archives ...................... 10 2.1.4 Specifying action files ................... 10 2.1.5 Home directories ......................... 10 2.1.6 Recursive file collection ................. 11 2.1.7 Specifying destination directory .......... 13 2.1.8 `@'-files ............................... 13 2.1.9 LhA limitations .......................... 13 2.3 Pattern matching .............................. 15 2.3.0 Exactly what is pattern matching anyway? ..... 15 2.3.1 Accepted pattern tokens ................... 15 2.3.1.1 Question mark (?) .................... 15 2.3.1.2 Star/Asterisk (*) ................... 16 2.3.1.3 Hash mark (#) ........................ 16 2.3.1.4 Square brackets ([]) ................. 16 2.3.1.5 Parentheses and the vertical bar ....... 17 2.3.1.6 Tilde (~) ........................... 18 2.3.1.7 Percent sign (%) ..................... 18 2.4 Commands ..................................... 19 2.4.1 `a' Add files to archive .................... 19 2.4.3 `d' Delete files from archive ............... 19 2.4.4 `e' Extract files from archive .............. 20 2.4.5 `f' Freshen files in archive ................ 20 2.4.8 `l' List archive contents (terse) ........... 20 2.4.9 `m' Move files to archive ................... 21 2.4.14 `p' Print files to stdout .................. 21 2.4.17 `t' Test archive integrity ................ 22 2.4.18 `u' Update archive ....................... 22 2.4.19 `v' List archive (verbose) ................ 22 2.4.20 `vv' List archive (full) .................. 23 2.4.21 `x' Extract files with path ................ 23 2.5 Options ...................................... 25 2.5.1 `-a' (upx) Preserve file attributes ......... 25 2.5.2 `-A' (upd) Set archive attributes ........... 26 2.5.3 `-b' (all) Set I/O buffer size ............... 26 - I - 2.5.5 `-c' (all) Confirm files ................... 27 2.5.6 `-C' (ext) Clear arc-bit on extract .......... 27 2.5.8 `-D' (all) Alternate progress display ....... 27 2.5.11 `-f' (all) Ignore filenotes ............... 28 2.5.12 `-F' (all) Use fast progress display ........ 28 2.5.16 `-i' (all) Read filelist from file .......... 29 2.5.17 `-k' (all) Keep partial files .............. 29 2.5.18 `-l' (ALL) Make filenames lowercase ........ 30 2.5.19 `-L' (ALL) Create filelist ................ 30 2.5.20 `-m' (ALL) No messages for query ............ 31 2.5.21 `-M' (ext) No autoshow files ............... 31 2.5.22 `-n' (upx) No byte progress indicator ....... 31 2.5.23 `-N' (all) No progress indicator ........... 32 2.5.25 `-p' (ALL) Pause after loading ............. 32 2.5.26 `-P' (ALL) Set task priority ............... 32 2.5.27 `-q' (ALL) Be quiet ....................... 32 2.5.28 `-Q' (ALL) Alternate option set ............ 32 2.5.29 `-r' (add) Collect action files recursively . 33 2.5.30 `-R' (ALL) Collect archive files recursively 33 2.5.32 `-S' (add) Set A-flag on archived files...... 34 2.5.33 `-t' (ext) Only new files .................. 34 2.5.34 `-T' (upx) New and newer files .............. 34 2.5.35 `-u' (ALL) Make filenames uppercase ........ 34 2.5.36 `-U' (upx) Set update interval ............. 35 2.5.37 `-v' (add) Set compression speed ........... 35 2.5.38 `-w' (upd) Set work directory .............. 35 2.5.39 `-x' (all) Preserve and use pathnames ....... 36 2.5.40 `-X' (ALL) Do not append suffix ............. 36 2.5.41 `-Y' (add) Store big files with ratio........ 36 2.5.42 `-z' (add) Do not compress files ............ 36 2.5.43 `-Z' (add) Compress archives .............. 37 2.5.45 `-0' (add) Use LhArc 1.x compression ........ 37 2.5.46 `-2' (add) Use LhA compression ............. 37 2.5.49 `-Qh' (add) Set Huffman buffer size ......... 38 2.6 Autoshow files ................................ 38 4 Politics .......................................... 39 4.1 Registration ................................. 39 4.2 Distribution ................................. 40 4.3 Support ...................................... 40 4.4 Program availability .......................... 41 4.5 License ...................................... 41 4.6 Disclaimer ................................... 42 5 Acknowledgements .................................. 43 - II -