########################################################################
# This program is Copyright (C) 1986-1996 by Jonathan Payne.  JOVE is  #
# provided to you without charge, and with no warranty.  You may give  #
# away copies of JOVE, including sources, provided that this notice is #
# included in all the files.                                           #
########################################################################

Jove has two classes of ifdefs.  Some are used to select system-dependent
features, others are to select Jove features.  The former are defined in
sysdep.h, the latter in tune.h.  This file describes the ones in sysdep.h.

sysdep.h is structured as a set of #ifdefs for different systems, each system
being identified by some unique symbol (e.g. SUNOS41 for SunOS version 4.1
and 4.1.*).  We do not use symbols pre-defined by the compilers, they're too
hard to predict and often do not provide the granularity that's necessary to
differentiate between system versions or types.  If the system you run is
included in sysdep.h, just use it.  If not, select a symbol to define your
system (e.g. SOMEOS) and choose the appropriate system-dependent options that
characterise your systems terminal handling, process handling, header files,
etc from the list below.

NOTE: We've removed almost all the "#ifdef system-type" ifdefs from the body
of Jove code, replacing those with the feature ifdefs documented below.
This sort of approach is necessary in this day & age of hybrid systems.
If you're porting Jove to a new system, please follow the feature-based
approach and don't stick "#ifdef system-type" ifdefs in the code.

For terminal handling under Unix, define one of the following, in
decreasing order of preference.
TERMIOS		Have "struct termios" and termios.h.  Posix systems,
		most modern Unixes.
SGTTY		Have stty() and gtty() for tty characteristics.
		BSD4.3 and precursors, including V7.
TERMIO		Have "struct termio" and termio.h for tty characteristics.
		System V derivatives.  Warning: if your system supports
		BSD-style Job Control, don't use TERMIO: it cannot
		suppress the action of some magic characters.

Jove needs to know the current working directory for pathname optimization
and the directory functions that it provides ("cd", "pushd", etc).
Define one of the following, in order of decreasing preference:
USE_GETCWD	have the getcwd() routine for the name of the current
		directory.  Posix.
USE_GETWD	have the getwd() routine for the name of the current dir.
		BSD4.2 and derivatives (SunOS3, old Ultrix)
USE_PWD		Run the 'pwd' program to find the name of the current
		directory.  Old Unixes.

If the compiler is ANSI C, then prototyping will be supported
automatically (this is determined by checking that __STDC__ is
defined (by the system), and it is greater than 0).  For other
systems, you may define:
USE_PROTOTYPES	for non-ANSI systems that nevertheless support prototypes
NO_PTRPROTO	for systems that botch prototypes in function pointer decls.
STDARGS		for non-ANSI systems that nevertheless support stdargs.h,
		as opposed to varargs.h
MIPS_CC_BUG	avoid function definition syntax that provokes a MIPS cc bug.
		This bug manifests itself as compiler complaints around the
		extern declarations that have parentheses around them.
		(e.g. select).  One version of the error looks like this:
		externs.h, line 145: ccom: Internal: compiler takes size of function

Newer systems tend to have header files with more system calls defined,
sometimes with prototypes.  Choose one of the following, depending on your
system.  If neither of the following is defined, then the declarations in
externs.h are used.
POSIX_UNISTD	Have Posix P1003.1 compliant unistd.h with declarations.
FULL_UNISTD	Have fully-prototyped header files, superset of Posix P1003.1

Usually, the result type returned by read() and write() is int.
Posix carefully defines a type name for this type: ssize_t (it logically
is a size_t, but it must be signed because -1 is a possible value).
We use SSIZE_T which defaults to ssize_t if FULL_UNISTD, otherwise int.
This can be overridden by defining SSIZE_T.

Different environments have different memory and address space limitations.
Generally, these controls default appropriately.
NBUF		Number of memory blocks allocated to cache for buffers.
JLGBUFSIZ	log-base-2(sizeof buffer block).  Generally 9 or 10,
		yielding blocks of size 512 or 1024 bytes.  Each text line
		in Jove is restricted to fit within a single block, so
		larger is better.  Also, larger blocks should reduce
		the number of blocks transfered between the temp file
		and RAM.  Smaller blocks reduce the number of bytes
		transferred and more efficiently use cache memory
		(there would be more blocks in an identically sized cache).
SMALL		Intended for machines with small address spaces, for example
		the PDP-11 and small or medium model on x86.  It drastically
		reduces NBUF, cuts down JLGBUFSIZ, and makes daddr an
		unsigned short.
MALLOC_CACHE	Causes the in-core cache for disk blocks to be malloced
		rather than allocated as a static variable.  This helps
		environments where statically allocated things are placed
		in one limited segment, but malloced things are placed
		in separate segments.  Examples include MAC and large
		model x86.  Remember that NBUF * ((1<<JLGBUFSIZ) + overhead)
		will probably have to fit within a single segment.
AUTO_BUFS	Allocate several of the fixed buffers on the stack
		instead of statically.  On the PDP-11, this exploits
		memory that would be otherwise wasted due to the
		granularity of the MMU.  On the Macintosh under Think C,
		this reduces the size of the static data segment enough
		to avoid "far data".

IPROCS is defined if interactive processes are to be supported.  It
is defined in tune.h, implying that it is a matter of preference, at
least on UNIX systems.  Unfortunately, in some cases control is
needed in sysdep.h (because it is a matter of feasibility).  To
reflect this, if NO_IPROCS is defined in sysdep.h, tune.h will not
define IPROCS.  Beware: doc/jove.rc (the standard system-wide rc file)
binds several process commands, so it will need changing if interactive
process support is not compiled in.

To multiplex between different processes and the keyboard (when IPROCS
is defined), define USE_SELECT.
USE_SELECT	Have the select() system call.  Almost essential!
USE_SELECT_H	sys/select.h needed for FD_* macros.  AIX and QNX.
Jove also uses select() for delays if available.  Without select(),
the code is a kludge, but it may work...


Jove sometimes tries to find out if there is pending keyboard input.
There are too many different ways of doing this.  Jove will use FIONREAD
if it finds that symbol defined by a header it includes.  It will use
select if USE_SELECT is defined.  Older systems may support
fcntl(... O_NDELAY); POSIX.1 systems should support O_NONBLOCK.
NONBLOCKINGREAD	use O_NDELAY/O_NONBLOCK to test for pending keyboard input


If IPROCS is defined in tune.h, one of the following two must be defined.
If your system supports neither PTYS nor PIPES, don't define IPROCS unless
you feel in the mood for very serious hacking.
PTYPROCS	Use pseudo-ttys.  BSD and most modern Unixes.
PIPEPROCS	Use pipes for interactive processes.  Older Unixes.


If PTYPROCS is defined, then one of the following must be defined.  Or add
your own code in iproc-ptys.c.
SVR4_PTYS	SYSVR4 pty allocation.  ptym, grantpt() and friends.
BSD_PTYS	canonical BSD ptys, search through pty[pqrst]
IRIX_PTYS	Irix 3.x onwards -- open a master device, then fstat to get
		major and minor numbers.

Certain early SVR4 systems have a buggy grantpt library routine that
is used if PTYPROCS is defined.  A symptom is that the "shell"
command will always fail with a [grantpt failed] message.  System V
Release 4.0 and Solaris 2.0 (but not Solaris 2.3) and have this bug.
GRANTPT_BUG  Define this to enable a work-around.

Certain systems, for example IRIX 4 and IRIX 5.3, define the symbol
TIOCREMOTE but don't implement this ioctl correctly.  A symptom is
that the eof-process command will not work.
NO_TIOCREMOTE	Define this to avoid using TIOCREMOTE even if the
		system defines it.

Certain systems, for example IRIX 5.3, define the symbol TIOCSIGNAL
but don't implement this ioctl correctly.  A symptom is that the
interrupt-process command will not work.
NO_TIOCSIGNAL	Define this to avoid using TIOCSIGNAL and TIOCSIG even
		if system defines them.

Certain systems, for example HP/UX 9, don't seem to send EOF to the master
side of the pty when the slave side shuts down.  On these systems, Jove
should be told not to wait for EOF:
NO_EOF_FROM_PTY	Define this if your system fails to signal EOF to pty master

To deal with SUBSHELL and IPROCS (both in tune.h), define one of the
following:
POSIX_PROCS	Supports Posix processes, waitpid()
BSD_WAIT	Has sys/wait.h and "union wait".
If neither POSIX_PROCS nor BSD_WAIT is defined, Jove uses wait().  (old Unixes)


If BSD_WAIT was defined, also consider defining
WAIT3		use wait3() on systems that have it.  (BSD4.2 and modern
		non-Posix Unixes).  If this is not defined, we try wait2().


Signal handling varies between systems.  The original UNIX signal mechanism
is unsafe -- if a second signal is received soon enough, the program will
crash.  Furthermore, there is no mechanism for a process to request that
signal delivery be held temporarily.  BSD, System V, and POSIX have each
provided better but different facilities.  Without safe signals, Jove might
crash, although this is not common.  Jove will use signal holding to more
gracefully handle SIGINTs while starting processes; otherwise those SIGINTs
will be ignored.  The feature select macros, in decreasing order of
preference are:
POSIX_SIGS	Use POSIX's safe sigaction(); use sigprocmask() for signal holding.
USE_SIGSET	Use sigset(), 4.2BSD's safe signal mechanism.
		Use sighold() and sigrelse() for signal holding.
BSD_SIGS	Use 4.x BSD's safe signal(); use for sigsetmask() for holding.
If none of these symbols is defined, unsafe normal signals are used (except
on BSD systems, where the normally unsafe signal() is in fact safe).


JOB_CONTROL	System supports job control (SIGTSTP, ^Z etc.  for pause-jove)


USE_VFORK	system has a vfork that is much faster than fork.  This
		capability should be nuked (any self-respecting copy-on-write
		memory implementation should be able to do fork almost as
		fast as vfork)!


The following are only needed for IPROCS.
BSD_SETPGRP	setpgrp takes two arguments.   If this is not defined,
		assume System V setpgrp with no arguments.
USE_KILLPG	Uses the BSD killpg() system call.  If this is not defined,
		Jove assumes that kill(-pid, ...) is equivalent (SysV).


If F_COMPLETION is defined, then Jove needs to be able to scan directories.
By default, Jove assumes the system has "struct dirent" and "dirent.h".
If not, define one of the following
BSD_DIR		has "struct direct" and "sys/dir.h".  BSD4.2.  (maybe 4.1?)
DIRENT_EMULATE	emulate dirent routines by open()ing and read()ing the
		directory.
M_XENIX		Support for some versions of XENIX, dealing with
		peculiarities of directory handling.  Not recently tested.


If F_COMPLETION is defined, and you want ~username to be expanded, then
you may need to define the following, especially on systems running YP/NIS,
or using a database form of the password file.
USE_GETPWNAM	has the getpwnam() system call.  Just about every modern
		Unix.


Choose the type of signal handler.  If you don't define these, Jove
defaults to "void" and "/*void!*/".
SIGRESTYPE	the return type of signal handlers.  "void" on most modern
		systems, "int" on older systems.
SIGRESVALUE	the return value of signal handlers.  "/*void!*/" on systems
		where SIGRESTYPE is "void", usually 0 on systems where
		SIGRESTYPE is "int".


Either of following two is useful to the "recover" program, but not both.
USE_UNAME	has the uname() system call.  True on System V and Posix
		and most hybrids.
USE_GETHOSTNAME	has gethostname() system call.  True on most BSD machines.


NO_STRERROR	If you do not have the strerror() routine.  Needed for
		pre-ANSI systems (SunOS older than 4.1, BSD, older Unixes)
		With this defined, Jove provides an emulation using
		sys_errlist, which should work on most Unixes.

USE_FSYNC	Have the fsync() system call.  True on just about all modern
		Unixes.  Not defining this does little harm (it's used only
		to force a flush on files)

If BIFF is defined, you can usefully define either or both of the following:
USE_FSTAT	Have the fstat() call.  Just about every modern Unix does.
USE_FCHMOD	Have the fchmod() call.  Again, true on most modern Unixes
		after BSD4.2.

Jove supports 7-bit or 8-bit character sets.  It has a wired-in
notion of what each kind of character is, but it can use the
system's classification of control characters.
NCHARS		the number of distinct character codes.  This defaults to 256
		but can be set to 128 for 7-bit character sets.
USE_CTYPE	use the system's <ctype.h> functions.  If this is
		defined and these functions only work for 7-bit
		characters, be sure to define NCHARS to be 128
NO_SETLOCALE	define if you wish to define USE_CTYPE but the system
		has no setlocale routine.
ISO_8859_1	use wired-in tables reflecting the characteristics of the
		ISO 8859-1 character set (Latin1) (USE_CTYPE is better if
		it works).
For the IBM PC under MSDOS, look below for the description of CODEPAGE437.
There is a wired-in table for the Macintosh used if MAC is defined.


DEFINE_PC_BC_UP_OSPEED
		Certain variables used by termcap/terminfo are
		declared in the library on almost all systems.  For
		those systems that don't define them, this macro
		enables declarations within Jove.  Needed for HPUX
		and possibly other SysV Rel.2 machines.  If you get
		messages like "ospeed undefined" when linking, try
		this.

USE_MEMORY_H	include memory.h for declarations of memcpy() et al.
		Older SysV, IBMPCs, Xenix.


USE_BCOPY	use bcopy in place of missing memcpy.
		BSD4.2 and precursors from Berkeley.

USE_INDEX	use index in place of missing strchr.
		BSD4.2 and precursors, including V7.

USE_INO		use the inode number (and device number) to tell if two
		paths refer to the same file or directory.  Automatically
		defined for UNIX.  Supported for MAC too.

USE_EXIT	Normally, Jove exits by calling _exit, to avoid stdio.
		When this symbol is defined, exit() is used instead.
		This is needed when profiling Jove or running it under
		debugging tools like purify.

UNIX		This is automatically defined if we're none of MAC, MSDOS
		or WIN32.  Yuk!

TERMCAP		Support display diversity via termcap database.
		This is automatically defined for UNIX.

TERMINFO	Support for System V variant of TERMCAP.  TERMCAP
		must also be defined.  This differentiates between
		tparm and tgoto.  It is untested.

Jove has been built and tested on PC-compatible computers under
several compilers and at least two environments.  The following
manifests are primarily used to tailor the characteristics of
various PC environments and/or differentiate them from the Unix or
MAC variants of Jove.

MSDOS		MSDOS or MSDOS-like system, such as IBM PC, DEC Rainbow,
		or Atari ST.  Only tested on IBMPCDOS recently.

IBMPCDOS	Indicates MSDOS on an IBM PC-Compatible hardware platform.
		This enables hardware-specific characterstics of Jove on
		this platform, such as the screen and keyboard interface.

WIN32		indicates Jove running as a Console app under the WIN32
		api on Windows NT or Windows 95.

The following characteristics are currently enabled only in the MSDOS
and WIN32 environments but could be enabled in other environments if
it made sense to do so.

FILENAME_CASEINSENSITIVE	indicates that Jove should ignore case
		when comparing filenames.  This should only be defined when
		building Jove in an environment with this characteristic,
		e.g. MSDOS or WIN32.  Note: this does not imply that filenames
		are monocase; they may be (as for MSDOS) but may not be (e.g.
		for WIN32).

DIRECT0RY_ADD_SLASH	indicates that Jove will display a slash at the end
		of directory names when browsing for a file (i.e. when a ?
		is entered during Jove's prompt for a file name).  Define
		this only if it can be done cheaply in the jscandir
		implementation (and also set up jscandir to do so).
		It is presently defined for MAC, MSDOS, and WIN32.

MSFILESYSTEM	enables certain filename parsing features in Jove to support
		Microsoft's manner of organizing a filesystem.  This includes
		one-letter device names, use of backslash as a directory
		separator, and avoidance of a "dot" as the first character of
		a filename (as in .joverc).

EOL		character to recognize and use as end-of-line when loading or
		saving text files.  Defaults to '\n'.

USE_CRLF	tells Jove to recognize and use CR/LF as end-of-line when
		loading or saving text files.  A bare LF will still be
		recognized on input.  EOL should be left as the default '\n'.

PCNONASCII	The IBM PC keyboards have a number of keys that don't
		generate ASCII characters (for example, function keys).
		Other systems use escape sequences or control characters
		to encode these keys.  For the PC, we use a special
		code (0xFF) as a prefix for the scan-code generated
		by the key.  PCNONASCII is both the feature selector,
		and, if defined, it has the value of this prefix.

NO_JSTDOUT	This suppresses stdio-style buffering for screen output.

CODEPAGE437	This is the name of the "ordinary" character set supported
		by IBM PC displays.  It is described in the appendix of
		"Microsoft MSDOS Operating System 5.0 User's Guide and
		Reference" as supporting USA English.

PCSCRATTR	Exploit IBMPC screen attributes.  Enables variables
		text-attribute, mode-line-attribute, and highlight-attribute.


Jove has been ported to the Macintosh using Think C version 5.0.  This port
has not been well tested, nor does it follow Mac conventions.  Perhaps it
should be considered a proof of portability.
MAC		Select all the Macintosh-specific code.