libdieharder(3) 					     Library Functions Manual						   libdieharder(3)

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  tem-
       plates.

       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 sug-
       gested 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  FIT-
       NESS,  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  appli-
       cations),  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  responsi-
       bility  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)