--- name: "VistaIOIdentifyFiles" section: "3" platform: "linux" package: "libvistaio-dev" version: "1.2.19-3+b2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/VistaIOIdentifyFiles" --- # VistaIOIdentifyFiles(3) identify files specified by command line arguments ## NAME VistaIOIdentifyFiles - identify files specified by command line arguments ## SYNOPSIS ``` #include ``` **VistaIOBoolean VistaIOIdentifyFiles (***noptions***,** *options***,** *keyword***,** *argc***,** *argv***,** *fd***)** **int** *noptions***;** **VistaIOOptionDescRec** *options***\[***noptions***\];** **VistaIOStringConst** *keyword***;** **int \****argc***;** **char \****argv***;** **int** *fd***;** ## ARGUMENTS - *noptions* **Specifies the number of entries in the table of option descriptors.** - *options* **Specifies the location of the table of option descriptors.** - *keyword* **Specifies the option keyword that is used on the command line to** **specify filenames.** - *argc* **Specifies the number of command line arguments to be parsed, and returns** **the number of arguments that were not recognized as valid filenames.** - *argv* **Specifies a vector of command line arguments to be parsed, and returns** **a vector of the arguments that were not recognized as valid filenames.** - *fd* **May specify an open file descriptor that should be checked to ensure it** **corresponds to a file or pipe if no filenames are explicitly given by** **command line arguments. Or it may be -1 to indicate that no such** **checking should be done.** ## DESCRIPTION **By convention, a Vista program that reads one or more files can be told** **of those files in any of three ways:** - (a) **the filenames can be supplied as arguments to a command line option (e.g.,** **vxview -in** *file1 file2* **...);** - (b) **the filenames can be supplied as command line arguments not associated** **with any particular option (e.g., vxview** *file1 file2* **...);** **or** - (c) **a file can be directed to the program's standard input stream** **(e.g., vxview \<** *file1***).** **In parsing a command's arguments, these alternatives are considered in** **order. That is, first the program looks for an appropriate command line** **option (e.g., -in). If no such option has been specified, it checks** **for command line arguments not associated with any option. If those are** **also absent, it tries to read its file from the standard input stream.** **Similarly, an output file may be specified using a command line** **option (e.g., vconvolve -out** *file1***), or, by omitting the** **option and directing the program's standard output stream** **(e.g., vconvolve \>** *file1***).** **VistaIOIdentifyFiles identifies a program's input files or output files** **according to this convention. It is called after [VistaIOParseCommand(3)](/VistaIOParseCommand/3.md)** **has parsed any command line arguments that can be identified as options,** **leaving the remaining arguments in** *\*argc* **and** *argv***.** **VistaIOIdentifyFiles is then called once to identify any input files, and** **perhaps again to identify an output file.** **The** *noptions* **and** *options* **parameters specify the table used** **earlier by VistaIOParseCommand to parse command line options. (See** **[VistaIOoption(3)](/VistaIOoption/3.md) for details.) The** *argc* **and** *argv* **parameters** **specify a list of command line arguments that VistaIOParseCommand has** **returned as unparsed (including the program's name, which should be first** **in this list). The** *keyword* **parameter specifies the command line** **option that may be used to specify filenames (e.g., \`\`in'' or \`\`out''),** **absent any \`\`-'' prefix. The entry in the option table for the option** **specified by** *keyword* **must (a) refer to a \`\`found'' flag that** **VistaIOParseCommand can use to record whether or not the option is present** **on the command line, and (b) refer to a location where the option's** **arguments can be stored.** **VistaIOIdentifyFiles consults the \`\`found'' flag to determine whether the** **option was present on the command line. If it was, VistaIOIdentifyFiles** **returns immediately. Otherwise, it then examines** *\*argc* **to determine** **whether an appropriate number of unparsed command line arguments exist. If** **there are a sufficient number of arguments present, they are interpreted as** **filenames and stored at the location indicated by the option table entry** **Finally, if no filenames are found either as arguments to a -***keyword* **option or as additional command line arguments, VistaIOIdentifyFiles** **considers the possibility that a file has been attached to a file** **descriptor such as the standard input or output stream. You may wish to** **ensure that a file is allowed to default to one of these streams only if** **the stream has been associated with a file or pipe, and not a terminal. In** **that case, pass as** *fd* **the file descriptor that will serve as the** **default source or destination of the file, and VistaIOIdentifyFiles will** **check that it is indeed associated with a file or pipe. Otherwise, pass -1** **for** *fd* **and it will not perform this check.** ## RETURN VALUES **VistaIOIdentifyFiles returns** **TRUE** **if it finds one or more files specified on the** **command line, and if the number of files specified is compatible with the** *number* **field of the option table entry. It returns** **FALSE** **if no files were specified, if the wrong number of files were specified, or** **if the file would default to a file descriptor but the file descriptor** *fd* **is not associated with a file or pipe.** **On successful return VistaIOIdentifyFiles will have eliminated, from the** **list represented by** *\*argc* **and** *argv***, any command line arguments** **that it identified as filenames. Also, the filenames found will be stored** **at the location indicated by the option table entry for** *keyword***. A default to the standard input or output stream will be** **identified by a filename of \`\`-''.** ## EXAMPLE **The following fragment is drawn from a program that reads one or more** **files and writes a single file. The input files may be specified with a** **-in option, as extra command line arguments, or by being directed to** **the standard input stream. The output file may be specified with a** **-out option, and, if that option is not present, the file will be** **written to the standard output stream regardless of whether it is associated** **with a file or a terminal.** ``` VistaIOArgVector in_filenames; VistaIOStringConst out_filename; VistaIOBoolean in_found, out_found; VistaIOOptionDescRec options[] = { { "in", VistaIOStringRepn, 0, & in_filenames, & in_found, NULL, "Input file(s)" }, { "out", VistaIOStringRepn, 1, & out_filename, & out_found, NULL, "Output file" } }; main (int argc, char *argv) { /* Parse command line options: */ if (! VistaIOParseCommand (VistaIONumber (options), options, & argc, argv)) { Usage: VistaIOReportUsage (argv[0], VistaIONumber (options), options, "file1 file2..."); exit (1); } /* Identify input file(s): */ if (! VistaIOIdentifyFiles (VistaIONumber (options), options, "in", & argc, argv, 0)) goto Usage; /* Any remaining unparsed arguments are erroneous: */ if (argc > 1) { VistaIOReportBadArgs (argc, argv); goto Usage; } /* Identify output file: */ if (! VistaIOIdentifyFiles (VistaIONumber (options), options, "out", & argc, argv, -1)) goto Usage; /* Open and process each input file: */ for (i = 0; i < in_filenames.number; i++) { filename = ((VistaIOStringConst *) in_filename.vector)[i]; if (strcmp (filename, "-") != 0) { f = fopen (filename, "r"); if (f == NULL) VistaIOError ("Unable to open file \"%s\"", filename); } else f = stdin; ... } } ``` ## SEE ALSO [**VistaIOOpenFile**(3)](/VistaIOOpenFile/3.md), [**VistaIOParseCommand**(3)](/VistaIOParseCommand/3.md), [**VistaIOReportBadArgs**(3)](/VistaIOReportBadArgs/3.md), [**VistaIOReportUsage**(3)](/VistaIOReportUsage/3.md),\ [**VistaIOoption**(3)](/VistaIOoption/3.md), ## DIAGNOSTICS **VistaIOIdentifyFiles** 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: - \`\`*n* files must be specified by -*keyword* or extra command arguments'' The program requires that *n* files be specified (*n* \> 1). Neither a -*keyword* option was present on the command line, nor were there at least *n* unparsed arguments that could be interpreted as filenames. - \`\`No file specified by -*keyword*, extra command argument, or \<'' The program requires that at least one file be specified, and it can be specified in any of three ways. However, it wasn't specified in any form. In addition, **VistaIOIdentifyFiles** may invoke **VistaIOError** with the following messages: - \`\`Option -*keyword* not defined in option table'' The *keyword* parameter specified a keyword not defined in the option table. - \`\`No value storage for option -*keyword''* The *keyword* parameter specifies an option table entry whose *value* field is **NULL** - \`\`No "found" flag for option -*keyword''* The *keyword* parameter specifies an option table entry whose *found* field doesn't point to a dedicated **VistaIOBoolean** variable. - \`\`Failed to fstat() fd *fd*'' An **fstat**() call failed on the supplied file descriptor, *fd*. ## AUTHOR Art Pope \ Adaption to vistaio: Gert Wollny \