GETOPT(3)                      Library Routines                      GETOPT(3)




NAME

       getopt - get option character from command line argument list


SYNOPSIS

       #include <stdlib.h>

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

       int getopt (int argc, char * const *argv, const char *optstring);
       int getopt_restart (void);


DESCRIPTION

       This manual page describes the BSD implementation of getopt.

       The  getopt  function incrementally parses a command line argument list
       argv and returns the next known option character.  An option  character
       is  known  if  it  has  been specified in the string of accepted option
       characters, optstring.

       The option string optstring may contain the following  elements:  indi-
       vidual  characters,  and  characters followed by a colon to indicate an
       option argument is to follow.  For example, an option string  x  recog-
       nizes  an  option  -x, and an option string x: recognizes an option and
       argument -x argument.  It does not matter  to  getopt  if  a  following
       argument has leading white space.

       On  return  from  getopt, optarg points to an option argument, if it is
       anticipated, and the variable optind contains the  index  to  the  next
       argv  argument  for  a  subsequent call to getopt.  The variable optopt
       saves the last known option character returned by getopt.

       The variable opterr and optind are both initialized to 1.   The  optind
       variable may be set to another value before a set of calls to getopt in
       order to skip over more or less argv entries.

       In order to use getopt to evaluate multiple sets of  arguments,  or  to
       evaluate  a single set of arguments multiple times, the variable optre-
       set must be set to 1 before the second and each additional set of calls
       to getopt, and the variable optind must be reinitialized.

       The getopt function returns an EOF when the argument list is exhausted,
       or a non-recognized  option  is  encountered.   The  interpretation  of
       options  in  the argument list may be canceled by the option -- (double
       dash) which causes getopt to signal the end of argument processing  and
       return  an  EOF.  When all options have been processed (i.e., up to the
       first non-option argument), getopt returns EOF.

       The getopt_restart function sets optreset and optind to 1  and  returns
       zero.   It  is provided for backwards compatibility with older versions
       of GNO, and should be avoided in new code.


DIAGNOSTICS

       If the getopt function encounters a character not found in  the  string
       optarg  or detects a missing option argument it writes an error message
       and returns ?  to the stderr.  Setting opterr to a  zero  will  disable
       these  error  messages.   If  optstring  has a leading : then a missing
       option argument causes a : to be returned in  addition  to  suppressing
       any error messages.

       Option  arguments  are  allowed to begin with -; this is reasonable but
       reduces the amount of error checking possible.


EXTENSIONS

       The optreset variable was added to make it possible to call the  getopt
       function  multiple  times.   This  is  an extension to the POSIX 1003.2
       specification.

       The getopt_reset function is also an extension, but one that  has  been
       deprecated.


LIMITATIONS

       This  implementation  of  getopt  does not allow one to mix options and
       non-option arguments; option processing will halt as soon as the  first
       non-option  argument  is  found.   The GNU implementation does not have
       this limitation, but also cannot be restarted.  The GNU  implementation
       also  allows "long options", where the option name may be more than one
       character.

       See the GNO FAQ regarding availability of  the  GNU  implementation  of
       getopt and getopt_long(3) for GNO.


EXAMPLE

       extern char *optarg;
       extern int optind;
       int bflag, ch, fd;

       bflag = 0;
       while ((ch = getopt(argc, argv, "bf:")) != EOF)
            switch(ch) {
            case 'b':
                 bflag = 1;
                 break;
            case 'f':
                 if ((fd = open(optarg, O_RDONLY, 0)) < 0) {
                      (void)fprintf(stderr,
                          "myname: %s: %s\n", optarg, strerror(errno));
                      exit(1);
                 }
                 break;
            case '?':
            default:
                 usage();
       }
       argc -= optind;
       argv += optind;


HISTORY

       The getopt function appeared 4.3BSD.


BUGS

       A  single dash - may be specified as an character in optstring, however
       it should never have an  argument  associated  with  it.   This  allows
       getopt  to be used with programs that expect - as an option flag.  This
       practice is wrong, and should not be used in any  current  development.
       It  is  provided for backward compatibility only.  By default, a single
       dash causes getopt to return EOF.  This is, we believe, compatible with
       System V.

       It  is  also  possible to handle digits as option letters.  This allows
       getopt to be used with programs that expect a number (such as -3) as an
       option.   This practice is wrong, and should not be used in any current
       development.  It is provided for backward compatibility only.  The fol-
       lowing code fragment works in most cases.
       int length;
       char *p;

       while ((c = getopt(argc, argv, "0123456789")) != EOF)
            switch (c) {
            case '0': case '1': case '2': case '3': case '4':
            case '5': case '6': case '7': case '8': case '9':
                 p = argv[optind - 1];
                 if (p[0] == '-' && p[1] == ch && !p[2])
                      length = atoi(++p);
                 else
                      length = atoi(argv[optind] + 1);
                 break;
            }
       }


SEE ALSO

       getsubopt(3), getopt_long(3G).



GNO                             26 January 1997                      GETOPT(3)

Man(1) output converted with man2html