##########################################################################
# This program is Copyright (C) 1986-2002 by Jonathan Payne.  JOVE is    #
# provided by Jonathan and Jovehacks without charge and without          #
# warranty.  You may copy, modify, and/or distribute JOVE, provided that #
# this notice is included in all the source files and documentation.     #
##########################################################################

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, recently, the result of the
uname command on an OS, for convenience.  (e.g. Linux, Darwin, FreeBSD etc,
but previously, SYSVR4 for various System V Release 4 machines). 

old/sysdep.h, not used by any Jove code, is a historical archive
of definitions that were once tested on various machines,
but have not been tested for the recent release, so it is
entirely possible that changes for other systems have caused
those older definitions to stop working.

We usually avoid 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.  There's also sometimes
a variety of compilers with different pre-defined symbols. 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
characterize your systems terminal handling, process handling, header files,
etc from the list below.  Using an existing system, or common group of
characteristics (XBSD, BSDPOSIX_REALSTDC, etc) is often a good start.

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 put "#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.

SunOS4 sys/ioctl.h conflicts seriously with termios.h, so it needs
NO_IOCTL_H_TTY

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.

When Jove is tries to make file pathnames canonical.  Handling of a ..
component must take account of symbolic links.  All modern UNIXes have
symlinks.  We don't yet know how to support MAC or WIN32 aliases.
HAS_SYMLINKS	use readlink(2) to handle symlinks

In order to canonicalize SHAREDIR and LIBDIR paths relative to the
executable directory, Jove needs to figure out where the exectutable
ran from.
PNAME_PROC_SELF	should be defined on Linux-like machines (or Debian Hurd)
		since they have /proc/self/exe as a symlink to the
		running executable path.
PNAME_GETEXECNAME should be defined on Solaris-like machines which have the
		getexecname() function to return the running executable path.
PNAME_SYSCTL_OID should be defined on FreeBSD or NetBSD, with the oid
		array that can be given to sysctl() to return the path
		to the running executable.
If the above do not exist, it will use argv[0] and hope for the best.

Jove needs to make a number of temporary files.  The traditional ways
of creating temp files are subject to race conditions allowing
security to be compromised on multi-user systems.  The mkstemp library
routine avoids this problem, but isn't available on all systems.  In
its place, Jove will make do by using mktemp.  If this isn't
available, Jove will use an even poorer technique.  The mktemp form
is safe if the open system call supports O_EXCL just right (it must
balk at symlinks).
NO_MKSTEMP	work around lack of mkstemp
NO_MKTEMP	work around lack of mktemp

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
		MIPS-based Ultrix upto 4.2 at least, RiscOS and IRIX (upto 3.3
		at least) need this.

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

Some really old systems may not have a header <fcntl.h>.  To stop JOVE
trying to #include it, define
NO_FCNTL	no <fcntl.h> header provided by system

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.

In modern systems, the type mode_t is used for permission bits (in
creat(2), stat(2), and open(2)).  In ancient systems, this was just int;
unsigned would have been better.  Jove uses the macro jmode_t.  If you
don't provide a definition, it defaults to mode_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.
LG_JBUFSIZ	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 transferred 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).
JSMALL		Intended for machines with small address spaces, for example
		the PDP-11 and  DOS 8086/8088.  It drastically
		reduces NBUF, cuts down LG_JBUFSIZ, 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<<LG_JBUFSIZ) + 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.
		Don't forget to set PORTSRVINST in Makefile.

If PTYPROCS is defined, then one of the following must be defined.  Or
add your own code in iproc-ptys.c.  SVR4_PTYS are more secure than
BSD_PTYS (the BSD weakness is described below).  SVR4_PTYS are also
known (at least in the LINUX world) as UNIX98 PTYS.  They are part of
"The Single UNIX Specification", Version 2.
SVR4_PTYS	SYSVR4 pty allocation.  Use /dev/ptmx, ptsname, grantpt, etc
BSD_PTYS	traditional BSD ptys.
IRIX_PTYS	Irix 3.x onwards -- open a master device, then fstat to get
		major and minor numbers.

WARNING: On BSD systems, there is a dangerous security hole in the PTY
system.  Although JOVE (or any other non-privileged program) can
allocate a PTY, it cannot change the ownership or permissions to
prevent other processes run by other users from mucking with the same
PTY.  An example of such mischief is that someone else could trick
your JOVE into running a shell command for him but as you!  The
traditional way to allocate a PTY is to search through search through
/dev/pty[p-s][0-9a-f] for a free one, and use that.  Modern BSD
systems have added a new library routine "openpty(3)" which could be
made to close this hole, but this hasn't happened at this time (2001
March 21).  In anticipation of such a fix, JOVE can be made to use
this routine.  Currently, the only advantage is that when JOVE is run
by the superuser, some versions of BSD do manage to close the hole.  A
disadvantage is that -lutil must be added to the link command because
openpty is in libutil.

OpenBSD 3.5 has closed this hole (2004).
USE_OPENPTY	use the new BSD openpty(3) routine (OpenBSD, NetBSD, MacOS X Darwin)
HAVE_LIBUTIL_H	use <libutil.h> instead of <util.h> (FreeBSD)
HAVE_PTY_H	use <pty.h> instead of <util.h> (Cygwin, glibc, Interix, OSF/1 4 and 5)

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 Digital UNIX 4.0
have this bug.  It turns out that this bug is documented as a feature
in "The Single UNIX Specification", Version 2!
GRANTPT_BUG  Define this to enable a work-around.

Certain systems, for example NetBSD (at least 7.x and 8.x),
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 modern copy-on-write
		memory implementation should be able to do fork almost as
		fast as vfork)!  It is only believed to be useful for
		architectures without an MMU (we welcome test reports)

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.  Used to ask the OS to really flush the file to disk.

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.

DEBUGCRASH	Do not trap on SEGV, BUS signals, useful for running Jove
		under a debugger (e.g. gdb, dbx)

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.

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.

JTC		Simple builtin-termcap emulation, avoids need
		for external library dependency on termcap/terminfo/*curses*.
		TERMCAP must also be defined.  The OS must support select(),
		which is used for timing delays.
		Only works on vt[123]NN or compatible terminals, or
		emulators like xterm/rxvt/st/vte etc. The environment
		variable JOVEVT can be set to the level of emulation,
		the number of the DEC terminal (e.g. 100 for vt100,
		102 for vt102, etc, and 999 or "alt" for xterm-like
		emulators that support the alternate screen.
		99 means ordinary minimal ANSI X3.64/ECMA-48 emulation,
		the minimal cursor movement and screen clearing capabilities
		needed for a screen editor. Even most ancient vt100-clones
		and half-hearted emulators should be able to support this.
		100 and above have visible bell, scrolling region, arrow keys.
		102 and above have insert and delete chars and lines.
		125 adds a meta-key.
		320 adds multi-line scroll or pan forward/backward (SU/SD)
		999 (aka alt) have alternate screens.

NCURSES_BUG	Work around the non-standard meaning of insert character
		capabilities in the termcap and terminfo databases
		distributed with ncurses.  Probably needed for FreeBSD,
		NetBSD, and LINUX.  Probably safe for all others (except
		if you use a Datamedia 2500 terminal).  We automatically
		define this for UNIX.

Jove has been built and tested on PC-compatible computers
under a couple of compilers and environments, but is neither
developed nor regression tested on them, so it might be in
active use there.  The following defines are primarily
used to tailor the characteristics of various PC
environments and/or differentiate them from the Unix or MAC
variants of Jove.

WIN32		indicates Jove running as a Console app under the WIN32
		(Windows NT, 95, 98, 2000, XP, etc)
		Tested on Windows 7 for 4.17.

OWCDOS		Open Watcom compiler for MSDOS.  This has been tested for 4.17

MSDOS		MSDOS or MSDOS-like system. Only tested on IBMPCDOS in recent
		memory, but worked on the DEC Rainbow ant Atari ST once.

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

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
		or the use of file descriptor 0 or /dev/tty.

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 was once ported to the old (pre OS X) 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.