manual/getopt.texi

   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.
  72
  73 If the @var{options} argument string begins with a hyphen (@samp{-}), this
  74 is treated specially.  It permits arguments that are not options to be
  75 returned as if they were associated with option character @samp{\0}.
  76
  77 The @code{getopt} function returns the option character for the next
  78 command line option.  When no more option arguments are available, it
  79 returns @code{-1}.  There may still be more non-option arguments; you
  80 must compare the external variable @code{optind} against the @var{argc}
  81 parameter to check this.
  82
  83 If the option has an argument, @code{getopt} returns the argument by
  84 storing it in the variable @var{optarg}.  You don't ordinarily need to
  85 copy the @code{optarg} string, since it is a pointer into the original
  86 @var{argv} array, not into a static area that might be overwritten.
  87
  88 If @code{getopt} finds an option character in @var{argv} that was not
  89 included in @var{options}, or a missing option argument, it returns
  90 @samp{?} and sets the external variable @code{optopt} to the actual
  91 option character.  If the first character of @var{options} is a colon
  92 (@samp{:}), then @code{getopt} returns @samp{:} instead of @samp{?} to
  93 indicate a missing option argument.  In addition, if the external
  94 variable @code{opterr} is nonzero (which is the default), @code{getopt}
  95 prints an error message.
  96 @end deftypefun
  97
  98 @node Example of Getopt
  99 @subsection Example of Parsing Arguments with @code{getopt}
 100
 101 Here is an example showing how @code{getopt} is typically used.  The
 102 key points to notice are:
 103
 104 @itemize @bullet
 105 @item
 106 Normally, @code{getopt} is called in a loop.  When @code{getopt} returns
 107 @code{-1}, indicating no more options are present, the loop terminates.
 108
 109 @item
 110 A @code{switch} statement is used to dispatch on the return value from
 111 @code{getopt}.  In typical use, each case just sets a variable that
 112 is used later in the program.
 113
 114 @item
 115 A second loop is used to process the remaining non-option arguments.
 116 @end itemize
 117
 118 @smallexample
 119 @include testopt.c.texi
 120 @end smallexample
 121
 122 Here are some examples showing what this program prints with different
 123 combinations of arguments:
 124
 125 @smallexample
 126 % testopt
 127 aflag = 0, bflag = 0, cvalue = (null)
 128
 129 % testopt -a -b
 130 aflag = 1, bflag = 1, cvalue = (null)
 131
 132 % testopt -ab
 133 aflag = 1, bflag = 1, cvalue = (null)
 134
 135 % testopt -c foo
 136 aflag = 0, bflag = 0, cvalue = foo
 137
 138 % testopt -cfoo
 139 aflag = 0, bflag = 0, cvalue = foo
 140
 141 % testopt arg1
 142 aflag = 0, bflag = 0, cvalue = (null)
 143 Non-option argument arg1
 144
 145 % testopt -a arg1
 146 aflag = 1, bflag = 0, cvalue = (null)
 147 Non-option argument arg1
 148
 149 % testopt -c foo arg1
 150 aflag = 0, bflag = 0, cvalue = foo
 151 Non-option argument arg1
 152
 153 % testopt -a -- -b
 154 aflag = 1, bflag = 0, cvalue = (null)
 155 Non-option argument -b
 156
 157 % testopt -a -
 158 aflag = 1, bflag = 0, cvalue = (null)
 159 Non-option argument -
 160 @end smallexample
 161
 162 @node Getopt Long Options
 163 @subsection Parsing Long Options with @code{getopt_long}
 164
 165 To accept GNU-style long options as well as single-character options,
 166 use @code{getopt_long} instead of @code{getopt}.  This function is
 167 declared in @file{getopt.h}, not @file{unistd.h}.  You should make every
 168 program accept long options if it uses any options, for this takes
 169 little extra work and helps beginners remember how to use the program.
 170
 171 @comment getopt.h
 172 @comment GNU
 173 @deftp {Data Type} {struct option}
 174 This structure describes a single long option name for the sake of
 175 @code{getopt_long}.  The argument @var{longopts} must be an array of
 176 these structures, one for each long option.  Terminate the array with an
 177 element containing all zeros.
 178
 179 The @code{struct option} structure has these fields:
 180
 181 @table @code
 182 @item const char *name
 183 This field is the name of the option.  It is a string.
 184
 185 @item int has_arg
 186 This field says whether the option takes an argument.  It is an integer,
 187 and there are three legitimate values: @w{@code{no_argument}},
 188 @code{required_argument} and @code{optional_argument}.
 189
 190 @item int *flag
 191 @itemx int val
 192 These fields control how to report or act on the option when it occurs.
 193
 194 If @code{flag} is a null pointer, then the @code{val} is a value which
 195 identifies this option.  Often these values are chosen to uniquely
 196 identify particular long options.
 197
 198 If @code{flag} is not a null pointer, it should be the address of an
 199 @code{int} variable which is the flag for this option.  The value in
 200 @code{val} is the value to store in the flag to indicate that the option
 201 was seen.
 202 @end table
 203 @end deftp
 204
 205 @comment getopt.h
 206 @comment GNU
 207 @deftypefun int getopt_long (int @var{argc}, char **@var{argv}, const char *@var{shortopts}, struct option *@var{longopts}, int *@var{indexptr})
 208 Decode options from the vector @var{argv} (whose length is @var{argc}).
 209 The argument @var{shortopts} describes the short options to accept, just as
 210 it does in @code{getopt}.  The argument @var{longopts} describes the long
 211 options to accept (see above).
 212
 213 When @code{getopt_long} encounters a short option, it does the same
 214 thing that @code{getopt} would do: it returns the character code for the
 215 option, and stores the options argument (if it has one) in @code{optarg}.
 216
 217 When @code{getopt_long} encounters a long option, it takes actions based
 218 on the @code{flag} and @code{val} fields of the definition of that
 219 option.
 220
 221 If @code{flag} is a null pointer, then @code{getopt_long} returns the
 222 contents of @code{val} to indicate which option it found.  You should
 223 arrange distinct values in the @code{val} field for options with
 224 different meanings, so you can decode these values after
 225 @code{getopt_long} returns.  If the long option is equivalent to a short
 226 option, you can use the short option's character code in @code{val}.
 227
 228 If @code{flag} is not a null pointer, that means this option should just
 229 set a flag in the program.  The flag is a variable of type @code{int}
 230 that you define.  Put the address of the flag in the @code{flag} field.
 231 Put in the @code{val} field the value you would like this option to
 232 store in the flag.  In this case, @code{getopt_long} returns @code{0}.
 233
 234 For any long option, @code{getopt_long} tells you the index in the array
 235 @var{longopts} of the options definition, by storing it into
 236 @code{*@var{indexptr}}.  You can get the name of the option with
 237 @code{@var{longopts}[*@var{indexptr}].name}.  So you can distinguish among
 238 long options either by the values in their @code{val} fields or by their
 239 indices.  You can also distinguish in this way among long options that
 240 set flags.
 241
 242 When a long option has an argument, @code{getopt_long} puts the argument
 243 value in the variable @code{optarg} before returning.  When the option
 244 has no argument, the value in @code{optarg} is a null pointer.  This is
 245 how you can tell whether an optional argument was supplied.
 246
 247 When @code{getopt_long} has no more options to handle, it returns
 248 @code{-1}, and leaves in the variable @code{optind} the index in
 249 @var{argv} of the next remaining argument.
 250 @end deftypefun
 251
 252 @node Getopt Long Option Example
 253 @subsection Example of Parsing Long Options with @code{getopt_long}
 254
 255 @smallexample
 256 @include longopt.c.texi
 257 @end smallexample