/* @(#) options.doc 1.4 88/08/22 15:24:59 */

Documentation about the file options.h.

The file options.h defines various symbols and macros that are needed
to ensure system-independence. The basic philosophy is to use a
distinct symbol for each attribute that varies from machine to machine.
Then, for each new system, we define symbols corresponding to its
attributes. Thus, ideally, the only place in Zoo code that we actually
use the name of a machine is in this file, in portable.h, and possibly in
machine.h and options.c. Everywhere else in the code we only use
names of attributes.

Machine names:

MSC Microsoft C 3.0 under MS-DOS (not currently in use)
TURBOC Turbo C 1.0 under MS-DOS (works, compiled version is
separately distributed)
DLC Datalight C under MS-DOS (not currently in use*)
FLEX FlexDOS (not currently in use*)
SYS_V UNIX System V release 2 (works)
VMS VAX/VMS 4.4 through 4.6 (works, stream-LF files only)
BSD4_3 4.3BSD (works)
MCH_AMIGA AmigaDOS Aztec/Manx C (compiled version is separately
distributed)
-----
*Mark Alexander provided me with changes to allow compilation using
FlexDOS and also Datalight's Optimum C under MSDOS but they have not
yet been incorporated into this release.

NOTE: The term "zoofile" below refers to an open file of type
ZOOFILE. Currently this is defined to be equivalent to a standard
buffered file pointer of type "ZOOFILE *" but this may change in the
future. Dependence on exact definition of ZOOFILE is localized to a
few files: options.h, portable.h, portable.c, and machine.c.

Attributes of systems:

CHEKDIR
Test each supplied filename and if it is a directory or other special
type of file, do not try to add it to an archive. If CHEKDIR is
defined, then machine.c must also contain function isadir() that
tests a supplied zoofile and returns 1 if it corresponds to a
directory or other special type of file, else 0.
CHEKUDIR
Like CHEKDIR but use function isuadir() that tests a pathname, not
a zoofile. Both CHEKDIR and CHEKUDIR may be defined, if both
functions isadir() and isuadir() are available; in this case
zoo code will use both and will execute slightly faster.
(However, simultaneous definition of CHEKDIR and CHEKUDIR has
not been tested.)
DISK_CH
If defined, must hold the value of a character that separates a
disk name from the rest of the pathname. All characters up to and
including this character will be removed from a pathname before it
is stored in an archive. Usually a colon (':').
EXISTS
If defined, is assumed to be a macro that accepts a filename and
returns an int value of 1 if the file exists and 0 if it doesn't.
If not defined, existence of files is tested by attempting to open
them for read or write access.
FATTR
If defined, file attributes will be preserved. A function
getfattr(f) must also exist that returns the attributes of a
zoofile f (or of a pathname f, if the symbol FATTR_FNAME is
also defined); and a function setfattr(f, a) must exist that
sets the attributes of a file with pathname f to the value a.
For more details see the source code in sysv.c and bsd.c. Currently
the attribute value a is required to be in the zoo portable
format. The lowest nine bits of this format correspond to
the **IX mode bits described for chmod(2) and these are the only
bits currently used.
FATTR_FNAME
If defined, and if FATTR is also defined, zoo code will
obtain the attributes of a file by calling the function
getfattr(f) and supplying it with filename f. If FATTR_FNAME
is not defined, then getfattr(f) is supplied a zoofile f.
LINT_ARGS
Use ANSI-style function argument lists in declarations. The symbols
MORE, NOTHING, and VOIDPTR must also be defined.
MORE
In function prototypes, a variable number of trailing arguments
is specified with the symbol MORE following a trailing comma.
For ANSI-conformant compilers, MORE will be defined to be three
dots (...); for others, it can be defined as necessary
(empty string for Microsoft C 3.0).
NOTHING
In a prototype for a function that takes no parameters, NOTHING is
used as the parameter. For ANSI-compatible compilers NOTHING should
be defined to be `void'. For other compilers it should be defined
to be empty.
VOIDPTR
VOIDPTR should be defined as void * if the compiler supports this
(e.g. Turbo C), else it should be defined as char * (e.g. Microsoft
C).
LINT
If defined, SCCS identifier strings will not be included in the
generated code. This will make the code smaller and will also
avoid complaints from lint about unused variables. This symbol
should be defined in the Makefile, NOT in `options.h', otherwise
it will not be fully effective.
FOLD
Fold filenames to lowercase. Define this for case-insensitive filesystems
FPUTCHAR
If defined, a library function fputchar() is assumed available
that is like fput() but is a function, not a macro, to save
space. If not defined Zoo uses its own fputchar() function.
PORTABLE
Use portable functions --- define for every system except MS-DOS
PURIFY
When filenames are being read from standard input, ignore all
characters begining with the first blank or tab encountered.
This will allow filenames to be fed from a program that produces
lines containing filenames followed by other information that
should be ignored. Should be defined for most non-**IX systems.
DONT_SORT
Don't sort filename arguments -- files will be stored in the
exact order in which names are supplied on the command line.
Not currently used for any system, but could be used if memory
is really tight.
NOENUM
Compiler does not support enumerations
DUMB_ASS
Dumb assertions must be used because the preprocessor doesn't define
the symbols __FILE__ and __LINE__ (which hold the name of the current
file and the number of the current line)
FNLIMIT
Pathname length limit for this system
NEEDCTYP
If defined, tells the code to include the header file ctype.h for
use by character conversion macros. If and only if NEEDCTYP is not
defined, macros or appropriate function declarations can be put in
portable.h. Zoo uses isupper(), isdigit(), toascii(), and tolower().
If NEEDCTYP is not defined, the symbol USE_ASCII can be defined to
cause zoo to assume the ASCII character set and use its own isupper(),
isdigit(), toascii(), and tolower() functions, possibly making the
executable code smaller.
USE_ASCII
See description of NEEDCTYP. USE_ASCII should not be defined if
NEEDCTYP is defined, else there may be conflicts between macro
and function names.
NIXTIME
If defined, a function setutime() must be defined that will set the
date and time of a file whose pathname is supplied. If not defined,
a function settime() must be defined that will do the same for
a zoofile.
GETUTIME
If defined, a function getutime() must be defined that will return
the MS-DOS format date and time of the specified filename. If this
symbol is not defined, then a function gettime() must be defined
that will do the same for a zoofile instead of a filename.
NOSIGNAL
don't use signals because library doesn't support them
PATH_CH
The character that separates the directory name from the filename
in a pathname. String value.
PATH_SEP
The set of characters that may separate preceding directory/device
information from the filename. String value.
EXT_SEP is the union of PATH_SEP and the set of characters separating a
filename extension from the rest of the filename. String value.
EXT_CH
Character that separates base part of filename from extension.
Char value.
MEMSET
If defined, a library function memset() is assumed available that
conforms to that available under System V. If not defined, Zoo uses
its own memset() function.
EXT_DFLT
default extension for archives. String. Currently ".zoo".
NIXFNAME
If defined, PATH_CH, PATH_SEP, EXT_SEP, EXT_CH, and EXT_DFLT get defined
to conform to **IX conventions and should not be separately defined
MSFNAME
if defined, PATH_CH, PATH_SEP, EXT_SEP, EXT_CH, EXT_DFLT, and
DISK_CH get defined to conform to MS-DOS conventions and should
not be separately defined (not currently implemented)
FORCESLASH
If defined any backslashes in names of files will be converted to
slashes before the files are added to an archive. This is useful
for MSDOS-like systems that accept both slashes and backslashes,
since the standard archive format allows only slashes as directory
separators.
REN_LINK
Rename a file by using link() followed by unlink() (e.g. Xenix, System V)
REN_NORM
Use normal rename function: "int rename(new, old)" (e.g. Microsoft C)
REN_REV
Use reverse rename function: "int rename(old, new)" (e.g. 4.3BSD,
Turbo C). Note: define exactly one of REN_LINK, REN_NORM, and REN_REV.
SETMODE
Change mode of standard output to binary when piping output, then change
it back to text. Macros MODE_BIN(zoofile) and MODE_TEXT(zoofile) must
also be defined.
SETBUF
Standard output should be set to be unbuffered so output shows up
quickly. Currently used only in Fiz, not in Zoo.
SPECNEXT
If defined, a machine-dependent function nextfile() must be defined that
will expand wildcards in a supplied pathname. If not defined, any
wildcard expansion must have been done before the command line parameters
are supplied to the program. For details see the file nextfile.c.
STRLWR
If defined, a library function strlwr() is assumed available that converts
a supplied string to lowercase and returns a pointer it. If not
defined, Zoo uses its own strlwr() function.
STRDUP
If defined, a library function strdup() is assumed available that
returns a pointer to a copy of a supplied string. If not defined,
Zoo uses its own strdup() function.
SPECEXIT
Custom exit handler is needed. A function called zooexit()
must be defined. If SPECEXIT is not defined, zoo uses its
own zooexit() function which simply calls exit().
SPECINIT
If defined, zoo's main() function will call spec_init() before
doing anything else. Any system-specific initialization may be
done at this point.
GETTZ
If defined, a function gettz() must also be defined that will
return the current timezone, in seconds west of GMT, as a long
value. Currently such a function is already defined in files
bsd.c and sysv.c. If and only if GETTZ is defined, zoo will
store the current timezone for each file that is archived,
and will list the timezone for each file that has one when it
lists archive contents.
ALWAYS_INT
In function prototypes for fgetc(), fread(), and fwrite(),
traditional practice made certain arguments int, though
they ought to be char and unsigned respectively. If
ALWAYS_INT is defined, prototypes will use int only,
else the correct types are used.
IO_MACROS
If defined, some portable I/O functions are defined as macros,
saving space.
ZOOCOMMENT
If defined, archive comments are fully enabled. If not defined,
zoo code will be smaller at the cost that archive comments will
be listed but cannot be updated. COMPILATION WITHOUT ZOOCOMMENT
DEFINED HAS NOT YET BEEN TESTED.
TRACE_IO
This is for debugging. If defined, it will cause code to
be compiled that will trace all archive header and directory
entry I/O by showing it on the screen in human-readable format.
The tracing will then occur if any Expert command given to zoo
is preceded by a colon. E.g., if compiled with TRACE_IO on and
given the command "zoo :l xyz", zoo will give a directory
listing of xyz.zoo exactly as it would with "zoo l xyz" except
that all archive header and directory entry reads and writes
will be shown on the screen. The tracing code is localized
to the files zoo.c and portable.c, so just these two files
can be compiled afresh when TRACE_IO is turned on or switched
off. NOTE: The symbol TRACE_LIST, internal to the file
"zoolist.c", enables debugging information too. Do not define
both TRACE_IO and TRACE_LIST because (a) a symbol conflict will
occur and (b) the debugging information will be duplicated.
UNBUF_IO
If defined, some I/O is done using low-level system calls read() and
write(). To do this, the low-level file descriptor is synchronized with
the buffered zoofile before such I/O is done. To do this, read(),
write(), and lseek() system calls must be available and the fileno()
macro must return the file descriptor for a buffered file. This is
not portable and should definitely not be done by most end users. If
UNBUF_IO is defined, also defined must be a symbol UNBUF_LIMIT with a
numerical value that specifies the threshold over which unbuffered I/O
should be used. For example, if the value of UNBUF_LIMIT is 512, then
any I/O on a zoofile that reads or writes more than 512 bytes will be
done using read() or write() system calls. The use of unbuffered I/O
with a threshold in the range 512 to 1024 can enhance performance by up
to 50%. The corruption of data is a serious matter. Do not define
UNBUF_IO unless you are willing to exhaustively test the compiled code
on your system to make sure it works, and accept full responsibility for
any adverse consequences. Some standard I/O libraries may attempt to
optimize the working of fseek() on files opened for read access only,
and cause UNBUF_IO to fail.
UNBUF_LIMIT
Needed if and only if UNBUF_IO is defined. Holds a numeric value.
All I/O done in blocks that are larger than UNBUF_LIMIT bytes
will be done unbuffered. See UNBUF_IO.
FILTER
If defined, code will be compiled in to enable the fc and fd
commands (compress or decompress, reading standard input and
writing to standard output). These commands are useful only
on systems that allow programs to easily act as filters.
VER_DISPLAY
The character that will separate filenames from generation numbers
in listings of archive contents. Must be a single character
in double quotes.
VER_INPUT
The characters that will be accepted as separating filenames
from generation numbers when typed as an argument to select
specific files from an archive. String value. May include
one or more characters; any of them may then be typed and
will work.
NOSTRCHR
Although 4.3BSD as distributed from Berkeley includes strchr()
and strrchr() library functions, 4.2BSD and similar systems
may not. If so, defining NOSTRCHR will cause zoo to use
index() and rindex() instead.