xref: /netbsd-src/external/gpl3/binutils.old/dist/zlib/contrib/blast/blast.h (revision e992f068c547fd6e84b3f104dc2340adcc955732)
116dce513Schristos /* blast.h -- interface for blast.c
2ede78133Schristos   Copyright (C) 2003, 2012, 2013 Mark Adler
3ede78133Schristos   version 1.3, 24 Aug 2013
416dce513Schristos 
516dce513Schristos   This software is provided 'as-is', without any express or implied
616dce513Schristos   warranty.  In no event will the author be held liable for any damages
716dce513Schristos   arising from the use of this software.
816dce513Schristos 
916dce513Schristos   Permission is granted to anyone to use this software for any purpose,
1016dce513Schristos   including commercial applications, and to alter it and redistribute it
1116dce513Schristos   freely, subject to the following restrictions:
1216dce513Schristos 
1316dce513Schristos   1. The origin of this software must not be misrepresented; you must not
1416dce513Schristos      claim that you wrote the original software. If you use this software
1516dce513Schristos      in a product, an acknowledgment in the product documentation would be
1616dce513Schristos      appreciated but is not required.
1716dce513Schristos   2. Altered source versions must be plainly marked as such, and must not be
1816dce513Schristos      misrepresented as being the original software.
1916dce513Schristos   3. This notice may not be removed or altered from any source distribution.
2016dce513Schristos 
2116dce513Schristos   Mark Adler    madler@alumni.caltech.edu
2216dce513Schristos  */
2316dce513Schristos 
2416dce513Schristos 
2516dce513Schristos /*
2616dce513Schristos  * blast() decompresses the PKWare Data Compression Library (DCL) compressed
2716dce513Schristos  * format.  It provides the same functionality as the explode() function in
2816dce513Schristos  * that library.  (Note: PKWare overused the "implode" verb, and the format
2916dce513Schristos  * used by their library implode() function is completely different and
3016dce513Schristos  * incompatible with the implode compression method supported by PKZIP.)
3116dce513Schristos  *
3216dce513Schristos  * The binary mode for stdio functions should be used to assure that the
3316dce513Schristos  * compressed data is not corrupted when read or written.  For example:
3416dce513Schristos  * fopen(..., "rb") and fopen(..., "wb").
3516dce513Schristos  */
3616dce513Schristos 
3716dce513Schristos 
3816dce513Schristos typedef unsigned (*blast_in)(void *how, unsigned char **buf);
3916dce513Schristos typedef int (*blast_out)(void *how, unsigned char *buf, unsigned len);
4016dce513Schristos /* Definitions for input/output functions passed to blast().  See below for
4116dce513Schristos  * what the provided functions need to do.
4216dce513Schristos  */
4316dce513Schristos 
4416dce513Schristos 
45ede78133Schristos int blast(blast_in infun, void *inhow, blast_out outfun, void *outhow,
46ede78133Schristos           unsigned *left, unsigned char **in);
4716dce513Schristos /* Decompress input to output using the provided infun() and outfun() calls.
4816dce513Schristos  * On success, the return value of blast() is zero.  If there is an error in
4916dce513Schristos  * the source data, i.e. it is not in the proper format, then a negative value
5016dce513Schristos  * is returned.  If there is not enough input available or there is not enough
5116dce513Schristos  * output space, then a positive error is returned.
5216dce513Schristos  *
5316dce513Schristos  * The input function is invoked: len = infun(how, &buf), where buf is set by
5416dce513Schristos  * infun() to point to the input buffer, and infun() returns the number of
5516dce513Schristos  * available bytes there.  If infun() returns zero, then blast() returns with
5616dce513Schristos  * an input error.  (blast() only asks for input if it needs it.)  inhow is for
5716dce513Schristos  * use by the application to pass an input descriptor to infun(), if desired.
5816dce513Schristos  *
59ede78133Schristos  * If left and in are not NULL and *left is not zero when blast() is called,
60*e992f068Schristos  * then the *left bytes at *in are consumed for input before infun() is used.
61ede78133Schristos  *
6216dce513Schristos  * The output function is invoked: err = outfun(how, buf, len), where the bytes
6316dce513Schristos  * to be written are buf[0..len-1].  If err is not zero, then blast() returns
6416dce513Schristos  * with an output error.  outfun() is always called with len <= 4096.  outhow
6516dce513Schristos  * is for use by the application to pass an output descriptor to outfun(), if
6616dce513Schristos  * desired.
6716dce513Schristos  *
68ede78133Schristos  * If there is any unused input, *left is set to the number of bytes that were
69ede78133Schristos  * read and *in points to them.  Otherwise *left is set to zero and *in is set
70ede78133Schristos  * to NULL.  If left or in are NULL, then they are not set.
71ede78133Schristos  *
7216dce513Schristos  * The return codes are:
7316dce513Schristos  *
7416dce513Schristos  *   2:  ran out of input before completing decompression
7516dce513Schristos  *   1:  output error before completing decompression
7616dce513Schristos  *   0:  successful decompression
7716dce513Schristos  *  -1:  literal flag not zero or one
7816dce513Schristos  *  -2:  dictionary size not in 4..6
7916dce513Schristos  *  -3:  distance is too far back
8016dce513Schristos  *
8116dce513Schristos  * At the bottom of blast.c is an example program that uses blast() that can be
8216dce513Schristos  * compiled to produce a command-line decompression filter by defining TEST.
8316dce513Schristos  */
84