summaryrefslogtreecommitdiff
path: root/manual/getopt.texi
blob: 5485fc46946631f73aea71d6da3fa77f8bbe2462 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
@node Getopt, Argp, , Parsing Program Arguments
@section Parsing program options using @code{getopt}

The @code{getopt} and @code{getopt_long} functions automate some of the
chore involved in parsing typical unix command line options.

@menu
* Using Getopt::                Using the @code{getopt} function.
* Example of Getopt::           An example of parsing options with @code{getopt}.
* Getopt Long Options::         GNU suggests utilities accept long-named
                                 options; here is one way to do.
* Getopt Long Option Example::  An example of using @code{getopt_long}.
@end menu

@node Using Getopt, Example of Getopt, , Getopt
@subsection Using the @code{getopt} function

Here are the details about how to call the @code{getopt} function.  To
use this facility, your program must include the header file
@file{unistd.h}.
@pindex unistd.h

@deftypevar int opterr
@standards{POSIX.2, unistd.h}
If the value of this variable is nonzero, then @code{getopt} prints an
error message to the standard error stream if it encounters an unknown
option character or an option with a missing required argument.  This is
the default behavior.  If you set this variable to zero, @code{getopt}
does not print any messages, but it still returns the character @code{?}
to indicate an error.
@end deftypevar

@deftypevar int optopt
@standards{POSIX.2, unistd.h}
When @code{getopt} encounters an unknown option character or an option
with a missing required argument, it stores that option character in
this variable.  You can use this for providing your own diagnostic
messages.
@end deftypevar

@deftypevar int optind
@standards{POSIX.2, unistd.h}
This variable is set by @code{getopt} to the index of the next element
of the @var{argv} array to be processed.  Once @code{getopt} has found
all of the option arguments, you can use this variable to determine
where the remaining non-option arguments begin.  The initial value of
this variable is @code{1}.
@end deftypevar

@deftypevar {char *} optarg
@standards{POSIX.2, unistd.h}
This variable is set by @code{getopt} to point at the value of the
option argument, for those options that accept arguments.
@end deftypevar

@deftypefun int getopt (int @var{argc}, char *const *@var{argv}, const char *@var{options})
@standards{POSIX.2, unistd.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:getopt} @mtsenv{}}@asunsafe{@ascuheap{} @ascuintl{} @asulock{} @asucorrupt{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
@c Swapping elements of passed-in argv may be partial in case of
@c cancellation.  Gettext brings about a whole lot of AS and AC safety
@c issues.  The getopt API involves returning values in the
@c non-thread-specific optarg variable, which adds another thread-safety
@c issue.  Given print_errors, it may output errors to stderr, which may
@c self-deadlock, leak locks, or encounter (in a signal handler) or
@c leave (in case of cancellation) stderr in an inconsistent state.
@c Various implicit, indirect uses of malloc, in uses of memstream and
@c asprintf for error-printing, bring about the usual malloc issues.
@c
@c _getopt_internal
@c  _getopt_internal_r
@c   gettext
@c   _getopt_initialize
@c    getenv
@c   open_memstream
@c   lockfile, unlockfile, __fxprintf -> stderr
@c   asprintf
The @code{getopt} function gets the next option argument from the
argument list specified by the @var{argv} and @var{argc} arguments.
Normally these values come directly from the arguments received by
@code{main}.

The @var{options} argument is a string that specifies the option
characters that are valid for this program.  An option character in this
string can be followed by a colon (@samp{:}) to indicate that it takes a
required argument.  If an option character is followed by two colons
(@samp{::}), its argument is optional; this is a GNU extension.

@code{getopt} has three ways to deal with options that follow
non-options @var{argv} elements.  The special argument @samp{--} forces
in all cases the end of option scanning.

@itemize @bullet
@item
The default is to permute the contents of @var{argv} while scanning it
so that eventually all the non-options are at the end.  This allows
options to be given in any order, even with programs that were not
written to expect this.

@item
If the @var{options} argument string begins with a hyphen (@samp{-}), this
is treated specially.  It permits arguments that are not options to be
returned as if they were associated with option character @samp{\1}.

@item
POSIX demands the following behavior: the first non-option stops option
processing.  This mode is selected by either setting the environment
variable @code{POSIXLY_CORRECT} or beginning the @var{options} argument
string with a plus sign (@samp{+}).
@end itemize

The @code{getopt} function returns the option character for the next
command line option.  When no more option arguments are available, it
returns @code{-1}.  There may still be more non-option arguments; you
must compare the external variable @code{optind} against the @var{argc}
parameter to check this.

If the option has an argument, @code{getopt} returns the argument by
storing it in the variable @var{optarg}.  You don't ordinarily need to
copy the @code{optarg} string, since it is a pointer into the original
@var{argv} array, not into a static area that might be overwritten.

If @code{getopt} finds an option character in @var{argv} that was not
included in @var{options}, or a missing option argument, it returns
@samp{?} and sets the external variable @code{optopt} to the actual
option character.  If the first character of @var{options} is a colon
(@samp{:}), then @code{getopt} returns @samp{:} instead of @samp{?} to
indicate a missing option argument.  In addition, if the external
variable @code{opterr} is nonzero (which is the default), @code{getopt}
prints an error message.
@end deftypefun

@node Example of Getopt
@subsection Example of Parsing Arguments with @code{getopt}

Here is an example showing how @code{getopt} is typically used.  The
key points to notice are:

@itemize @bullet
@item
Normally, @code{getopt} is called in a loop.  When @code{getopt} returns
@code{-1}, indicating no more options are present, the loop terminates.

@item
A @code{switch} statement is used to dispatch on the return value from
@code{getopt}.  In typical use, each case just sets a variable that
is used later in the program.

@item
A second loop is used to process the remaining non-option arguments.
@end itemize

@smallexample
@include testopt.c.texi
@end smallexample

Here are some examples showing what this program prints with different
combinations of arguments:

@smallexample
% testopt
aflag = 0, bflag = 0, cvalue = (null)

% testopt -a -b
aflag = 1, bflag = 1, cvalue = (null)

% testopt -ab
aflag = 1, bflag = 1, cvalue = (null)

% testopt -c foo
aflag = 0, bflag = 0, cvalue = foo

% testopt -cfoo
aflag = 0, bflag = 0, cvalue = foo

% testopt arg1
aflag = 0, bflag = 0, cvalue = (null)
Non-option argument arg1

% testopt -a arg1
aflag = 1, bflag = 0, cvalue = (null)
Non-option argument arg1

% testopt -c foo arg1
aflag = 0, bflag = 0, cvalue = foo
Non-option argument arg1

% testopt -a -- -b
aflag = 1, bflag = 0, cvalue = (null)
Non-option argument -b

% testopt -a -
aflag = 1, bflag = 0, cvalue = (null)
Non-option argument -
@end smallexample

@node Getopt Long Options
@subsection Parsing Long Options with @code{getopt_long}

To accept GNU-style long options as well as single-character options,
use @code{getopt_long} instead of @code{getopt}.  This function is
declared in @file{getopt.h}, not @file{unistd.h}.  You should make every
program accept long options if it uses any options, for this takes
little extra work and helps beginners remember how to use the program.

@deftp {Data Type} {struct option}
@standards{GNU, getopt.h}
This structure describes a single long option name for the sake of
@code{getopt_long}.  The argument @var{longopts} must be an array of
these structures, one for each long option.  Terminate the array with an
element containing all zeros.

The @code{struct option} structure has these fields:

@table @code
@item const char *name
This field is the name of the option.  It is a string.

@item int has_arg
This field says whether the option takes an argument.  It is an integer,
and there are three legitimate values: @w{@code{no_argument}},
@code{required_argument} and @code{optional_argument}.

@item int *flag
@itemx int val
These fields control how to report or act on the option when it occurs.

If @code{flag} is a null pointer, then the @code{val} is a value which
identifies this option.  Often these values are chosen to uniquely
identify particular long options.

If @code{flag} is not a null pointer, it should be the address of an
@code{int} variable which is the flag for this option.  The value in
@code{val} is the value to store in the flag to indicate that the option
was seen.
@end table
@end deftp

@deftypefun int getopt_long (int @var{argc}, char *const *@var{argv}, const char *@var{shortopts}, const struct option *@var{longopts}, int *@var{indexptr})
@standards{GNU, getopt.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:getopt} @mtsenv{}}@asunsafe{@ascuheap{} @ascuintl{} @asulock{} @asucorrupt{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
@c Same issues as getopt.
Decode options from the vector @var{argv} (whose length is @var{argc}).
The argument @var{shortopts} describes the short options to accept, just as
it does in @code{getopt}.  The argument @var{longopts} describes the long
options to accept (see above).

When @code{getopt_long} encounters a short option, it does the same
thing that @code{getopt} would do: it returns the character code for the
option, and stores the option's argument (if it has one) in @code{optarg}.

When @code{getopt_long} encounters a long option, it takes actions based
on the @code{flag} and @code{val} fields of the definition of that
option.

If @code{flag} is a null pointer, then @code{getopt_long} returns the
contents of @code{val} to indicate which option it found.  You should
arrange distinct values in the @code{val} field for options with
different meanings, so you can decode these values after
@code{getopt_long} returns.  If the long option is equivalent to a short
option, you can use the short option's character code in @code{val}.

If @code{flag} is not a null pointer, that means this option should just
set a flag in the program.  The flag is a variable of type @code{int}
that you define.  Put the address of the flag in the @code{flag} field.
Put in the @code{val} field the value you would like this option to
store in the flag.  In this case, @code{getopt_long} returns @code{0}.

For any long option, @code{getopt_long} tells you the index in the array
@var{longopts} of the options definition, by storing it into
@code{*@var{indexptr}}.  You can get the name of the option with
@code{@var{longopts}[*@var{indexptr}].name}.  So you can distinguish among
long options either by the values in their @code{val} fields or by their
indices.  You can also distinguish in this way among long options that
set flags.

When a long option has an argument, @code{getopt_long} puts the argument
value in the variable @code{optarg} before returning.  When the option
has no argument, the value in @code{optarg} is a null pointer.  This is
how you can tell whether an optional argument was supplied.

When @code{getopt_long} has no more options to handle, it returns
@code{-1}, and leaves in the variable @code{optind} the index in
@var{argv} of the next remaining argument.
@end deftypefun

Since long option names were used before @code{getopt_long}
was invented there are program interfaces which require programs
to recognize options like @w{@samp{-option value}} instead of
@w{@samp{--option value}}.  To enable these programs to use the GNU
getopt functionality there is one more function available.

@deftypefun int getopt_long_only (int @var{argc}, char *const *@var{argv}, const char *@var{shortopts}, const struct option *@var{longopts}, int *@var{indexptr})
@standards{GNU, getopt.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:getopt} @mtsenv{}}@asunsafe{@ascuheap{} @ascuintl{} @asulock{} @asucorrupt{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
@c Same issues as getopt.

The @code{getopt_long_only} function is equivalent to the
@code{getopt_long} function but it allows the user of the
application to pass long options with only @samp{-} instead of
@samp{--}.  The @samp{--} prefix is still recognized but instead of
looking through the short options if a @samp{-} is seen it is first
tried whether this parameter names a long option.  If not, it is parsed
as a short option.

Assuming @code{getopt_long_only} is used starting an application with

@smallexample
  app -foo
@end smallexample

@noindent
the @code{getopt_long_only} will first look for a long option named
@samp{foo}.  If this is not found, the short options @samp{f}, @samp{o},
and again @samp{o} are recognized.
@end deftypefun

@node Getopt Long Option Example
@subsection Example of Parsing Long Options with @code{getopt_long}

@smallexample
@include longopt.c.texi
@end smallexample