getopt(S)                      6 January 1993                      getopt(S)


 Name

    getopt - get option letter from argument vector

 Syntax


    cc  . . .  -lc


    int getopt (argc, argv, optstring)
    int argc;
    char **argv, *optstring;

    extern char *optarg;
    extern int optind, opterr;


 Description

    The getopt function returns the next option letter in argv that matches a
    letter in optstring.  It supports all the rules of the command syntax
    standard.  Use getopts(C)) or getopt to ensure that all new commands
    adhere to the command syntax standard.  These routines parse positional
    parameters and check for options that are legal for that command.

    optstring must contain the option letters the command using getopt recog-
    nizes; if a letter is followed by a colon, the option is expected to have
    an argument, or group of arguments, which must be separated from it by
    white space.

    optarg is set to point to the start of the option-argument on return from
    getopt.

    getopt places in optind the argv index of the next argument to be pro-
    cessed.  optind is external and is initialized to 1 before the first call
    to getopt.

    When all options have been processed (that is, up to the first non-option
    argument), getopt returns -1.  The special option ``--'' may be used to
    delimit the end of the options; when it is encountered, -1 is returned,
    and ``--'' is skipped.

    The following rules comprise the standard for command line syntax:

    +  Command names must be between two and nine characters.

    +  Command names must only include lowercase letters and digits.

    +  Option names must be a single character in length.

    +  All options must be delimited by the ``-'' character.

    +  Options with no arguments may be grouped behind one delimiter.

    +  The first option argument following an option must be preceded by
       white space.

    +  Option arguments cannot be optional.

    +  Groups of option arguments following an option must be separated by
       commas or separated by white space and quoted.

    +  All options must precede operands on the command line.

    +  The characters -- may be used to delimit the end of the options.

    +  The order of options relative to one another should not matter.

    +  The order of operands may matter and position-related interpretations
       should be determined on a command-specific basis.

    +  The ``-'' character preceded and followed by white space should be
       used only to mean standard input.

    The function getopt is the command line parser that enforces the rules of
    this command syntax standard.

 Diagnostics

    getopt prints an error message on standard error and returns a question
    mark (?) when it encounters an option letter not included in optstring or
    no option-argument after an option that expects one.  This error message
    may be disabled by setting opterr to 0.

 Warning

    Although the following command syntax rule (see Intro(C)) relaxations are
    permitted under the current implementation, they should not be used
    because they may not be supported in future releases of the system.  As
    in the ``Example'' section above, a and b are options, and the option o
    requires an option-argument:

    cmd -aboxxx file    violation: options with option-arguments must not be
                        grouped with other options

    cmd -ab -oxxx file  violation: there must be white space after an option
                        that takes an option-argument

    Changing the value of the variable optind or calling getopt with dif-
    ferent values of argv may lead to unexpected results.

 See also

    getopts(C), Intro(C)

 Standards conformance

    getopt is conformant with:
    AT&T SVID Issue 2;
    Intel386 Binary Compatibility Specification, Edition 2 (iBCSe2);
    and X/Open Portability Guide, Issue 3, 1989.

 Example

    The following code fragment shows how one might process the arguments for
    a command that can take the mutually exclusive options a and b, and the
    option o, which requires an option argument:

       main (argc, argv)
       int argc;
       char **argv;
       {
               int c;
               extern char *optarg;
               extern int optind;
               .
               .
               .
               while ((c = getopt(argc, argv, "abo:")) != -1)
                       switch (c) {
                       case 'a':
                               if (bflg)
                                       errflg++;
                               else
                                       aflg++;
                               break;
                       case 'b':
                               if (aflg)
                                       errflg++;
                               else
                                       bproc( );
                               break;
                       case 'o':
                               ofile = optarg;
                               break;
                       case '?':
                               errflg++;
                       }
               if (errflg) {
                       (void)fprintf(stderr, "usage: . . . ");
                       exit (1);
               }
               for ( ; optind < argc; optind++) {
                       if (access(argv[optind], 4)) {
               .
               .
               .
       }