usr.bin/mkuzip/mkuzip.8

   1 .\"-
   2 .\" Copyright (c) 2004-2016 Maxim Sobolev <sobomax@FreeBSD.org>
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd March 17, 2006
  29 .Dt MKUZIP 8
  30 .Os
  31 .Sh NAME
  32 .Nm mkuzip
  33 .Nd compress disk image for use with
  34 .Xr geom_uzip 4
  35 class
  36 .Sh SYNOPSIS
  37 .Nm
  38 .Op Fl v
  39 .Op Fl o Ar outfile
  40 .Op Fl s Ar cluster_size
  41 .Op Fl j Ar compression_jobs
  42 .Ar infile
  43 .Sh DESCRIPTION
  44 The
  45 .Nm
  46 utility compresses a disk image file so that the
  47 .Xr geom_uzip 4
  48 class will be able to decompress the resulting image at run-time.
  49 This allows for a significant reduction of size of disk image at
  50 the expense of some CPU time required to decompress the data each
  51 time it is read.
  52 The
  53 .Nm
  54 utility
  55 works in two phases:
  56 .Bl -enum
  57 .It
  58 An
  59 .Ar infile
  60 image is split into clusters; each cluster is compressed using
  61 .Xr zlib 3
  62 or
  63 .Xr lzma 3 .
  64 .It
  65 The resulting set of compressed clusters along with headers that allow
  66 locating each individual cluster is written to the output file.
  67 .El
  68 .Pp
  69 The options are:
  70 .Bl -tag -width indent
  71 .It Fl o Ar outfile
  72 Name of the output file
  73 .Ar outfile .
  74 The default is to use the input name with the suffix
  75 .Pa .uzip
  76 for the
  77 .Xr zlib 3
  78 compression or
  79 .Pa .ulzma
  80 for the
  81 .Xr lzma 3 .
  82 .It Fl L
  83 Use
  84 .Xr lzma 3
  85 compression algorithm instead of the default
  86 .Xr zlib 3 .
  87 The
  88 .Xr lzma 3
  89 provides noticeable better compression levels on the same data set
  90 at the expense of much slower compression speed (10-20x) and somewhat slower
  91 decompression (2-3x).
  92 .It Fl s Ar cluster_size
  93 Split the image into clusters of
  94 .Ar cluster_size
  95 bytes, 16384 bytes by default.
  96 The
  97 .Ar cluster_size
  98 should be a multiple of 512 bytes.
  99 .It Fl v
 100 Display verbose messages.
 101 .It Fl Z
 102 Disable zero-blocks detection and elimination.
 103 When this option is set, the
 104 .Nm
 105 would compress empty blocks (i.e. clusters that consist of only zero bytes)
 106 just as it would any other block.
 107 When the option is not set, the
 108 .Nm
 109 detects such blocks and skips them from the output.
 110 Setting
 111 .Fl Z
 112 results is slight increase of compressed image size, typically less than 0.1%
 113 of a final size of the compressed image.
 114 .It Fl d
 115 Enable de-duplication.
 116 When the option is enabled the
 117 .Nm
 118 detects identical blocks in the input and replaces each subsequent occurence
 119 of such block with pointer to the very first one in the output.
 120 Setting this option results is moderate decrease of compressed image size,
 121 typically around 3-5% of a final size of the compressed image.
 122 .It Fl S
 123 Print summary about the compression ratio as well as output
 124 file size after file has been processed.
 125 .It Fl j Ar compression_jobs
 126 Specify the number of compression jobs that
 127 .Nm
 128 runs in parallel to speed up compression.
 129 When option is not specified the number of jobs set to be equal
 130 to the value of
 131 .Va hw.ncpu
 132 .Xr sysctl 8
 133 variable.
 134 .El
 135 .Sh NOTES
 136 The compression ratio largely depends on the cluster size used.
 137 .\" The following two sentences are unclear: how can gzip(1) be
 138 .\" used in a comparable fashion, and wouldn't a gzip-compressed
 139 .\" image suffer from larger cluster sizes as well?
 140 For large cluster sizes (16K and higher), typical compression ratios
 141 are only 1-2% less than those achieved with
 142 .Xr gzip 1 .
 143 However, it should be kept in mind that larger cluster
 144 sizes lead to higher overhead in the
 145 .Xr geom_uzip 4
 146 class, as the class has to decompress the whole cluster even if
 147 only a few bytes from that cluster have to be read.
 148 .Pp
 149 The
 150 .Nm
 151 utility
 152 inserts a short shell script at the beginning of the generated image,
 153 which makes it possible to
 154 .Dq run
 155 the image just like any other shell script.
 156 The script tries to load the
 157 .Xr geom_uzip 4
 158 class if it is not loaded, configure the image as an
 159 .Xr md 4
 160 disk device using
 161 .Xr mdconfig 8 ,
 162 and automatically mount it using
 163 .Xr mount_cd9660 8
 164 on the mount point provided as the first argument to the script.
 165 .Pp
 166 The de-duplication is a
 167 .Fx
 168 specific feature and while it does not require any changes to on-disk
 169 compressed image format, however it did require some matching changes to the
 170 .Xr geom_uzip 4
 171 to handle resulting images correctly.
 172 .Sh EXIT STATUS
 173 .Ex -std
 174 .Sh SEE ALSO
 175 .Xr gzip 1 ,
 176 .Xr xz 1 ,
 177 .Xr lzma 3 ,
 178 .Xr zlib 3 ,
 179 .Xr geom 4 ,
 180 .Xr geom_uzip 4 ,
 181 .Xr md 4 ,
 182 .Xr mdconfig 8 ,
 183 .Xr mount_cd9660 8
 184 .Sh AUTHORS
 185 .An Maxim Sobolev Aq Mt sobomax@FreeBSD.org