--- a
+++ b/doc/man3/parse_ranges.3
@@ -0,0 +1,169 @@
+.\"
+.\" $Id: parse_ranges.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 PARSE_RANGES 3 07/25/2000 "Linux Test Project"
+.SH NAME
+parse_ranges \- function to parse a string formatted like 'min:max:mult,...'
+.SH SYNOPSIS
+.nf
+int parse_ranges(char *str, int defmin, int defmax, int defmult, int (*parse_func)(), char **rangeptr, char **errptr);
+int range_min(char *rbuf, int r);
+int range_max(char *rbuf, int r);
+int range_mult(char *rbuf, int r);
+.fi
+.SH DESCRIPTION
+parse_ranges() is a function to parse a comma-separated list of range
+tokens each having the following form:
+.SP
+.nf
+		num
+	or
+		min:max[:mult]
+.fi
+
+any of the values may be blank (ie. min::mult, :max, etc.) and default
+values for missing arguments may be supplied by the caller.
+
+The special first form is short hand for 'num:num'.
+
+After parsing the string, the ranges are put into an array of integers,
+which is malloc'd by the routine.  The min, max, and mult entries of each
+range can be extracted from the array using the range_min(), range_max(),
+and range_mult() functions.
+
+If \fIrange_ptr\fP is not NULL, and parse_ranges() successfully parses the
+range string (ie. does not return -1), *range_ptr will point to space
+malloc'd by parse_ranges().  The user may free this space by calling free().
+
+parse_ranges() parameters are:
+.SP
+.TP 1i
+\fIstr\fP
+The string to parse - assumed to be a comma-separated
+list of tokens having the above format.
+.TP 1i
+\fIdefmin\fP
+default value to plug in for min, if it is missing
+.TP 1i
+\fIdefmax\fP
+default value to plug in for max, if it is missing
+.TP 1i
+\fIdefmult\fP
+default value to plug in for mult, if missing
+.TP 1i
+\fIparse_func\fP
+A user-supplied function pointer, which parse_ranges()
+can call to parse the min, max, and mult strings.  This
+allows for customized number formats.  The function
+MUST have the following prototype:
+.SP
+.nf
+	int parse_func(char *str, int *val)
+.fi
+.SP
+The function should return -1 if str cannot be parsed
+into an integer, or >= 0 if it was successfully
+parsed.  The resulting integer will be stored in
+*val.  If parse_func is NULL, parse_ranges will parse
+the tokens in a manner consistent with the the sscanf %i format.
+.TP 1i
+\fIrange_ptr\fP
+A user-supplied char **, which will be set to point
+at malloc'd space which holds the parsed range
+values.   If range_ptr is NULL, parse_ranges() just
+parses the string.  The data returned in range_ptr
+should not be processed directly - use the functions
+range_min(), range_max(), and range_mult() to access
+data for a given range.
+.TP 1i
+\fIerrptr\fP
+user-supplied char ** which can be set to point to a
+static error string.  If errptr is NULL, it is ignored.
+.in -1i
+
+.SP
+range_min(), range_max(), and range_mult() parameters are:
+.SP
+.SP
+.TP 1i
+\fIrbuf\fP
+An array of ranges set up by parse_ranges().
+.TP 1i
+\fIr\fP
+The range number to extract information from.  Must be an integer >= 0 and
+< the number of ranges returned by parse_ranges().
+.in -1i
+
+.SH EXAMPLES
+\fC
+.ta .25i +.25i +.25i +.25i
+.nf
+/*
+ * simple example to take a list of ranges on the cmdline (in argv[1]), and
+ * print a random number from within that range.
+ */
+
+#include <stdio.h>
+
+main()
+{
+	extern int	parse_ranges(), range_min(), range_max(), range_mult();
+	extern long	random_range(), random_range_seed();
+	int		min, max, mult, nranges;
+	char		*ep, *rp;
+
+	random_range_seed(getpid());
+	if ((nranges = parse_ranges(argv[1], 0, INT_MAX, 1, NULL, &rp, &ep)) < 0) {
+		fprintf(stderr, "parse_ranges() failed:  %s\n", ep);
+		exit(1);
+	}
+
+	range = random_range(0, nranges-1, 1);
+	min = range_min(rp, range);
+	max = range_max(rp, range);
+	mult = range_mult(rp, range);
+
+	fprintf("%d\\n", random_range(min, max-1, mult));
+	exit(0);
+}
+\fP
+.DT
+.SH "SEE ALSO"
+random_range(3),
+random_range_seed(3),
+str_to_bytes(3).
+.SH DIAGNOSTICS
+parse_ranges() returns -1 on error or the number of ranges parsed.  No space
+will be malloc'd if parse_ranges() fails.  Error
+messages are passed back through the errptr parameter.  There are no error
+conditions for range_min(), range_max(), or range_mult().