ARGSCAN(3C) COMMAND REFERENCE ARGSCAN(3C)
NAME
argscan, argsbad - formatted conversion of command arguments
SYNOPSIS
int
argscan(argc, argv, format [, pointer]... )
int argc;
char *argv[];
char *format;
argsbad(error)
char *error
DESCRIPTION
Argscan converts the given argument list according to the
specified format, removing converted arguments from the list
and storing the results of the conversions in the locations
provided. If successful, argscan returns the number of
arguments remaining in the list (excluding argv[0]);
otherwise, it will return a -1 after printing messages
describing the error encountered and the correct usage of
the calling program.
Argscan expects as its parameters an argument count argc, a
pointer to an argument list argv (see execve(2)), a control
string format, described below, and a set of pointer
arguments indicating where the converted arguments should be
stored.
The format string consists of a set of fields and comments
separated by spaces or tabs. Each comment is a string not
containing percent (%) or exclamation (!) and is printed ver
batum in the usage message. It does not affect argument
conversion. Each field describes the format of an
acceptable argument (or arguments) and has the following
structure:
key conversion flag(s) whitespace fieldname
Key may be either of:
% Means the argument is optional -- its absence is
ignored.
! Indicates a required argument -- if absent, an error
return ensues.
Conversion is a single character which specifies the type of
argument expected; the corresponding pointer parameter(s)
must be of the appropriate type.
Printed 3/13/89 1
ARGSCAN(3C) COMMAND REFERENCE ARGSCAN(3C)
Flag(s) consists of the alphabetic character(s) from a
command argument acceptable under this field.
Whitespace is any number of blanks and tabs. It separates
flag(s) from fieldname.
Fieldname is any string not containing blank, tab, percent
(%), or exclamation (!). It is a mnemonic for this field
and will appear in the usage message generated from this
format string.
The following conversion characters are supported:
s A character string is expected in the command arguments;
the corresponding parameter should be a pointer to a char
pointer. If such a string is found, the char pointer will
be set to the address of the string. The flag(s) part of
this field must be empty.
- A dash (-) followed by one and only one of the characters
in flag(s) is expected in the command arguments; the
corresponding parameter should be an int pointer. Each
bit of the integer pointed to corresponds to one
character in flag(s), the leftmost character
corresponding to the integer's least significant bit.
When processed, only the bit corresponding to the flag
specified is set; none of the other bits of the integer
are modified. Whitespace and fieldname must be empty.
+ A dash (-) followed by the single character in flag(s)
followed in the next argument by an unsigned decimal
string is expected in the command arguments; the
corresponding parameters should be two int pointers. If
the proper information appears in the command arguments,
the first integer will be set to 1 and the second to the
converted decimal number; otherwise, neither integer is
modified.
a The command arguments are expected to contain the same
information as +, but a character string, rather than a
decimal number, is expected; the corresponding parameters
should be an int pointer and a pointer to a char pointer.
If the proper information appears in the command
arguments, the integer is set to 1 and the char pointer
is set to the address of the string; otherwise, neither
parameter is changed.
The scanner will process the format string from left to
right, searching for command arguments that match the
specified fields.
Printed 3/13/89 2
ARGSCAN(3C) COMMAND REFERENCE ARGSCAN(3C)
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
fieldnames are used directly. The fieldnames should be both
terse and descriptive.
Consider the following example of a call to argscan for the
diff command:
int blanks; int flags; char *filename1; char *filename2;
argscan(argc, argv, "%-b !-efh !s filename1 !s filename2",
&blanks, &flags, &filename1, &filename2 );
This would require one and only one of either -e, -f, or -h
to be chosen, with -b as an independent option. Filename1
and filename2 are both required. The usage message for this
version of diff would be:
Usage:
diff [-b] -{efh} filename1 filename2
Argsbad is the subroutine used by argscan to print an error
message followed by a usage message. It is made available
so that a program can call argscan to make a preliminary
check of the command line, then call argsbad passing an
appropriate error message (or a pointer to a null string) if
any further command line error is discovered.
Since argsbad uses the format string and argv[0] passed to
argscan, argscan must be called sometime prior to calling
argsbad.
CAVEATS
By its nature a call to argscan defines a syntax which may
be ambiguous, and although the results may be surprising,
they are predictable.
To prevent string and number parameters (conversions a and
+) from being gobbled up as string arguments (s conversion),
all string conversion fields must follow all string and
number parameter fields in the format string. For example:
"%-xyz !s zapstr %as string" is illegal;
"%-xyz %as string !s zapstr" is legal.
No check is made of the correctness of the format string.
SEE ALSO
execve(2).
Printed 3/13/89 3
%%index%%
na:336,112;
sy:448,1209;
de:1657,2124;4189,2774;7371,2345;
ca:9716,759;
se:10475,111;
%%index%%000000000119