getopt(S)

getopt -- get option letter from argument vector

Syntax

cc . . . -lc

# include <unistd.h>

int getopt (argc, argv, optstring)
int argc;
char * const argv[];
const char *optstring;

extern char *optarg;
extern int optind, opterr, optopt;

Description

The getopt(S) routine 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 recognizes; 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 processed. optind is external and is initialized to 1 before the first call to getopt. Each time getopt( ) parses an option, it increments optind by one with only one exception: if the option is the last letter in the string argv[optind] and the option also takes an argument, optind is incremented by two.

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 routine getopt is the command line parser that enforces the rules of this command syntax standard.

Return values

getopt returns the next valid option letter entered on the command line.

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, ``--'' is skipped, and optind is incremented by one.

If argv[optind] is NULL or points to a string "-", or if *argv[optind] is not the character `-', getopt(S) returns -1 without changing optind.

Diagnostics

getopt prints an error message on standard error when it encounters an option letter not included in optstring or if an option-argument is missing. This error message may be disabled by setting opterr to 0 or by setting the first character of optstring to be a colon.

In both error conditions, a question mark (?) is returned and optopt is set to the value of the option character causing the error. A colon character (:) is returned instead if optstring starts with a colon and an option-argument is missing.

Warning

Although the following command syntax rule 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, 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 different values of argv may lead to unexpected results.

Examples

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:

   #include <unistd.h>
   main (argc, argv)
   int argc;
   char **argv;
   {
           int c;
   	int aflg, bflg, errflg;
   	char *ofile;
           extern char *optarg;
           extern int optind, optopt;
           .
           .
           .
           while ((c = getopt(argc, argv, "abo:")) != -1)
                   switch (c) {
                   case 'a':
                      if (bflg)
                              errflg++;
                      else
                              aflg++;
                      break;
                   case 'b':
                      if (aflg)
                              errflg++;
                      else
                              bflg++;
                              bproc( );
                      break;
                   case 'o':
                      ofile = optarg;
                      break;
                   case ':':        /* argument for -o is missing */
                      errflg++;
                      fprintf(stderr,
                             "option -%c requires an argument\n", optopt);
                   case '?':
                      errflg++;
                      fprintf(stderr,
                             "option -%c not recognized\n", optopt);
                   }
           if (errflg) {
                   (void)fprintf(stderr, "usage: . . . ");
                   exit (1);
           }
           for ( ; optind < argc; optind++) {
                   if (access(argv[optind], R_OK)) {
           .
           .
           .
   }

Standards conformance

getopt is conformant with:

Intel386 Binary Compatibility Specification, Edition 2 (iBCSe2) ;

X/Open CAE Specification, System Interfaces and Headers, Issue 4, 1992. .