---
name: "VistaIOParseFilterCmd"
section: "3"
platform: "linux"
package: "libvistaio-dev"
version: "1.2.19-3+b2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/VistaIOParseFilterCmd"
---

# VistaIOParseFilterCmd(3)

parse command line options and filenames

## 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)](/VistaIOoption/3.md)**  **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)](/VistaIOSetProgramName/3.md) 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)](/VistaIOParseCommand/3.md), [**VistaIOIdentifyFiles**(3)](/VistaIOIdentifyFiles/3.md), [**VistaIOoption**(3)](/VistaIOoption/3.md),

## 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\>**