NAME¶
VistaIOParseFilterCmd - parse command line options and filenames
SYNOPSIS¶
#include <vistaio.h>
void VistaIOParseFilterCmd ( noptions, options, argc, argv, input, output)
int noptions, argc;
VistaIOOptionDescRec options[noptions];
char * argv;
FILE * input;
FILE * output;
ARGUMENTS¶
- noptions
- Specifies the number of entries in the table of option descriptors.
- options
- Specifies the location of the table of option descriptors.
- argc
- Specifies the number of command line arguments to be parsed.
- argv
- Specifies a vector of command line arguments to be parsed.
- input
- Returns a pointer to the input file. The input file is set as specified in
the command line, or else it defaults to the standard input stream. If
input is NULL, then it is assumed that no
input file is required. Note that the file is opened and ready for input
when VistaIOParseFilterCmd returns.
- output
- Similar to input, except that it returns the output file, which
defaults to the standard output stream.
DESCRIPTION¶
VistaIOParseFilterCmd is used to parse command line options and filenames
for most Vista programs. It implements the standard Vista command line options
-help,
-in, and
-out, and reports all errors in parsing
or in attempting to open the input and output files. Its major limitation is
that it allows at most one input file and one output file.
Options particular to a program are specified in a table given by the
noptions and
options arguments. See the
VistaIOoption(3)
manual page for the form of this table.
The
argc and
argv arguments to
VistaIOParseFilterCmd are
normally identical to the parameters of the program's
main function.
VistaIOParseFilterCmd uses the first command line argument,
argv[0], in a call to
VistaIOSetProgramName(3) to record the
program's name for future error messages.
The remaining command line arguments are then processed sequentially. An
argument is examined to determine whether it is an initial substring of any
option keyword defined in the options table. If so, arguments following the
keyword may be parsed as values associated with the option. The values are
stored at locations specified by the options table.
In addition to the options specified by the options table,
VistaIOParseFilterCmd recognizes the options
-help,
-in,
and
-out. When it encounters
-help,
VistaIOParseFilterCmd
prints the command usage information and exits. The
-in and
-out
arguments are used to identify input and output files, as is standard for
Vista programs.
SEE ALSO¶
VistaIOParseCommand(3),
VistaIOIdentifyFiles(3),
VistaIOoption(3),
NOTES¶
VistaIOParseFilterCmd may modify the
argv vector of command line
arguments.
DIAGNOSTICS¶
VistaIOParseFilterCmd reports errors in command line options by printing
directly to the standard error stream. For all major errors,
VistaIOParseFilterCmd also exits the program with a status code of 1
rather than return to the caller. Error reports include the program name
obtained from
argv[0]. The following messages may be produced:
- ``Duplicate -option option; ignoring all but last.''
- The specified option was found more than once on the command line.
- ``Option -option has incorrect value arg.''
- One of the values associated with -option on the command line is
arg, which is of the wrong form with respect to the type of value
required.
- ``Option -option requires m value(s); found only
n.''
- The option keyword -option must be followed by n values on
the command line. Only m were present, however.
- ``Option -option must be specified.''
- The option -option is required but it was not present on the
command line.
- ``Unable to open input/output file filename.''
- An error was detected while attempting to open a file named on the command
line.
AUTHOR¶
David Lowe <lowe@cs.ubc.ca>
Adaption to vistaio: Gert Wollny <gw.fossdev@gmail.com>