Help save net neutrality! Learn more.

Diff of /doc/man3/parse_ranges.3 [000000] .. [7ce3a7]  Maximize  Restore

Switch to side-by-side view

--- 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
+.\" 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:
+.\" For further information regarding this notice, see: 
+.TH PARSE_RANGES 3 07/25/2000 "Linux Test Project"
+parse_ranges \- function to parse a string formatted like 'min:max:mult,...'
+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);
+parse_ranges() is a function to parse a comma-separated list of range
+tokens each having the following form:
+		num
+	or
+		min:max[:mult]
+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:
+.TP 1i
+The string to parse - assumed to be a comma-separated
+list of tokens having the above format.
+.TP 1i
+default value to plug in for min, if it is missing
+.TP 1i
+default value to plug in for max, if it is missing
+.TP 1i
+default value to plug in for mult, if missing
+.TP 1i
+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:
+	int parse_func(char *str, int *val)
+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
+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
+user-supplied char ** which can be set to point to a
+static error string.  If errptr is NULL, it is ignored. -1i
+range_min(), range_max(), and range_mult() parameters are:
+.TP 1i
+An array of ranges set up by parse_ranges().
+.TP 1i
+The range number to extract information from.  Must be an integer >= 0 and
+< the number of ranges returned by parse_ranges(). -1i
+.ta .25i +.25i +.25i +.25i
+ * 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>
+	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);
+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().