1/* derived from: options.doc 1.4 88/08/22 15:24:59 */
2/* $Source: /usr/home/dhesi/zoo/RCS/options.doc,v $ */
3/* $Id: options.doc,v 1.5 91/07/09 02:53:10 dhesi Exp $ */
4
5Documentation about the file options.h.
6
7The file options.h defines various symbols and macros that are needed
8to ensure system-independence.  The basic philosophy is to use a
9distinct symbol for each attribute that varies from machine to machine.
10Then, for each new system, we define symbols corresponding to its
11attributes. Thus, ideally, the only place in Zoo code that we actually
12use the name of a machine is in this file, in portable.h, and possibly in
13machine.h and options.c.  Everywhere else in the code we only use
14names of attributes.
15
16LOOK IN THE FOLLOWING FILES WHEN MAKING CHANGES TO SUPPORT A NEW SYSTEM:
17
18	  options.h, portable.h, machine.c
19
20ALSO GLANCE AT THESE FILES TO MAKE SURE THEY WILL WORK:
21
22	  zooio.h, machine.h
23
24Machine names:
25
26MSC         Microsoft C under MS-DOS      (not currently in use)
27TURBOC      Turbo C++ 1.0 under MS-DOS    (works, compiled version is
28                                          separately distributed)
29SYS_V       Most releases of System V     (works)
30VMS         VAX/VMS 5.4                   (works, stream-LF files only)
31BSD4_3      4.3BSD an most derivatives    (works)
32MCH_AMIGA   AmigaDOS Aztec/Manx C         (not tested; compiled version
33														 will eventually follow)
34
35
36MERGED OR MIXED SYSTEMS.  Many vendors of **IX systems take one of the
37two (System V or BSD) and add features from the other.  In some cases
38they do a terrible job of reconciling irreconcilable differences between
39the two, such that the merged system will now compile neither System V
40stuff nor BSD stuff.  If you are dealing with such a system, try
41compiling with both BSD4_3 and SYS_V in turn, and see if one of them
42works.  If not, then go through the list of compilation symbols below
43and pick a set that matches your system.
44
45------------------------------------------------------------------------
46NOTE:  The term "zoofile" below refers to an open file of type
47ZOOFILE.  Currently this is defined to be equivalent to a standard
48buffered file pointer of type "ZOOFILE *" but this could change in the
49future.  Dependence on exact definition of ZOOFILE is localized to a
50few files:  options.h, portable.h, portable.c, and machine.c.
51------------------------------------------------------------------------
52
53Attributes of systems:
54
55CHEKDIR
56   Test each supplied filename and if it is a directory or other special
57   type of file, do not try to add it to an archive.  If CHEKDIR is
58   defined, then machine.c must also contain function isadir() that
59   tests a supplied zoofile and returns 1 if it corresponds to a
60   directory or other special type of file, else 0.
61CHEKUDIR
62   Like CHEKDIR but use function isuadir() that tests a pathname, not
63   a zoofile.  Both CHEKDIR and CHEKUDIR may be defined, if both
64   functions isadir() and isuadir() are available;  in this case
65   zoo code will use both and will execute slightly faster.
66   (However, simultaneous definition of CHEKDIR and CHEKUDIR has
67   not been tested.)
68DISK_CH
69   If defined, must hold the value of a character that separates a
70   disk name from the rest of the pathname.  All characters up to and
71   including this character will be removed from a pathname before it
72   is stored in an archive.  Usually a colon (':').
73EXISTS
74   If defined, is assumed to be a macro that accepts a filename and
75   returns an int value of 1 if the file exists and 0 if it doesn't.
76   If not defined, existence of files is tested by attempting to open
77   them for read or write access.
78FATTR
79   If defined, file attributes will be preserved.  A function
80   getfattr(f) must also exist that returns the attributes of a
81   zoofile f (or of a pathname f, if the symbol FATTR_FNAME is
82   also defined); and a function setfattr(f, a) must exist that
83   sets the attributes of a file with pathname f to the value a.
84   For more details see the source code in sysv.c and bsd.c.  Currently
85   the attribute value a is required to be in the zoo portable
86   format.  The lowest nine bits of this format correspond to
87   the **IX mode bits described for chmod(2) and these are the only
88   bits currently used.
89FATTR_FNAME
90   If defined, and if FATTR is also defined, zoo code will
91   obtain the attributes of a file by calling the function
92   getfattr(f) and supplying it with filename f.  If FATTR_FNAME
93   is not defined, then getfattr(f) is supplied a zoofile f.
94ANSI_PROTO
95   Use ANSI-style function prototypes declarations.
96VOIDPTR
97   The type of a generic pointer, as returned by malloc().  This
98   should be defined as void * in an ANSI C environment.  In most
99   other environments it will be char *.
100LINT
101   If defined, SCCS identifier strings will not be included in the
102   generated code.  This will make the code smaller and will also
103   avoid complaints from lint about unused variables.  This symbol
104   should be defined in the Makefile, NOT in `options.h', otherwise
105   it will not be fully effective.
106FOLD
107   Fold filenames to lowercase.  Define this for case-insensitive filesystems
108FPUTCHAR
109   If defined, a library function fputchar() is assumed available
110   that is like fput() but is a function, not a macro, to save
111   space.  If not defined Zoo uses its own fputchar() function.
112PORTABLE
113   Use portable functions --- define for every system except MS-DOS
114PURIFY
115   When filenames are being read from standard input, ignore all
116   characters begining with the first blank or tab encountered.
117   This will allow filenames to be fed from a program that produces
118   lines containing filenames followed by other information that
119   should be ignored.  Should be defined for most non-**IX systems.
120DONT_SORT
121   Don't sort filename arguments -- files will be stored in the
122   exact order in which names are supplied on the command line.
123   Not currently used for any system, but could be used if memory
124   is really tight.
125NOENUM
126   Compiler does not support enumerations
127FNLIMIT
128   Pathname length limit for this system
129NEEDCTYP
130   If defined, tells the code to include the header file ctype.h for
131   use by character conversion macros.  If and only if NEEDCTYP is not
132   defined, macros or appropriate function declarations can be put in
133   portable.h.  Zoo uses isupper(), isdigit(), toascii(), and tolower().
134   If NEEDCTYP is not defined, the symbol USE_ASCII can be defined to
135   cause zoo to assume the ASCII character set and use its own isupper(),
136   isdigit(), toascii(), and tolower() functions, possibly making the
137   executable code smaller.
138USE_ASCII
139   See description of NEEDCTYP.  USE_ASCII should not be defined if
140   NEEDCTYP is defined, else there may be conflicts between macro
141   and function names.
142NIXTIME
143   If defined, a function setutime() must be defined that will set the
144   date and time of a file whose pathname is supplied.  If not defined,
145   a function settime() must be defined that will do the same for
146   a zoofile.
147GETUTIME
148   If defined, a function getutime() must be defined that will return
149   the MS-DOS format date and time of the specified filename.  If this
150   symbol is not defined, then a function gettime() must be defined
151   that will do the same for a zoofile instead of a filename.
152NOSIGNAL
153   Don't use signals because library doesn't support them
154T_SIGNAL
155   The data type returned by a signal handler.  Historically
156   "int", but "void" in ANSI C.
157PATH_CH
158   The character that separates the directory name from the filename
159   in a pathname.  String value.
160PATH_SEP
161   The set of characters that may separate preceding directory/device
162   information from the filename.  String value.
163EXT_SEP is the union of PATH_SEP and the set of characters separating a
164   filename extension from the rest of the filename.  String value.
165EXT_CH
166   Character that separates base part of filename from extension.
167   Char value.
168NEED_MEMSET  If defined, zoo will define its own equivalent of memset().
169	if not defined, zoo will try to link with a standard library function
170	memset().
171EXT_DFLT
172   default extension for archives.  String.  Currently ".zoo".
173NIXFNAME
174   If defined, PATH_CH, PATH_SEP, EXT_SEP, EXT_CH, and EXT_DFLT get defined
175   to conform to **IX conventions and should not be separately defined
176MSFNAME
177   if defined, PATH_CH, PATH_SEP, EXT_SEP, EXT_CH, EXT_DFLT, and
178   DISK_CH get defined to conform to MS-DOS conventions and should
179   not be separately defined (not currently implemented)
180FORCESLASH
181   If defined any backslashes in names of files will be converted to
182   slashes before the files are added to an archive.  This is useful
183   for MSDOS-like systems that accept both slashes and backslashes,
184   since the standard archive format allows only slashes as directory
185   separators.
186REN_LINK
187   Rename a file by using link() followed by unlink() (e.g. Xenix, System V)
188REN_STDC
189   Use ANSI standard rename function:  "int rename(old, new)" (e.g. 4.3BSD,
190   Turbo C).  Note:  define exactly one of REN_LINK, REN_REV, and REN_STDC.
191REN_REV
192   Use reverse rename function:  "int rename(new, old)" (e.g. Microsoft C)
193SETMODE
194   Change mode of standard output to binary when piping output, then change
195   it back to text.  Macros MODE_BIN(zoofile) and MODE_TEXT(zoofile) must
196   also be defined.  Probably specific to MS-DOS.
197SETBUF
198   Standard output should be set to be unbuffered so output shows up
199   quickly.
200SPECNEXT
201   If defined, a machine-dependent function nextfile() must be defined that
202   will expand wildcards in a supplied pathname. If not defined, any
203   wildcard expansion must have been done before the command line parameters
204   are supplied to the program.  For details see the file nextfile.c.
205SPECEXIT
206   Custom exit handler is needed.  A function called zooexit()
207   must be defined.  If SPECEXIT is not defined, zoo uses its
208   own zooexit() function which simply calls exit().
209SPECINIT
210   If defined, zoo's main() function will call spec_init() before
211   doing anything else.  Any system-specific initialization may be
212   done at this point.
213GETTZ
214   If defined, a function gettz() must also be defined that will
215   return the current timezone, in seconds west of GMT, as a long
216   value.  Currently such a function is already defined in files
217   bsd.c and sysv.c.  If and only if GETTZ is defined, zoo will
218   store the current timezone for each file that is archived,
219   and will list the timezone for each file that has one when it
220   lists archive contents.
221ALWAYS_INT
222   In function prototypes for fgetc(), fread(), and fwrite(),
223   traditional practice made certain arguments int, though
224   they ought to be char and unsigned respectively.  If
225   ALWAYS_INT is defined, prototypes will use int only,
226   else the correct types are used.
227NO_STDIO_FN
228   Defining this symbol will cause declarations of fputc(),
229	fread(), and fwrite() to not be done by the zoo header files.
230	Reported necessary for VMS;  may also help in other environments.
231IO_MACROS
232   If defined, some portable I/O functions are defined as macros,
233   saving space.
234ZOOCOMMENT
235   If defined, archive comments are fully enabled.  If not defined,
236   zoo code will be smaller at the cost that archive comments will
237   be listed but cannot be updated.  COMPILATION WITHOUT ZOOCOMMENT
238   DEFINED HAS NOT YET BEEN TESTED.
239TRACE_IO
240   This is for debugging.  If defined, it will cause code to
241   be compiled that will trace all archive header and directory
242   entry I/O by showing it on the screen in human-readable format.
243   The tracing will then occur if any Expert command given to zoo
244   is preceded by a colon.  E.g., if compiled with TRACE_IO on and
245   given the command "zoo :l xyz", zoo will give a directory
246   listing of xyz.zoo exactly as it would with "zoo l xyz" except
247   that all archive header and directory entry reads and writes
248   will be shown on the screen.  The tracing code is localized
249   to the files zoo.c and portable.c, so just these two files
250   can be compiled afresh when TRACE_IO is turned on or switched
251   off.  NOTE:  The symbol TRACE_LIST, internal to the file
252   "zoolist.c", enables debugging information too.  Do not define
253   both TRACE_IO and TRACE_LIST because (a) a symbol conflict will
254   occur and (b) the debugging information will be duplicated.
255UNBUF_IO
256   If defined, some I/O is done using low-level system calls read() and
257   write().  To do this, the low-level file descriptor is synchronized with
258   the buffered zoofile before such I/O is done.  To do this, read(),
259   write(), and lseek() system calls must be available and the fileno()
260   macro must return the file descriptor for a buffered file.  This is
261   not portable and should definitely not be done by most end users.  If
262   UNBUF_IO is defined, also defined must be a symbol UNBUF_LIMIT with a
263   numerical value that specifies the threshold over which unbuffered I/O
264   should be used.  For example, if the value of UNBUF_LIMIT is 512, then
265   any I/O on a zoofile that reads or writes more than 512 bytes will be
266   done using read() or write() system calls.  The use of unbuffered I/O
267   with a threshold in the range 512 to 1024 can enhance performance by up
268   to 50%.  The corruption of data is a serious matter.  Do not define
269   UNBUF_IO unless you are willing to exhaustively test the compiled code
270   on your system to make sure it works, and accept full responsibility for
271   any adverse consequences.  Some standard I/O libraries may attempt to
272   optimize the working of fseek() on files opened for read access only,
273   and cause UNBUF_IO to fail.
274UNBUF_LIMIT
275   Needed if and only if UNBUF_IO is defined.  Holds a numeric value.
276   All I/O done in blocks that are larger than UNBUF_LIMIT bytes
277   will be done unbuffered.  See UNBUF_IO.
278FILTER
279   If defined, code will be compiled in to enable the fc and fd
280   commands (compress or decompress, reading standard input and
281   writing to standard output).  These commands are useful only
282   on systems that allow programs to easily act as filters.
283VER_DISPLAY
284   The character that will separate filenames from generation numbers
285   in listings of archive contents.  Must be a single character
286   in double quotes.
287VER_INPUT
288   The characters that will be accepted as separating filenames
289   from generation numbers when typed as an argument to select
290   specific files from an archive.  String value.  May include
291   one or more characters;  any of them may then be typed and
292   will work.
293NOSTRCHR
294   Although 4.3BSD as distributed from Berkeley includes strchr()
295   and strrchr() library functions, 4.2BSD and similar systems
296   may not.  If so, defining NOSTRCHR will cause zoo to use
297   index() and rindex() instead.
298STDARG, VARARGS.  How to invoke functions that accept a variable
299   number of arguments.  Define one of these.  STDARG causes the
300   ANSI-style header stdarg.h to be used.  VARARGS causes the **IX-style
301   varargs.h header to be used.  If you define STDARG, you must also
302   define ANSI_PROTO (see above).
303DIRECT_CONVERT.  Zoo archives use a canonical little-endian byte order,
304   and functions are portably defined to convert between this and the
305   internal format used by an implementation.  If the symbol
306   DIRECT_CONVERT is defined, the zoo code will not bother doing this
307   portable conversion, but simply assume that the machine's internal
308   format is the same as the canonical byte order used in zoo archives.
309   DIRECT_CONVERT should be defined *only* if your implementation uses:
310   little-endian byte order, 2-byte ints, and 4-byte longs.  If there is
311   any doubt whatsoever, don't define DIRECT_CONVERT;  the overhead of
312   portable conversion is not significant.
313SZ_SCREEN.  If this symbol is not defined, a screen height of 24 lines
314	is assumed by the multiscreen help.  If desired, this symbol can be
315	defined to some other nonnegative value of screen height.
316NEED_MEMMOVE.  If defined, zoo will define its own equivalent of memmove().
317	If not defined, zoo will try to link with a standard library function
318	memmove().
319NEED_VPRINTF.  If this symbol is defined, zoo will use its own jury-
320	rigged vprintf function.  If this symbol is not defined, zoo will
321	try to link with vprintf in the standard library.
322