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