src/bin/compress/compress.1

   1 .PU
   2 .TH COMPRESS 1 local
   3 .SH NAME
   4 compress, uncompress, zcat  \-  compress and uncompress files
   5 .SH SYNOPSIS
   6 .ll +8
   7 .B compress
   8 [
   9 .B \-c
  10 ] [
  11 .B \-C
  12 ] [
  13 .B \-d
  14 ] [
  15 .B \-f
  16 ] [
  17 .B \-v
  18 ] [
  19 .B \-b
  20 .I bits
  21 ] [
  22 .I "filename \&..."
  23 ]
  24 .ll -8
  25 .br
  26 .B uncompress
  27 [
  28 .B \-c
  29 ] [
  30 .B \-f
  31 ] [
  32 .B \-v
  33 ] [
  34 .B \-V
  35 ] [
  36 .I "filename \&..."
  37 ]
  38 .br
  39 .B zcat
  40 [
  41 .I "filename \&..."
  42 ]
  43 .SH DESCRIPTION
  44 Compresses the specified files or standard input.
  45 Each file is replaced by a file with the extension
  46 .B "\&.Z,"
  47 but only if the file got smaller.
  48 If no files are specified,
  49 the compression is applied to the standard input
  50 and is written to standard output
  51 regardless of the results.
  52 Compressed files can be restored
  53 to their original form by specifying the
  54 .B \-d
  55 option, or by running
  56 .I uncompress
  57 (linked to
  58 .IR compress ),
  59 on the
  60 .B "\&.Z"
  61 files or the standard input.
  62 .PP
  63 If the output file exists, it will not be overwritten unless the
  64 .B \-f
  65 flag is given.  If
  66 .B \-f
  67 is not specified and
  68 .I compress
  69 is run in the foreground,
  70 the user is prompted
  71 as to whether the file should be overwritten.
  72 .PP
  73 If the
  74 .B \-f
  75 flag is given, all files specified are replaced with
  76 .B "\&.Z"
  77 files \- even if the file didn't get smaller.
  78 .PP
  79 When file names are given, the ownership (if run by root), modes, accessed
  80 and modified times are maintained between the file and its
  81 .B "\&.Z"
  82 version.  In this respect,
  83 .I compress
  84 can be used for archival purposes, yet can still be used with
  85 .IR make "(1)"
  86 after uncompression.
  87 .PP
  88 The
  89 .B \-c
  90 option causes the results of the compress/uncompress operation to be written
  91 to stdout; no files are changed.  The
  92 .I zcat
  93 program is the same as specifying
  94 .B \-c
  95 to
  96 .I uncompress
  97 (all files are unpacked and written to stdout).
  98 .PP
  99 .I Compress
 100 uses the modified Lempel-Ziv algorithm described in
 101 "A Technique for High Performance Data Compression",
 102 Terry A. Welch,
 103 .I "IEEE Computer"
 104 Vol 17, No 6 (June 1984), pp 8-19.
 105 Common substrings in the file are first replaced by 9-bit codes 257 and up.
 106 When code 512 is reached, the algorithm switches to 10-bit codes and
 107 continues to use more bits until the
 108 .I bits
 109 limit as specified by the
 110 .B \-b
 111 flag is reached (default 16).
 112 .I Bits
 113 must be between 9 and 16.  The default can be changed in the source to allow
 114 .I compress
 115 to be run on a smaller machine.
 116 .PP
 117 After the
 118 .I bits
 119 limit is reached,
 120 .I compress
 121 periodically checks the compression ratio.  If it is increasing,
 122 .I compress
 123 continues to use the codes that were previously found in the file.  However,
 124 if the compression ratio decreases,
 125 .I compress
 126 discards the table of substrings and rebuilds it from scratch.  This allows
 127 the algorithm to adapt to the next "block" of the file.  The
 128 .B \-C
 129 (compatibility) flag prevents subdivision of the file into blocks;
 130 this produces an output file that old versions of
 131 .I compress
 132 can read.
 133 .PP
 134 A two byte magic number is prepended to the file
 135 to ensure that neither uncompression of random text nor recompression of
 136 compressed text are attempted.  In addition, the
 137 .I bits
 138 specified during
 139 .I compress
 140 is written to the file so that the
 141 .B \-b
 142 flag can be omitted for
 143 .IR uncompress \.
 144 .PP
 145 .ne 8
 146 The amount of compression obtained depends on the size of the
 147 input file, the amount of
 148 .I bits
 149 per code, and the distribution of character substrings.
 150 Typically, text files, such as C programs,
 151 are reduced by 50\-60%.
 152 Compression is generally much better than that achieved by
 153 Huffman coding (as used in
 154 .IR pack ),
 155 or adaptive Huffman coding
 156 .RI ( compact ),
 157 and takes less time to compute.
 158 .PP
 159 .PP
 160 If the
 161 .B \-v
 162 (verbose) flag is given, then
 163 after each file is compressed, a message is printed giving the percentage of
 164 the input file that has been saved by compression.
 165 .PP
 166 If the
 167 .B \-V
 168 (version) flag is given, the program's version number is printed.
 169 .PP
 170 The exit status is normally 0;
 171 if the last file gets bigger after compression, the exit status is 2;
 172 if an error occurs, the exit status is 1.
 173 .SH "SEE ALSO"
 174 compact(1), pack(1)
 175 .SH "DIAGNOSTICS"
 176 Usage: compress [-cCdfvV] [-b maxbits] [file ...]
 177 .in +8
 178 Invalid options were specified on the command line.
 179 .in -8
 180 Missing maxbits
 181 .in +8
 182 Maxbits must follow
 183 .BR \-b \.
 184 .in -8
 185 Unknown flag:
 186 .I "\'x\';"
 187 .in +8
 188 Invalid flags were specified on the command line.
 189 .in -8
 190 .IR file :
 191 not in compressed format
 192 .in +8
 193 The specified file has not been compressed.
 194 .in -8
 195 .IR file :
 196 compressed with
 197 .I xx
 198 bits, can only handle
 199 .I yy
 200 bits
 201 .in +8
 202 The specified file was compressed by a compress program that could handle
 203 more
 204 .I bits
 205 than the current compress program.  Recompress the file with a smaller
 206 .IR bits \.
 207 .in -8
 208 .IR file :
 209 already has .Z suffix -- no change
 210 .in +8
 211 Cannot compress a file that has a ".Z" suffix.
 212 .IR mv "(1)"
 213 the file to a different name and try again.
 214 .in -8
 215 .IR file :
 216 filename too long to tack on .Z
 217 .in +8
 218 The specified file cannot be compressed because its filename is longer than
 219 12 characters.
 220 .IR mv "(1)"
 221 the file to a different name and try again.  This message does not occur on
 222 4.2BSD systems.
 223 .in -8
 224 .I file
 225 already exists; do you wish to overwrite (y or n)?
 226 .in +8
 227 Respond "y" if you want the output file to be replaced; "n" if you want it
 228 to be left alone.
 229 .in -8
 230 .IR file :
 231 .in +8
 232 This message fragment is written during the processing of a file.
 233 .in -8
 234 Compression:
 235 .I "xx.xx%"
 236 .in +8
 237 This message fragment gives the percentage of the input file that has been
 238 saved by compression.
 239 .in -8
 240 -- not a regular file: unchanged
 241 .in +8
 242 This message fragment is written when the input file is not a regular file.
 243 The input file is left unchanged.
 244 .in -8
 245 -- has
 246 .I xx
 247 other links: unchanged
 248 .in +8
 249 This message fragment is written when the input file has links.  The input
 250 file is left unchanged.  See
 251 .IR ln "(1)"
 252 for more information.
 253 .in -8
 254 -- file unchanged
 255 .in +8
 256 This message fragment is written when no savings are achieved by
 257 compression.  The input file is left unchanged.
 258 .in -8
 259 -- replaced with
 260 .I file
 261 .in +8
 262 This message fragment is written when a file has been sucessfully
 263 compressed/uncompressed.
 264 .in -8