usr.bin/mkuzip/mkuzip.8

   1 .\" ----------------------------------------------------------------------------
   2 .\" "THE BEER-WARE LICENSE" (Revision 42):
   3 .\" <sobomax@FreeBSD.org> wrote this file. As long as you retain this notice you
   4 .\" can do whatever you want with this stuff. If we meet some day, and you think
   5 .\" this stuff is worth it, you can buy me a beer in return.       Maxim Sobolev
   6 .\" ----------------------------------------------------------------------------
   7 .\"
   8 .\" $FreeBSD$
   9 .\"
  10 .Dd March 17, 2006
  11 .Dt MKUZIP 8
  12 .Os
  13 .Sh NAME
  14 .Nm mkuzip
  15 .Nd compress disk image for use with
  16 .Xr geom_uzip 4
  17 class
  18 .Sh SYNOPSIS
  19 .Nm
  20 .Op Fl v
  21 .Op Fl o Ar outfile
  22 .Op Fl s Ar cluster_size
  23 .Ar infile
  24 .Sh DESCRIPTION
  25 The
  26 .Nm
  27 utility compresses a disk image file so that the
  28 .Xr geom_uzip 4
  29 class will be able to decompress the resulting image at run-time.
  30 This allows for a significant reduction of size of disk image at
  31 the expense of some CPU time required to decompress the data each
  32 time it is read.
  33 The
  34 .Nm
  35 utility
  36 works in two phases:
  37 .Bl -enum
  38 .It
  39 An
  40 .Ar infile
  41 image is split into clusters; each cluster is compressed using
  42 .Xr zlib 3 .
  43 .It
  44 The resulting set of compressed clusters along with headers that allow
  45 locating each individual cluster is written to the output file.
  46 .El
  47 .Pp
  48 The options are:
  49 .Bl -tag -width indent
  50 .It Fl o Ar outfile
  51 Name of the output file
  52 .Ar outfile .
  53 The default is to use the input name with the suffix
  54 .Pa .uzip .
  55 .It Fl s Ar cluster_size
  56 Split the image into clusters of
  57 .Ar cluster_size
  58 bytes, 16384 bytes by default.
  59 The
  60 .Ar cluster_size
  61 should be a multiple of 512 bytes.
  62 .It Fl v
  63 Display verbose messages.
  64 .El
  65 .Sh NOTES
  66 The compression ratio largely depends on the cluster size used.
  67 .\" The following two sentences are unclear: how can gzip(1) be
  68 .\" used in a comparable fashion, and wouldn't a gzip-compressed
  69 .\" image suffer from larger cluster sizes as well?
  70 For large cluster sizes (16K and higher), typical compression ratios
  71 are only 1-2% less than those achieved with
  72 .Xr gzip 1 .
  73 However, it should be kept in mind that larger cluster
  74 sizes lead to higher overhead in the
  75 .Xr geom_uzip 4
  76 class, as the class has to decompress the whole cluster even if
  77 only a few bytes from that cluster have to be read.
  78 .Pp
  79 The
  80 .Nm
  81 utility
  82 inserts a short shell script at the beginning of the generated image,
  83 which makes it possible to
  84 .Dq run
  85 the image just like any other shell script.
  86 The script tries to load the
  87 .Xr geom_uzip 4
  88 class if it is not loaded, configure the image as an
  89 .Xr md 4
  90 disk device using
  91 .Xr mdconfig 8 ,
  92 and automatically mount it using
  93 .Xr mount_cd9660 8
  94 on the mount point provided as the first argument to the script.
  95 .Sh EXIT STATUS
  96 .Ex -std
  97 .Sh SEE ALSO
  98 .Xr gzip 1 ,
  99 .Xr zlib 3 ,
 100 .Xr geom 4 ,
 101 .Xr geom_uzip 4 ,
 102 .Xr md 4 ,
 103 .Xr mdconfig 8 ,
 104 .Xr mount_cd9660 8
 105 .Sh AUTHORS
 106 .An Maxim Sobolev Aq sobomax@FreeBSD.org