--- a
+++ b/doc/man3/random_range_seed.3
@@ -0,0 +1,114 @@
+.\"
+.\" $Id: random_range_seed.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., 59
+.\" Temple Place - Suite 330, Boston MA 02111-1307, 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.
+