User's Manual for LHA v1.30 (13 April 1991) ------------------------------------------- Program & documentation by: Roger Burrows Based on: LHarc version 1.13b (for MS-DOS), Copyright(c) Haruyasu Yoshizaki (Yoshi),1988-89 Documentation dated 1989-3-4 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 end with .LZH. This archive format was invented by a programmer in Japan, and implemented in an MS-DOS program called LHARC. LHA is based on version 1.13b of LHARC, but with a number of extensions and a great deal of optimisation to improve its speed. 2. Terms and Conditions As of version 1.30, LHA is available in two formats: non-registered and 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 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: [ ... ] In either case: is the archive name; by default, the extension '.LZH' is assumed ... 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; in this case, 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 archive 'sample.lzh' to the standard output. -test (equivalent basic command: th+) LHA -test new ACTION: tests specified members (in this case, all members) of archive 'new.lzh', 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' 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: {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 eleven listed commands 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; if the file extension is omitted, it is assumed to be .LZH. If it is specified, and is not .LZH, and the command could update 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 archive 'sample.lzh' 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 archive 'new.lzh', 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' 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 '+' or '-' sign after switches with the following meanings: '+' sets the switch on, and '-' sets the switch off. In addition, a '2' may be placed after the '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[-|+] (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[-|+] (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[-|+] (use Comments) Applicable commands: {aumflv} ACTION: adds or displays comments that have been stored in a format compatible with that used by LHARC051, 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 50 characters in length. 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 []. NOTE: Certain archivers (including LHARC102) create archive headers that appear to contain LHARC051-style comments, but in fact contain extension information, some of which is non-printable. When displaying such archives with this switch set, the displayed comment line will contain an interpretation of the extension information, rather than a literal display of the data. The interpreted data will be enclosed in curly braces {}. g[-|+|] (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. h[-|+] (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[-|+] (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. m[-|+] (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[-|+] (No indicator) Applicable commands: {aumfexpst} ACTION: suppresses the display of the progress indicator when compressing or decompressing files. p[-|+] (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[-|+|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[-|+] (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[-|+|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[-|+|] (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[-|+] (eXtend) z[-|+] 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 technique The encryption technique used is simple and therefore does not have significant performance overhead, 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. Since no other archiver currently provides encryption, you may wish to avoid using this feature to encrypt archives that you are providing to others, unless you are sure that they are using LHA v1.30 or above. 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 */ } 7. Concepts and terminology 1) 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 ! 2) Drive name, Path name, Directory name, File name: drive name || a:\cc\include\stdio.h |<--- path name --->| |<---------->||<--->| directory name file name 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: may be used to specify the working directory. For example, to set the working directory to d:\tmp, use: ARCTEMP=d:\tmp\ Note that the trailing \ in ARCTEMP is optional. ARCTEMP is overridden by the 'w' switch if specified in the program arguments. ARCTEMP is supported for full compatibility with the ARCSHELL program. 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. 11. Using LHA with ARC Shell v2.3 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 (v2.3) has some improvements which LHA v1.30 now takes advantage of. LHA v1.30 is now compatible with ARC Shell v2.3 in all of the basic functions, including subdirectory processing. There are still some minor incompatibilities: certain ARC Shell buttons have no effect on LHA, and certain functions of LHA are not currently available via ARC Shell. The following summarises the interface betweeen LHA v1.30 and ARC Shell v2.3: 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, Keep Backup, Include Subdirectories, Encrypt, LZH comments b) The following ARC Shell button is not passed to LHA, and therefore has no effect: Overwrite Existing Files c) The following ARC Shell buttons are not supported by LHA and will cause an error message to be issued: Run, cOnvert, Suppress compression d) The following ARCSHELL buttons have unexpected effects: Suppress Messages This is interpreted by LHA as specifying a working directory and if Suppress Notes and/or LZH Comments are set, they will be treated as the working directory name. DON'T USE THIS SWITCH ! Suppress Notes This actually suppresses display of the progress indicator. e) The following LHA switches provide functions that are NOT supported by ARC Shell: a (any Attribute), i (Ignore comparison of time stamp), m (no Message), p (Precise), r (Recursively search directories), t (archive Time-stamp), v (View by page) Lack of access to these options will probably not cause problems to most users of ARC Shell. f) The 'Printer Name' for LHA on the ARC Shell configuration screen should be PRN:, not PRT:. I would like to make LHA as compatible with ARC Shell as possible, and I would like to thank Charles Johnson for changes to ARC Shell which have made it easier to be compatible; I have added some additional compatibility features in LHA v1.30 as a result. I welcome any suggestions for further increasing compatibility with ARC Shell, or with any other graphic shell you use. Priority, as always, will be given to suggestions from registered users ! 12. Performance A great amount of time has been spent fine-tuning the code to increase compression & decompression speeds. For most files, the elapsed time for adding files to an archive is around 40% less than that of LHARC v0.51; for extracting files, the elapsed time is around 45% less. The following table compares LHA to four other utilities that process .LZH files: ------- LHA ------- LHARC LHARC Test v1.30 v1.21 v1.10 102 051 FSTLZH16 UNLZH11 ---- ----- ----- ----- ----- ----- -------- ------- Add binary file 20 20 22 23 26 26 n/a Add text file 82 100 106 116 143 147 n/a Extract binary file 11 11 13 18 20 25 8 Extract text file 25 25 33 41 44 58 10 All processing was done on 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 13. 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.15 Internal version only: source changed where necessary to compile under Lattice C v5.04.00. This mostly consisted of adding function prototypes where not already present, and handling small changes in the library. Version 1.20 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. 14. 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. 15. 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). * Special gratitude for H.Okumura who uploaded the code for LZARI in PCVAN on which this LZHuf coding 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 version, thanks to (alphabetically) Walter Cole, Alan Dalgliesh, and Bob Deskin for their efforts in improving the useability of this program, both code and documentation; and for being brave enough to risk an untried file compression program. Thanks also to Alexander Smith for helping to make this a better program by his clear and concise bug reports. * Although LHA is principally based on LHarc v1.13b, numerous changes were made. They fall into eight 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.06.01 for the Atari ST). 4. to use different library functions, as provided with the Lattice C compiler. 5. to provide additional checking of error codes returned by library functions; I believe that all possible errors are now checked for. 6. to split the code into more modules, for easier maintenance. 7. to rewrite parts of the code in assembler to improve performance. 8. to add support for storing and retrieving comments associated with each archive member; these are stored in a manner compatible with LHARC051. Because of the many revisions, there is a non-zero probability that some bugs have been introduced into the ST 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) 737-1133 (1200/2400 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.