NAME

       libdieharder - A testing and benchmarking library for random number generators

SYNOPSIS

       #include dieharder.h

       void run_user_template()
       {

       Test **user_template_test;
       /*
        * Create the test
        */
       user_template_test = create_test(&user_template_dtest,tsamples,psamples,&user_template);

       /*
        * Set any GLOBAL data used by the test.
        */
       user_template_lag = (int)x_user;

       /*
        * Show the standard test header
        */
       show_test_header(&user_template_dtest,user_template_test);

       /*
        * Call the test
        */
       std_test(&user_template_dtest,user_template_test);

       /*
        * This almost certainly belongs in the show_test_results section,
        * possibly with additional conditionals rejecting test results involving
        * rewinds, period.
        */
       if(strncmp(
         printf( # %u rands were used in this test0,file_input_get_rtot(rng));"
         printf( # The file %s was rewound %u times0,gsl_rng_name(rng),file_input_get_rewind_cnt(rng));"
       }

       /*
        * Show standard test results
        */ .
       show_test_results(&user_template_dtest,user_template_test);

       }

DESCRIPTION

       libdieharder

       The  libdieharder  library  provides  an  API to user interface programs wishing to call dieharder tests.
       Commands are defined for creating tests, initializing the tests  and  running  the  tests.   Showing  the
       results is of course the responsibility of the UI.

       libdieharder  also  wraps  certain  additional  random  number  generators  so  that  they can be tested.
       libdieharder can be default test all the random number generators in  the  Gnu  Scientific  Library  plus
       these additional generators (which include "generators" for reading in numbers from a file).

       libdieharder  is  extensible.   It  is  fairly  easy  to  add  additional test "objects" or random number
       generators using existing sources as templates.

       The API will be documented in more detail as the project approaches completion.  In the meantime,  it  is
       strongly  recommended  that users wishing to call the library use the source of the dieharder tty UI as a
       template and list of all currently supported objects, as  this  is  the  primary  libdieharder  debugging
       vehicle in addition to being the current "standard" application of the library.

PUBLICATION RULES

       libdieharder is entirely original code and can be modified and used at will by any user, provided that:

         a)  The  original copyright notices are maintained and that the source, including all modifications, is
       made publically available at the time of any derived publication.  This is open source software according
       to the precepts and spirit of the Gnu Public License.  See the accompanying file COPYING, which also must
       accompany any redistribution.

         b) The author of the code (Robert G. Brown) is appropriately acknowledged and referenced in any derived
       publication.  It is strongly suggested that George Marsaglia  and  the  Diehard  suite  and  the  various
       authors  of  the  Statistical  Test Suite be similarly acknowledged, although this suite shares no actual
       code with these random number test suites.

         c) Full responsibility for the accuracy, suitability, and effectiveness of the program rests  with  the
       users and/or modifiers.  As is clearly stated in the accompanying copyright.h:

       THE  COPYRIGHT  HOLDERS  DISCLAIM  ALL  WARRANTIES  WITH  REGARD  TO THIS SOFTWARE, INCLUDING ALL IMPLIED
       WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL THE COPYRIGHT  HOLDERS  BE  LIABLE  FOR  ANY
       SPECIAL,  INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
       PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,  ARISING  OUT  OF  OR  IN
       CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

ACKNOWLEDGEMENTS

       The  author of this suite gratefully acknowledges George Marsaglia (the author of the diehard test suite)
       and the various authors of NIST Special Publication 800-22 (which describes the  Statistical  Test  Suite
       for testing pseudorandom number generators for cryptographic applications), for excellent descriptions of
       the  tests  therein.   These  descriptions  enabled  this  suite  to be developed with a clean copyright,
       licensable under the GPL.

       The author also wishes to reiterate that the academic correctness and accuracy of the  implementation  of
       these tests is his sole responsibility and not that of the authors of the Diehard or STS suites.  This is
       especially true where he has seen fit to modify those tests from their strict original descriptions.

COPYRIGHT

       GPL  2b;  see  the  file  COPYING that accompanies the source of this program.  This is the "standard Gnu
       General Public License version 2 or  any  later  version",  with  the  one  minor  (humorous)  "Beverage"
       modification  listed  below.   Note  that this modification is probably not legally defensible and can be
       followed really pretty much according to the honor rule.

       As to my personal preferences in beverages, red wine is great, beer  is  delightful,  and  Coca  Cola  or
       coffee  or  tea  or  even  milk  acceptable  to those who for religious or personal reasons wish to avoid
       stressing my liver.

       The Beverage Modification to the GPL:

       Any satisfied user of this software shall, upon meeting the primary author(s) of this  software  for  the
       first  time  under  the  appropriate  circumstances,  offer  to  buy him or her or them a beverage.  This
       beverage may or may not be alcoholic, depending on the personal ethical and moral views of  the  offerer.
       The  beverage  cost  need  not  exceed  one  U.S.  dollar  (although  it certainly may at the whim of the
       offerer:-) and may be accepted or declined with no further obligation on the part of the offerer.  It  is
       not necessary to repeat the offer after the first meeting, but it can't hurt...

libdieharder                             Copyright 2006 Robert G. Brown                          libdieharder(3)