optind(3p) - phpMan

GETOPT(3P)                 POSIX Programmer's Manual                GETOPT(3P)

PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
       implementation of this interface may differ (consult the  corresponding
       Linux  manual page for details of Linux behavior), or the interface may
       not be implemented on Linux.
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  Util-
       ity  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  Guide-
       lines.
       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[] vec-
       tor  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 argu-
       ment 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) {
                      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,
                                          "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) {
                  case 'a':
                      printf("a is set\n");
                      break;
                  case 'b':
                      printf("b is set\n");
                      break;
                  case 'f':
                      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 por-
       table. Note that support for multi-byte option characters is only  pos-
       sible 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 appli-
       cation to make a distinction between a missing argument and  an  incor-
       rect  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 .

IEEE/The Open Group                  2003                           GETOPT(3P)