1 .TH GETOPT 1 "May 31, 1997" Linux ""
3 getopt \- parse command options (enhanced)
6 .I optstring parameters
11 .I optstring parameters
24 options in command lines for easy parsing by
25 shell procedures, and to check for legal options.
33 is called with can be divided into two parts: options
34 which modify the way getopt will parse
41 and the parameters which are to be
46 The second part will start at the first non\-option parameter
47 that is not an option argument, or after the first occurrence of
53 option is found in the first part, the first
54 parameter of the second part is used as the short options string.
56 If the environment variable
58 is set, or if its first parameter
59 is not an option (does not start with a
61 this is the first format in the
64 will generate output that is compatible with that of other versions of
66 It will still do parameter shuffling and recognize optional
67 arguments (see section
69 for more information).
71 Traditional implementations of
73 are unable to cope with whitespace and other (shell\-specific) special characters
74 in arguments and non\-option parameters. To solve this problem, this
75 implementation can generate
76 quoted output which must once again be interpreted by the shell (usually
79 command). This has the effect of preserving those characters, but
82 in a way that is no longer compatible with other versions (the second
83 or third format in the
85 To determine whether this enhanced version of
87 is installed, a special test option
92 .BR \-a , " \-\-alternative"
93 Allow long options to start with a single
97 Output a small usage guide and exit successfully. No other output is generated.
99 .BR \-l , " \-\-longoptions \fIlongopts\fP"
100 The long (multi\-character) options to be recognized.
101 More than one option name
102 may be specified at once, by separating the names with commas. This option
103 may be given more than once, the
106 Each long option name
109 may be followed by one colon to indicate it has a required argument, and by two colons to indicate it has an optional argument.
111 .BR \-n , " \-\-name \fIprogname\fP"
112 The name that will be used by the
114 routines when it reports errors. Note that errors of
116 are still reported as coming from getopt.
118 .BR \-o , " \-\-options \fIshortopts\fP"
119 The short (one\-character) options to be recognized. If this option is not
120 found, the first parameter of
122 that does not start with
125 (and is not an option argument) is used as the short options string.
126 Each short option character
129 may be followed by one colon to indicate it has a required argument,
130 and by two colons to indicate it has an optional argument.
131 The first character of shortopts may be
136 options are parsed and output is generated (see section
140 .BR \-q , " \-\-quiet"
141 Disable error reporting by getopt(3).
143 .BR \-Q , " \-\-quiet\-output"
144 Do not generate normal output. Errors are still reported by
149 .BR \-s , " \-\-shell \fIshell\fP"
150 Set quoting conventions to those of shell. If no \-s argument is found,
153 conventions are used. Valid arguments are currently
160 .BR \-u , " \-\-unquoted"
161 Do not quote the output. Note that whitespace and special (shell\-dependent)
162 characters can cause havoc in this mode (like they do with other
166 .BR \-T , " \-\-test"
169 is this enhanced version or an old version. This generates no output,
170 and sets the error status to 4. Other implementations of
172 and this version if the environment variable
179 .BR \-V , " \-\-version"
180 Output version information and exit successfully. No other output is generated.
182 This section specifies the format of the second part of the parameters of
190 describes the output that is
191 generated. These parameters were typically the parameters a shell function
193 Care must be taken that each parameter the shell function was
194 called with corresponds to exactly one parameter in the parameter list of
198 All parsing is done by the GNU
202 The parameters are parsed from left to right. Each parameter is classified as a
203 short option, a long option, an argument to an option,
204 or a non\-option parameter.
206 A simple short option is a
208 followed by a short option character. If
209 the option has a required argument, it may be written directly after the option
210 character or as the next parameter (ie. separated by whitespace on the
211 command line). If the
212 option has an optional argument, it must be written directly after the
213 option character if present.
215 It is possible to specify several short options after one
217 as long as all (except possibly the last) do not have required or optional
220 A long option normally begins with
222 followed by the long option name.
223 If the option has a required argument, it may be written directly after
224 the long option name, separated by
226 or as the next argument (ie. separated by whitespace on the command line).
227 If the option has an optional argument, it must
228 be written directly after the long option name, separated by
230 if present (if you add the
232 but nothing behind it, it is interpreted
233 as if no argument was present; this is a slight bug, see the
235 Long options may be abbreviated, as long as the abbreviation is not
238 Each parameter not starting with a
240 and not a required argument of
241 a previous option, is a non\-option parameter. Each parameter after
244 parameter is always interpreted as a non\-option parameter.
245 If the environment variable
247 is set, or if the short
248 option string started with a
250 all remaining parameters are interpreted
251 as non\-option parameters as soon as the first non\-option parameter is
254 Output is generated for each element described in the previous section.
256 in the same order as the elements are specified in the input, except
257 for non\-option parameters. Output can be done in
260 mode, or in such way that whitespace and other special characters within
261 arguments and non\-option parameters are preserved (see
263 When the output is processed in the shell script, it will seem to be
264 composed of distinct elements that can be processed one by one (by using the
265 shift command in most shell languages). This is imperfect in unquoted mode,
266 as elements can be split at unexpected places if they contain whitespace
267 or special characters.
269 If there are problems parsing the parameters, for example because a
270 required argument is not found or an option is not recognized, an error
271 will be reported on stderr, there will be no output for the offending
272 element, and a non\-zero error status is returned.
274 For a short option, a single
276 and the option character are generated
277 as one parameter. If the option has an argument, the next
278 parameter will be the argument. If the option takes an optional argument,
279 but none was found, the next parameter will be generated but be empty in
281 but no second parameter will be generated in unquoted (compatible) mode.
284 implementations do not support optional arguments.
286 If several short options were specified after a single
288 each will be present in the output as a separate parameter.
292 and the full option name are generated as one
293 parameter. This is done regardless whether the option was abbreviated or
294 specified with a single
296 in the input. Arguments are handled as with short options.
298 Normally, no non\-option parameters output is generated until all options
299 and their arguments have been generated. Then
302 single parameter, and after it the non\-option parameters in the order
303 they were found, each as a separate parameter.
304 Only if the first character of the short options string was a
306 non\-option parameter output is generated at the place they are found in the
307 input (this is not supported if the first format of the
309 is used; in that case all preceding occurrences of
315 In compatible mode, whitespace or 'special' characters in arguments or
316 non\-option parameters are not handled correctly. As the output is
317 fed to the shell script, the script does not know how it is supposed to break
318 the output into separate parameters. To circumvent this
319 problem, this implementation offers quoting. The idea is that output
320 is generated with quotes around each parameter. When this output is once
321 again fed to the shell (usually by a shell
323 command), it is split correctly into separate parameters.
325 Quoting is not enabled if the environment variable
327 is set, if the first form of the
329 is used, or if the option
333 Different shells use different quoting conventions. You can use the
335 option to select the shell you are using. The following shells are
342 Actually, only two `flavors' are distinguished: sh\-like quoting conventions
343 and csh\-like quoting conventions. Chances are that if you use another shell
344 script language, one of these flavors can still be used.
347 The first character of the short options string may be a
351 to indicate a special scanning mode. If the first calling form
354 is used they are ignored; the environment variable
356 is still examined, though.
358 If the first character is
360 or if the environment variable
362 is set, parsing stops as soon as the first non\-option parameter
363 (ie. a parameter that does not start with a
366 is not an option argument. The remaining parameters are all interpreted as
367 non\-option parameters.
369 If the first character is a
371 non\-option parameters are outputted at the place where they are found; in normal
372 operation, they are all collected at the end of output after a
374 parameter has been generated. Note that this
376 parameter is still generated, but it will always be the last parameter in
381 is written to be as compatible as possible to
382 other versions. Usually you can just replace them with this version
383 without any modifications, and with some advantages.
385 If the first character of the first parameter of getopt is not a
387 getopt goes into compatibility mode. It will interpret its first parameter as
388 the string of short options, and all other arguments will be parsed. It
389 will still do parameter shuffling (ie. all non\-option parameters are outputted
390 at the end), unless the environment variable
394 The environment variable
398 into compatibility mode. Setting both this environment variable and
400 offers 100% compatibility for `difficult' programs. Usually, though,
403 In compatibility mode, leading
407 characters in the short options string are ignored.
412 for successful parsing,
418 if it does not understand its own parameters,
420 if an internal error occurs like out\-of\-memory, and
425 Example scripts for (ba)sh and (t)csh are provided with the
427 distribution, and are optionally installed in
428 .BR /usr/share/getopt .
432 This environment variable is examined by the
435 If it is set, parsing stops as soon as a parameter
436 is found that is not an option or an option argument. All remaining
437 parameters are also interpreted as non\-option parameters, regardless
438 whether they start with a
440 .IP GETOPT_COMPATIBLE
443 to use the first calling format as specified in the
447 can parse long options with optional arguments that are given an empty optional
448 argument (but can not do this for short options). This
450 treats optional arguments that are empty as if they were not present.
452 The syntax if you do not want any short option variables at all is
453 not very intuitive (you have to set them explicitly to the empty
457 Frodo Looijaard <frodo@frodo.looijaard.name>
463 The getopt command is part of the util-linux-ng package and is available from
464 ftp://ftp.kernel.org/pub/linux/utils/util-linux-ng/.