COMP(2)								       COMP(2)

NAME    [Toc]    [Back]

     comp,uncomp,comp_compress,uncomp_uncompress - data	stream compression and
     uncompression

C SYNOPSIS    [Toc]    [Back]

     #include <comp.h>

     typedef void *(*comp_allocator_t)(size_t);

     typedef void (*comp_free_t)(void *);

     typedef ssize_t (*comp_output_t)(void *param, void	*buf, size_t buflen);

     void comp_options_default(COMP_OPTIONS *);

     void comp_init(COMP_DATA *, comp_allocator_t,
		    comp_free_t, comp_output_t);

     int comp_begin(COMP_DATA *, COMP_OPTIONS *);

     int comp_compress(COMP_DATA *,
		       const char_type *buf, long buflen);

     int comp_end(COMP_DATA *);

     void comp_destroy(COMP_DATA *);

     int comp_geterrno(COMP_DATA *);

     void comp_clrerrno(UNCOMP_DATA *);

     #include <uncomp.h>

     typedef void *(*uncomp_allocator_t)(size_t);

     typedef void (*uncomp_free_t)(void	*);

     typedef ssize_t (*uncomp_output_t)(void *param, void *buf,	size_t buflen);

     void uncomp_options_default(UNCOMP_OPTIONS	*);

     int uncomp_init(UNCOMP_DATA *, uncomp_allocator_t,
		     uncomp_free_t, uncomp_output_t);

     int uncomp_begin(UNCOMP_DATA *, UNCOMP_OPTIONS *);

     int uncomp_uncompress(UNCOMP_DATA *,
			   const char_type *buf, long buflen);

     int uncomp_end(UNCOMP_DATA	*);





									Page 1






COMP(2)								       COMP(2)



     void uncomp_destroy(UNCOMP_DATA *);

     int uncomp_geterrno(UNCOMP_DATA *);

     void uncomp_clrerrno(UNCOMP_DATA *);

OVERVIEW    [Toc]    [Back]

     The comp library and associated system calls allows applications to use
     the compression and decompression algorithms from compress(1) and
     uncompress(1) directly, without having to invoke a	separate executable.

     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.

     You must link with	the comp library:

	  cc -o	prog prog.c -lcomp

DESCRIPTION    [Toc]    [Back]

     Applications wishing to compress data should:


     1	  include comp.h header	file

     2	  define an instance of	a COMP_DATA stream (let's call it xxx)

     3	  define memory	allocator method: void *xxxmalloc(size_t)

     4	  define corresponding memory free method: void	xxxfree(buf)

     5	  define output	handler	method:	ssize_t	xxxoutput(param, outbuf,
	  outbuflen)

     6	  define an instance of	COMP_OPTIONS options structure:	xxxopts

     7	  invoke comp_options_default(&xxxopts)	to set default options

     8	  invoke comp_init(&xxx, &xxxmalloc, &xxxfree, &xxxoutput)

     9	  explicitly set any non-default options desired in xxxopts,
	  especially xxxopts.output_param, which is passed to xxxoutput()

     10	  invoke comp_begin(&xxx, &xxxopts)

     11	  invoke comp_compress(&xxx, inbuf, inbuflen)

     12	  invoke comp_end(&xxx)






									Page 2






COMP(2)								       COMP(2)



     13	  repeat steps (9) through (12)	as necessary, for each file to be
	  compressed.

     14	  it is	okay to	reuse compress structs for other compressed streams,
	  by invoking comp_begin() on them again.

     15	  invoke comp_destroy(&xxx) to free up allocated memory

     Expect during above:

     1	  calls	to xxxmalloc() during comp_begin() for space that the
	  compressor might need

     2	  calls	to xxxoutput() during comp_compress() and comp_end(), to emit
	  compressed results.

     3	  calls	to xxxfree() during comp_destroy() and comp_begin().

     To	uncompress data:


     1	  include uncomp.h header file

     2	  define an instance of	a UNCOMP_DATA stream (let's call it xxx)

     3	  define memory	allocator method: void *xxxmalloc(size_t)

     4	  define corresponding memory free method: void	xxxfree(buf)

     5	  define output	handler	method:	ssize_t	xxxoutput(param, outbuf,
	  outbuflen)

     6	  define an instance of	UNCOMP_OPTIONS options structure: xxxopts

     7	  invoke uncomp_options_default(&xxxopts) to set default options

     8	  invoke uncomp_init(&xxx, &xxxmalloc, &xxxfree, &xxxoutput)

     9	  explicitly set any non-default options desired in xxxopts,
	  especially xxxopts.output_param, which is passed to xxxoutput()

     10	  invoke uncomp_begin(&xxx, &xxxopts)

     11	  invoke uncomp_uncompress(&xxx, inbuf,	inbuflen)

     12	  invoke uncomp_end(&xxx)

     13	  repeat steps (9) through (12)	as necessary, for each file to be
	  compressed.






									Page 3






COMP(2)								       COMP(2)



     14	  it is	okay to	reuse uncompress structs for other compressed streams,
	  by invoking uncomp_begin() on	them again.

     15	  invoke uncomp_destroy(&xxx) to free up allocated memory

     Expect during above:

     1	  calls	to xxxmalloc() during uncomp_init() for	space that the
	  uncompressor might need

     2	  calls	to xxxoutput() during uncomp_uncompress() and uncomp_end(), to
	  emit uncompressed results.

     3	  calls	to xxxfree() during uncomp_destroy() and uncomp_begin()..

SEE ALSO    [Toc]    [Back]

     compress(1), uncompress(1)

DIAGNOSTICS    [Toc]    [Back]

     All routines that return a	status value return 0 for success, -1 for
     failure.  comp_end	and uncomp_end can also	return -2 if no	gain was had
     by	compressing the	stream.


									PPPPaaaaggggeeee 4444