Autah-cs.208
net.sources
utcsrgv!utzoo!decvax!ucbvax!mhtsa!harpo!utah-cs!thomas
Mon Feb 22 10:07:23 1982
scanargs doc
TH SCANARGS 3 "AMPEX CORP."
SH NAME
scanargs, qscanargs - formatted conversion from command argument list
SH SYNOPSIS
B "#include <STDIO.H>"
PP
B "scanargs(argc, argv, format"
[, pointer]...
B )
br
B "int argc;"
br
B "char *argv[];"
br
B "char *format;"
SH DESCRIPTION
I Scanargs
reads
I argc
arguments from an argument list pointed to by
I argv.
It converts the argument list according to the format string,
and stores the results of the conversions in its parameters.
I Qscanargs
is a smaller and slightly less powerful version.
PP
Scanargs expects as its parameters an argument count
I argc,
a pointer to an argument list
I argv
(see exec(2)), a control string
I format,
described below, and a set of
I pointer
arguments indicating where the converted output should be stored.
PP
The control string contains specifications, which are used to direct
interpretation of argument sequences.  It consists of
the necessary information to describe both an acceptable
syntax for the argument list, and the expected meaning of each argument.
PP
If the scanning fails it will print a cryptic
message telling why it failed, and generate a
I usage
message from the control string.
PP
The control string is composed of two parts:
PP
B NAME:\ \
The first characters in the string are assumed to be the calling
name of the program being executed. This is used for generation of
usage messages.
PP
B CONVERSIONS:\ \
Following the name, an optional list of conversion specifications is given,
with separating spaces.  The structure of a conversion specification:
RS
PP
B "label_key_conversion"
RE
PP
consists of a
I label
which is a string of non-space characters describing the acceptable
argument, a
I key
which may be either of
TP 4
B %
The argument is optional. Its absence is ignored.
TP 4
B !
A required argument. If absent, an error return ensues.
PP
and a
I conversion
character which indicates the interpretation of the argument; the corresponding
pointer parameter must be of a restricted type.
PP
The following conversion characters are supported:
TP 4
B d
a decimal integer is expected; the corresponding parameter should be an
I int
pointer.
TP 4
B o
an octal integer is expected; the corresponding parameter should be an
I int
pointer.
TP 4
B f
a floating point number is expected; the corresponding parameter should
be a pointer to a
I float.
Not available in
I qscanargs.
TP 4
B "x X d D o O f F"
all numeric types supported by
I scanf(3S)
are legal in
I scanargs;
I qscanargs
supports all but
B f
and
B F
formats, and avoids including the large size of the
I scanf
routine.
TP 4
B s
a character string is expected; the corresponding parameter should be a
I "pointer to a char pointer."
TP 4
B -
a single character flag is expected; the corresponding parameter should
be an
I int
pointer.  The occurrence of a
B -
followed by the character specified in the label
will cause the setting of the least significant bit of the integer pointed to
by the corresponding parameter.  The label may consist of up to sixteen option
characters, in which case one of the bits of the integer is independantly
set to reflect which one of the flags was present. (The right most character
corresponds to the LSB of the integer)  Only one option may be chosen from
each conversion specification.  The bits which are not set will remain in
their previous state.
The
B -
may be followed immediately by more label_key_conversion specifications.
These should not be separated by blanks and should not contain any
B -
specifications.  They will be processed only if the flag argument is scanned.
This allows optional specification of parameters corresponding to a flag
(e.g. -f file).
PP
The scanner will process the control string from left to right,
and where there are multiple conversions of the same type, they will
be assigned one to one with their order of occurrence in the argument list.
Where the order of the arguments is not ambiguous in the control string,
they may occur in any order in the argument list. (ie. A decimal number
will not be confused with a flag, but may
be confused with an octal number or another decimal number. So if an
octal and a decimal number are to be arguments, their order will determine
their conversion, while a decimal number and a flag as arguments may occur
in any order and still be converted correctly.)
PP
An argument list that does not match the requirements of the control
string will cause the printing of a short message telling why, and
a message telling what the correct usage is.
This usage is gleaned from the control string, and the labels are used
directly.  The labels should be both terse and descriptive!
bp
PP
The
I scanargs
function returns 1 when the argument list matched the requirements
of the control string, and returns 0 if there was a failure.
Parameters for any conversions not matched are left untouched.
br
For example, the call
RS
PP
int i; double x; char *name;
br
scanargs(argc, argv, "program decimal%d floating%F file%s"
in 15
, &i, &x, &name );
RE
PP
in a C program executed by the shell command
RS
PP
% program 10 3.5397 inputfile
RE
PP
will assign to
I i
the value 10,
I x
the value 3.5397, and
I name
will point to the string "inputfile".
PP
If the program was executed by the shell command
RS
PP
% program  3.4 5.7 inputfile
RE
PP
the following would be printed on the standard error:
RS
PP
extra arguments not processed
br
usage : program [decimal] [floating] [file]
RE
PP
because 3.4 matches the type of 'floating' and inputfile matches
the type of 'file', leaving 5.7 unmatched.
br
This call could be used for the
I diff
command
RS
PP
int blanks; int flags; char *file1; char *file2;
br
scanargs(argc, argv, "diff b%- efh%- file1!s file2!s"
in 15
, &blanks, &flags, &file1, &file2 );
RE
PP
and would only allow one of either
B "-e -f"
or
B -h
to be chosen optionally, with
B -b
as an independent option.
B File1
and
B file2
are both required.
The usage message for this version of
I diff
would be
RS
PP
usage : diff [-b] -{efh} file1 file2
RE

This call could be used for a simplified version of the
I sed
command
RS
PP
int efile; int noprint; char *script; char *file1; char *file2;
br
scanargs(argc, argv, "sed n%- script%s f%-editfile!s file%s"
in 15
, &noprint, &script, &efile, &file1, &file2 );
RE
PP
If the
B -f
option is specified, then a file name must be given as the next string
argument.
The usage message for this version of
I sed
would be
RS
PP
usage : sed [-n] [script] [-f editfile] [file]
RE

SH SEE ALSO
exec(2), scanf(3S)
SH DIAGNOSTICS
By its nature a call to scanargs defines a syntax
which may be ambiguous, and although the results may be surprising,
they are quite predictable.
SH AUTHOR
Gary Newman - Ampex Corporation
Heavily modified by Spencer W. Thomas - University of Utah
SH BUGS
A flag argument at the end of the format string should be followed by
a space.  Otherwise the routine which prints the usage message sometimes
misses the end of the format string.  Arguments conditionalized on a flag
are not handled properly.  Someday this will be fixed.

-----------------------------------------------------------------
gopher://quux.org/ conversion by John Goerzen <[email protected]>
of http://communication.ucsd.edu/A-News/


This Usenet Oldnews Archive
article may be copied and distributed freely, provided:

1. There is no money collected for the text(s) of the articles.

2. The following notice remains appended to each copy:

The Usenet Oldnews Archive: Compilation Copyright (C) 1981, 1996
Bruce Jones, Henry Spencer, David Wiseman.

You are viewing proxied material from gopher.quux.org. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.