(argz_delete): Fix prototype.
[kopensolaris-gnu/glibc.git] / 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.  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