                    sausage v 0.1 beta October 15, 1997
                           by Brennan Underwood
                             brennan@rt66.com
                       http://brennan.home.ml.org/

***  What is it?
SAUSAGE is a yet another WAD-type file format. Pack a .sau file once with
makesaus, read from it as much as you want with sausage_* functions. There
are no 'extract' functions, you just do stdio-type stuff.

A nice perk is that you can 'overlay' 2 or more .sau files for patches and
addons; and if a file is not found in any mounted .sau, sausage will look for
a standalone file and read from it transparently.

*** Public symbol list:
int mount_sausage(char *filename, int *version);
	Call this first, to mount your sausage, before you can read any
	files from it. The version number of the sausage will be stored in
	*version, 8.8 fixed point, i.e. 1.0 is 0x100. Pass in NULL if you
	don't care about the version.
int control_sausage(int control, int param);
	Controls sausage behavior.
	control == SAUS_OVERLAY; defaults to on (1).
		Newly mounted sausages' entries override previous' if an
		entry's filename matches.
	control == SAUS_OPEN_STANDALONE; defaults to on (1).
		If a requested file is not in any mounted sau files,
		check the local filesystem and open matching files.
		Useful for when you're still developing and don't want
		to repack your sausage all the dang time. But you might
		want to turn this off so those pesky users can't get too tricky.

SAUSAGE_FILE *sausage_fopen(char *filename, char *mode);
void sausage_fclose(SAUSAGE_FILE *sfp);
int sausage_fread(void *buf, int size, int num, SAUSAGE_FILE *sfp);
char *sausage_fgets(char *buf, int len, SAUSAGE_FILE *sfp);
int sausage_fseek(SAUSAGE_FILE *sfp, int offset, int mode);
int sausage_ftell(SAUSAGE_FILE *sfp);
	These behave pretty much like their stdio equivalents. If they have
	some behavior I forgot to simulate, let me know.

extern char *sausage_error;
	This will sometimes point to a static string that describes the
	latest error encountered. Otherwise, it's NULL.

*** Basic usage:
#include "sausage.h"

int main(void) {
  mount_sausage("blah.sau", NULL);
  blah();
}

int blah(void) {
  SAUSAGE_FILE *sfp = sausage_fopen("blah", "rb");
  int p;
  sausage_fread(&p, sizeof(p), 1, sfp);
  sasauge_fclose(sfp);
}

If you #define SAUSAGE_EASY_PORT before you #include "sausage.h" it will map
all your stdio calls to sausage calls. It's probably best to explicitly use
sausage calls, though.

If you *have* to get at a real FILE*, there's a macro in sausage.h, but
if you use it, there's nothing stopping you from reading past a file and
into the next one. sausage's behavior will be undefined if you do that.

**** makesaus
This is a quick-n-dirty sausage packer.  Handles errors OK, but I guarantee
nothing. Usage:
	makesaus sausfile.sau file1 file2 file3...
If you're compiling with DJGPP, you can use response files like
	makesaus sausage.sau @filelist
where filelist is a list of files to pack.
You can also recursively pack an entire directory tree:
	makesaus sausage.sau progdata/.../*
where progdata is a directory will all your files to be packed.
That's just one of the cool functionalities writing a program with DJGPP
automatically gives you.

BUGS/LIMITATIONS:
* strlen(filename) can't be > 80 chars
* Can't unmount sausages
* Every file is opened in BINARY mode, so bounds checking will work
* sausage_fseek() doesn't bounds check at the moment

TODO/WISH LIST:
* Transparent compression via Zlib
* Password protection (SLOWer)
* Caching (maybe not, who doesn't run smartdrv these days?)
* Maybe an option to look for a standalone file first...
* Unmount sausage option

*** Guarantees:
None. Use at your own risk. I'm not gonna say I was never off by a byte
in my bounds-checking, either. It works for me, and Big Bird told me to
share things.

If you didn't get this from my pages, it came from
http://brennan.home.ml.org/programming/

If you use sausage, please let me know. I don't ask any money for it,
(it only represents a few days' worth of hours here and there) but I
wouldn't mind you letting me know what you end up using it for, and I
definitly wouldn't mind getting a copy of whatever it was (especially
if it's a nifty game or something.)

Another thing, if you modify sausage, you should send me the changes so
I can incorporate them into the main sausage distribution.

Additionally, you must not redistribute sausage unless you include all the
original files:
readme
makefile
sausage.c
sausage.h
sauspriv.h
makesaus.c
and you must not claim ownership or authorship of the original code.


                                 end of line
