dir.c (plib.h plibu.h pstdlib.h) <unistd.h sys/types.h sys/stat.h>
  DIRENT_HEADER undef, <sys/dir.h>, <sys/ndir.h>, <ndir.h>
    set only if <dirent.h> not present
  USE_GETWD
    set to use getwd instead of getcwd

files.c (pstdio.h pstdlib.h plibu.h) <string.h unistd.h>

fpuset.c (plibu.h)
  see README.fpu for list of FPU_* macros

fputest.c is related to fpuset.c

getpath.c (plib.h pstdlib.h)

handler.c (plib.h) <signal.h>

main.c (plib.h pstdlib.h plibu.h) <setjmp.h>

pathnm.c (plib.h pstdlib.h) <string.h>
  NO_PASSWD -- define to skip ~user expansion, otherwise
    <sys/types.h unistd.h pwd.h>

pgrp.c
  HDR_WITH_TIOCGPGRP -- if undef, <sgtty.h>
  - pgrp.c only necessary for systems missing tcgetpgrp

stdinit.c (plib.h pstdlib.h pstdio.h plibu.h) <string.h>

timeu.c (plib.h)
  USE_GETRUSAGE -- (preferred if present) <sys/time.h sys/resource.h>
  USE_TIMES -- (POSIX standard) <time.h sys/times.h>
  else      -- (ANSI C standard) <time.h>

timew.c (plib.h)
  USE_GETTIMEOFDAY -- (X11 uses this) <sys/time.h>
  else             -- (ANSI C standard) <time.h>

uevent.c (plibu.h pstdlib.h) <errno.h>
  USE_SELECT -- use upoll.c implementation of poll (upoll.h)
  else       -- use system poll (preferred)
    USE_SYS_POLL_H <sys/poll.h>
    else           <poll.h>

ugetc.c (pstdio.h plibu.h ugetc.h)

uinbg.c (plibu.h) <sys/types.h>

upoll.c (upoll.h pstdlib.h)
  HAVE_SYS_SELECT_H <sys/select.h>
  else
    NO_SYS_TIME_H <time.h> else <sys/time.h>
    NEED_SELECT_PROTO <sys/types.h>

usernm.c (plib.h pstdlib.h)
  NO_PASSWD -- use cuserid function
  else      -- <sys/types.h unistd.h pwd.h>

waiter.c (plib.h plibu.h)





Notes on UNIX variants
----------------------

Required headers not part of ANSI C standard:

<unistd.h>      dir.c usernm.c
  chdir rmdir getcwd (in dir.c)
  getlogin getuid (to implement cuserid in usernm.c)
<sys/types.h>   dir.c usernm.c
<sys/stat.h>
  stat S_IFDIR (in dir.c)
<dirent.h>      dir.c
  or one of: <sys/dir.h>, <sys/ndir.h>, or <ndir.h>
  opendir readdir closedir (in dir.c)
<pwd.h>         usernm.c, pathnm.c (unused if NO_PASSWD set)
  getpwnam (to expand ~user/* pathnames)
  getpwuid (to implement cuserid in usernm.c)

pathname expansion: (pathnm.c)
-------------------
  $ENVVAR $(ENVVAR) ${ENVVAR}
  $ENVVAR/path $(ENVVAR)/path ${ENVVAR}/path
  ~ ~/path
  ~user ~user/path
    are all expanded by u_pathname, which is used in every plib
      function requiring a pathname
    ~ is the same as $HOME, but if no such environment variable exists
      and NO_PASSWD is not set, tries to get the home directory for
      the current real user
    ~user will not work if NO_PASSWD is set

dirent.h (dir.c)
--------
   Old style is struct direct instead of struct dirent; directory
     functions may be in <sys/dir.h>, <sys/ndir.h>, or <ndir.h>
   Autoconf manual notes that d_namlen member may be missing from
     struct dirent (present in struct direct); that raises the
     possibility that d_name is not a 0-terminated string
     -- xfig source assumes that it is, so I do too
  DIRENT_HEADER - if no dirent.h, set to <sys/dir.h> etc

getcwd (dir.c)
------
   SunOS deprecates use of getcwd in favor of getwd,
     but apparently getcwd is more portable (getwd is non-POSIX)...
   Comments in HPUX unistd.h indicate that original POSIX.1 1988
     definition had second parameter of type int; POSIX now size_t
   NextOS has no getwd, at least in some old versions
  USE_GETWD - define to use getwd instead of getcwd

cuserid (usernm.c)
-------
   cuserid was removed from POSIX due to a religious war over
     whether it should return the real or effective username
   I call getlogin(), then getpwuid(getuid())
  NO_PASSWD - define to use cuserid (requires no headers)

Notes on play configuration
---------------------------

There are two configuration files:

config.h       - #defines for source code in play/*/*.[ch]
../../Make.cfg - Makefile definitions required to compile or load
                 (common to all packages)

Both of these can hopefully be computed by the config.sh script; if
not, you may be able to do the job by hand.

------------------------------------------------------------------------
_POSIX_SOURCE, _XOPEN_SOURCE_EXTENDED, _HPUX_SOURCE macros:

I want to try to use the POSIX standard whenever possible and
applicable.  System header files known to be affected on some systems
include:
<signal.h>, <dirent.h>, <sys/types.h>, <unistd.h>, <pwd.h>, <time.h>

The files files.c and ugetc.c need _POSIX_SOURCE before <stdio.h> in
order to get the fileno macro declared.  The dir.c, pathnm.c,
usernm.c, and uinbg.c files use explicitly POSIX functions and also
declare the macro.

A few play features are implemented using non-POSIX functions.  At
these places in the source code, I undef _POSIX_SOURCE.  The timers
gettimeofday (timew.c) and getrusage (timeu.c) are the only examples
so far; HPUX additionally needs _HPUX_SOURCE in the former case.

The poll/select functions in uevent.c and upoll.c are the other
non-POSIX routines and have caused some problems.  HPUX wants
_HPUX_SOURCE defined, and Digital UNIX wants _XOPEN_SOURCE_EXTENDED
defined in order to pick up the poll.h header correctly.

A yorick package using a specifically POSIX feature should declare
_POSIX_SOURCE before any other includes.  If a specifically non-ANSI
feature is used, _POSIX_SOURCE should be undef'd after config.h but
before any system headers are included (note that pstdio.h and
pstdlib.h indirectly include system headers).
------------------------------------------------------------------------

#define USE_GETRUSAGE
-or-
#define USE_TIMES
-or-
neither

------------------------------------------------------------------------
On systems which have the BSD getrusage function, it generally provides
the most accurate CPU timer (much better than the POSIX times often).
The POSIX times function is an alternative; if neither is defined, the
timeu.c source falls back to the ANSI clock function.
------------------------------------------------------------------------

/* play/unix/timew.c- specify which wall timing function to use
 *   - gettimeofday needs <sys/time.h>
 *   - if undefined, will use ANSI C time and difftime functions */
#define USE_GETTIMEOFDAY
-or-
nothing

------------------------------------------------------------------------
The BSD gettimeofday routine is the preferred wall clock timer; it is
the one used universally by the X11 library, so you ought to get
agreement between X server times and p_wall_secs with it.  The
fallback in timew.c if USE_GETTIMEOFDAY is not defined is the ANSI C
time and difftime functions.
------------------------------------------------------------------------

nothing
-or-
#define NO_PASSWD

------------------------------------------------------------------------
The POSIX getlogin, getpwuid, and getuid functions permit expansion of
~user/... pathnames (pathnm.c).  If these functions are not present,
define NO_PASSWD and that functionality will be disabled.  This also
affects the p_getuser function (usernm.c), which falls back to the
deprecated cuserid function if NO_PASSWD is defined.
------------------------------------------------------------------------

nothing
-or-
#define USE_TIOCGPGRP_IOCTL <sys/termios.h>
-or-
#define USE_TIOCGPGRP_IOCTL <sgtty.h>

------------------------------------------------------------------------
If the POSIX tcgetpgrp function is missing (used to determine whether
the program is running as a background task in uinbg.c), define
USE_TIOCGPGRP_IOCTL as the name of the system header file which
defines the TIOCGPGRP ioctl.
------------------------------------------------------------------------

nothing
-or-
/* play/unix/dir.c- use getwd instead of POSIX getcwd */
#define USE_GETWD

------------------------------------------------------------------------
If the POSIX getcwd function is missing (used to find current working
directory in dir.c), define USE_GETWD to use getwd instead.
------------------------------------------------------------------------

nothing
-or-
#define DIRENT_HEADER <sys/dir.h>
-or-
#define DIRENT_HEADER <sys/ndir.h>
-or-
#define DIRENT_HEADER <ndir.h>

------------------------------------------------------------------------
If the POSIX dirent.h header is missing or broken, define DIRENT_HEADER
as the name of the system header file containing the directory handling
functions.  See dir.c more more.
------------------------------------------------------------------------

nothing
-or-
#define USE_SYS_POLL_H

-or-

#define USE_SELECT
-and-
nothing
-or-
#define HAVE_SYS_SELECT_H
-or none, one, or both of-
#define NO_SYS_TIME_H
#define NEED_SELECT_PROTO

------------------------------------------------------------------------
To handle multiple input sources, you need either the poll function or
the select function.  I prefer the poll interface (and select was
apparently broken on at least one IRIX system).  If <poll.h> exists,
you don't need any defines; if <sys/poll.h> exists, define
USE_SYS_POLL_H.

If poll is missing or you need to use select instead (upoll.c implements
a barebones poll in terms of select), define USE_SELECT.  In that case,
define HAVE_SYS_SELECT_H if <sys/select.h> is present; otherwise you
may need to define NO_SYS_TIME_H (you will need either <sys/time.h> or
<time.h>).  You may also need to define NEED_SELECT_PROTO.

See uevent.c and upoll.c for more.
------------------------------------------------------------------------

in config.h:
-exactly one of-
#define FPU_DIGITAL
#define FPU_AIX
#define FPU_HPUX
#define FPU_IRIX
#define FPU_SUN4
#define FPU_SOLARIS
#define FPU_UNICOS
#define FPU_ALPHA_LINUX
#define FPU_GCC_I86
#define FPU_GCC_POWERPC
#define FPU_GCC_SPARC
#define FPU_GCC_M68K
#define FPU_GCC_ARM
#define FPU_IGNORE

in config.mak:
FPELIB =
-or-
FPELIB = -lsunmath
-or-
FPELIB = -lfpe

------------------------------------------------------------------------
UNIX systems usually do not deliver SIGFPE (floating point exception
signals) by default.  The code to turn on SIGFPE delivery is highly
system dependent.  You must define exactly one of the above symbols
in order to compile fpuset.c.  The fputest.c program will tell you if
you have succeeded in turning on SIGFPE delivery (config.sh runs it).

FPU_HPUX, FPU_SUN4, and FPU_UNICOS require routines in libm (-lm).

FPU_SUN4 may require libsunmath (-lsunmath), and FPU_IRIX requires
libfpe (-lfpe).  In these two cases, the config.mak file will set the
FPELIB flag to the required loader option.  Otherwise, FPELIB will be
set to nil.
------------------------------------------------------------------------

in config.mak:

XINC =
-or-
XINC = -Ipath_to_X11/Xlib.h

-and-

XLIB =
-or-
XLIB = -Lpath_to_libX11

------------------------------------------------------------------------
The X11 headers and libraries may be hidden from the compiler without
appropriate -I and -L options, which are written into config.mak.
------------------------------------------------------------------------

All interactive numerical programs benefit from prompt delivery of
SIGFPE signals.  The processor should trap on zero divide, overflow,
or invalid operations, and give the process a chance to abort the
operation cleanly.  Testing for these conditions (which is supported
in a portable fashion by the C9X standard) is at best a poor
substitute for prompt interrupt, since it must be done in a very large
number of places in the code.  Testing on an operation by operation
basis (as would be necessary before C9X) will obviously ruin
performance of any numerically demanding program (you'd need to take
logarithms to check for overflow, for example).  Allowing huge arrays
of numbers to slowly fill wil NaN and Inf wastes computer time, and
makes debugging nearly impossible.

Every UNIX operating system and machine requires a different procedure
for setting up the hardware to trap and deliver this interrupt; the
universal default is to ignore all floating point errors.  I know how
to set up the FPU for the following platforms:

FPU_DIGITAL     DEC Alpha / Digital UNIX (FPU_ALPHA_LINUX also works?)
FPU_AIX         IBM RS6000 / AIX
FPU_HPUX        HP PA-RISC / HPUX
FPU_IRIX        SGI MIPS / IRIX
FPU_SUN4        Sun SPARC / SunOS 4
FPU_SOLARIS     Sun SPARC / Solaris (SunOS 5)
FPU_UNICOS      Cray X/YMP, J90 / UNICOS
FPU_ALPHA_LINUX DEC Alpha / Linux
FPU_GCC_I86     Intel x86 / gcc (Linux)
FPU_GCC_POWERPC IBM Power PC (RS6000?) / gcc (Linux)
FPU_GCC_SPARC   Sun SPARC / gcc (Linux or SunOS)
FPU_GCC_M68K    Motorola 680x0 / gcc (Linux or NextStep)
FPU_GCC_ARM     ARM / gcc (Linux)
FPU_IGNORE      dummy, for those few platforms with proper default
                  (NetBSD?  FreeBSD?)

If none of these works for your machine, and you can figure out what
does, please contact me at munro@icf.llnl.gov.  (I've never been able
to make Ultrix trap SIGFPE, for example.)  You can use the fputest.c
program (and Make.fpu) to test your ideas.

SIGFPE PROBLEMS
---------------

On SGI/IRIX machines, you must be extremely careful *not* to set the
TRAP_FPE environment variable, which will override anything your code
does.  The best policy there is to undefine TRAP_FPE before running
your code (do this by starting with a shell script).

If you are using gcc on a SunOS 4 machine, you may not have the
required routines for FPU_SUN4 (look in /usr/lib/libm.a; otherwise,
they are in /usr/lang/SC*/lib/libsunmath.a, which comes with Sun's
compilers).  In that case, try FPU_GCC_SPARC.

Pentium (and other x86) machines do not always deliver SIGFPE
promptly, so the signal may be delivered on a (non-faulting)
subsequent floating point instruction.  This is aggravating, but
apparently not much can be done about it.


MacOS X 10.3 (2/Feb/04)
------------

MacOS X 10.3.0, 10.3.1, and 10.3.2 (at least) shipped with a broken
libm (/usr/lib/libm.dylib).  The system functions sqrt and tanh cause
SIGFPE for every argument.  The errors are in Libm-47 in the files
sqrt.c, shchth.c, and ashachath.c (the latter is inverse hyperbolic
functions not used by yorick), which perform operations involving
infinity (FPR_inf) before they switch to a non-trapping floating point
environment.  The sqrt function in sqrt.c is unused on G5 hardware,
which selects a hardware fsqrt instruction instead of the sqrt.c code.
However, on G4 and earlier hardware, the software sqrt in sqrt.c does
generate incorrect SIGFPEs.  The only easy fix is to use FPU_IGNORE
instead of FPU_MACOSX, but that will ignore all floating point
exceptions, which is dangerous in any numerical program.

Earlier versions of setfpu.c did not reset the vx_sqrt bit in the
fp_scr register, which caused a fault loop on sqrt(any negative
value); see the comment in fpuset.c.


SIGFPE on Linux (18/May/99)
---------------

The __setfpucw function used to be available for general use; here is
its generic implementation.  Sometime in early 1999, GNU libc6
switched to making __setfpucw only available internally, forcing the
use of assembler macros in application code (see fpuset.c).

#include <fpu_control.h>

void
__setfpucw (fpu_control_t set)
{
  fpu_control_t cw;

  /* Fetch the current control word.  */
  _FPU_GETCW (cw);

  /* Preserve the reserved bits, and set the rest as the user
     specified (or the default, if the user gave zero).  */
  cw &= _FPU_RESERVED;
  cw |= set & ~_FPU_RESERVED;

  _FPU_SETCW (cw);
}

Note that the macros are not always defined -- the alpha has its own
__setfpucw which translates i386 bits.  In all other cases, when they
are defined, the bit macros are all different.

More recently, Linux 2.6 kernels apparently cause fputest.c to fail,
although yorick itself still works.  If you figure out why, please
contact me at munro1 at llnl.gov.

Alpha Linux
-----------

Alpha Linux implements the Digital UNIX (now Tru64)
ieee_set_fp_control() function, although it puts the fpu.h header in a
different place than Digital (now Compaq now HP).

The alpha hardware cannot handle denormals, infinity, or other IEEE
constructs.  In particular, denormals cause the hardware to trap.  You
can let the Linux kernel (or Tru64 kernel) handle these exceptions and
fill in the IEEE-compliant value by compiling every module with the
-mieee option to GCC.  This is obviously slow if you have lots of
underflows (as with many FFTs).  Furthermore, -mieee inhibits some
types of optimizations which would interfere with the kernel math
emulator's ability to compute the IEEE-compliant result.

Unfortunately, the Linux libc and libm libraries produce denormals,
for example exp(-720), which are not numbers unless you have compiled
with -mieee.  Hence, by default, the C expressions exp(-700)+0.0 and
exp(-800)+0.0 work fine, but exp(-720)+0.0 causes a SIGFPE.  The
problem is that the alpha hardware does not support denormals, but
exp() returns them.  The best workaround is to use the Compaq math
library if you can get it.  The libc also contains routines like scanf
which will return denormals (hence the yorick read() function can
produce them).  These are rare enough that you probably don't care
about trying to replace libc.

If you don't have access to a correct libm, you can put
       CC=gcc -mieee
in the top level Make.cfg file.  This will cause a significant
performance penalty, but at least exp() won't randomly trigger SIGFPE.
If you do have a good libm, put it in the MATHLIB= line in Make.cfg.

IRIX
----

Apparently handle_sigfpes (see manpage), as loaded from the libfpe
library, is the preferred way to get control after SIGFPE.  The
fpsetmask function can masquerade as a FPU_SOLARIS, but that code
fails for some reason in full yorick, despite passing the fputest.c
suite.  When floating point exceptions are masked, IRIX delivers
SIGTRAP (causing a core dump) on integer divide by zero (gag me with a
spoon).  When floating point exceptions are being delivered, integer
divide by zero generates SIGFPE, but only on 32-bit platforms.

An additional headache is that libm does not generate SIGFPE on
overflow.  An alternative library libmx is available, but requires a
matherr function.

Notes on how to implement plib over gtk
---------------------------------------

(1) gtk_timeout_add (gtkmain.c) uses g_timeout_add (glib gmain.c),
which gets the time as of the call and adds the specified interval as
the first select timeout.  Hence, p_timer/p_idler can be implemented
neatly like this:

As far as gtk is concerned, the application has a single routine that
alternates between being called as an idler: Its data context tells
whether it has been invoked as a timeout or an idler.  If it is a
timeout, then services the timeout; if it is an idler, it calls the
application on_idle (and remembers if it wants to be called again).
In either case, before returning, it calls the application on_poll
function.  If app_on_poll returns >=0, it calls gtk_timeout_add to add
itself as a timeout with the specified interval, then returns 0 to
remove its previous incarnation (as either a timeout or idler).
Otherwise, it returns 0 unless app_on_idle was called and returned 0.

Unclear: need to know whether gtk calls its idler over and over
without waiting for new input between idler calls (seems most likely),
or whether it calls an idler only once and waits for new input before
calling it again.  In the former case, really just want a sequence of
timeouts with 0 for immediate recall, or HUGE to wait forever.