alaffin | 7ce3a79 | 2000-07-27 16:59:03 +0000 | [diff] [blame^] | 1 | .\" |
| 2 | .\" $Id: random_range_seed.3,v 1.1 2000/07/27 16:59:03 alaffin Exp $ |
| 3 | .\" |
| 4 | .\" Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved. |
| 5 | .\" |
| 6 | .\" This program is free software; you can redistribute it and/or modify it |
| 7 | .\" under the terms of version 2 of the GNU General Public License as |
| 8 | .\" published by the Free Software Foundation. |
| 9 | .\" |
| 10 | .\" This program is distributed in the hope that it would be useful, but |
| 11 | .\" WITHOUT ANY WARRANTY; without even the implied warranty of |
| 12 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. |
| 13 | .\" |
| 14 | .\" Further, this software is distributed without any warranty that it is |
| 15 | .\" free of the rightful claim of any third person regarding infringement |
| 16 | .\" or the like. Any license provided herein, whether implied or |
| 17 | .\" otherwise, applies only to this software file. Patent licenses, if |
| 18 | .\" any, provided herein do not apply to combinations of this program with |
| 19 | .\" other software, or any other product whatsoever. |
| 20 | .\" |
| 21 | .\" You should have received a copy of the GNU General Public License along |
| 22 | .\" with this program; if not, write the Free Software Foundation, Inc., 59 |
| 23 | .\" Temple Place - Suite 330, Boston MA 02111-1307, USA. |
| 24 | .\" |
| 25 | .\" Contact information: Silicon Graphics, Inc., 1600 Amphitheatre Pkwy, |
| 26 | .\" Mountain View, CA 94043, or: |
| 27 | .\" |
| 28 | .\" http://www.sgi.com |
| 29 | .\" |
| 30 | .\" For further information regarding this notice, see: |
| 31 | .\" |
| 32 | .\" http://oss.sgi.com/projects/GenInfo/NoticeExplan/ |
| 33 | .\" |
| 34 | .TH random_range 3 07/25/2000 "Linux Test Project" |
| 35 | .SH NAME |
| 36 | random_range \- a set of routines for dealing with integer ranges, and random numbers in a range |
| 37 | .SH SYNOPSIS |
| 38 | .nf |
| 39 | void random_range_seed(int seed) |
| 40 | long random_range(int min, int max, int mult, char **errp) |
| 41 | long random_rangel(long min, long max, long mult, char **errp) |
| 42 | long long random_rangell(long long min, long long max, |
| 43 | long long mult, char **errp) |
| 44 | long random_bit(long mask) |
| 45 | .fi |
| 46 | .SH DESCRIPTION |
| 47 | This is a set of routines for parsing numeric ranges, and choosing random |
| 48 | numbers from a range. |
| 49 | |
| 50 | random_range() chooses a random number in the range min-max (inclusive) which |
| 51 | is a multiple of mult. min and max may be any integer, but mult must be |
| 52 | a positive integer greater than 0. errp is a char ** which is used to detect |
| 53 | error conditions. If errp is not NULL, *errp will be set to point to an |
| 54 | error message. If errp is NULL, error conditions cannot be detected by the |
| 55 | caller. If mult is 1 (the most common case), there are no possible error |
| 56 | conditions, and the return value is guaranteed to be valid. |
| 57 | |
| 58 | random_range_seed() sets the random number generator seed to the specified |
| 59 | value. |
| 60 | |
| 61 | random_bit() will return a randomly selected single bit bitmask from the bits |
| 62 | set in mask. The bit is randomly chosen using random_range(). |
| 63 | If mask is zero, zero is returned. |
| 64 | |
| 65 | random_range() functions uses lrand48() internally. If the range is bigger |
| 66 | than will fit in a 32 bit long (2G), lrand48() with a |
| 67 | a internal recursive algorithm to produce a random number. |
| 68 | |
| 69 | .SH EXAMPLES |
| 70 | \fC |
| 71 | .ta .25i +.25i +.25i +.25i |
| 72 | .nf |
| 73 | #include <stdio.h> |
| 74 | |
| 75 | main(argc, argv) |
| 76 | int argc; |
| 77 | char **argv; |
| 78 | { |
| 79 | int r; |
| 80 | char *errp; |
| 81 | extern void random_range_seed(); |
| 82 | extern long random_range(); |
| 83 | |
| 84 | random_range_seed(getpid()); |
| 85 | |
| 86 | r = random_range(atoi(argv[1]), atoi(argv[2]), atoi(argv[3]), &errp); |
| 87 | if (errp == NULL) { |
| 88 | fprintf(stderr, "random_range failed: %s\n", errp); |
| 89 | exit(1); |
| 90 | } else { |
| 91 | printf("%d\n", r); |
| 92 | } |
| 93 | |
| 94 | exit(0); |
| 95 | } |
| 96 | \fP |
| 97 | .fi |
| 98 | |
| 99 | .SH "SEE ALSO" |
| 100 | lrand48(3c) |
| 101 | .SH DIAGNOSTICS |
| 102 | If random_range() fails, errp will point to NULL, and the return value will be |
| 103 | undefined. If mult is 1, there are no possible error conditions, so the return |
| 104 | value is always valid in this case. |
| 105 | |
| 106 | .SH BUGS |
| 107 | On CRAY systems, random_range(), random_rangel(), random_rangell() |
| 108 | all have the 64 bit limit since int, long and long long are always 64 bits. |
| 109 | |
| 110 | On IRIX systems, random_range() can only produce a 32 number. |
| 111 | random_rangel() when compiled as a 32 bit object is still limited to 32 bit |
| 112 | number. random_rangell() can be used to return a value bigger than 32 bits |
| 113 | even when compiled as a 32 bit object. |
| 114 | |