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