--- name: "VistaIOParseCommand" section: "3" platform: "linux" package: "libvistaio-dev" version: "1.2.19-3+b2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/VistaIOParseCommand" --- # VistaIOParseCommand(3) parse command line arguments ## NAME VistaIOParseCommand - parse command line arguments ## SYNOPSIS ``` #include ``` ``` VistaIOBoolean VistaIOParseCommand (noptions, options, argc, argv) int noptions, *argc; VistaIOOptionDescRec options[noptions]; char *argv; ``` ## 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, and returns* *the number of arguments that were not recognized as valid options.* - *argv* *Specifies a vector of command line arguments to be parsed, and returns* *a vector of the arguments that were not recognized as valid options.* ## DESCRIPTION **VistaIOParseCommand** *parses command line arguments according to a table that* *describes valid command line options. The* **VistaIOoption***(3) manual page* *describes this table's contents and specifies the forms that command line* *options may take. The noptions and options arguments specify the* *length and location of the table.* *The argc and argv arguments to* **VistaIOParseCommand** *are normally* *identical to the parameters of the program's* **main** *function. (Note,* *however, that the address of* **main***'s argc is passed rather than* *the actual value of argc.)* **VistaIOParseCommand** *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 from* *argv\[1\] through argv\[\*argc - 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,* **VistaIOParseCommand** *will allocate a* *vector of the appropriate length for them. Following the value arguments,* **VistaIOParseCommand** *expects either another option keyword or the end of the* *list of command line arguments.* *If* **VistaIOParseCommand** *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).* **VistaIOParseCommand** *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* **VistaIOBoolean** *that is to be set to indicate whether the option was* *encountered.* **VistaIOParseCommand** *will set the* **VistaIOBoolean** *to* **TRUE** *if the option was encountered, and to* **FALSE** *otherwise.* *In addition to the options specified by the options table,* **VistaIOParseCommand** *recognizes the option* **-help***. When it encounters* **-help***,* **VistaIOParseCommand** *ignores the remaining arguments on the command* *line, sets \*argc to 1 to indicate that all arguments have been accounted* *for, and returns* **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.* ## RETURN VALUES **VistaIOParseCommand** *returns* **FALSE** *if an option that appears among the command line arguments lacks the* *correct number of values of the appropriate form. It also returns* **FALSE** *if a required option is missing from the command line arguments. Finally,* *it returns* **FALSE** *if it encounters a* **-help** *option. Otherwise,* **VistaIOParseCommand** *returns* **TRUE** *. Thus,* **TRUE** *indicates that* *the command were parsed successfully by* **VistaIOParseCommand** *and that the* *program may continue on that basis.* **VistaIOParseCommand** *also returns a revised argv containing only the* *command* *line arguments that it did not recognize as valid options. In \*argc it* *returns the number of such arguments.* **VistaIOParseCommand** *moves elements of the* *argv vector of strings so that all arguments that are not part of valid* *options are in the first \*argc 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* **VistaIOParseCommand** *— e.g., X* *Windows parameters that must be given to* **XtDisplayInitialize***(3Xt)* *instead.* ## EXAMPLES *The following code fragment parses command line arguments using* **VistaIOParseCommand***. Any arguments not recognized by* **VistaIOParseCommand** *are then parsed by some other means (e.g., by* **XtDisplayInitialize***(3Xt)).* *Finally, if any arguments remain, having not been recognized during either* *parsing, they are printed along with information on the valid program* *options.* ``` #include ``` **static VistaIOOptionDescRec options\[\] = { /\* option table entries \*/ };** **int main (int argc, char \*argv)** **{** **if (! VistaIOParseCommand (VistaIONumber (options), options, & argc, argv))** **goto Usage;** **/\* Parse arguments remaining in argv\[1\] ... argv\[argc - 1\]. \*/** **...** **if (argc \> 1) {** **VistaIOReportBadArgs (argc, argv);** **Usage:** **VistaIOReportUsage (argv\[0\], VistaIONumber (options), options, NULL);** **fprintf (stderr, " plus any X Windows options.\\n\\n");** **exit (1);** **}** **...** **}** ## SEE ALSO [**VistaIOReportBadArgs**(3)](/VistaIOReportBadArgs/3.md), [**VistaIOReportUsage**(3)](/VistaIOReportUsage/3.md), [**VistaIOIdentifyFiles**(3)](/VistaIOIdentifyFiles/3.md), [**VistaIOoption**(3)](/VistaIOoption/3.md), ## DIAGNOSTICS **VistaIOParseCommand reports errors in command line options by printing** **directly to the standard error stream. 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.** **In addition, VistaIOParseCommand may invoke VistaIOError with the following** **message:** - \`\`Parsing of command options with *type* values is not implemented.'' **Options, as described in the options table, must take values that are of** **type VistaIOBit, VistaIOUByte, VistaIOSByte, VistaIOShort, VistaIOLong,** **VistaIOFloat, VistaIODouble, VistaIOBoolean, or VistaIOString.** **VistaIOParseCommand encountered a table entry describing an option of type** *type* **instead.** ## AUTHOR **Art Pope \** **Adaption to vistaio: Gert Wollny \**