Correct values for INTFAST_MIN, INTFAST_MAX, and UINTFAST_MAX.
[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.
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