'\"macro stdmacro
.if n .pH g2.comp @(#)comp	1.1 of 3/13/96
.TH COMP 2
.SH NAME
comp,uncomp,comp_compress,uncomp_uncompress \- data stream compression
and uncompression
.Op c p a
.SH C SYNOPSIS
.PP
.sp
.nf
.B #include <comp.h>
.sp
.B "typedef void *(*comp_allocator_t)(size_t);"
.PP
.B "typedef void (*comp_free_t)(void *);"
.PP
.B "typedef ssize_t (*comp_output_t)(void *param, void *buf, size_t buflen);"
.sp
.B "void comp_options_default(COMP_OPTIONS *);"
.PP
.B "void comp_init(COMP_DATA *, comp_allocator_t,"
.B "               comp_free_t, comp_output_t);"
.PP
.B "int comp_begin(COMP_DATA *, COMP_OPTIONS *);"
.PP
.B "int comp_compress(COMP_DATA *,"
.B "                  const char_type *buf, long buflen);"
.PP
.B "int comp_end(COMP_DATA *);"
.PP
.B "void comp_destroy(COMP_DATA *);"
.PP
.B "int comp_geterrno(COMP_DATA *);"
.PP
.B "void comp_clrerrno(UNCOMP_DATA *);"
.sp
.nf
.B #include <uncomp.h>
.sp
.B "typedef void *(*uncomp_allocator_t)(size_t);"
.PP
.B "typedef void (*uncomp_free_t)(void *);"
.PP
.B "typedef ssize_t (*uncomp_output_t)(void *param, void *buf, size_t buflen);"
.PP
.B "void uncomp_options_default(UNCOMP_OPTIONS *);"
.PP
.B "int uncomp_init(UNCOMP_DATA *, uncomp_allocator_t,"
.B "                uncomp_free_t, uncomp_output_t);"
.PP
.B "int uncomp_begin(UNCOMP_DATA *, UNCOMP_OPTIONS *);"
.PP
.B "int uncomp_uncompress(UNCOMP_DATA *,"
.B "                      const char_type *buf, long buflen);"
.PP
.B "int uncomp_end(UNCOMP_DATA *);"
.PP
.B "void uncomp_destroy(UNCOMP_DATA *);"
.PP
.B "int uncomp_geterrno(UNCOMP_DATA *);"
.PP
.B "void uncomp_clrerrno(UNCOMP_DATA *);"
.Op
.SH OVERVIEW
The
.I comp
library and associated system calls allows applications to use the
compression and decompression algorithms from
.IR compress (1)
and
.IR uncompress (1)
directly, without having to invoke a separate executable.
.P
The compression code in this library has been optimized, and if used
in combination with large buffer file reading can result in improved
compression times of up to 30% over the standard compress code.
.P
You must link with the \f4comp\f2 library:
.Ex
cc -o prog prog.c -lcomp
.Ee
.SH DESCRIPTION
Applications wishing to compress data should:
.sp .5
.de No
.IP "\\$1"
..
.No "1"
include \f2comp.h\fP header file
.No "2"
define an instance of a \f2COMP_DATA\fP stream (let's call it \f4xxx\fP)
.No "3"
define memory allocator method: \f2void *xxxmalloc(size_t)\fP
.No "4"
define corresponding memory free method: \f2void xxxfree(buf)\fP
.No "5"
define output handler method: \f2ssize_t xxxoutput(param, outbuf, outbuflen)\fP
.No "6"
define an instance of COMP_OPTIONS options structure: \f4xxxopts\fP
.No "7"
invoke \f2comp_options_default(&xxxopts)\fP to set default options
.No "8"
invoke \f2comp_init(&xxx, &xxxmalloc, &xxxfree, &xxxoutput)\fP
.No "9"
explicitly set any non-default options desired in \f4xxxopts\fP,
especially \f4xxxopts.output_param\fP, which is passed to \f2xxxoutput()\fP
.No "10"
invoke \f2comp_begin(&xxx, &xxxopts)\fP
.No "11"
invoke \f2comp_compress(&xxx, inbuf, inbuflen)\fP
.No "12"
invoke \f2comp_end(&xxx)\fP
.No "13"
repeat steps (9) through (12) as necessary, for each file to be compressed.
.No "14"
it is okay to reuse compress structs for other compressed
streams, by invoking \f2comp_begin()\fP on them again.
.No "15"
invoke \f2comp_destroy(&xxx)\fP to free up allocated memory
.PP
Expect during above:
.de No
.IP "\\$1"
..
.No "1"
calls to \f2xxxmalloc()\fP during \f2comp_begin()\fP for
space that the compressor might need
.No "2"
calls to \f2xxxoutput()\fP during \f2comp_compress()\fP
and \f2comp_end()\fP, to emit compressed results.
.No "3"
calls to \f2xxxfree()\fP during \f2comp_destroy()\fP and
\f2comp_begin()\fP.
.PP
To uncompress data:
.sp .5
.de No
.IP "\\$1"
..
.No "1"
include \f2uncomp.h\fP header file
.No "2"
define an instance of a \f2UNCOMP_DATA\fP stream (let's call it \f4xxx\fP)
.No "3"
define memory allocator method: \f2void *xxxmalloc(size_t)\fP
.No "4"
define corresponding memory free method: \f2void xxxfree(buf)\fP
.No "5"
define output handler method: \f2ssize_t xxxoutput(param, outbuf, outbuflen)\fP
.No "6"
define an instance of UNCOMP_OPTIONS options structure: \f4xxxopts\fP
.No "7"
invoke \f2uncomp_options_default(&xxxopts)\fP to set default options
.No "8"
invoke \f2uncomp_init(&xxx, &xxxmalloc, &xxxfree, &xxxoutput)\fP
.No "9"
explicitly set any non-default options desired in \f4xxxopts\fP,
especially \f4xxxopts.output_param\fP, which is passed to \f2xxxoutput()\fP
.No "10"
invoke \f2uncomp_begin(&xxx, &xxxopts)\fP
.No "11"
invoke \f2uncomp_uncompress(&xxx, inbuf, inbuflen)\fP
.No "12"
invoke \f2uncomp_end(&xxx)\fP
.No "13"
repeat steps (9) through (12) as necessary, for each file to be compressed.
.No "14"
it is okay to reuse uncompress structs for other compressed
streams, by invoking \f2uncomp_begin()\fP on them again.
.No "15"
invoke \f2uncomp_destroy(&xxx)\fP to free up allocated memory
.PP
Expect during above:
.de No
.IP "\\$1"
..
.No "1"
calls to \f2xxxmalloc()\fP during \f2uncomp_init()\fP for
space that the uncompressor might need
.No "2"
calls to \f2xxxoutput()\fP during \f2uncomp_uncompress()\fP
and \f2uncomp_end()\fP, to emit uncompressed results.
.No "3"
calls to \f2xxxfree()\fP during \f2uncomp_destroy()\fP and
\f2uncomp_begin()\fP..
.PP

.SH "SEE ALSO"
compress(1), uncompress(1)
.SH "DIAGNOSTICS"
All routines that return a status value return 0 for success, -1 for
failure.  \f2comp_end\fP and \f2uncomp_end\fP can also return -2 if no
gain was had by compressing the stream.
.\"	@(#)comp.2	1.0 of 3.13.96
.Ee