1: @node Getopt, Argp, , Parsing Program Arguments
    2: @section Parsing program options using @code{getopt}
    3: 
    4: The @code{getopt} and @code{getopt_long} functions automate some of the
    5: chore involved in parsing typical unix command line options.
    6: 
    7: @menu
    8: * Using Getopt::                Using the @code{getopt} function.
    9: * Example of Getopt::           An example of parsing options with @code{getopt}.
   10: * Getopt Long Options::         GNU suggests utilities accept long-named
   11:                                  options; here is one way to do.
   12: * Getopt Long Option Example::  An example of using @code{getopt_long}.
   13: @end menu
   14: 
   15: @node Using Getopt, Example of Getopt, , Getopt
   16: @subsection Using the @code{getopt} function
   17: 
   18: Here are the details about how to call the @code{getopt} function.  To
   19: use this facility, your program must include the header file
   20: @file{unistd.h}.
   21: @pindex unistd.h
   22: 
   23: @comment unistd.h
   24: @comment POSIX.2
   25: @deftypevar int opterr
   26: If the value of this variable is nonzero, then @code{getopt} prints an
   27: error message to the standard error stream if it encounters an unknown
   28: option character or an option with a missing required argument.  This is
   29: the default behavior.  If you set this variable to zero, @code{getopt}
   30: does not print any messages, but it still returns the character @code{?}
   31: to indicate an error.
   32: @end deftypevar
   33: 
   34: @comment unistd.h
   35: @comment POSIX.2
   36: @deftypevar int optopt
   37: When @code{getopt} encounters an unknown option character or an option
   38: with a missing required argument, it stores that option character in
   39: this variable.  You can use this for providing your own diagnostic
   40: messages.
   41: @end deftypevar
   42: 
   43: @comment unistd.h
   44: @comment POSIX.2
   45: @deftypevar int optind
   46: This variable is set by @code{getopt} to the index of the next element
   47: of the @var{argv} array to be processed.  Once @code{getopt} has found
   48: all of the option arguments, you can use this variable to determine
   49: where the remaining non-option arguments begin.  The initial value of
   50: this variable is @code{1}.
   51: @end deftypevar
   52: 
   53: @comment unistd.h
   54: @comment POSIX.2
   55: @deftypevar {char *} optarg
   56: This variable is set by @code{getopt} to point at the value of the
   57: option argument, for those options that accept arguments.
   58: @end deftypevar
   59: 
   60: @comment unistd.h
   61: @comment POSIX.2
   62: @deftypefun int getopt (int @var{argc}, char **@var{argv}, const char *@var{options})
   63: The @code{getopt} function gets the next option argument from the
   64: argument list specified by the @var{argv} and @var{argc} arguments.
   65: Normally these values come directly from the arguments received by
   66: @code{main}.
   67: 
   68: The @var{options} argument is a string that specifies the option
   69: characters that are valid for this program.  An option character in this
   70: string can be followed by a colon (@samp{:}) to indicate that it takes a
   71: required argument.  If an option character is followed by two colons
   72: (@samp{::}), its argument is optional; this is a GNU extension.
   73: 
   74: @code{getopt} has three ways to deal with options that follow
   75: non-options @var{argv} elements.  The special argument @samp{--} forces
   76: in all cases the end of option scanning.
   77: 
   78: @itemize @bullet
   79: @item
   80: The default is to permute the contents of @var{argv} while scanning it
   81: so that eventually all the non-options are at the end.  This allows
   82: options to be given in any order, even with programs that were not
   83: written to expect this.
   84: 
   85: @item
   86: If the @var{options} argument string begins with a hyphen (@samp{-}), this
   87: is treated specially.  It permits arguments that are not options to be
   88: returned as if they were associated with option character @samp{\1}.
   89: 
   90: @item
   91: POSIX demands the following behavior: The first non-option stops option
   92: processing.  This mode is selected by either setting the environment
   93: variable @code{POSIXLY_CORRECT} or beginning the @var{options} argument
   94: string with a plus sign (@samp{+}).
   95: @end itemize
   96: 
   97: The @code{getopt} function returns the option character for the next
   98: command line option.  When no more option arguments are available, it
   99: returns @code{-1}.  There may still be more non-option arguments; you
  100: must compare the external variable @code{optind} against the @var{argc}
  101: parameter to check this.
  102: 
  103: If the option has an argument, @code{getopt} returns the argument by
  104: storing it in the variable @var{optarg}.  You don't ordinarily need to
  105: copy the @code{optarg} string, since it is a pointer into the original
  106: @var{argv} array, not into a static area that might be overwritten.
  107: 
  108: If @code{getopt} finds an option character in @var{argv} that was not
  109: included in @var{options}, or a missing option argument, it returns
  110: @samp{?} and sets the external variable @code{optopt} to the actual
  111: option character.  If the first character of @var{options} is a colon
  112: (@samp{:}), then @code{getopt} returns @samp{:} instead of @samp{?} to
  113: indicate a missing option argument.  In addition, if the external
  114: variable @code{opterr} is nonzero (which is the default), @code{getopt}
  115: prints an error message.
  116: @end deftypefun
  117: 
  118: @node Example of Getopt
  119: @subsection Example of Parsing Arguments with @code{getopt}
  120: 
  121: Here is an example showing how @code{getopt} is typically used.  The
  122: key points to notice are:
  123: 
  124: @itemize @bullet
  125: @item
  126: Normally, @code{getopt} is called in a loop.  When @code{getopt} returns
  127: @code{-1}, indicating no more options are present, the loop terminates.
  128: 
  129: @item
  130: A @code{switch} statement is used to dispatch on the return value from
  131: @code{getopt}.  In typical use, each case just sets a variable that
  132: is used later in the program.
  133: 
  134: @item
  135: A second loop is used to process the remaining non-option arguments.
  136: @end itemize
  137: 
  138: @smallexample
  139: @include testopt.c.texi
  140: @end smallexample
  141: 
  142: Here are some examples showing what this program prints with different
  143: combinations of arguments:
  144: 
  145: @smallexample
  146: % testopt
  147: aflag = 0, bflag = 0, cvalue = (null)
  148: 
  149: % testopt -a -b
  150: aflag = 1, bflag = 1, cvalue = (null)
  151: 
  152: % testopt -ab
  153: aflag = 1, bflag = 1, cvalue = (null)
  154: 
  155: % testopt -c foo
  156: aflag = 0, bflag = 0, cvalue = foo
  157: 
  158: % testopt -cfoo
  159: aflag = 0, bflag = 0, cvalue = foo
  160: 
  161: % testopt arg1
  162: aflag = 0, bflag = 0, cvalue = (null)
  163: Non-option argument arg1
  164: 
  165: % testopt -a arg1
  166: aflag = 1, bflag = 0, cvalue = (null)
  167: Non-option argument arg1
  168: 
  169: % testopt -c foo arg1
  170: aflag = 0, bflag = 0, cvalue = foo
  171: Non-option argument arg1
  172: 
  173: % testopt -a -- -b
  174: aflag = 1, bflag = 0, cvalue = (null)
  175: Non-option argument -b
  176: 
  177: % testopt -a -
  178: aflag = 1, bflag = 0, cvalue = (null)
  179: Non-option argument -
  180: @end smallexample
  181: 
  182: @node Getopt Long Options
  183: @subsection Parsing Long Options with @code{getopt_long}
  184: 
  185: To accept GNU-style long options as well as single-character options,
  186: use @code{getopt_long} instead of @code{getopt}.  This function is
  187: declared in @file{getopt.h}, not @file{unistd.h}.  You should make every
  188: program accept long options if it uses any options, for this takes
  189: little extra work and helps beginners remember how to use the program.
  190: 
  191: @comment getopt.h
  192: @comment GNU
  193: @deftp {Data Type} {struct option}
  194: This structure describes a single long option name for the sake of
  195: @code{getopt_long}.  The argument @var{longopts} must be an array of
  196: these structures, one for each long option.  Terminate the array with an
  197: element containing all zeros.
  198: 
  199: The @code{struct option} structure has these fields:
  200: 
  201: @table @code
  202: @item const char *name
  203: This field is the name of the option.  It is a string.
  204: 
  205: @item int has_arg
  206: This field says whether the option takes an argument.  It is an integer,
  207: and there are three legitimate values: @w{@code{no_argument}},
  208: @code{required_argument} and @code{optional_argument}.
  209: 
  210: @item int *flag
  211: @itemx int val
  212: These fields control how to report or act on the option when it occurs.
  213: 
  214: If @code{flag} is a null pointer, then the @code{val} is a value which
  215: identifies this option.  Often these values are chosen to uniquely
  216: identify particular long options.
  217: 
  218: If @code{flag} is not a null pointer, it should be the address of an
  219: @code{int} variable which is the flag for this option.  The value in
  220: @code{val} is the value to store in the flag to indicate that the option
  221: was seen.
  222: @end table
  223: @end deftp
  224: 
  225: @comment getopt.h
  226: @comment GNU
  227: @deftypefun int getopt_long (int @var{argc}, char *const *@var{argv}, const char *@var{shortopts}, const struct option *@var{longopts}, int *@var{indexptr})
  228: Decode options from the vector @var{argv} (whose length is @var{argc}).
  229: The argument @var{shortopts} describes the short options to accept, just as
  230: it does in @code{getopt}.  The argument @var{longopts} describes the long
  231: options to accept (see above).
  232: 
  233: When @code{getopt_long} encounters a short option, it does the same
  234: thing that @code{getopt} would do: it returns the character code for the
  235: option, and stores the options argument (if it has one) in @code{optarg}.
  236: 
  237: When @code{getopt_long} encounters a long option, it takes actions based
  238: on the @code{flag} and @code{val} fields of the definition of that
  239: option.
  240: 
  241: If @code{flag} is a null pointer, then @code{getopt_long} returns the
  242: contents of @code{val} to indicate which option it found.  You should
  243: arrange distinct values in the @code{val} field for options with
  244: different meanings, so you can decode these values after
  245: @code{getopt_long} returns.  If the long option is equivalent to a short
  246: option, you can use the short option's character code in @code{val}.
  247: 
  248: If @code{flag} is not a null pointer, that means this option should just
  249: set a flag in the program.  The flag is a variable of type @code{int}
  250: that you define.  Put the address of the flag in the @code{flag} field.
  251: Put in the @code{val} field the value you would like this option to
  252: store in the flag.  In this case, @code{getopt_long} returns @code{0}.
  253: 
  254: For any long option, @code{getopt_long} tells you the index in the array
  255: @var{longopts} of the options definition, by storing it into
  256: @code{*@var{indexptr}}.  You can get the name of the option with
  257: @code{@var{longopts}[*@var{indexptr}].name}.  So you can distinguish among
  258: long options either by the values in their @code{val} fields or by their
  259: indices.  You can also distinguish in this way among long options that
  260: set flags.
  261: 
  262: When a long option has an argument, @code{getopt_long} puts the argument
  263: value in the variable @code{optarg} before returning.  When the option
  264: has no argument, the value in @code{optarg} is a null pointer.  This is
  265: how you can tell whether an optional argument was supplied.
  266: 
  267: When @code{getopt_long} has no more options to handle, it returns
  268: @code{-1}, and leaves in the variable @code{optind} the index in
  269: @var{argv} of the next remaining argument.
  270: @end deftypefun
  271: 
  272: Since long option names were used before before the @code{getopt_long}
  273: options was invented there are program interfaces which require programs
  274: to recognize options like @w{@samp{-option value}} instead of
  275: @w{@samp{--option value}}.  To enable these programs to use the GNU
  276: getopt functionality there is one more function available.
  277: 
  278: @comment getopt.h
  279: @comment GNU
  280: @deftypefun int getopt_long_only (int @var{argc}, char *const *@var{argv}, const char *@var{shortopts}, const struct option *@var{longopts}, int *@var{indexptr})
  281: 
  282: The @code{getopt_long_only} function is equivalent to the
  283: @code{getopt_long} function but it allows to specify the user of the
  284: application to pass long options with only @samp{-} instead of
  285: @samp{--}.  The @samp{--} prefix is still recognized but instead of
  286: looking through the short options if a @samp{-} is seen it is first
  287: tried whether this parameter names a long option.  If not, it is parsed
  288: as a short option.
  289: 
  290: Assuming @code{getopt_long_only} is used starting an application with
  291: 
  292: @smallexample
  293:   app -foo
  294: @end smallexample
  295: 
  296: @noindent
  297: the @code{getopt_long_only} will first look for a long option named
  298: @samp{foo}.  If this is not found, the short options @samp{f}, @samp{o},
  299: and again @samp{o} are recognized.
  300: @end deftypefun
  301: 
  302: @node Getopt Long Option Example
  303: @subsection Example of Parsing Long Options with @code{getopt_long}
  304: 
  305: @smallexample
  306: @include longopt.c.texi
  307: @end smallexample