Provided by: libvistaio-dev_1.2.19-3_amd64 bug

NAME

       VistaIOIdentifyFiles - identify files specified by command line arguments

SYNOPSIS

       #include <vistaio.h>

       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)  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)  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), VistaIOParseCommand(3), VistaIOReportBadArgs(3),
       VistaIOReportUsage(3),
       VistaIOoption(3),

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 <pope@cs.ubc.ca>

       Adaption to vistaio: Gert Wollny <gw.fossdev@gmail.com>