1GETOPT(1) GETOPT(1)
2
6 getopt - parse command options (enhanced)
7
9 getopt optstring parameters
10 getopt [options] [--] optstring parameters
12 getopt [options] -o|--options optstring [options] [--] parameters
14
16 getopt is used to break up (parse) options in command lines for easy
17 parsing by shell procedures, and to check for legal options. It uses
18 the GNU getopt(3) routines to do this.
19 The parameters getopt is called with can be divided into two parts:
21 options which modify the way getopt will parse (options and
22 -o|--options optstring in the SYNOPSIS), and the parameters which are
23 to be parsed (parameters in the SYNOPSIS). The second part will start
24 at the first non-option parameter that is not an option argument, or
25 after the first occurrence of `--'. If no `-o' or `--options' option
26 is found in the first part, the first parameter of the second part is
27 used as the short options string.
28 If the environment variable GETOPT_COMPATIBLE is set, or if its first
30 parameter is not an option (does not start with a `-', this is the
31 first format in the SYNOPSIS), getopt will generate output that is com‐
32 patible with that of other versions of getopt(1). It will still do
33 parameter shuffling and recognize optional arguments (see section COM‐
34 PATIBILITY for more information).
35 Traditional implementations of getopt(1) are unable to cope with white‐
37 space and other (shell-specific) special characters in arguments and
38 non-option parameters. To solve this problem, this implementation can
39 generate quoted output which must once again be interpreted by the
40 shell (usually by using the eval command). This has the effect of pre‐
41 serving those characters, but you must call getopt in a way that is no
42 longer compatible with other versions (the second or third format in
43 the SYNOPSIS). To determine whether this enhanced version of getopt(1)
44 is installed, a special test option (-T) can be used.
45
47 -a, --alternative
48 Allow long options to start with a single `-'.
49 -h, --help
51 Output a small usage guide and exit succesfully. No other output
52 is generated.
53 -l, --longoptions longopts
55 The long (multi-character) options to be recognized. More than
56 one option name may be specified at once, by separating the
57 names with commas. This option may be given more than once, the
58 longopts are cumulative. Each long option name in longopts may
59 be followed by one colon to indicate it has a required argu‐
60 ment,and by two colons to indicate it has an optional argument.
61 -n, --name progname
63 The name that will be used by the getopt(3) routines when it
64 reports errors. Note that errors of getopt(1) are still reported
65 as coming from getopt.
66 -o, --options shortopts
68 The short (one-character) options to be recognized. If this
69 option is not found, the first parameter of getopt that does not
70 start with a `-' (and is not an option argument) is used as the
71 short options string. Each short option character in shortopts
72 may be followed by one colon to indicate it has a required argu‐
73 ment, and by two colons to indicate it has an optional argument.
74 The first character of shortopts may be `+' or `-' to influence
75 the way options are parsed and output is generated (see section
76 SCANNING MODES for details).
77 -q, --quiet
79 Disable error reporting by getopt(3).
80 -Q, --quiet-output
82 Do not generate normal output. Errors are still reported by
83 getopt(3), unless you also use -q.
84 -s, --shell shell
86 Set quoting conventions to those of shell. If no -s argument is
87 found, the BASH conventions are used. Valid arguments are cur‐
88 rently `sh' `bash', `csh', and `tcsh'.
89 -u, --unquoted
91 Do not quote the output. Note that whitespace and special
92 (shell-dependent) characters can cause havoc in this mode (like
93 they do with other getopt(1) implementations).
94 -T --test
96 Test if your getopt(1) is this enhanced version or an old ver‐
97 sion. This generates no output, and sets the error status to 4.
98 Other implementations of getopt(1), and this version if the
99 environment variable GETOPT_COMPATIBLE is set, will return `--'
100 and error status 0.
101 -V, --version
103 Output version information and exit succesfully. No other output
104 is generated.
105
107 This section specifies the format of the second part of the parameters
108 of getopt (the parameters in the SYNOPSIS). The next section (OUTPUT)
109 describes the output that is generated. These parameters were typically
110 the parameters a shell function was called with. Care must be taken
111 that each parameter the shell function was called with corresponds to
112 exactly one parameter in the parameter list of getopt (see the EXAM‐
113 PLES). All parsing is done by the GNU getopt(3) routines.
114 The parameters are parsed from left to right. Each parameter is classi‐
116 fied as a short option, a long option, an argument to an option, or a
117 non-option parameter.
118 A simple short option is a `-' followed by a short option character. If
120 the option has a required argument, it may be written directly after
121 the option character or as the next parameter (ie. separated by white‐
122 space on the command line). If the option has an optional argument, it
123 must be written directly after the option character if present.
124 It is possible to specify several short options after one `-', as long
126 as all (except possibly the last) do not have required or optional
127 arguments.
128 A long option normally begins with `--' followed by the long option
130 name. If the option has a required argument, it may be written
131 directly after the long option name, separated by `=', or as the next
132 argument (ie. separated by whitespace on the command line). If the
133 option has an optional argument, it must be written directly after the
134 long option name, separated by `=', if present (if you add the `=' but
135 nothing behind it, it is interpreted as if no argument was present;
136 this is a slight bug, see the BUGS). Long options may be abbreviated,
137 as long as the abbreviation is not ambiguous.
138 Each parameter not starting with a `-', and not a required argument of
140 a previous option, is a non-option parameter. Each parameter after a
141 `--' parameter is always interpreted as a non-option parameter. If the
142 environment variable POSIXLY_CORRECT is set, or if the short option
143 string started with a `+', all remaining parameters are interpreted as
144 non-option parameters as soon as the first non-option parameter is
145 found.
146
148 Output is generated for each element described in the previous section.
149 Output is done in the same order as the elements are specified in the
150 input, except for non-option parameters. Output can be done in compati‐
151 ble (unquoted) mode, or in such way that whitespace and other special
152 characters within arguments and non-option parameters are preserved
153 (see QUOTING). When the output is processed in the shell script, it
154 will seem to be composed of distinct elements that can be processed one
155 by one (by using the shift command in most shell languages). This is
156 imperfect in unquoted mode, as elements can be split at unexpected
157 places if they contain whitespace or special characters.
158 If there are problems parsing the parameters, for example because a
160 required argument is not found or an option is not recognized, an error
161 will be reported on stderr, there will be no output for the offending
162 element, and a non-zero error status is returned.
163 For a short option, a single `-' and the option character are generated
165 as one parameter. If the option has an argument, the next parameter
166 will be the argument. If the option takes an optional argument, but
167 none was found, the next parameter will be generated but be empty in
168 quoting mode, but no second parameter will be generated in unquoted
169 (compatible) mode. Note that many other getopt(1) implemetations do
170 not support optional arguments.
171 If several short options were specified after a single `-', each will
173 be present in the output as a separate parameter.
174 For a long option, `--' and the full option name are generated as one
176 parameter. This is done regardless whether the option was abbreviated
177 or specified with a single `-' in the input. Arguments are handled as
178 with short options.
179 Normally, no non-option parameters output is generated until all
181 options and their arguments have been generated. Then `--' is generated
182 as a single parameter, and after it the non-option parameters in the
183 order they were found, each as a separate parameter. Only if the first
184 character of the short options string was a `-', non-option parameter
185 output is generated at the place they are found in the input (this is
186 not supported if the first format of the SYNOPSIS is used; in that case
187 all preceding occurrences of `-' and `+' are ignored).
188
190 In compatible mode, whitespace or 'special' characters in arguments or
191 non-option parameters are not handled correctly. As the output is fed
192 to the shell script, the script does not know how it is supposed to
193 break the output into separate parameters. To circumvent this problem,
194 this implementation offers quoting. The idea is that output is gener‐
195 ated with quotes around each parameter. When this output is once again
196 fed to the shell (usually by a shell eval command), it is split cor‐
197 rectly into separate parameters.
198 Quoting is not enabled if the environment variable GETOPT_COMPATIBLE is
200 set, if the first form of the SYNOPSIS is used, or if the option `-u'
201 is found.
202 Different shells use different quoting conventions. You can use the
204 `-s' option to select the shell you are using. The following shells are
205 currently supported: `sh', `bash', `csh' and `tcsh'. Actually, only
206 two `flavors' are distinguished: sh-like quoting conventions and
207 csh-like quoting conventions. Chances are that if you use another shell
208 script language, one of these flavors can still be used.
209
212 The first character of the short options string may be a `-' or a `+'
213 to indicate a special scanning mode. If the first calling form in the
214 SYNOPSIS is used they are ignored; the environment variable
215 POSIXLY_CORRECT is still examined, though.
216 If the first character is `+', or if the environment variable
218 POSIXLY_CORRECT is set, parsing stops as soon as the first non-option
219 parameter (ie. a parameter that does not start with a `-') is found
220 that is not an option argument. The remaining parameters are all inter‐
221 preted as non-option parameters.
222 If the first character is a `-', non-option parameters are outputed at
224 the place where they are found; in normal operation, they are all col‐
225 lected at the end of output after a `--' parameter has been generated.
226 Note that this `--' parameter is still generated, but it will always be
227 the last parameter in this mode.
228
230 This version of getopt(1) is written to be as compatible as possible to
231 other versions. Usually you can just replace them with this version
232 without any modifications, and with some advantages.
233 If the first character of the first parameter of getopt is not a `-',
235 getopt goes into compatibility mode. It will interpret its first param‐
236 eter as the string of short options, and all other arguments will be
237 parsed. It will still do parameter shuffling (ie. all non-option param‐
238 eters are outputed at the end), unless the environment variable
239 POSIXLY_CORRECT is set.
240 The environment variable GETOPT_COMPATIBLE forces getopt into compati‐
242 bility mode. Setting both this environment variable and POSIXLY_CORRECT
243 offers 100% compatibility for `difficult' programs. Usually, though,
244 neither is needed.
245 In compatibility mode, leading `-' and `+' characters in the short
247 options string are ignored.
248
250 getopt returns error code 0 for succesful parsing, 1 if getopt(3)
251 returns errors, 2 if it does not understand its own parameters, 3 if an
252 internal error occurs like out-of-memory, and 4 if it is called with
253 -T.
254
256 Example scripts for (ba)sh and (t)csh are provided with the getopt(1)
257 distribution, and are optionally installed in /usr/local/lib/getopt or
258 /usr/lib/getopt.
259
261 POSIXLY_CORRECT
262 This environment variable is examined by the getopt(3) routines.
263 If it is set, parsing stops as soon as a parameter is found that
264 is not an option or an option argument. All remaining parameters
265 are also interpreted as non-option parameters, regardless
266 whether they start with a `-'.
267 GETOPT_COMPATIBLE
269 Forces getopt to use the first calling format as specified in
270 the SYNOPSIS.
271
273 getopt(3) can parse long options with optional arguments that are given
274 an empty optional argument (but can not do this for short options).
275 This getopt(1) treats optional arguments that are empty as if they were
276 not present.
277 The syntax if you do not want any short option variables at all is not
279 very intuitive (you have to set them explicitely to the empty string).
280
283 Frodo Looijaard <frodo@frodo.looijaard.name>
284
286 getopt(3), bash(1), tcsh(1).
287Linux May 31, 1997 GETOPT(1)