Provided by: minc-tools_2.1.00-2_amd64 bug

NAME

       ParseArgv - process command-line options

SYNOPSIS

       #include <ParseArgv.h>

       int
       ParseArgv(argcPtr, argv, argTable, flags)

ARGUMENTS

       int        argcPtr     (in/out)  Pointer to number of arguments in argv;  gets modified to
                                        hold number of unprocessed arguments  that  remain  after
                                        the call.

       char       **argv      (in/out)  Command  line arguments passed to main program.  Modified
                                        to hold unprocessed arguments that remain after the call.

       ArgvInfo   *argTable   (in)      Array of argument descriptors, terminated by element with
                                        type ARGV_END.

       int        flags       (in)      If  non-zero,  then  it  specifies one or more flags that
                                        control the parsing of arguments.  Different flags may be
                                        OR'ed together.  The flags currently defined are
                                        ARGV_DONT_SKIP_FIRST_ARG, ARGV_NO_ABBREV,
                                        ARGV_NO_LEFTOVERS, ARGV_NO_DEFAULTS and ARGV_NO_PRINT.
_________________________________________________________________________________________________

DESCRIPTION

       ParseArgv processes an array of command-line arguments according to a table describing the
       kinds of arguments that are expected.  Each of the arguments in argv is processed in turn:
       if  it matches one of the entries in argTable, the argument is processed according to that
       entry and discarded.  The arguments that do not match anything in argTable are copied down
       to  the beginning of argv (retaining their original order) and returned to the caller.  At
       the end of the call ParseArgv sets *argcPtr to hold the number of arguments that are  left
       in  argv,  and  argv[*argcPtr] will hold the value NULL.  Normally, ParseArgv assumes that
       argv[0] is a command name, so it is treated like an argument that doesn't  match  argTable
       and  returned to the caller;  however, if the ARGV_DONT_SKIP_FIRST_ARG bit is set in flags
       then argv[0] will be processed just like the other elements of argv.

       ParseArgv normally returns the value FALSE (0).  If an  error  occurs  while  parsing  the
       arguments,  then TRUE (1) is returned and ParseArgv will print an error message on stderr.
       In the event of an error return, *argvPtr will not have been modified, but argv could have
       been partially modified.  The possible causes of errors are explained below.

       The  argTable  array  specifies  the  kinds  of  arguments that are expected;  each of its
       entries has the following structure: typedef struct {
           char*key;
           int type;
           char*src;
           char*dst;
           char*help; } ArgvInfo;

       The key field is a string such as ``-display'' or ``-bg'' that is compared with the values
       in argv.  Type indicates how to process an argument that matches key (more on this below).
       Src and dst are additional values used in processing  the  argument.   Their  exact  usage
       depends  on type, but typically src indicates a value and dst indicates where to store the
       value.  The char * declarations for src and dst are placeholders:  the actual types may be
       different.   Lastly,  help  is  a  string giving a brief description of this option;  this
       string is printed when users ask for help about command-line options.

       When processing an argument in argv, ParseArgv compares the argument to each of the  key's
       in  argTable.   ParseArgv  selects  the  first  specifier  whose  key matches the argument
       exactly, if such a specifier exists.  Otherwise ParseArgv selects a  specifier  for  which
       the  argument is a unique abbreviation.  If the argument is a unique abbreviation for more
       than one specifier, then an error is returned.  If there is no matching entry in argTable,
       then the argument is skipped and returned to the caller.

       Once a matching argument specifier is found, ParseArgv processes the argument according to
       the type field of the specifier.  The argument that matched key is called  ``the  matching
       argument''  in  the descriptions below.  As part of the processing, ParseArgv may also use
       the next argument in argv after the matching argument, which  is  called  ``the  following
       argument''.   The  legal  values  for  type,  and  the  processing that they cause, are as
       follows:

       ARGV_END
              Marks the end of the table.  The last entry in argTable must have this  type;   all
              of its other fields are ignored and it will never match any arguments.

       ARGV_CONSTANT
              Src is treated as an integer and dst is treated as a pointer to an integer.  Src is
              stored at *dst.  The matching argument is discarded.

       ARGV_INT
              The following argument must contain an integer string in  the  format  accepted  by
              strtol  (e.g. ``0'' and ``0x'' prefixes may be used to specify octal or hexadecimal
              numbers, respectively).  Dst is treated as a pointer to an integer;  the  following
              argument is converted to an integer value and stored at *dst.  Src is treated as an
              integer count: if its value is  greater  than  1,  then  that  many  arguments  are
              processed  and  Dst  is  treated  as  an array pointer.  The matching and following
              arguments are discarded from argv.

       ARGV_FLOAT
              The following argument must contain a floating-point number in the format  accepted
              by  strtol.   Dst  is  treated as the address of an double-precision floating point
              value;  the following argument is converted to a double-precision value and  stored
              at  *dst.  Src is treated as an integer count: if its value is greater than 1, then
              that many arguments are processed and Dst is treated  as  an  array  pointer.   The
              matching and following arguments are discarded from argv.

       ARGV_STRING
              In this form, dst is treated as a pointer to a (char *); ParseArgv stores at *dst a
              pointer to  the  following  argument,  and  discards  the  matching  and  following
              arguments  from  argv.  Src is treated as an integer count: if its value is greater
              than 1, then that many arguments are processed and  Dst  is  treated  as  an  array
              pointer.

       ARGV_HELP
              When this kind of option is encountered, ParseArgv uses the help fields of argTable
              to format a message describing all the valid arguments.  The message is written  on
              stderr  and ParseArgv returns TRUE.  When this happens, the caller normally aborts.
              If the key field of a ARGV_HELP specifier is NULL, then the  specifier  will  never
              match   any   arguments;    in  this  case  the  specifier  simply  provides  extra
              documentation, which will be included when some other ARGV_HELP entry  causes  help
              information to be returned.

       ARGV_REST
              This  option  is  used by programs or commands that allow the last several of their
              options to be the name and/or options for  some  other  program.   If  a  ARGV_REST
              argument  is  found, then ParseArgv doesn't process any of the remaining arguments;
              it returns them all at the beginning of argv  (along  with  any  other  unprocessed
              arguments).   In addition, ParseArgv treats dst as the address of an integer value,
              and stores at *dst the index of the first of the ARGV_REST options in the  returned
              argv.   This  allows  the  program  to distinguish the ARGV_REST options from other
              unprocessed options that preceeded the ARGV_REST.

       ARGV_FUNC
              For this kind of argument, src is treated as the address of a procedure,  which  is
              invoked to process the following argument.  The procedure should have the following
              structure: int func(dst, key, nextArg)
                  char    *dst;
                  char    *key;
                  char    *nextArg; { }

              The dst and key parameters will contain the corresponding fields from the  argTable
              entry, and nextArg will point to the following argument from argv (or NULL if there
              aren't any more arguments left in argv).  If func uses nextArg (so  that  ParseArgv
              should  discard  it),  then  it  should return 1.  Otherwise it should return 0 and
              TkParseArgv will process the following argument in the normal fashion.   In  either
              event the matching argument is discarded.

       ARGV_GENFUNC
              This  form provides a more general procedural escape.  It treats src as the address
              of a procedure, and passes that procedure all  of  the  remaining  arguments.   The
              procedure should have the following form: int genfunc(dst, key, argc, argv)
                  char    *dst;
                  char    *key;
                  int argc;
                  char    **argv; { }

              The  dst and key parameters will contain the corresponding fields from the argTable
              entry.  Argc and argv refer to all of the options after the matching one.   Genfunc
              should  behave  in  a fashion similar to ParseArgv:  parse as many of the remaining
              arguments as it can, then return any that  are  left  by  compacting  them  to  the
              beginning of argv (starting at argv[0]).  Genfunc should return a count of how many
              arguments are left in argv; ParseArgv will process them.  If genfunc encounters  an
              error  then  it  should print an error message on stderr, and return -1;  when this
              happens ParseArgv will abort its processing and return TRUE.

FLAGS

       ARGV_DONT_SKIP_FIRST_ARG
              ParseArgv normally treats argv[0] as a program or command name, and returns  it  to
              the  caller  just  as  if  it hadn't matched argTable.  If this flag is given, then
              argv[0] is not given special treatment.

       ARGV_NO_ABBREV
              Normally, ParseArgv accepts unique abbreviations for key values  in  argTable.   If
              this flag is given then only exact matches will be acceptable.

       ARGV_NO_LEFTOVERS
              Normally,  ParseArgv  returns unrecognized arguments to the caller.  If this bit is
              set in flags then ParseArgv will return an error if it encounters any argument that
              doesn't  match argTable.  The only exception to this rule is argv[0], which will be
              returned to the caller with no errors as  long  as  ARGV_DONT_SKIP_FIRST_ARG  isn't
              specified.

       ARGV_NO_DEFAULTS
              Normally,  ParseArgv  searches an internal table of standard argument specifiers in
              addition to argTable.  If this bit is set in flags, then ParseArgv  will  use  only
              argTable and not its default table.

       ARGV_NO_PRINT
              Normally,  ParseArgv  prints  error message on stderr. If this bit is set in flags,
              then ParseArgv will not print any error messages.

EXAMPLE

       Here is an example definition of an argTable and some sample command lines  that  use  the
       options.   Note  the  effect  on  argc  and  argv;   arguments  processed by ParseArgv are
       eliminated from argv, and argc is updated to reflect reduced number of arguments.  /*
        * Define and set default values for globals.
        */ int debugFlag = 0; int numReps = 100; char defaultFileName[] = "out"; char *fileName =
       defaultFileName; Boolean exec = FALSE;

       /*
        * Define option descriptions.
        */  ArgvInfo  argTable[]  =  {     {"-X", ARGV_CONSTANT, (char *) 1, (char *) &debugFlag,
               "Turn on debugging  printfs"},      {"-N",  ARGV_INT,  (char  *)  NULL,  (char  *)
       &numReps,          "Number of repetitions"},     {"-of", ARGV_STRING, (char *) NULL, (char
       *) &fileName,         "Name of file for output"},      {"x",  ARGV_REST,  (char  *)  NULL,
       (char  *)  &exec,          "File  to  exec,  followed  by  any  arguments  (must  be  last
       argument)."},     {(char *) NULL, ARGV_END, (char *) NULL, (char *) NULL,         (char *)
       NULL} };

       main(argc, argv)     int argc;     char *argv[]; {     ...

           if (ParseArgv(&argc, argv, argTable, 0)) {         exit(1);     }

           /*      * Remainder of the program.       */ }

       Note  that  default  values can be assigned to variables named in argTable:  the variables
       will only be overwritten if the particular arguments are present in argv.  Here  are  some
       example  command lines and their effects.  prog -N 200 infile      # just sets the numReps
       variable to 200 prog -of out200 infile  # sets fileName to reference "out200" prog -XN  10
       infile      #  sets  the  debug flag, also sets numReps In all of the above examples, argc
       will be set by ParseArgv to 2, argv[0] will be ``prog'', argv[1] will be  ``infile'',  and
       argv[2] will be NULL.

KEYWORDS

       arguments, command line, options

                                                                                     ParseArgv(3)