freebsd-dev/usr.bin/mkuzip/mkuzip.8

.\" ----------------------------------------------------------------------------
.\" "THE BEER-WARE LICENSE" (Revision 42):
.\" <sobomax@FreeBSD.ORG> wrote this file. As long as you retain this notice you
.\" can do whatever you want with this stuff. If we meet some day, and you think
.\" this stuff is worth it, you can buy me a beer in return.       Maxim Sobolev
.\" ----------------------------------------------------------------------------
.\"
.\" $FreeBSD$
.\"
.Dd March 17, 2006
.Dt MKUZIP 8
.Os
.Sh NAME
.Nm mkuzip
.Nd compress disk image for use with
.Xr geom_uzip 4
class
.Sh SYNOPSIS
.Nm
.Op Fl v
.Op Fl o Ar outfile
.Op Fl s Ar cluster_size
.Ar infile
.Sh DESCRIPTION
The
.Nm
utility compresses a disk image file so that the
.Xr geom_uzip 4
class will be able to decompress the resulting image at run-time.
This allows for a significant reduction of size of disk image at
the expense of some CPU time required to decompress the data each
time it is read.
The
.Nm
utility
works in two phases:
.Bl -enum
.It
An
.Ar infile
image is split into clusters; each cluster is compressed using
.Xr zlib 3 .
.It
The resulting set of compressed clusters along with headers that allow
locating each individual cluster is written to the output file.
.El
.Pp
The options are:
.Bl -tag -width indent
.It Fl o Ar outfile
Name of the output file
.Ar outfile .
The default is to use the input name with the suffix
.Pa .uzip .
.It Fl s Ar cluster_size
Split the image into clusters of
.Ar cluster_size
bytes, 16384 bytes by default.
The
.Ar cluster_size
should be a multiple of 512 bytes.
.It Fl v
Display verbose messages.
.El
.Sh NOTES
The compression ratio largely depends on the cluster size used.
.\" The following two sentences are unclear: how can gzip(1) be
.\" used in a comparable fashion, and wouldn't a gzip-compressed
.\" image suffer from larger cluster sizes as well?
For large cluster sizes (16K and higher), typical compression ratios
are only 1-2% less than those achieved with
.Xr gzip 1 .
However, it should be kept in mind that larger cluster
sizes lead to higher overhead in the
.Xr geom_uzip 4
class, as the class has to decompress the whole cluster even if
only a few bytes from that cluster have to be read.
.Pp
The
.Nm
utility
inserts a short shell script at the beginning of the generated image,
which makes it possible to
.Dq run
the image just like any other shell script.
The script tries to load the
.Xr geom_uzip 4
class if it is not loaded, configure the image as an
.Xr md 4
disk device using
.Xr mdconfig 8 ,
and automatically mount it using
.Xr mount_cd9660 8
on the mount point provided as the first argument to the script.
.Sh EXIT STATUS
.Ex -std
.Sh SEE ALSO
.Xr gzip 1 ,
.Xr zlib 3 ,
.Xr geom 4 ,
.Xr geom_uzip 4 ,
.Xr md 4 ,
.Xr mdconfig 8 ,
.Xr mount_cd9660 8
.Sh AUTHORS
.An Maxim Sobolev Aq sobomax@FreeBSD.org