[etc] getopt function in C usage

getopt
The Single UNIX ® Specification, Version 2
Copyright © 1997 The Open Group

--------------------------------------------------------------------------------

NAME
  getopt, optarg, optind, opterr, optopt - command option parsing
SYNOPSIS


#include <unistd.h>

int getopt(int argc, char * const argv[], const char *optstring);
extern char *optarg;
extern int optind, opterr, optopt;


DESCRIPTION
  The getopt() function is a command-line parser that can be used by applications that follow Utility Syntax Guidelines 3, 4, 5, 6, 7, 9 and 10 in the XBD specification, Utility Syntax Guidelines . The remaining guidelines are not addressed by getopt() and are the responsibility of the application.
  The parameters argc and argv are the argument count and argument array as passed to main() (see exec). The argument optstring is a string of recognised option characters; if a character is followed by a colon, the option takes an argument. All option characters allowed by Utility Syntax Guideline 3 are allowed in optstring. The implementation may accept other characters as an extension.

  The variable optind is the index of the next element of the argv[] vector to be processed. It is initialised to 1 by the system, and getopt() updates it when it finishes with each element of argv[]. When an element of argv[] contains multiple option characters, it is unspecified how getopt() determines which options have already been processed.

  The getopt() function returns the next option character (if one is found) from argv that matches a character in optstring, if there is one that matches. If the option takes an argument, getopt() sets the variable optarg to point to the option-argument as follows:


    1.. If the option was the last character in the string pointed to by an element of argv, then optarg contains the next element of argv, and optind is incremented by 2. If the resulting value of optind is not less than argc, this indicates a missing option-argument, and getopt() returns an error indication.

    2.. Otherwise, optarg points to the string following the option character in that element of argv, and optind is incremented by 1.

  If, when getopt() is called:


argv[optind]    is a null pointer
*argv[optind]    is not the character -
argv[optind]    points to the string "-"


  getopt() returns -1 without changing optind. If:

argv[optind]     points to the string "--"


  getopt() returns -1 after incrementing optind.
  If getopt() encounters an option character that is not contained in optstring, it returns the question-mark (?) character. If it detects a missing option-argument, it returns the colon character (:) if the first character of optstring was a colon, or a question-mark character (?) otherwise. In either case, getopt() will set the variable optopt to the option character that caused the error. If the application has not set the variable opterr to 0 and the first character of optstring is not a colon, getopt() also prints a diagnostic message to stderr in the format specified for the getopts utility.


RETURN VALUE
  The getopt() function returns the next option character specified on the command line.
  A colon (:) is returned if getopt() detects a missing argument and the first character of optstring was a colon (:).

  A question mark (?) is returned if getopt() encounters an option character not in optstring or detects a missing argument and the first character of optstring was not a colon (:).

  Otherwise getopt() returns -1 when all command line options are parsed.

ERRORS
  No errors are defined.
EXAMPLES
  The following code fragment shows how one might process the arguments for a utility that can take the mutually exclusive options a and b and the options f and o, both of which require arguments:

#include <unistd.h>

int
main (int argc, char *argv[ ])
{
    int c;
    int bflg, aflg, errflg;
    char *ifile;
    char *ofile;
    extern char *optarg;
    extern int optind, optopt;
    . . .
    while ((c = getopt(argc, argv, ":abf:o:")) != -1) {
        switch (c) {
        case 'a':
            if (bflg)
                errflg++;
            else
                aflg++;
            break;
        case 'b':
            if (aflg)
                errflg++;
            else {
                bflg++;
                bproc();
            }
            break;
        case 'f':
            ifile = optarg;
            break;
        case 'o':
            ofile = optarg;
            break;
            case ':':       /* -f or -o without operand */
                    fprintf(stderr,
                            "Option -%c requires an operand\n", optopt);
                    errflg++;
                    break;
        case '?':
                    fprintf(stderr,
                            "Unrecognised option: -%c\n", optopt);
            errflg++;
        }
    }
    if (errflg) {
        fprintf(stderr, "usage: . . . ");
        exit(2);
    }
    for ( ; optind < argc; optind++) {
        if (access(argv[optind], R_OK)) {
    . . .
}


  This code accepts any of the following as equivalent:

cmd -ao arg path path
cmd -a -o arg path path
cmd -o arg -a path path
cmd -a -o arg -- path path
cmd -a -oarg path path
cmd -aoarg path path


APPLICATION USAGE
  The getopt() function is only required to support option characters included in Guideline 3. Many historical implementations of getopt() support other characters as options. This is an allowed extension, but applications that use extensions are not maximally portable. Note that support for multi-byte option characters is only possible when such characters can be represented as type int.
  The getopt() interface need not be reentrant.

FUTURE DIRECTIONS
  None.
SEE ALSO
  exec, getopts, <unistd.h>, the XCU specification.
DERIVATION
  Derived from Issue 1 of the SVID.

--------------------------------------------------------------------------------