I.  Introduction
    ------------

    This directory comprises a test suite which tests a large part of
    the C library.  It was originally written by Cygnus for the FDLIBM
    distribution (which is the base of the DJGPP libm math library,
    see the sources in src/libm/math directory inside the djlsrNNN.zip
    distribution).  Although the primary goal of this test suite is to
    test the math functions, it also tests many other standard library
    functions which have some bearing to manipulating numbers.  In
    particular, the suite includes an extensive test of the `printf'
    family of functions, and other functions, such as `strtod' and
    `ecvt', that are used for converting numbers to and from strings.

    The original test suite needed a lot of work to make it useful.
    For example, many of the test vectors (arrays of arguments to
    functions and expected results) were incorrect, and some low-level
    functionality on which the tests depended was unavailable in
    DJGPP.  Most of the hard work of making this suite an accurate and
    reliable testing tool for the DJGPP library was done by
    K.B. Williams <Kbwms@aol.com>, who also wrote the test vector
    generating programs in the `tgen' subdirectory.  Eli Zaretskii
    <eliz@is.elta.co.il> corrected the `printf' test vectors, adapted
    the sources to DJGPP, and wrote the top-level makefile for the
    test suite.


II. What's in here
    --------------

    The top-level directory, `tests/cygnus', includes a makefile,
    sources of the test program, and the test vectors (these are the
    files whose names end with `_vec.c').  These are compiled and
    linked into a single program called `mtest.exe', which, when run,
    produces a test report on its standard output.  The program is
    linked against the libm.a library, so the test program by default
    tests the versions of math functions in libm.a only; the versions
    of math functions inside libc.a are NOT tested.  However, some
    libc.a functions, like the `printf' family mentioned in the first
    paragraph of the introduction above, ARE tested.

    The subdirectory `tgen' contains programs written by K.B. Williams
    that generate the *_vec.c test vectors.  The programs are written
    in C++ and are linked with a library of extended-precision math
    functions in the `qfloat' subdirectory.  The qfloat library was
    written by Stephen L. Moshier.  Use of extended-precision math
    functions to generate the test cases ensures that the expected
    results are accurate to the last bit of the mantissa.  See the
    README files in `tgen' and `tgen/qfloat', for more details.


III.How to run the tests
    --------------------

    To run the tests, chdir to the tests/cygnus directory and say
    "make".  This builds the test program and runs it.  The run
    results are written to the file `mtest.results', for later
    examination, and a one-line summary of the test is printed on the
    standard error stream.

    If you wish to run the tests on alternate libraries, define the
    LIBS variable on the Make command line.  For example, the command
    "make LIBS='-lc -lm'" will build a test suite where math functions
    from libc.a are tested (except those functions which only exist in
    libm.a).

    Since some library functions are not accurate to the last bit,
    some tests will trigger inaccuracy reports.  The test suite is set
    up so that it requires 62 accurate bits for functions that return
    a double, and 34 bits for the float variants.  Some functions
    aren't accurate enough to pass these requirements for some
    arguments.  In particular, many results of Bessel functions `j0',
    `yn', etc. are only accurate to 61 bits, and many float versions
    only return 33 accurate bits for some arguments.  The distribution
    includes a file `standard.results' with the results of running the
    test suite with the latest DJGPP libraries.  By comparing
    `mtest.results' with this file you could find out which messages
    are ``normal'' and which indicate problems.

    Two additional files with results of running the test suite are
    provided: the file `std-v202.results' was produced with the
    libraries of DJGPP v2.02, the version where this test suite was
    first introduced; and std-libc.results was produced with a test
    suite that used the math functions from libc.a introduced with
    DJGPP v2.03 (it was compiled with "make LIBS='-lc -lm'").

    Note that, as the file `std-libc.results' shows, math functions
    from libc.a behave differently for abnormal arguments, and use a
    different bit pattern for NaN.  The behavior of functions from
    libc.a is documented in the library reference for each function.