Man Linux: Main Page and Category List

NAME

       getopt, optarg, opterr, optind, 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 shall follow
       Utility Syntax Guidelines 3, 4,  5,  6,  7,  9,  and  10  in  the  Base
       Definitions  volume  of  IEEE Std 1003.1-2001,  Section  12.2,  Utility
       Syntax Guidelines.

       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 recognized 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 shall be initialized to 1 by the system, and
       getopt()  shall update 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 shall return 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() shall  set  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 shall  contain  the  next  element  of
           argv,  and optind shall be incremented by 2. If the resulting value
           of optind is greater than argc, this indicates  a  missing  option-
           argument, and getopt() shall return an error indication.

        2. Otherwise,  optarg  shall  point to the string following the option
           character in that element of argv, and optind shall be  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() shall return -1 without changing optind. If:

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

       getopt() shall return -1 after incrementing optind.

       If  getopt()  encounters  an  option character that is not contained in
       optstring, it shall return the question-mark ( ’?’ ) character.  If  it
       detects  a missing option-argument, it shall return the colon character
       ( ’:’ ) if the first character of optstring was a colon, or a question-
       mark  character  (  ’?’ ) otherwise. In either case, getopt() shall 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()  shall  also  print  a
       diagnostic  message  to  stderr in the format specified for the getopts
       utility.

       The getopt() function need not be reentrant. A  function  that  is  not
       required to be reentrant is not required to be thread-safe.

RETURN VALUE

       The  getopt() function shall return the next option character specified
       on the command line.

       A colon ( ’:’ )  shall  be  returned  if  getopt()  detects  a  missing
       argument and the first character of optstring was a colon ( ’:’ ).

       A  question  mark  (  ’?’ ) shall be 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()  shall return -1 when all command line options are
       parsed.

ERRORS

       No errors are defined.

       The following sections are informative.

EXAMPLES

   Parsing Command Line Options
       The following code fragment shows how you 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) {
                      casea:
                          if (bflg)
                              errflg++;
                          else
                              aflg++;
                          break;
                      caseb:
                          if (aflg)
                              errflg++;
                          else {
                              bflg++;
                              bproc();
                          }
                          break;
                      casef:
                          ifile = optarg;
                          break;
                      caseo:
                          ofile = optarg;
                          break;
                          case::       /* -f or -o without operand */
                                  fprintf(stderr,
                                          "Option -%c requires an operand\n", optopt);
                                  errflg++;
                                  break;
                      case?:
                                  fprintf(stderr,
                                          "Unrecognized 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

   Checking Options and Arguments
       The following example parses a set of command line options  and  prints
       messages  to  standard  output  for  each  option  and argument that it
       encounters.

              #include <unistd.h>
              #include <stdio.h>
              ...
              int c;
              char *filename;
              extern char *optarg;
              extern int optind, optopt, opterr;
              ...
              while ((c = getopt(argc, argv, ":abf:")) != -1) {
                  switch(c) {
                  casea:
                      printf("a is set\n");
                      break;
                  caseb:
                      printf("b is set\n");
                      break;
                  casef:
                      filename = optarg;
                      printf("filename is %s\n", filename);
                      break;
                  case::
                      printf("-%c without filename\n", optopt);
                      break;
                  case?:
                      printf("unknown arg %c\n", optopt);
                      break;
                  }
              }

   Selecting Options from the Command Line
       The following example selects the type of database  routines  the  user
       wants to use based on the Options argument.

              #include <unistd.h>
              #include <string.h>
              ...
              char *Options = "hdbtl";
              ...
              int dbtype, i;
              char c;
              char *st;
              ...
              dbtype = 0;
              while ((c = getopt(argc, argv, Options)) != -1) {
                  if ((st = strchr(Options, c)) != NULL) {
                      dbtype = st - Options;
                      break;
                  }
              }

APPLICATION USAGE

       The  getopt()  function  is  only required to support option characters
       included in Utility Syntax 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.

RATIONALE

       The optopt variable  represents  historical  practice  and  allows  the
       application to obtain the identity of the invalid option.

       The  description  has been written to make it clear that getopt(), like
       the getopts utility, deals with option-arguments whether separated from
       the  option  by <blank>s or not. Note that the requirements on getopt()
       and getopts are more stringent than the Utility Syntax Guidelines.

       The getopt() function  shall  return  -1,  rather  than  EOF,  so  that
       <stdio.h> is not required.

       The special significance of a colon as the first character of optstring
       makes getopt() consistent  with  the  getopts  utility.  It  allows  an
       application  to  make  a  distinction between a missing argument and an
       incorrect option letter without having to examine the option letter. It
       is  true  that a missing argument can only be detected in one case, but
       that is a case that has to be considered.

FUTURE DIRECTIONS

       None.

SEE ALSO

       exec()  ,  the  Base  Definitions   volume   of   IEEE Std 1003.1-2001,
       <unistd.h>, the Shell and Utilities volume of IEEE Std 1003.1-2001

COPYRIGHT

       Portions  of  this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
       Electrical  and  Electronics  Engineers, Inc and The Open Group. In the
       event of any discrepancy between this version and the original IEEE and
       The  Open Group Standard, the original IEEE and The Open Group Standard
       is the referee document. The original Standard can be  obtained  online
       at http://www.opengroup.org/unix/online.html .