random_range.3

.\"
.\" $Id: random_range.3,v 1.1 2000/07/27 16:59:03 alaffin Exp $
.\"
.\" Copyright (c) 2000 Silicon Graphics, Inc.  All Rights Reserved.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of version 2 of the GNU General Public License as
.\" published by the Free Software Foundation.
.\"
.\" This program is distributed in the hope that it would be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
.\"
.\" Further, this software is distributed without any warranty that it is
.\" free of the rightful claim of any third person regarding infringement
.\" or the like.  Any license provided herein, whether implied or
.\" otherwise, applies only to this software file.  Patent licenses, if
.\" any, provided herein do not apply to combinations of this program with
.\" other software, or any other product whatsoever.
.\"
.\" You should have received a copy of the GNU General Public License along
.\" with this program; if not, write the Free Software Foundation, Inc.,
.\" 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
.\"
.\" Contact information: Silicon Graphics, Inc., 1600 Amphitheatre Pkwy,
.\" Mountain View, CA  94043, or:
.\"
.\" http://www.sgi.com
.\"
.\" For further information regarding this notice, see:
.\"
.\" http://oss.sgi.com/projects/GenInfo/NoticeExplan/
.\"
.TH random_range 3 07/25/2000 "Linux Test Project"
.SH NAME
random_range \- a set of routines for dealing with integer ranges, and random numbers in a range
.SH SYNOPSIS
.nf
void random_range_seed(int seed)
long random_range(int min, int max, int mult, char **errp)
long random_rangel(long min, long max, long mult, char **errp)
long long random_rangell(long long min, long long max,
		         long long mult, char **errp)
long random_bit(long mask)
.fi
.SH DESCRIPTION
This is a set of routines for parsing numeric ranges, and choosing random
numbers from a range.

random_range() chooses a random number in the range min-max (inclusive) which
is a multiple of mult.  min and max may be any integer, but mult must be
a positive integer greater than 0.  errp is a char ** which is used to detect
error conditions.  If errp is not NULL, *errp will be set to point to an
error message.  If errp is NULL, error conditions cannot be detected by the
caller.  If mult is 1 (the most common case), there are no possible error
conditions, and the return value is guaranteed to be valid.

random_range_seed() sets the random number generator seed to the specified
value.

random_bit() will return a randomly selected single bit bitmask from the bits
set in mask.  The bit is randomly chosen using random_range().
If mask is zero, zero is returned.

random_range() functions uses lrand48() internally.  If the range is bigger
than will fit in a 32 bit long (2G), lrand48() with a
a internal recursive algorithm to produce a random number.

.SH EXAMPLES
\fC
.ta .25i +.25i +.25i +.25i
.nf
#include <stdio.h>

main(argc, argv)
int	argc;
char	**argv;
{
	int		r;
	char		*errp;
	extern void	random_range_seed();
	extern long	random_range();

	random_range_seed(getpid());

	r = random_range(atoi(argv[1]), atoi(argv[2]), atoi(argv[3]), &errp);
	if (errp == NULL) {
		fprintf(stderr, "random_range failed:  %s\n", errp);
		exit(1);
	} else {
		printf("%d\n", r);
	}

	exit(0);
}
\fP
.fi

.SH "SEE ALSO"
lrand48(3c)
.SH DIAGNOSTICS
If random_range() fails, errp will point to NULL, and the return value will be
undefined.  If mult is 1, there are no possible error conditions, so the return
value is always valid in this case.

.SH BUGS
On CRAY systems, random_range(), random_rangel(), random_rangell()
all have the 64 bit limit since int, long and long long are always 64 bits.

On IRIX systems, random_range() can only produce a 32 number.
random_rangel() when compiled as a 32 bit object is still limited to 32 bit
number.  random_rangell() can be used to return a value bigger than 32 bits
even when compiled as a 32 bit object.