.TH lha 1
.SH NAME
lha \- compression tool for .lzh archive files.
.SH SYNOPSIS
.B lha
.RB [ - ]{ lvtxep [ q { \f[I]num\f[] }][ finv ]}[ w= < \f[I]dir\f[] >]
.I archive_file
.RI [ "file ..." ]
.SH DESCRIPTION
.PP
.B lha
is a tool for extracting .lzh archive files. It also supports variants
of the .lzh archive, such as .lzs and .pma.
.PP
This version of the lha tool is part of Lhasa, a free implementation
of the .lzh format.
.PP
.SH COMMAND SYNTAX
The lha tool has an unusual command syntax, compared to most other
Unix commands. The first parameter to the program specifies the command
to perform and all additional options. The second parameter specifies
the path to the archive file to operate on. Following this is a list
of wildcard patterns to match against the filenames of the archived
files.
.PP
The first character of the command parameter specifies the command to
perform, which is one of the following:
.TP
\fB-l\fR
List contents of the specified archive.
.TP
\fB-v\fR
Verbosely list contents of the specified archive.
.TP
\fB-t\fR
Test the integrity of the specified archive: decompress its contents and
check the CRC.
.TP
\fB-e\fR or \fB-x\fR
Extract archive. Files are extracted to the current working directory
unless the 'w' option is specified.
.TP
\fB-p\fR
Extract archive, sending decompressed files to stdout rather than
writing them to the filesystem as actual files. This is useful when used
as part of a shell pipeline.
.PP
.SH OPTIONS
The remainder of the command parameter is used to specify additional
options:
.TP
\fBq[012]\fR
Quiet mode. Higher numbers suppress more output. Level 0 is normal
operation. If no number is specified, full suppression (level 2)
is used. The quiet option also turns on the force overwrite option
('f').
.TP
\fBf\fR
Force overwrite of existing files: do not prompt.
.TP
\fBi\fR
Ignore paths of archived files: extract all archived files to the
same directory, ignoring subdirectories.
.TP
\fBn\fR
Do not perform any actual operations: instead, perform a dry run of
the requested operation and describe what would have been done on
standard output.
.TP
\fBv\fR
Verbose mode: causes extra information to be written to standard
output.
.TP
\fBw=dir\fR
Specify destination directory for extracting files. This must be
the last option of the first parameter.
.SH LIST OUTPUT FORMAT
Lhasa inherits its list output format from the original Unix port of lha, and
retains the same format for compatibility, since some tools parse the output.
Four different output formats are supported, depending on the command line
arguments:
.TP
\fBlha -l filename.lzh\fR
Shows: Unix permissions / OS type, UID/GID, uncompressed size, compression
ratio, modification time, filename.
.TP
\fBlha -lv filename.lzh\fR
Two line output. First line shows the filename, second line shows: Unix
permissions / OS type, UID/GID, uncompressed size, compression ratio,
modification time, filename, header level.
.TP
\fBlha -v filename.lzh\fR
Shows: Unix permissions / OS type, UID/GID, compressed size, uncompressed size,
compression ratio, compression format, checksum, modification time, filename.
.TP
\fBlha -vv filename.lzh\fR
Two line output. First line shows the filename, second line shows: Unix
permissions / OS type, UID/GID, compressed size, uncompressed size, compression
ratio, compression format, checksum, long form modification time, header
level.
.PP
The following are detailed descriptions of each of these fields:
.TP
\fBUnix permissions / OS type (PERMSSN)\fR
For files compressed on a Unix system, this lists the permissions in the same
format that \fBls\fR(1) uses when it is invoked with the \fB-l\fR option. If
the file was not created on a Unix system, the OS type is instead displayed in
square brackets. Examples are "[MS-DOS]" and "[MacOS]"; the OS name never
contains a space. If the file was created on Microware OS-9, the permissions
for that system will also be shown.
.TP
\fBUnix user ID / group IDs (UID/GID)\fR
For files compressed on a Unix system, this lists the user and group IDs of
the file, similar to the output seen from \fBls\fR(1) when it is invoked with
the \fB-ln\fR option. If the file was not created on a Unix system,
"*****/*****" is shown; see \fBLIST FORMAT DIFFERENCES\fR below.
.TP
\fBCompressed size (PACKED)\fR
Size of the file in bytes as it is stored inside the archive (not including
the header, which contains metadata about the file). If an uncompressed format
like \fB-lh0-\fR is used, this will be equal to SIZE.
.TP
\fBUncompressed size (SIZE)\fR
Size of the file in bytes before it was compressed.
.TP
\fBFile compression ratio (RATIO)\fR
Compressed size as a percentage of uncompressed size. This measures the
effectiveness of the compression format; the smaller the percentage, the
better. The value is (pessimistically) rounded up to the next 0.1%. If an
uncompressed format like \fB-lh0-\fR is used, this will be equal to 100%. For
directories, "******" is shown. Note that the value here is backwards relative
to \fBunzip\fR(1), which instead shows the percentage of the original file size
reduced.
.TP
\fBCompression format (METHOD)\fR
The compression format used to store this file. See the \fBCOMPRESSION
FORMATS\fR section below.
.TP
\fBChecksum (CRC)\fR
CRC16 checksum of the file's contents in hexadecimal format. Warning: while
this is useful for casually checking file integrity, it is only a 16-bit
checksum and should not be considered reliable for protecting files larger than
a few kilobytes.
.TP
\fBModification time (STAMP)\fR
Date and time that the file was last modified before it was stored in the
archive. If the file doesn't have a timestamp stored, nothing is shown.
The output can be in one of two forms: if the date is within the past six
months, the month, day and time are shown; an example is "Aug 24 12:38". For
older files, the month, day and year are shown; an example is "Aug 24 2020".
.TP
\fBLong form modification time (STAMP)\fR
This is only used when listing in the \fB-vv\fR format. The full date and
timestamp are listed in numeric form, close to ISO 8601 format (though not
quite conformant with that standard). An example is "2020-08-24 12:38:25".
.TP
\fBHeader level (LV)\fR
Lha header format used to store this file. Supported formats are 0-3.
.SH LIST FORMAT DIFFERENCES
The list mode output from the original Unix lha tool was not designed to be
machine-readable. Since some tools do try to parse the list output, Lhasa's
list output has been deliberately tweaked slightly to make the output more
consistent and easier to parse.
.PP
Here are the main differences:
.IP \(bu
If a file was not created on a Unix system, a spacer word is shown in the
UID/GID column. The original lha just showed whitespace.
.IP \(bu
The OS type for archives generated by MacLHA is listed as "MacOS" (no space).
The original lha showed "Mac OS".
.PP
Note that in general, the approach of parsing text output is inherently fragile
and prone to bugs. It's recommended that you instead use the proper API
(liblhasa).
.SH COMPRESSION FORMATS
The following gives some basic description of the various different supported
compression formats (as listed when using the list command documented above).
All formats are variants on the LZSS compression algorithm.
.TP
\fB\-lz4\-\fR
Uncompressed (stored) data, as used by the original LArc tool. This is not
related to the LZ4 compression algorithm of the same name.
.TP
\fB\-lz5\-\fR, \fB\-lzs\-\fR
Compression formats introduced with the original LArc tool.
\-lzs\- uses a 2KiB sliding window while \-lz5\- uses a 4KiB window.
.TP
\fB\-lhd\-\fR
Directory entry. No data is stored, only headers.
.TP
\fB\-lh0\-\fR
Uncompressed (stored) data, as used in LHarc and LHa.
.TP
\fB\-lh1\-\fR
Compression algorithm introduced with LHarc. This uses a 4KiB sliding window
with dynamic Huffman encoding.
.TP
\fB\-lh4\-\fR, \fB\-lh5\-\fR, \fB\-lh6\-\fR, \fB\-lh7\-\fR
New algorithm introduced with LHa (aka LHarc v2.0). The original versions
(\-lh4\- and \-lh5\-) used 8KiB and 16KiB sliding window sizes, respectively.
Later versions introduced new variants with larger window sizes: \-lh6\-
(64KiB) and \-lh7\- (128KiB).
.TP
\fB\-lhx\-\fR
Variant on the \-lh4\- format listed above introduced by UNLHA32.dll that
extends the window size to 1MiB.
.TP
\fB\-lk7\-\fR
Variant on the \-lh4\- format listed above that was introduced by the LHark
tool (a fork of LHa). This is actually named \-lh7\- within the archive files,
but Lhasa renames it internally to avoid clashing with the other algorithm of
the same name. Uses a 128KiB sliding window, with some minor improvement to the
algorithm.
.TP
\fB\-pm0\-\fR
Uncompressed (stored) data, as used by the PMarc tool.
.TP
\fB\-pm1\-\fR
Algorithm used by version 1 of the PMarc tool.
.TP
\fB\-pm2\-\fR
Algorithm used by version 2 of the PMarc tool.
.PP
.SH UNSUPPORTED FORMATS
The following formats are \fBnot\fR currently supported by Lhasa (but possibly
will be in the future):
.TP
\fB\-lh2\-\fR, \fB\-lh3\-\fR
These formats can be decompressed by LHa v2.0 but the tool could not actually
generate archives with these formats; they appear to have only been supported
in beta versions before the v2.0 release. As a result, few if any examples
exist in the wild.
.TP
\fB\-lh8\-\fR, \fB\-lh9\-\fR, \fB\-lha\-\fR, \fB\-lhb\-\fR, \fB\-lhc\-\fR, \fB\-lhe\-\fR
Extensions of the \-lh4\- format to even larger window sizes.
.TP
\fB\-ll0\-\fR, \fB\-ll1\-\fR
Generated by ThunderSoft's PAKLEO utility (.pll).
.TP
\fB\-sw0\-\fR, \fB\-sw1\-\fR
Used in SourceWare Archival Group's .swg (SWAG packet) format.
.TP
\fB\-lz6\-\fR, \fB\-LD6\-\fR
Generated by LDarc and LDIFF (.lzd).
.TP
\fB\-hf0\-\fR, \fB\-ah0\-\fR, \fB\-ari\-\fR, \fB\-arn\-\fR, \fB\-arw\-\fR
Generated by the Micrognosis Compression Archiver utility.
.TP
\fB\-pc1\-\fR
Format generated by the PopCom! compression utility for CP/M.
.PP
If you encounter examples of these in the wild, please get in touch.
.SH EXAMPLES
Here are some examples for how to invoke the program:
.TP
lha -v foobar.lzs
List the contents of the file \fBfoobar.lzs\fR (producing verbose output).
.TP
lha -xf foobar.exe
Extract the contents of a self-extracting archive file named \fBfoobar.exe\fR
to the current directory, overwriting existing files with the same names if
they exist.
.TP
lha -xqw=/tmp foobar.lzh
Extract the contents of \fBfoobar.lzh\fR to \fB/tmp\fR, overwriting any
existing files found there, and suppressing normal output (similar to
how other Unix tools such as \fBcp\fR(1) or \fBtar\fR(1) act silently
by default).
.SH WWW
.UR https://lhasa.soulsphere.org/
https://lhasa.soulsphere.org/
.UE
.SH BUG REPORTS
Bugs can be reported to the GitHub issue tracker:
.UR https://github.com/fragglet/lhasa
https://github.com/fragglet/lhasa
.UE
.SH SEE ALSO
\fBunzip\fR(1), \fBtar\fR(1), \fBgzip\fR(1), \fBbzip2\fR(1),
\fBxz\fR(1), \fBlzip\fR(1)
.SH HISTORY
The .lzh format originated with Kazuhiko Miki's MS\-DOS archive tool,
LArc, using the LZSS algorithm developed by Haruhiko Okumura, and
the .lzs filename extension. The container format was reused for
LHarc, by Haruyasu Yoshizaki (Yoshi), which used a new algorithm
named LZHUF and the .lzh extension. In later versions, LHarc was
renamed to LHA and extended with more effective compression algorithms.
.PP
Versions of the LHA tool were later ported to various different
operating systems, including the Amiga, Atari, MacOS, OS/2 and Unix.
A tool for MSX\-DOS named PMarc reused the container format with a new
compression algorithm (.pma extension).
.PP
The Unix version of the tool was developed by Masaru Oki, Nobutaka
Watazaki and Tsugio Okamoto, but was released under a software
license that does not conform to the Free Software or Open Source
Definitions. Lhasa was developed as a drop\-in replacement that is
Free Software and Open Source.
.PP
The name "LHA" and the .lzh filename extension are a reference to the
compression algorithm: a combination of Lempel–Ziv–Storer–Szymanski
dictionary coding and Huffman encoding. Similar schemes are used in
other compression algorithms such as Deflate (used in gzip/zlib, PNG
image files, and the .zip format).
.SH BUGS
The current version does not allow the creation of new archive files.
.PP
Some obscure compression algorithms are not currently supported (see the
UNSUPPORTED FORMATS section above).
.PP
The tool does not currently do text format conversion for non-ASCII
filenames when listing the contents of archives. Non-ASCII characters
are replaced by a question mark.
.SH AUTHOR
Lhasa was written and is maintained by
.MT fraggle@gmail.com
Simon Howard
.ME .
.SH COPYRIGHT
Copyright \(co 2011-2025 Simon Howard.
.PP
Permission to use, copy, modify, and/or distribute this software
for any purpose with or without fee is hereby granted, provided
that the above copyright notice and this permission notice appear
in all copies.
.PP
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR
CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.