User's Manual for LHA v2.10 (12 July 1993) ------------------------------------------ Program & documentation (c) Roger Burrows, 1990-1993 Based on: LHarc version 1.13b (for MS-DOS), copyright(c) Haruyasu Yoshizaki (Yoshi),1988-89 (documentation dated 1989-3-4) and: The public domain AR archiver by Haruhiko Okumura (source file dated 14/Aug/1990) I. Introduction to LHA ---------------------- 1. What is LHA? LHA is an archiving program: that is, it allows you to collect together a number of files and store them under one file name. This is convenient for transferring files between users and to/from bulletin boards, as it makes it easy to keep related files together. Besides collecting files together, LHA also compresses them so that they (almost always) take up less space than they would do on their own. The files LHA creates are called LZH archives, since the filenames usually end with .LZH. This archive format was invented by a programmer in Japan, and implemented in an MS-DOS program called LHARC. The initial version of LHARC (version 1.xx) compressed files using a method known as -lh1-. Subsequently, a new compression method known as -lh5- was invented by another Japanese programmer and MS-DOS LHARC was upgraded in version 2.xx to use this new method by default (although the original -lh1- compression method can still be selected if desired). LHA is based on version 1.13b of LHARC, but has been upgraded independently to support the new -lh5- compression method. It has also been enhanced with a number of extensions and a great deal of optimisation to improve its speed. 2. Terms and Conditions Starting with version 1.30, LHA is available in two formats: registered and non-registered. Both formats have all the functions that you need to process LZH archives, but registered copies have additional functions to make LHA easier to use. Registered copies are also supplied with a a number of other programs written by myself. Please refer to the README.1ST file in this distribution for a list of the programs included. The non-registered format may be made freely available on bulletin boards, and I encourage you to pass it on to your friends. However, please note that LHA is copyrighted by Roger Burrows, and therefore NEITHER format is in the Public Domain. The registered version is available from Roger Burrows at the address given at the very end of this document. To order, please refer to the file README.1ST which is part of this distribution. If you're reading this manual as part of your registration package, thank you! Your contribution will encourage me to keep improving this package. II. LHA Reference Manual ------------------------ 1. Optional command usage summary (registered users only) Registered copies of LHA support an optional command set which simplifies the use of LHA in most circumstances, by assuming a standard set of switches. The full range of commands and switches is still available at all times should you need them. The syntax from a shell like Gulam is: LHA [ ... ] If you are running LHA from the Desktop, double-click on LHA.TTP, and enter the following in the dialog box: [ ... ] In either case: is the archive name; by default, the extension '.LZH' is assumed when modifying archives. If listing or extracting from archives, the standard TOS wild-card characters (*,?) may be used to process multiple archives, and archives with extension '.LHA' as well as '.LZH' are examined. ... is one or more filenames is one of the following. Note the '-' prefix which MUST be specified: -add adds the specified files -backup like -add, but also includes files from all directories beneath the specified directory; all file names are stored completely (i.e. including the full path) -update adds the specified files to the archive if either: an older file by the same name already exists in the archive or: a file by the same name does not already exist in the archive -move equivalent to -add except that files that are added successfully are deleted from the specified directory after addition -freshen adds the specified files to the archive if and only if an older file by the same name already exists in the archive -delete deletes the specified files from the archive -extract extracts the specified files; the logical counterpart of the -add command -restore the logical counterpart of the -backup command: will extract files from an archive using any directory information present, creating any (sub)directories needed which do not exist. -display like -extract, but the extracted data is displayed on standard output -print same as -display -test tests the integrity of the specified files in archive; equivalent to -extract except that the extracted files are not saved -list displays information about the specified archived files including full path names and any attached comments As a convenience to the user, LHA may be invoked without arguments; one simple way of accomplishing this is to rename LHA.TTP to LHA.TOS. If LHA is invoked in this way, a help message is displayed, followed by a prompt for the command. If the simplified command set does not provide the exact features required, you may use the basic command set (see section 3 below). A technical note to the curious: the simplified command set is translated internally into the basic command set (the translation used is shown along side the command name in section 2 below). It is therefore possible to add/override switches to the simplified command set, although this hybrid command form is probably more confusing than just using the basic command set with switches. 2. Detailed description of optional commands 1) Archive modifying commands These commands can operate on only one archive. Wild-card characters may NOT be used to specify the archive. -add (equivalent basic command: ah+t+) LHA -add Archive.LZH project.* ACTION: all files matching 'project.*' are archived and added to 'Archive.LZH'. The timestamp of the archive is set equal to that of the latest file in the archive. NOTE: If the archive 'Archive.LZH' does not exist, then LHA creates it. If any file matching 'project.*' is already in the archive, then LHA replaces it with the external file. -backup (equivalent basic command: ah+r+t+) LHA -backup Archive.LZH project.* ACTION: all files matching 'project.*' in the specified directory AND all its subdirectories are archived and added to 'Archive.LZH'. Files are stored with full pathnames, ready for extraction by the '-restore' command. The timestamp of the archive is set equal to that of the latest file in the archive. NOTE: If the archive 'Archive.LZH' does not exist, then LHA creates it. If any file matching 'project.*' is already in the archive, then LHA replaces it with the external file. -update (equivalent basic command: uh+t+) LHA -update csource file1.c file2.c ACTION: 'file1.c' and 'file2.c' are archived into 'csource.LZH' exactly as though by the 'a' command, except that if either file already exists in the archive, LHA checks the date/time stamps of the archive version against that of the external version. LHA keeps the newer one and ignores the other. -move (equivalent basic command: mh+t+) LHA -move zoom.lzh file.ext ACTION: 'file.ext' is archived into 'zoom.lzh' in the same way as with the 'u' command. If the external file 'file.ext' is, in fact, added to the archive, then the external copy of it is deleted. Otherwise, the external copy is retained. -freshen (equivalent basic command: fh+t+) LHA -freshen headers.lzh *.h ACTION: if any external file that matches '*.h' already exists in 'headers.lzh', then it will be replaced if the external copy of the file is newer than the archive copy. NOTE: This is the same as the 'u' command, except that nothing will be done if the matching file does not already exist in the archive. -delete (equivalent basic command: dh+t+) LHA -delete bigarc small.txt ACTION: deletes 'small.txt' from the archive 'bigarc.lzh'. 2) Archive extraction commands These commands may operate on one or more archives. Multiple archives are specified through wild-card characters. -extract (equivalent basic command: eh+) LHA -extract download.lzh *.doc ACTION: extracts all files matching '*.doc' from 'download.lzh'. LHA -extract * ACTION: extracts all files from all archives in the current directory. NOTE: If there is a file with the same name in the target directory, then LHA refrains from extraction if the existing file has the same time stamp or is newer. -restore (equivalent basic command: eh+x+) LHA -restore * ACTION: extracts all files from all archives in the current directory. If full pathnames (i.e. including subdirectories) are present, then those subdirectories will be recreated. NOTE: If there is a file with the same name in the target directory, then LHA refrains from extraction if the existing file has the same time stamp or is newer. -display or -print (equivalent basic command: ph+) LHA -display sample sample.txt ACTION: extracts 'sample.txt' from the archives 'sample.lzh' and/or 'sample.lha' to the standard output. -test (equivalent basic command: th+) LHA -test new ACTION: tests specified members (in this case, all members) of archives 'new.lzh' and/or 'new.lha', by extracting each of them and performing a CRC check. CRC mismatches are reported; the extracted files are not kept. -list (equivalent basic command: lh+x+c+) LHA -list save ACTION: displays the names of each of the specified files (in this case, all the files) in 'save.lzh' and/or 'save.lha' together with the file size (compressed & uncompressed), attributes, date/time, CRC value and compression method. The listing for each file occupies one output line, unless comments are present, in which case an additional line is used to display the comment. 3. Basic command usage summary (available to all users) The following summarises the basic command format which is available to all users. From a command-line shell, such as Gulam, the syntax to run LHA is: LHA {aumfexpstdlv}[switches] [-[switches] ... ] [\ | :] [ ... ] If you are running LHA from the Desktop, double-click on LHA.TTP, and enter a line with a format that matches the following: {aumfexpstdlv}[switches] [-[switches] ... ] [\ | :] [ ... ] [In either case, the parameters should be entered on one line; they are split on to two lines above for readability only.] As a convenience to the user, LHA may be invoked without arguments; in this case, a help message is displayed, followed by a prompt for the command. Otherwise, the command is entered as the first argument. One of the twelve listed commands {aumfexpstdlv} must be specified. Switches (see below for a complete list) are optional; they may be concatenated as desired, with the exception of the 'g', 'v' and 'w' switches, which each take everything following in the string as an argument and thus must be the last switches in a string. Switches are normally placed immediately following the command; however, they may also be separated from the command and immediately preceded by a '-'; this allows for the case when you wish to specify more than one of the 'g', 'v' or 'w' switches. Commands and switches may be entered in upper or lower case, as desired. The remaining specifications may contain pathnames. As a convenience for those used to Un*x-style pathnames, directories may be separated by '/' or '\' characters transparently. The Archive must be specified, but may be specified with or without a file extension. When modifying archives (commands {aumfd}), the file extension is assumed to be .LZH if omitted; when listing or extracting from archives (commands {expstlv}), archives with extension .LHA as well as .LZH are processed if the file extension is omitted, and the standard TOS wild-card characters (*,?) may be used to process multiple archives. In order to avoid unintentional file modification, the following safety check is made: if the file extension is specified, and is not .LZH, and the command could modify the archive, and the 'm' (no prompt) switch is not set, then the user will be asked to verify the update. The Base directory or Base drive is optional, and is indicated by a name ending with a '\' or ':'. If specified, everything happens as if this directory or drive were the current directory or drive. Specifically: 1) when updating an archive with the 'x' switch, there will be no record of this directory name in the archive, and 2) when extracting files from an archive, the extracted files will be written to this directory by default. In practice, you will probably never wish to specify this; see section 4 (concepts and terminology) for more details, and also the 'Important Note' below. One or more files may be specified, either as unique filenames or with standard GEMDOS wild-card specifications; if omitted, a default of '*.*' (i.e. all files in the current or Base directory) is assumed for all commands except 'd' (delete). For safety, the filename(s) or wild-card specification(s) must be explicitly entered for the delete command. The case of filenames and pathnames is ignored in comparisons. This allows the selective extraction of files created on other systems that support lower case in filenames (e.g. Un*x). As noted above, just type LHA to see the help menu. Important Note: --------------- In early versions of LHA, files could only be extracted to directories other than the default directory by specifying a Base directory or Base drive. This feature was a carry-over from the original MS-DOS lharc program. Since this is incompatible with ARCSHELL and standard ARC syntax, a compatibility feature was added to LHA in version 1.10. As of version 1.10, you may continue to use the Base drive/directory syntax, OR you may use an ARC-like syntax: e myarc.lzh g:\some\abc.def will extract file abc.def from the 'myarc.lzh' archive into the 'g:\some' directory. In order for LHA to use the ARCSHELL-compatible syntax, the following must be true: 1) the 'p' switch must be zero 2) the Base drive/directory must be omitted. 4. Detailed description of basic commands 1) Archive modifying commands [aumfd] These commands can operate on only one archive. Wild-card characters may NOT be used to specify the archive. a (Add) LHA a Archive.LZH project.* ACTION: all files matching 'project.*' are archived and added to 'Archive.LZH'. NOTE: If the archive 'Archive.LZH' does not exist, then LHA creates it. If any file matching 'project.*' is already in the archive, then LHA replaces it with the external file. u (Update) LHA u csource file1.c file2.c ACTION: 'file1.c' and 'file2.c' are archived into 'csource.LZH' exactly as though by the 'a' command, except that if either file already exists in the archive, LHA checks the date/time stamps of the archive version against that of the external version. LHA keeps the newer one and ignores the other. NOTE: If the 'i' switch is specified, the 'u' command is exactly the same as the 'a' command. m (Move) LHA m zoom.lzh file.ext ACTION: 'file.ext' is archived into 'zoom.lzh' in the same way as with the 'u' command. If the external file 'file.ext' is, in fact, added to the archive, then the external copy of it is deleted. Otherwise, the external copy is retained. f (Freshen) LHA f headers.lzh *.h ACTION: if any external file that matches '*.h' already exists in 'headers.lzh', then it will be replaced if the external copy of the file is newer than the archive copy. NOTE: This is the same as the 'u' command, except that nothing will be done if the matching file does not already exist in the archive. The 'i' switch may be specified to force replacement without regard to date/time checking. d (Delete) LHA d bigarc small.txt ACTION: deletes 'small.txt' from the archive 'bigarc.lzh'. 2) Archive extraction commands [expstlv] These commands may operate on one or more archives. Multiple archives are specified through wild-card characters. e (Extract) or x (eXtract) LHA e download.lzh *.doc ACTION: extracts all files matching '*.doc' from 'download.lzh'. LHA x * ACTION: extracts all files from all archives in the current directory. NOTE: If there is a file with the same name in the target directory, then LHA refrains from extraction if the existing file has the same time stamp or is newer. The 'i' switch will force LHA to ignore the time stamp check. p (disPlay) or s (diSplay) LHA s sample sample.txt ACTION: extracts 'sample.txt' from the archives 'sample.lzh' and/or 'sample.lha' to the standard output. NOTE: The 'v' switch may be specified to allow browsing through the output; it functions by writing the standard output to a temporary file instead, and invoking a utility program to browse the file; the temporary file is deleted automatically afterwards. The default utility invoked is 'less' (supplied with the LHA registration package), but this may be overridden by specifying the name of the utility immediately following the 'v' switch. For example, LHA pvmore archive.lzh file1.ext file2.ext will write 'file1.ext' and 'file2.ext' to a temporary file and invoke the 'more' command to browse it. t (Test) LHA t new ACTION: tests specified members (in this case, all members) of archives 'new.lzh' and/or 'new.lha', by extracting each of them and performing a CRC check. CRC mismatches are reported; the extracted files are not kept. l (List) LHA l save ACTION: displays the names of each of the specified files (in this case, all the files) in 'save.lzh' and/or 'save.lha' together with the file size (compressed & uncompressed), attributes, date/time, CRC value and compression method. The listing for each file occupies one output line. NOTE: The 'x' switch may be specified to cause listing of the full stored pathname; if the stored pathname includes subdirectories, this requires one additional line per file. The 'c' switch may be specified to cause listing of any stored comments; if present, this requires one additional line per file. v (Verbose list) LHA v foobar.xxx *.h ACTION: displays the full stored pathname of each of the files in 'foobar.xxx' (assumed to be a .LZH archive) that has a file extension of '.h'. The following information is also listed: their size (compressed & uncompressed), attributes, date/time, CRC value, compression method, and comment (if present). NOTE: This is exactly the same display as produced by the 'l' command with the 'x' switch. 5. Detailed switch description General: You may specify switch(es) immediately following the command, and/or following a '-'. If you want to specify more than one switch, type characters continuously without any spaces between (for example, -rxw or -cxv). When the switches 'g', 'v' or 'w' are used with other switch(es), they must be specified at the end of the sequence. You may place a '+', '-', '1' or '0' after switches with the following meanings: '+' or '1' sets the switch on, and '-' or '0' sets the switch off. In addition, a '2' may be placed after the 'l', 'r' or 'v' switch with a special meaning (as described later). A switch on its own acts as a toggle; if the option was off, it is turned on, and vice versa. a[-|+|0|1] (any Attribute) Applicable commands: {aum} ACTION: allows files with any attributes to be archived. If the 'a' switch is not specified, files with the Hidden or System attribute are not included when building the list of files to be added. If the 'a' switch is specified, these files are included in addition to 'Normal' and Read-Only files. Example: LHA aa test *.* adds all files in the current directory to 'test.lzh', including those with Hidden or System attributes. b[-|+|0|1] (retain Backup) Applicable commands: {aumfd} ACTION: preserves the archive prior to the update as a .BAK file. Note that any existing .BAK file will be removed if the update is successful. c[-|+|0|1] (use Comments) Applicable commands: {aumflv} ACTION: adds or displays comments that have been stored in an Atari- or Amiga-compatible format, as follows: a) the command is one of {aumf}. In this case, the 'c' switch allows comments to be tagged to a file as it is added to the archive. As each file is added, the user will be prompted for a comment of up to 60 characters in length. If the file extension of the archive is .LHA, the added comment will be in a format compatible with the Amiga; otherwise it will be in a format compatible with other Atari archivers. b) the command is one of {lv}. In this case, any stored comments will be displayed as part of the output, enclosed by square brackets []. Both Atari- and Amiga- style comments are automatically recognised irrespective of file extension. NOTE 1: Certain archivers (including LHARC102) create archive headers that appear to contain Atari-style comments, but in fact contain extension information, some of which is non-printable. Other archivers (including v2.xx of MS-DOS LHARC) generate headers containing a one-byte comment which indicates which system the header was created on (e.g. MS-DOS, Atari TOS, Mac OS etc). When displaying such headers with this switch set, the displayed comment line will contain an interpretation of the comment, rather than a literal display of the comment data. The interpreted data will be enclosed in curly braces {} to indicate that it's an interpretation. NOTE 2: The 'c' switch also forces the header level of archived files to be set to zero (see the 'l' switch for information about header levels). h[-|+|0|1] (Hold screen) Applicable commands: {aumfdexpstlv} ACTION: causes the program to wait for a keypress before exiting. This is mostly intended for when LHA is called from the desktop, to allow program messages to be read before the desktop is redisplayed. i[-|+|0|1] (Ignore comparison of time stamp) Applicable commands: {aumfexpst} ACTION: causes date/time stamps of files to be ignored when adding to, or extracting from, archives. Example: LHA ei old file1.ext file2.ext extracts 'file1.ext' and 'file2.ext' from 'old.lzh', overwriting any existing files of the same name, regardless of date/time stamps. l[-|+|0|1|2] (set header Level) Applicable commands: {aumf} ACTION: sets the format of the internal archive header, for files added to an archive (when listing or extracting files, the header level is automatically detected and handled properly). Header level 0 is compatible with previous versions of LHA, and is the default, but headers of level 1 or 2 can be created if desired. However, there are no significant benefits to using header levels other than 0, since other archivers may not be able to handle them; they are only supported at this time for complete compatibility with MS-DOS LHARC. NOTE: When the 'o' or 'c' switch is specified, the header level switch is automatically set to 0. m[-|+|0|1] (no Message) Applicable commands: {aumfdexpst} ACTION: suppresses program prompt in the following cases: a) the command is one of {aumfd}, the archive file extension is specified, and it is not '.LZH'. In this case, the program will continue, with the (initial) assumption that the archive file is valid. b) the command is one of {ex}, and a directory must be created to receive the extracted file. In this case, the directory will be created automatically, without prompting the user. c) the command is one of {ex}, and an existing file would be overwritten by a file being extracted from the archive (either due to a more recent time stamp, or through specifying the 'i' switch). In this case, the file will be silently overwritten. Example: LHA xm archive temp\file1.ext will cause LHA to create the directory 'temp' if it does not already exist, or to overwrite the file 'file1.ext' in directory 'temp' if it does exist, without prompting. n[-|+|0|1] (No indicator) Applicable commands: {aumfexpst} ACTION: suppresses the display of the progress indicator when compressing or decompressing files. NOTE: the progress indicator 'ticks' every N bytes of uncompressed data, where N is 4096 for -lh0-, -lh1-, -lh4-, -lz4- and -lz5- files and 8192 for -lh5- files. If this would make the indicator more than 64 bytes long, N is instead set to (uncompressed file size)/64. o[-|+|0|1] (Old archive compatibility) Applicable commands: {aumf} ACTION: causes LHA to use the old style compression method (i.e. -lh1-). This permits compatibility with older archiving programs, at the cost of (usually) worse compression. NOTE: This also forces the header level to be set to zero (see the 'l' switch for information about header levels). p[-|+|0|1] (Precise) Applicable commands: {fdexpstlv} ACTION: allows the user to precisely distinguish between archived files, that have the same filename but are stored with different pathnames. Assume an archive cc.lzh contains both \stat.h and \sys\stat.h: LHA e cc stat.h will extract both files to 'stat.h' in the current directory; as a result, the one with the older date/time stamp will be overwritten by the other. LHA ep cc.lzh stat.h will extract only \stat.h to 'stat.h'. LHA ep cc.lzh sys\stat.h will extract only sys\stat.h to 'stat.h'. NOTE: As of LHA version 1.10, specifying the 'p' switch also has the side effect of turning off ARCSHELL compatibility; this should not be a concern, since ARCSHELL itself never sets the 'p' switch. r[-|+|0|1|2] (Recursively search directories) Applicable commands: {aum} ACTION: recursively searches directories for files to be archived. If the 'r' switch is not specified, only files in the Base or Current directory will be archived. If the 'r' switch is specified, it selects one of two modes: a) filename mode, if 'r' or 'r+' is specified This disregards directory names, and adds to the archive all the files in the Base or Current directory (and its subdirectories) with names that match the specified filename. b) directory mode, if 'r2' is specified This disregards filenames, and adds to the archive all files under the Base or Current directory (and its subdirectories). This is normally used to archive a complete directory. Examples: LHA ar cstuff *.c adds to archive 'cstuff.lzh' all the files with the extension .c under the current directory. LHA ar2 documents.lzh \doc\ archives all the files in the \doc\ directory (and subdirectories) into documents.lzh. Normally used to archive a complete directory. NOTE: Switches 'r' and 'r2' automatically set the 'x' switch. If you wish to have 'r' or 'r2' without 'x', set the 'x' switch off (by using 'x-') after the 'r' or 'r2' specification. t[-|+|0|1] (archive Time-stamp) Applicable commands: {aumfd} ACTION: causes the output archive to be time-stamped with the date and time of the most recent file in the archive, rather than the current date & time. v[-|+|0|1|2|] (View by page) Applicable commands: {ps} ACTION: allows browsing of output produced by the 'p'/'s' command. Instead of copying the output to stdout, a temporary file LHA.TMP is created, and a browse utility is invoked to access it. The name of the browse utility follows the 'v' switch; if not specified, the default browse utility is 'less'. After the browse utility ends, the temporary file is deleted automatically. The standard 'v' switch generates a separator line between each file copied to LHA.TMP so that the user can distinguish them; the 'v2' switch suppresses this separator line. This is primarily to facilitate viewing binary files with a dump utility. Note that if a browse command name is present, the switch is always set. If 'v2' was specified, it remains a '2'; otherwise it is treated as 'v+'. Examples: LHA pv myarc *.doc allows browsing of all '.doc' files in 'myarc.lzh', using the 'less' utility. LHA pv2xd hexarc allows browsing of all files in 'hexarc.lzh', using the 'xd' utility. w[-|+|0|1|] (set Work directory name) Applicable commands: {aumfdps} ACTION: causes any temporary files that are needed to be created in the specified working directory (the directory must already exist). If no directory name is specified, the current directory becomes the working directory. Temporary files are needed in two circumstances: a) the command is one of {aumfd}, and thus an archive is being updated. The updated archive is created in the working directory, the old archive is deleted, and the updated archive is put back into the current directory. This is done by renaming the file (if possible), or by copying the file to the current directory. b) the command is one of {ps}, and the 'v' switch is set to allow browsing the output. The browse file is created in the working directory, and deleted when the browse utility terminates. Note that if a work directory name is present, the switch is always set, i.e. it is always treated as 'w+'. Example: LHA awm:\tmp xyzzy file1.ext file2.ext adds 'file1.ext' and 'file2.ext' to the archive 'xyzzy.lzh', placing the updated archive in directory 'm:\tmp' temporarily. There are two common uses for this feature: 1) you have no room in the directory where the .LZH file resides, or 2) you want your work done silently and swiftly on a ram disk. x[-|+|0|1] (eXtend) z[-|+|0|1] Applicable commands: {aumexlv} ACTION: extends file names with directory names, in the following cases: a) the command is one of {aum}. In this case, the 'x' switch will include the pathname (excluding drivename) in the filename stored in the archive. Suppose you are in the root directory \, and you have a file stat.h in directory \cc\include\sys: LHA a Archive.LZH \cc\include\sys\stat.h will store the filename as stat.h only. LHA ax Archive.LZH \cc\include\sys\stat.h will store the filename as \cc\include\sys\stat.h. b) the command is one of {ex}. In this case, the 'x' switch will extend the filenames so that files are restored to the appropriate subdirectories. Suppose you are in the root directory \, and Archive.LZH was created with the 'x' switch and contains the stat.h file from directory \cc\include\sys\: LHA e Archive.LZH stat.h will extract the stat.h file to the current directory. LHA ez Archive.LZH stat.h will extract stat.h into the directory \cc\include\sys (if one or more of the directories in the path does not exist, you will be prompted whether to create it). c) the command is {l}. In this case, the full stored pathname is listed for each member of the archive (the 'l' command with the 'x' option is exactly equivalent to the 'v' command). NOTE 1: You may specify this function with the 'z' switch instead of the 'x' switch; they are interchangeable. The 'z' switch is introduced in LHA v1.30 for compatibility with the 'Include Subdirectories' feature of ARCSHELL v2.3. NOTE 2: Switches 'r' and 'r2' automatically set the 'x' switch. If you wish to have 'r' or 'r2' without 'x', set the 'x' switch off (by using 'x-') after the 'r' or 'r2' specification. 6. Encryption As of release 2.00 of LHA, encryption is only supported in a special version of LHA, available to registered users. This was done for two reasons: 1) Since no other archiver currently provides encryption, most people will probably not need this feature, and 2) There is a small performance overhead to include encryption even when it is not used. When using the encryption-enabled version of LHA, the following switch is available: g[-|+|0|1|] (set encryption key) Applicable commands: {aumfexpst} ACTION: encrypts or decrypts archive members, as follows: a) the command is one of {aumf}, and thus an archive is being updated. The added members will be encrypted with the specified encryption key as they are added. b) the command is one of {expst}, and thus a member is being extracted. The extracted members will be decrypted with the specified encryption key as they are extracted. Note that if an encryption key is present, the switch is always set, i.e. it is always treated as 'g+'. Example: LHA agAAA new secret.txt adds an encrypted copy of 'secret.txt' to the archive 'new.lzh'. The copy is encrypted with the key AAA. In order to minimise overhead, the encryption technique used is simple, yet it provides effective protection against casual efforts at breaking. It is based on exclusive ORing a variable-length key with the data; the same technique will recover the original data. For anyone wishing to add this feature to another archiver, the following fragment of C code demonstrates the technique used: char *key; /* ptr to start of variable-length key */ char *keyptr; /* work ptr; NULL if no key */ /* * crypt - encryption/decryption routine */ int crypt(int c) /* c is the CHARACTER to encode */ { if (keyptr) { /* key supplied ? */ if (!*keyptr) /* at end of key ? */ keyptr = key; /* yes - reinitialise */ return c^*keyptr++; /* XOR it */ } return c; /* no key, no change */ } Note that encryption takes place IMMEDIATELY before writing the archive (i.e. after compression), and decryption takes place IMMEDIATELY after reading the archive (i.e. before decompression). 7. Concepts and terminology 1) Drive name, Path name, Directory name, File name: The following diagram shows the terminology used in LHA for various components of the filename: drive name file extension || |<>| c:\lc\lib\lcmasrnb.lib |<--- path name ---->| |<------>||<-------->| directory file name name 2) Base directory/drive This is a concept inherited from the original PC version of LHARC, and retained since it allows for complex processing of subdirectory structures that would not otherwise be possible. As of LHA version 1.10, it is not necessary to use (or understand) it, UNLESS you are extracting files using the 'p' switch (however, if you're comfortable with the concept, don't panic: you can can still use it at any time). If you DO use the 'p' switch, in order to distinguish between archived files of the same name in different subdirectories, then you WILL need to use the Base directory/drive if you wish to restore the files to directory(ies) other than the ones they are archived under. The use of Base directory/drive is probably best explained by examples. Example 1: to extract from an archive to another drive/directory: lha x z:\temp99\boring m:\somedir\ *.txt ^ SEE NOTE This extracts all .txt files from the boring archive to subdirectory somedir of drive m:. NOTE: there are one or more spaces between the target directory name and the file specification. In this example, z:\temp99\boring is the ARCHIVE m:\somedir\ is the BASE directory *.txt is the file specification Example 2: suppose your archive contains a pathname of \ABC\DEF\FILE.DOC. a) lha x archive file.doc puts FILE.DOC into current directory b) lha xx archive file.doc puts FILE.DOC into subdirectory \ABC\DEF within the current directory c) lha x archive z: file.doc puts FILE.DOC into drive Z d) lha xx archive z: file.doc puts FILE.DOC into subdirectory \ABC\DEF within drive Z. You've probably noticed that neither of the above two examples uses the 'p' switch: thus they could in fact be done by using the more familiar syntax of ARC. Example 1 becomes: lha x z:\temp99\boring m:\somedir\*.txt Example 2 becomes: a) lha x archive file.doc puts FILE.DOC into current directory b) lha xx archive file.doc puts FILE.DOC into subdirectory \ABC\DEF within the current directory c) lha x archive z:file.doc puts FILE.DOC into drive Z d) lha xx archive z:file.doc puts FILE.DOC into subdirectory \ABC\DEF within drive Z. However, the next example illustrates why Base directory/drive may be required when using the 'p' switch. Example 3: suppose you've got an archive containing two different files, stored with full pathnames as follows: \abc\test.txt \def\test.txt and you want to extract the first one into c:\pqr\test.txt and the second into d:\def\test.txt. This can be done as follows: lha xp archive c:\pqr\ \abc\test.txt lha xp archive d:\def\ \def\test.txt An alternative way of doing the second is: lha xpx archive d: \def\test.txt Of course, most people would just extract the files into the directories named in the archive, and move them afterwards; but the code to implement the 'p' switch was already there, and it took me hours to figure out what it meant. So I left the code in and tried to document its usage: who knows, someone might use it one day ! 8. Environment variables The following environment variables are examined by LHA. They are independent, except that the working directory may be specified by any of them; in case of such conflict, ARCTEMP overrides LHA which overrides TMP. ARCTEMP: supported in order to allow the ARCSHELL program to specify the working directory. It should NOT be used otherwise, since LHA uses the presence of this variable to detect that it is being run from ARCSHELL, and thence to support "Quester LZH Mode" compatibility. The working directory specified by ARCTEMP is overridden by that specified by the 'w' switch (if present) in the program arguments. LHA: may be used to set switches. For example, to set switches 'x' and 'm', use: LHA=xm The LHA environment variable is modified by program arguments. TMP: may be used to specify the working directory. For example, to set the working directory to d:\tmp, use: TMP=d:\tmp\ Note that the trailing \ in TMP is optional. The TMP environment variable is overridden by the 'w' switch from the 'LHA' environment variable, by the ARCTEMP environment variable, or by the 'w' switch from program arguments. 9. Result codes LHA returns the following result codes on termination: 0 normal termination. 1 an error has occurred: a) the user denied permission to update an archive file that did not have the standard '.LZH' extension, or b) some specified pathname was not used, or c) a header checksum error was detected in an existing archive, or d) a CRC error occurred during an unarchiving command (one of {expst}). Note that, since CRCs are calculated based on the unarchived & non-encrypted text, specification of the wrong encryption key when decrypting will cause a CRC error. 2 a fatal error has occurred. In most cases, no archive will have been created or moved, but check the displayed error messages for more detailed information. 3 a fatal error has occurred while copying the temporary output archive to the permanent output. The original archive has been deleted; the temporary archive is named LHA.)2( and is located in the work directory specified by the 'w' switch. Try renaming LHA.)2( to your archive's name, although note that it could be damaged. 10. Temporary Files The following filenames are used for temporary files during LHA processing: LHA.)1( Old archive file after rename. LHA.)2( New archive file before rename. LHA.TMP Work file when the 'w' switch, or the 'p' command with the 'v' switch, is specified. If a file with any of these names already exists, then LHA may not operate normally. III. LHA Appendices ------------------- 1. Using LHA with ARC Shell v3.1 ARC Shell (by Charles F. Johnson) is a shareware GEM program which adds a GEM interface to archiving programs, letting you point and click to select the various options instead of typing a command line. The latest version of ARC Shell (v3.1) has some improvements which LHA v2.xx takes advantage of. LHA v2.xx is now compatible with ARC Shell v3.1 in all of the basic functions, including subdirectory processing. Although LHA will work satisfactorily in ARC shell's normal mode in many cases, it is designed to work with the "Quester LZH Mode" button selected. The following summarises the interface betweeen LHA v2.xx and ARC Shell v3.1 (in Quester LZH Mode): a) The following ARC Shell buttons are fully compatible with LHA: Add, Move, Update, Freshen, Delete, Test, eXtract, copy to Stdout, List, Verbose list, Hold Screen, No Indicator, No Warnings, Full Paths, All Attribs, Skip Timestamp Comparison, Update Archive Timestamp, Search All Folders, Include Specified Folder, LH1 Mode b) The following ARC Shell buttons are not supported by LHA and will cause an error message to be issued: Run, cOnvert, No Compr., LARC Mode c) The 'Printer Name' for LHA on the ARC Shell configuration screen should be PRN:, not PRT:. If the remaining incompatibilities in (b) above are of significance to anyone, please let me know, since it is my objective to make LHA as easy to use with ARC Shell as possible. Priority, as always, will be given to suggestions/comments/complaints from registered users ! As an aside: ARC Shell is an excellent product that greatly simplifies usage of archivers from the desktop. I strongly encourage regular users of it (or any other shareware product) to register: there is no better way to let programmers know that the products of hours of effort are appreciated, and to encourage them to continue. 2. Performance A great amount of time has been spent fine-tuning the code to increase compression & decompression speeds. The following tables compare LHA to other utilities that process .LZH files, using two different files. The "binary" file is actually an ARC file, and thus hard to compress; this file is used as an indicator of worst-case compression performance. The "text" file is a series of real text messages from Usenet; this file is used as an indicator of typical text compression performance. 1) Old-style compression (-lh1-) LHA LHARC LHARC Test v2.10 LZH201K 102 051 FSTLZH16 UNLZH11 ---- ----- ------- ----- ----- -------- ------- Add binary file 18 14 23 26 26 n/a Add text file 80 56 116 143 147 n/a Extract binary file 9 8 18 20 25 8 Extract text file 24 15 41 44 58 10 All processing was done on a 1040 ST using a RAM disk to eliminate differences due to data location. All times are in seconds. File sizes (as reported by an archive list) are as follows: Original size Compressed size ------------- --------------- Binary file 26719 24854 Text file 157050 72692 2) New-style compression (-lh5-) ------------- TT030 ------------ ---- 1040 ST --- --- TT RAM --- --- ST RAM --- LHA LHA LHA Test v2.10 LZH201K v2.10 LZH201K v2.10 LZH201K ---- ----- ------- ----- ------- ----- ------- Add binary file 3.7 3.4 5.6 5.0 13.1 12.2 Add text file 19.4 16.8 32.0 26.3 75.7 68.3 Extract binary file 1.3 1.6 1.9 2.1 4.9 4.8 Extract text file 3.4 3.7 5.2 5.1 17.2 15.0 Processing was done in an empty disk partition to eliminate differences due to data location. All times are in seconds. File sizes (as reported by an archive list) are as follows: Original size Compressed size ------------- --------------- Binary file 26719 24788 Text file 157050 66696 The results show that times for -lh5- compression are generally less than those for -lh1- compression, and compressed sizes are smaller; thus there seems to be no reason to use old-style compression unless it is required for compatibility. Although archiving is clearly not a general-purpose benchmark, the results also provide an interesting comparison between the TT with the ST: 1. The TT (without TT RAM) is approximately 2.3 to 3.3 times the speed of the ST. 2. Executing out of TT RAM increases performance by a further 40-60% compared to ST RAM, giving a TT:ST ratio of between 3 and 5. 3. LHA Revision History Version 1.00 First released version Version 1.10 Fixes the following bugs: a) when extracting a file which already exists in the target directory, the comparison for date/time was incorrect; this caused the message 'Skipped xxx: same or more recent file exists' to be issued when it shouldn't have been, and NOT to be issued when it should have been. Changes the following design peculiarities, inherited from the PC version of LHARC: a) archives that contain header checksum errors, such as the 'WORLD.LZH' file on GEnie, are now handled with a warning message, rather than silently treating such headers as end-of-archive. b) extracting identically named files from archives that contain subdirectories is now handled more consistently (the situation in which this actually changes the behaviour of LHA is so obscure that it is not worth describing). Adds the following features: a) ARCSHELL compatibility when extracting files: if the 'p' switch is not specified, and the 'basedir' is omitted, the user may specify a fully-qualified path for each file, and the file will be extracted to the specified path. The ARCTEMP environment variable, which is set by ARCSHELL, is now used by LHA to control placement of the working directory. b) comment display, as well as comment addition, is now controlled by the 'c' switch; this helps in cases where the "comments" are really garbage (as in archives created by LHARC102). c) a smaller i/o buffer size is used when listing archives; this should speed up archive display, particularly on slower devices like floppies. Version 1.20 Source changed where necessary to compile under Lattice C v5.04.00. Fixes the following bugs: a) output redirection is now more consistent: for example, the initial title/usage messages are no longer subject to redirection. b) the 'a'/'u'/'m' commands can no longer erroneously add the temporary file 'lha.)1(' (the temporarily- renamed existing archive) when updating that archive. Previously, this could have happened if the filename specification allowed it (e.g. with a filename spec of '*.*'). Changes the following design peculiarities, inherited from the PC version of LHARC: a) if moving a file to an archive (via the M command) fails, due to a more recent version of the file already existing in the archive, the external file is no longer deleted. This provides greater safety in the event that either the archive or file timestamp is wrong, or that different files have inadvertently been given the same name. Adds the following features: a) the 's' command is now accepted as a synonym for display: this allows LHA to display files when running under ARCSHELL v2.1b. b) LHA now operates more quickly, particularly when extracting files. Overall performance is around 5%-30% faster than LHA v1.10. Version 1.21 Fixes the following bugs: a) the date/time stamp of extracted files (and of output archive files when the 't' switch is specified) is finally set correctly when running LHA under TOS 1.0! This problem has apparently existed in all previous versions of LHA. Sincere thanks to Alexander Smith for pointing this out, and apologies to everyone for this long-standing major bug; my only defence is that it always worked correctly under TOS 1.4. b) the 'h' flag no longer causes the program to hang under TOS 1.0. This problem was introduced in v1.20. Version 1.30 Changes the following features: a) the temporary file in the work directory (if present) is now renamed (possibly across directories) to the target file, rather than copied. This provides some performance improvement. b) output from the verbose list function now occupies the minimum number of lines necessary; in particular, a verbose list of an archive that does not contain directory information is now the same as a list of the same archive. Adds the following features: a) the 'g' flag may now be used to specify an encryption/decryption key. b) case is ignored when matching filenames, allowing for the selective extraction of archive members stored under Un*x-style systems. c) the extension information stored by lharc102 and other Un*x-derived versions of lharc is decoded and displayed when comments display is enabled. d) LHA now operates more quickly when adding files. Overall performance is up to 18% faster than LHA v1.21. Version 2.00 Adds the following features: a) -lh5- archives are now supported! This introduces a new compression method plus two new varieties of internal archive header. b) for downward compatibility, the 'o' flag has been added. Setting this on forces old-style (i.e. -lh1-) compression to be used; otherwise, by default, -lh5- archives are created. c) compatibility with ARCSHELL has been greatly improved. With ARCSHELL's "Quester LZH Mode" set, LHA implements all the major functions of ARCSHELL. d) for compatibility with archivers on other platforms, .LHA is now recognised as a valid archive extension in the following circumstances: when listing or extracting from an archive; and when updating an archive when the 'm' switch is not set. e) for compatibility with MSDOS LHARC v2.xx, the 'l' flag has been added to set the header level to 0, 1 or 2. By default, it is set to zero for downward compatibility with earlier versions of LHA. f) an id of 'A' stored as a 1-byte comment is now interpreted to mean that the archive was created under 'Atari TOS'; this code will also be generated when an archive is created, if no other comment is specified. g) new error messages have been added to cover additional error situations that can arise. Fixes a minor bug: the stored file name in an archive was not listed correctly if it was skipped during extraction due to an unrecognised header type. Version 2.01 Fixes the following bug, introduced in v2.00: a) when screen output (e.g. archive listing or file display) was interrupted by pressing control-C, LHA terminated abnormally, usually with 2 bombs. This could also cause system crashes. Version 2.10 Adds the following features: a) -lz4-, -lz5-, and -lh4- archives can now be decompressed by LHA. These are older compression methods that may still be encountered in existing archives created by older programs on various platforms; in particular, self-extracting archives often use -lz5- compression, and such files can now be processed with LHA. b) Amiga-style comments ("filenotes") are now supported. When adding comments to a new or existing archive, the type of comment stored depends on the archive file extension: Amiga-style comments are generated for a .LHA extension Atari-style comments are generated otherwise When decoding an archive, both styles of comments are recognised, irrespective of the archive extension. 4. Our Distribution Policy Under the following conditions, you may freely copy and distribute this software: 1. Under all circumstances, 'Copyright by Roger Burrows' and 'Copyright by Haruyasu Yoshizaki' must be attached to the copy. 2. This manual or its hardcopy should go together with the software. 3. You must try to distribute the newest version available. 4. Neither Roger Burrows nor Haruyasu Yoshizaki ("the authors") assume any liability for any damages, consequential or otherwise, that you may sustain in using this software. 5. The authors have no obligation to revise the program to correct any fault in this software. 6. For the commercial use of this software, the authors add the following: a. Any software that is distributed with, or incorporates, this program shall not be copy protected; that is, the standard copy functions of the GEM disktop shall be capable of making an exact copy. b. Every part of the package shall print the copyright banner. c. The distribution policy of this software shall be printed either in the manual, in the package or on the disk-label. 5. Acknowledgments * Principal thanks to Haruyasu Yoshizaki ('Yoshi') for placing the source code in the public domain, and for writing most of it in C (hooray for portability). Also many thanks to Haruhiko Okumura for placing the code for -lh5- compression in the public domain (via his AR archiver). * Further gratitude to H. Okumura who uploaded the code for LZARI in PCVAN on which -lh1- compression is based. To K. Miki, who re-posted LZARI to Nifty Serve, and who is the author of Larc we also express our gratitude. For those who contributed reports and comments and information on bugs in the MSDOS version, we thank you very much. * For the Atari ST/TT version, thanks to (alphabetically) Walter Cole, Alan Dalgliesh, Bob Deskin, Tim Rosenquist and Alexander Smith of the Ottawa National Capital Atari Users Group (NCAUG) for beta testing various versions of this program. Their efforts have made this a better program, and have encouraged me to continue to improve it. Special thanks to Alexander Smith for his clear and concise bug reports. * Last but not least, thanks to Atari for developing the TT + 19" monitor, and to HiSoft for porting Lattice C to the TT environment. Together, they're a great development environment! 6. Changes For The ST/TT Environment Although LHA is principally based on LHarc v1.13b, numerous changes have been made. They fall into the following areas: 1. to handle the architectural differences between Intel and Motorola processors; this principally affects the order of bytes in 16- and 32-bit integers. 2. to accommodate the different operating system; although GEMDOS is patterned after MSDOS, there are some differences at the lowest levels. 3. to allow the use of a different compiler (currently Lattice C version 5.51 for the Atari ST/TT) with different library functions. 4. to provide additional checking of error codes returned by library functions; I believe that all possible errors are now checked for. 5. to split the code into more modules, for easier maintenance. 6. to rewrite parts of the code in assembler to improve performance. 7. to add support for storing and retrieving comments associated with each archive member; these are stored in a manner compatible with LHARC051. 8. to add support for -lh5- archives, and various archive header formats. Because of the many revisions, there is a non-zero probability that some bugs have been introduced into the Atari version of this program (there may still be bugs lurking from the PC version). I would appreciate your comments and bug reports. Please route them to me via the following addresses: 1) GEnie: Userid: R.BURROWS1 2) BBS: NCAUG Bulletin Board (613) 738-2887 (1200/2400/9600 baud) Userid: Roger Burrows 3) Snail-mail: Roger Burrows Anodyne Software 6 Cobbler Court Ottawa Ontario K1V 0B8 Canada Bug reports and suggestions from registered owners will be handled first, but I will endeavour to fix any bugs reported by any user.