197 lines
5.4 KiB
Groff
197 lines
5.4 KiB
Groff
'\"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
|