Geek Gadgets 1/ADE-1.bin/ade-dist/jove-4.16-src.tgz/tar.out/bsd/jove/sysdep.doc

Text File | 1996-09-28 | 18KB | 383 lines

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