usr.bin/mkulzma/mkulzma.8

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