TSP (libtsp/UT) - UTgetOption

## UTgetOption

#### Routine

int UTgetOption (int *Index, int argc, const char *argv[], const char *OptTable[], const char *OptArg[])

#### Purpose

Decode command line options and arguments

#### Description

This routine decodes command line options, returning option values and other (non-option) argument strings. Typically this routine is used to decode Unix style command options and to return argument strings. An example of a Unix command line is as follows.

      command -x -f name --delay=30 argA argB.

Each of the items in the command line, including the command itself, appears in an array of strings. This routine compares the elements of the command line after the command name for a match to a table of option keywords. Options normally have a leading "-" character.

The table of keywords contains entries which can specify the minimum length needed for a match with an optional "*" character.

-d
  This form specifies that an exact match to "-d" is required. The "-" character is just treated as an ordinary character for the match.
--d*elay
  This form specifies that the option must match the first three characters and optionally match additional characters. For instance, "--d" matches as does "--del", but not "--dx".

The need for an option value is signalled in two ways.

-d#
  The presence of the trailing "#" indicates that the option can either directly follow the option as in "-d30" or in the next argument as in "-d" followed by "30" in the next argument.
--d*elay=
  The presence of the trailing "=" indicates that the option can either follow the option, separated by a '=' character as in "--del=30" or in the next argument as in "--del" followed by "30" in the next argument.

The keywords are searched in order. Keywords can contain a second asterisk can be used to indicate that characters after this point need not match.

Errors detected by this routine result in an error message being printed and an error code being returned.

Invalid option:
  If all keywords in the list of option keywords start with a "-" character, then any argument with a leading "-", followed by one or more characters and not matching any of the options causes an error condition. This means that ordinary arguments (non-option) cannot start with a "-" if the first option keyword starts with a "-".
Missing option value:
  If an option requires a value, and none is supplied, an error is reported. Such an error can only happen if the option is the last item in the list of arguments, since in other cases the item after the option will be picked up as the option value.

The results of the option scan are communicated to the calling program via the pointer OptArg. OptArg is a pointer to a pointer to a null terminated strings (substrings of the strings in argv). The interpretation of these strings is given by the return code. When this routine is called in a loop, the OptArg strings are returned in the same order as the options and arguments appeared in argv. The OptArg pointer can be NULL. This is the case for an option with no option value. Each call to UTgetOption returns at most one option or argument.

Return codes:

      -2 - Error detected, invalid option or missing value
      -1 - Normal end of processing
       0 - Argument string, not an option.
       n - Option specified by the n'th keyword, n >= 1.

For the non-negative return codes, the argument string or the option value string are pointed to by OptArg. OptArg will be NULL for an option for which no option value is allowed.

The use of this routine is illustrated in the following program fragment.

      static const char *OptTable[] = {
        "-d#", "--d*elay=",
        "-p", "--p*rint",
        NULL};

      void main (int argc, const char *argv[])
      {
        const char *OptArg;
        int Index;
        int n;

        Index = 1;
        while (Index < argc) {
          n = UTgetOption (&Index, argc, argv, OptTable, &OptArg);
          switch (n) {
          case 0:
            ... process non-option OptArg
            break;
          case 1:
          case 2:
            ... process option 1 (-d or --delay)
            break;
          case 3:
          case 4:
            ... process option 2 (-p or --print)
            break;
          default:
            ... error
          }
        }
      }

#### Parameters

<- int UTgetOptions
  Status code,

         -2 - Error, invalid option or missing value
         -1 - End of arguments/options
          0 - Argument value
        >=1 - Option code

<-> int *Index
  Integer used internally for saving the state of the search. It is the index of the next element of argv to be examined. This value should be saved from call to call. Note that the index may be incremented by zero (error detected), one or two (option followed by a value in the next element of argv). The initial value of Index should be one.
-> int argc
  Number of argument strings in argv
-> const char *argv[]
  Pointers to option/argument strings. Note that with ANSI C, if the actual parameter is not declared to have the const attribute, an explicit cast to (const char **) is required.
-> const char *OptTable[]
  Pointers to the option keywords. The end of the keyword table is signalled by a NULL pointer. Note that with ANSI C, if the actual parameter is not declared to have the const attribute, an explicit cast to (const char **) is required.
<- const char *OptArg[]
  Argument/option string. For an argument or an option taking a value, this is a pointer to a null terminated substring string in argv. If the decoded option does not take a value, this pointer will be NULL. Note that with ANSI C, if the actual parameter is not declared to have the const attribute, an explict cast to (const char **) is required.

#### Author / revision

P. Kabal Copyright (C) 1998 / Revision 1.29 1998/04/06

Main Index libtsp