You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
170 lines
5.3 KiB
170 lines
5.3 KiB
.\"
|
|
.\" $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.,
|
|
.\" 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 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),
|
|
bytes_by_prefix(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().
|