.ds Vv 1.2.14 .TH VistaIOParseCommand 3 "24 April 1993" "VistaIO Version \*(Vv" .SH NAME VistaIOParseCommand \- parse command line arguments .SH SYNOPSIS .PP .nf .B #include .fi .PP .nf .B VistaIOBoolean VistaIOParseCommand (\fInoptions\fP, \fIoptions\fP, \fIargc\fP, \fIargv\fP) .RS .ft B int \fInoptions\fP, *\fIargc\fP; VistaIOOptionDescRec \fIoptions\fP[\fInoptions\fP]; char *\fIargv\fP; .ft .fi .SH ARGUMENTS .IP \fInoptions\fP 10n Specifies the number of entries in the table of option descriptors. .IP \fIoptions\fP Specifies the location of the table of option descriptors. .IP \fIargc\fP Specifies the number of command line arguments to be parsed, and returns the number of arguments that were not recognized as valid options. .IP \fIargv\fP Specifies a vector of command line arguments to be parsed, and returns a vector of the arguments that were not recognized as valid options. .SH DESCRIPTION \fBVistaIOParseCommand\fP parses command line arguments according to a table that describes valid command line options. The \fBVistaIOoption\fP(3) manual page describes this table's contents and specifies the forms that command line options may take. The \fInoptions\fP and \fIoptions\fP arguments specify the length and location of the table. .PP The \fIargc\fP and \fIargv\fP arguments to \fBVistaIOParseCommand\fP are normally identical to the parameters of the program's \fBmain\fP function. (Note, however, that the address of \fBmain\fP's \fIargc\fP is passed rather than the actual value of \fIargc\fP.) .PP \fBVistaIOParseCommand\fP uses the first command line argument, \fIargv\fP[0], in a call to \fBVistaIOSetProgramName\fP(3) to record the program's name for future error messages. .PP The remaining command line arguments are then processed sequentially from \fIargv\fP[1] through \fIargv\fP[*\fIargc\fP\ -\ 1]. 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. If a variable number of values are associated with the option, \fBVistaIOParseCommand\fP will allocate a vector of the appropriate length for them. Following the value arguments, \fBVistaIOParseCommand\fP expects either another option keyword or the end of the list of command line arguments. .PP If \fBVistaIOParseCommand\fP encounters an argument that could be an option keyword (based on its position among the command line arguments) but that isn't among the keywords defined in the table, it merely passes over it without complaint. Any such arguments that are not recognized are returned to the caller (see ``RETURN VALUES'', below). .PP \fBVistaIOParseCommand\fP checks that each required option appears once in the command line, and that each optional option appears at most once. If an option appears more than once, a message is printed and only values supplied with the last appearance of the option are retained. The options table entry for an optional option may specify the location of a \fBVistaIOBoolean\fP that is to be set to indicate whether the option was encountered. \fBVistaIOParseCommand\fP will set the \fBVistaIOBoolean\fP to .SB TRUE if the option was encountered, and to .SB FALSE otherwise. .PP In addition to the options specified by the options table, \fBVistaIOParseCommand\fP recognizes the option \fB-help\fP. When it encounters \fB-help\fP, \fBVistaIOParseCommand\fP ignores the remaining arguments on the command line, sets *\fIargc\fP to 1 to indicate that all arguments have been accounted for, and returns .SB FALSE to indicate that the command line parse was not completed successfully. These returned indications normally cause the caller to print command usage information as shown in the code example below. .SH "RETURN VALUES" \fBVistaIOParseCommand\fP returns .SB FALSE if an option that appears among the command line arguments lacks the correct number of values of the appropriate form. It also returns .SB FALSE if a required option is missing from the command line arguments. Finally, it returns .SB FALSE if it encounters a \fB-help\fP option. Otherwise, \fBVistaIOParseCommand\fP returns .SB TRUE\c \&. Thus, .SB TRUE indicates that the command were parsed successfully by \fBVistaIOParseCommand\fP and that the program may continue on that basis. .PP \fBVistaIOParseCommand\fP also returns a revised \fIargv\fP containing only the command line arguments that it did not recognize as valid options. In *\fIargc\fP it returns the number of such arguments. \fBVistaIOParseCommand\fP moves elements of the \fIargv\fP vector of strings so that all arguments that are not part of valid options are in the first *\fIargc\fP elements. At minimum, there will be one: the program's name. Others might be options that, for some reason, the programmer chooses not to handle with \fBVistaIOParseCommand\fP \(em e.g., X Windows parameters that must be given to \fBXtDisplayInitialize\fP(3Xt) instead. .SH EXAMPLES The following code fragment parses command line arguments using \fBVistaIOParseCommand\fP. Any arguments not recognized by \fBVistaIOParseCommand\fP are then parsed by some other means (e.g., by \fBXtDisplayInitialize\fP(3Xt)). Finally, if any arguments remain, having not been recognized during either parsing, they are printed along with information on the valid program options. .PP .nf .ft B #include .PP .ft B static VistaIOOptionDescRec options[] = { /* option table entries */ }; .PP .ft B int main (int argc, char *argv) { .RS if (! VistaIOParseCommand (VistaIONumber (options), options, & argc, argv)) .RS goto Usage; .RE .PP /* Parse arguments remaining in argv[1] ... argv[argc - 1]. */ .PP \&... .PP .ft B if (argc > 1) { .RS VistaIOReportBadArgs (argc, argv); .RE .RE Usage: .RS .RS VistaIOReportUsage (argv[0], VistaIONumber (options), options, NULL); fprintf (stderr, " plus any X Windows options.\\n\\n"); exit (1); .RE } .PP \&... .PP .RE .B } .fi .SH "SEE ALSO" .nh .na .BR VistaIOReportBadArgs (3), .BR VistaIOReportUsage (3), .BR VistaIOIdentifyFiles (3), .BR VistaIOoption (3), .hy .ad .SH DIAGNOSTICS \fBVistaIOParseCommand\fP reports errors in command line options by printing directly to the standard error stream. Error reports include the program name obtained from \fIargv\fP[0]. The following messages may be produced: .IP "``Duplicate -\fIoption\fP option; ignoring all but last.''" The specified option was found more than once on the command line. .IP "``Option -\fIoption\fP has incorrect value \fIarg\fP.''" One of the values associated with -\fIoption\fP on the command line is \fIarg\fP, which is of the wrong form with respect to the type of value required. .IP "``Option -\fIoption\fP requires \fIm\fP value(s); found only \fIn\fP.''" The option keyword -\fIoption\fP must be followed by \fIn\fP values on the command line. Only \fIm\fP were present, however. .IP "``Option -\fIoption\fP must be specified.''" The option -\fIoption\fP is required but it was not present on the command line. .PP In addition, \fBVistaIOParseCommand\fP may invoke \fBVistaIOError\fP with the following message: .IP "``Parsing of command options with \fItype\fP values is not implemented.''" Options, as described in the options table, must take values that are of type \fBVistaIOBit\fP, \fBVistaIOUByte\fP, \fBVistaIOSByte\fP, \fBVistaIOShort\fP, \fBVistaIOLong\fP, \fBVistaIOFloat\fP, \fBVistaIODouble\fP, \fBVistaIOBoolean\fP, or \fBVistaIOString\fP. \fBVistaIOParseCommand\fP encountered a table entry describing an option of type \fItype\fP instead. .SH AUTHOR Art Pope Adaption to vistaio: Gert Wollny