VNDCOMPRESS(1)          NetBSD General Commands Manual          VNDCOMPRESS(1)

NAME
     vndcompress, vnduncompress -- compress and uncompress disk images in
     cloop2 format

SYNOPSIS
     vndcompress [-c] [-rR] [-b blocksize] [-k checkpoint-blocks] [-l length]
                 [-p partial-offset] [-w winsize] image compressed-image
                 [blocksize]
     vnduncompress [-d] [-w winsize] compressed-image image

DESCRIPTION
     The vndcompress utility compresses disk images in cloop2 format, which
     the kernel's vnd(4) device can interpret as read-only disk devices using
     the -z option to vnconfig(8).

     By default, vndcompress compresses an image, and vnduncompress uncom-
     presses an image, but the -c and -d options can control whether either
     utility compresses or decompresses.

     The following options are available for the compression operation:

     -b blocksize
             Set the compression block size to blocksize, which must be a mul-
             tiple of 512 and must be no more than 4294966784, or 0xfffffe00.
             (On 32-bit systems, the limit may be smaller, limited by the
             available virtual address space.)

             For compatibility with the old version of vndcompress, the com-
             pression block size may instead be specified at the end of the
             command line.

     -k checkpoint-blocks
             Write a checkpoint after every checkpoint-blocks blocks of out-
             put.  If interrupted, vndcompress can restart at the last check-
             point with the -r option.  You can also request a checkpoint at
             any time by sending SIGUSR2 to the vndcompress process.

     -l length
             Specify the length of the input, so that the input may be a pipe,
             socket, or FIFO.  Otherwise, the input must know its size, i.e.
             must have its size reported in st_size by fstat(2).

     -p partial-blocks
             Stop after writing partial-blocks blocks of output.  This option
             is mainly useful for automatic testing of restarts.

     -R      With the -r option, if restarting fails, then abort right now and
             don't touch the output file.

     -r      Try to restart a partial compression from the last checkpoint.
             If restarting fails, and the -R option is not specified, then
             truncate the output file and start compression afresh.  Restart-
             ing may fail for various reasons: if there have been no check-
             points, or if the output file has been corrupted in some easily
             recognizable ways, or if the input file's size has changed, or if
             the block size does not match, and so on.

     The following option is available for both compression and decompression:

     -w winsize
             Use an in-memory window of winsize entries into the table of com-
             pressed block offsets.  If winsize is zero, vndcompress will use
             memory proportional to the number of blocks in the uncompressed
             image, namely 64 bits or 8 bytes per block.  If winsize is
             nonzero, vndcompress will use memory proportional to winsize, and
             independent of the size of the uncompressed image.

             A nonzero winsize requires the compressed image to be a seekable
             file, which compression requires anyway, in order to record the
             offsets of compressed blocks once they are compressed and writ-
             ten, but which is a limitation for decompression.  Thus, decom-
             pressing from a pipe is incompatible with a nonzero winsize.

             By default, vndcompress uses a fixed window size, unless decom-
             pressing with nonseekable input.

EXIT STATUS
     The vndcompress utility exits 0 on success, and >0 if an error occurs.

EXAMPLES
     Compress an ISO 9660 CD-ROM image:

           # vndcompress cdrom.iso cdrom.izo

     Send a 59 GB disk partition over a local network with netcat (don't do
     this over the internet!):

           # nc 10.0.1.2 12345 < /dev/rcgd1h

     Receive it and save it compressed on another host, showing a progress bar
     interactively, restarting if possible, and taking a checkpoint every 16
     MB (i.e., every 256 compression blocks, which are 64 KB by default):

           # nc -l 12345 | progress -l 59g \
               vndcompress -l 59g -k 256 -r /dev/stdin disk.cloop2

     If the process is interrupted and you rewire your network and disks so
     that the receiving host now has the disk you want to image, you can start
     up where you left off, using the -R option to keep vndcompress from clob-
     bering the partial transfer if anything goes wrong:

           # vndcompress -l 59g -k 256 -rR /dev/rcgd1h disk.cloop2

     Mount the disk with vnd(4), assuming your kernel was built with the
     VND_COMPRESSION option enabled:

           # vnconfig -z vnd0 disk.cloop2
           # mount /dev/vnd0d /mnt

SIGNALS
     vndcompress responds to the following signals:

     SIGINFO, SIGUSR1
             Report progress to standard error.

     SIGUSR2
             Write a checkpoint to disk now.

FORMAT
     The cloop2 format consists of a header, an offset table, and a sequence
     of compressed blocks.  The header is described by the following packed
     structure:

           struct cloop2_header {
                   char            cl2h_magic[128];
                   uint32_t        cl2h_blocksize;
                   uint32_t        cl2h_n_blocks;
           } __packed;

     The cl2h_magic field is an arbitrary sequence of 128 bits, the
     cl2h_blocksize field is a big-endian integer number of bytes per compres-
     sion block, and the cl2h_n_blocks field is a big-endian integer number of
     the compression blocks in the image.

     The offset table is a sequence of one more than cl2h_n_blocks big-endian
     64-bit integers specifying the offset of each compression block relative
     to the start of the file.  The extra offset specifies the end of the last
     compression block, which may be truncated if the uncompressed image's
     size is not a multiple of the compression block size.

SEE ALSO
     vnd(4), vnconfig(8)

HISTORY
     The vndcompress command first appeared in NetBSD 3.0.  It was rewritten
     to be more robust, to support restarting partial transfers, and to sup-
     port bounded memory usage in NetBSD 7.0.

NetBSD 6.0                     January 21, 2014                     NetBSD 6.0

You can also request any man page by name and (optionally) by section:

Command: 
Section: 
Architecture: 
Collection: 
 

Use the DEFAULT collection to view manual pages for third-party software.


©1994 Man-cgi 1.15, Panagiotis Christias <christia@softlab.ntua.gr>
©1996-2014 Modified for NetBSD by Kimmo Suominen