Fresh Fish 5

home *** CD-ROM | disk | FTP | other *** search

/ Fresh Fish 5 / FreshFish_July-August1994.bin / bbs / util / zoo-2.1.lha / zoo-2.1 / options.doc < prev next >

Wrap

Text File | 1991-07-17 | 15.9 KB | 322 lines

/* derived from: options.doc 1.4 88/08/22 15:24:59 */ /* $Source: /usr/home/dhesi/zoo/RCS/options.doc,v $ */ /* $Id: options.doc,v 1.5 91/07/09 02:53:10 dhesi Exp $ */ 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. LOOK IN THE FOLLOWING FILES WHEN MAKING CHANGES TO SUPPORT A NEW SYSTEM: options.h, portable.h, machine.c ALSO GLANCE AT THESE FILES TO MAKE SURE THEY WILL WORK: zooio.h, machine.h Machine names: MSC Microsoft C under MS-DOS (not currently in use) TURBOC Turbo C++ 1.0 under MS-DOS (works, compiled version is separately distributed) SYS_V Most releases of System V (works) VMS VAX/VMS 5.4 (works, stream-LF files only) BSD4_3 4.3BSD an most derivatives (works) MCH_AMIGA AmigaDOS Aztec/Manx C (not tested; compiled version will eventually follow) MERGED OR MIXED SYSTEMS. Many vendors of **IX systems take one of the two (System V or BSD) and add features from the other. In some cases they do a terrible job of reconciling irreconcilable differences between the two, such that the merged system will now compile neither System V stuff nor BSD stuff. If you are dealing with such a system, try compiling with both BSD4_3 and SYS_V in turn, and see if one of them works. If not, then go through the list of compilation symbols below and pick a set that matches your system. ------------------------------------------------------------------------ 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 could 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. ANSI_PROTO Use ANSI-style function prototypes declarations. VOIDPTR The type of a generic pointer, as returned by malloc(). This should be defined as void * in an ANSI C environment. In most other environments it will be char *. 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 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 T_SIGNAL The data type returned by a signal handler. Historically "int", but "void" in ANSI C. 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. NEED_MEMSET If defined, zoo will define its own equivalent of memset(). if not defined, zoo will try to link with a standard library function memset(). 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_STDC Use ANSI standard rename function: "int rename(old, new)" (e.g. 4.3BSD, Turbo C). Note: define exactly one of REN_LINK, REN_REV, and REN_STDC. REN_REV Use reverse rename function: "int rename(new, old)" (e.g. Microsoft C) 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. Probably specific to MS-DOS. SETBUF Standard output should be set to be unbuffered so output shows up quickly. 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. 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. NO_STDIO_FN Defining this symbol will cause declarations of fputc(), fread(), and fwrite() to not be done by the zoo header files. Reported necessary for VMS; may also help in other environments. 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. STDARG, VARARGS. How to invoke functions that accept a variable number of arguments. Define one of these. STDARG causes the ANSI-style header stdarg.h to be used. VARARGS causes the **IX-style varargs.h header to be used. If you define STDARG, you must also define ANSI_PROTO (see above). DIRECT_CONVERT. Zoo archives use a canonical little-endian byte order, and functions are portably defined to convert between this and the internal format used by an implementation. If the symbol DIRECT_CONVERT is defined, the zoo code will not bother doing this portable conversion, but simply assume that the machine's internal format is the same as the canonical byte order used in zoo archives. DIRECT_CONVERT should be defined *only* if your implementation uses: little-endian byte order, 2-byte ints, and 4-byte longs. If there is any doubt whatsoever, don't define DIRECT_CONVERT; the overhead of portable conversion is not significant. SZ_SCREEN. If this symbol is not defined, a screen height of 24 lines is assumed by the multiscreen help. If desired, this symbol can be defined to some other nonnegative value of screen height. NEED_MEMMOVE. If defined, zoo will define its own equivalent of memmove(). If not defined, zoo will try to link with a standard library function memmove(). NEED_VPRINTF. If this symbol is defined, zoo will use its own jury- rigged vprintf function. If this symbol is not defined, zoo will try to link with vprintf in the standard library.