]>
Commit | Line | Data |
---|---|---|
00388ebc | 1 | .TH GETOPT "1" "June 2012" "util-linux" "User Commands" |
2b6fc908 KZ |
2 | .SH NAME |
3 | getopt \- parse command options (enhanced) | |
4 | .SH SYNOPSIS | |
e009d808 BS |
5 | .BI getopt |
6 | .I optstring parameters | |
09a47014 | 7 | .br |
e009d808 BS |
8 | .B getopt |
9 | .RI [ options ] | |
10 | .RB [ \-\- ] | |
11 | .I optstring parameters | |
09a47014 | 12 | .br |
e009d808 BS |
13 | .B getopt |
14 | .RI [ options ] | |
15 | .BR \-o | \-\-options | |
16 | .I optstring | |
17 | .RI [ options ] | |
18 | .RB [ \-\- ] | |
09a47014 | 19 | .I parameters |
2b6fc908 KZ |
20 | .SH DESCRIPTION |
21 | .B getopt | |
09a47014 | 22 | is used to break up |
2b6fc908 | 23 | .RI ( parse ) |
00388ebc SK |
24 | options in command lines for easy parsing by shell procedures, and to |
25 | check for legal options. It uses the | |
2b6fc908 | 26 | .SM GNU |
09a47014 | 27 | .BR getopt (3) |
2b6fc908 | 28 | routines to do this. |
00388ebc | 29 | .PP |
09a47014 | 30 | The parameters |
2b6fc908 | 31 | .B getopt |
00388ebc | 32 | is called with can be divided into two parts: options which modify |
e009d808 BS |
33 | the way |
34 | .B getopt | |
35 | will do the parsing | |
36 | .RI "(the " options | |
37 | and the | |
09a47014 PB |
38 | .I optstring |
39 | in the | |
40 | .BR SYNOPSIS ), | |
00388ebc | 41 | and the parameters which are to be parsed |
2b6fc908 | 42 | .RI ( parameters |
09a47014 PB |
43 | in the |
44 | .BR SYNOPSIS ). | |
00388ebc SK |
45 | The second part will start at the first non\-option parameter that is |
46 | not an option argument, or after the first occurrence of | |
47 | .RB ' \-\- '. | |
09a47014 | 48 | If no |
00388ebc | 49 | .RB ' \-o ' |
09a47014 | 50 | or |
00388ebc SK |
51 | .RB ' \-\-options ' |
52 | option is found in the first part, the first parameter of the second | |
53 | part is used as the short options string. | |
54 | .PP | |
2b6fc908 KZ |
55 | If the environment variable |
56 | .B GETOPT_COMPATIBLE | |
e009d808 | 57 | is set, or if the first \fIparameter\fR is not an option (does not start |
00388ebc SK |
58 | with a |
59 | .RB ' \- ', | |
e009d808 | 60 | the first format in the |
00388ebc | 61 | .BR SYNOPSIS ), |
2b6fc908 | 62 | .B getopt |
09a47014 PB |
63 | will generate output that is compatible with that of other versions of |
64 | .BR getopt (1). | |
00388ebc SK |
65 | It will still do parameter shuffling and recognize optional arguments |
66 | (see section | |
2b6fc908 | 67 | .B COMPATIBILITY |
09a47014 | 68 | for more information). |
00388ebc | 69 | .PP |
2b6fc908 KZ |
70 | Traditional implementations of |
71 | .BR getopt (1) | |
00388ebc SK |
72 | are unable to cope with whitespace and other (shell\-specific) |
73 | special characters in arguments and non\-option parameters. To solve | |
74 | this problem, this implementation can generate quoted output which | |
75 | must once again be interpreted by the shell (usually by using the | |
2b6fc908 | 76 | .B eval |
00388ebc | 77 | command). This has the effect of preserving those characters, but |
09a47014 | 78 | you must call |
2b6fc908 | 79 | .B getopt |
09a47014 PB |
80 | in a way that is no longer compatible with other versions (the second |
81 | or third format in the | |
82 | .BR SYNOPSIS ). | |
2b6fc908 KZ |
83 | To determine whether this enhanced version of |
84 | .BR getopt (1) | |
85 | is installed, a special test option | |
09a47014 | 86 | .RB ( \-T ) |
2b6fc908 KZ |
87 | can be used. |
88 | .SH OPTIONS | |
09a47014 PB |
89 | .TP |
90 | .BR \-a , " \-\-alternative" | |
91 | Allow long options to start with a single | |
00388ebc | 92 | .RB ' \- '. |
09a47014 PB |
93 | .TP |
94 | .BR \-h , " \-\-help" | |
b4362b6f | 95 | Display help text and exit. No other output is generated. |
09a47014 PB |
96 | .TP |
97 | .BR \-l , " \-\-longoptions \fIlongopts\fP" | |
00388ebc SK |
98 | The long (multi\-character) options to be recognized. More than one |
99 | option name may be specified at once, by separating the names with | |
100 | commas. This option may be given more than once, the | |
09a47014 | 101 | .I longopts |
00388ebc | 102 | are cumulative. Each long option name in |
09a47014 | 103 | .I longopts |
00388ebc SK |
104 | may be followed by one colon to indicate it has a required argument, |
105 | and by two colons to indicate it has an optional argument. | |
09a47014 PB |
106 | .TP |
107 | .BR \-n , " \-\-name \fIprogname\fP" | |
108 | The name that will be used by the | |
2b6fc908 | 109 | .BR getopt (3) |
00388ebc | 110 | routines when it reports errors. Note that errors of |
2b6fc908 KZ |
111 | .BR getopt (1) |
112 | are still reported as coming from getopt. | |
09a47014 PB |
113 | .TP |
114 | .BR \-o , " \-\-options \fIshortopts\fP" | |
00388ebc SK |
115 | The short (one\-character) options to be recognized. If this option |
116 | is not found, the first parameter of | |
09a47014 | 117 | .B getopt |
00388ebc SK |
118 | that does not start with a |
119 | .RB ' \- ' | |
2b6fc908 | 120 | (and is not an option argument) is used as the short options string. |
00388ebc | 121 | Each short option character in |
09a47014 | 122 | .I shortopts |
2b6fc908 | 123 | may be followed by one colon to indicate it has a required argument, |
00388ebc SK |
124 | and by two colons to indicate it has an optional argument. The first |
125 | character of shortopts may be | |
126 | .RB ' + ' | |
2b6fc908 | 127 | or |
00388ebc SK |
128 | .RB ' \- ' |
129 | to influence the way options are parsed and output is generated (see | |
130 | section | |
2b6fc908 KZ |
131 | .B SCANNING MODES |
132 | for details). | |
09a47014 PB |
133 | .TP |
134 | .BR \-q , " \-\-quiet" | |
2b6fc908 | 135 | Disable error reporting by getopt(3). |
09a47014 PB |
136 | .TP |
137 | .BR \-Q , " \-\-quiet\-output" | |
00388ebc | 138 | Do not generate normal output. Errors are still reported by |
09a47014 PB |
139 | .BR getopt (3), |
140 | unless you also use | |
e009d808 | 141 | .BR \-q . |
09a47014 PB |
142 | .TP |
143 | .BR \-s , " \-\-shell \fIshell\fP" | |
e009d808 BS |
144 | Set quoting conventions to those of \fIshell\fR. |
145 | If the \fB\-s\fR option is not given, the | |
2b6fc908 | 146 | .SM BASH |
00388ebc SK |
147 | conventions are used. Valid arguments are currently |
148 | .RB ' sh ' | |
149 | .RB ' bash ', | |
150 | .RB ' csh ', | |
2b6fc908 | 151 | and |
00388ebc | 152 | .RB ' tcsh '. |
09a47014 PB |
153 | .TP |
154 | .BR \-u , " \-\-unquoted" | |
00388ebc SK |
155 | Do not quote the output. Note that whitespace and special |
156 | (shell\-dependent) characters can cause havoc in this mode (like they | |
157 | do with other | |
2b6fc908 KZ |
158 | .BR getopt (1) |
159 | implementations). | |
09a47014 PB |
160 | .TP |
161 | .BR \-T , " \-\-test" | |
162 | Test if your | |
163 | .BR getopt (1) | |
00388ebc SK |
164 | is this enhanced version or an old version. This generates no |
165 | output, and sets the error status to 4. Other implementations of | |
2b6fc908 KZ |
166 | .BR getopt (1), |
167 | and this version if the environment variable | |
168 | .B GETOPT_COMPATIBLE | |
00388ebc SK |
169 | is set, will return |
170 | .RB ' \-\- ' | |
2b6fc908 | 171 | and error status 0. |
09a47014 PB |
172 | .TP |
173 | .BR \-V , " \-\-version" | |
b4362b6f | 174 | Display version information and exit. No other output is generated. |
2b6fc908 | 175 | .SH PARSING |
00388ebc SK |
176 | This section specifies the format of the second part of the |
177 | parameters of | |
2b6fc908 | 178 | .B getopt |
09a47014 PB |
179 | (the |
180 | .I parameters | |
181 | in the | |
182 | .BR SYNOPSIS ). | |
183 | The next section | |
184 | .RB ( OUTPUT ) | |
00388ebc SK |
185 | describes the output that is generated. These parameters were |
186 | typically the parameters a shell function was called with. Care must | |
187 | be taken that each parameter the shell function was called with | |
188 | corresponds to exactly one parameter in the parameter list of | |
09a47014 PB |
189 | .B getopt |
190 | (see the | |
191 | .BR EXAMPLES ). | |
192 | All parsing is done by the GNU | |
193 | .BR getopt (3) | |
194 | routines. | |
00388ebc SK |
195 | .PP |
196 | The parameters are parsed from left to right. Each parameter is | |
197 | classified as a short option, a long option, an argument to an | |
198 | option, or a non\-option parameter. | |
199 | .PP | |
09a47014 | 200 | A simple short option is a |
00388ebc SK |
201 | .RB ' \- ' |
202 | followed by a short option character. If the option has a required | |
203 | argument, it may be written directly after the option character or as | |
e009d808 | 204 | the next parameter (i.e. separated by whitespace on the command |
00388ebc SK |
205 | line). If the option has an optional argument, it must be written |
206 | directly after the option character if present. | |
207 | .PP | |
09a47014 | 208 | It is possible to specify several short options after one |
00388ebc SK |
209 | .RB ' \- ', |
210 | as long as all (except possibly the last) do not have required or | |
211 | optional arguments. | |
212 | .PP | |
09a47014 | 213 | A long option normally begins with |
00388ebc SK |
214 | .RB ' \-\- ' |
215 | followed by the long option name. If the option has a required | |
216 | argument, it may be written directly after the long option name, | |
217 | separated by | |
218 | .RB ' = ', | |
219 | or as the next argument (i.e. separated by whitespace on the command | |
220 | line). If the option has an optional argument, it must be written | |
221 | directly after the long option name, separated by | |
222 | .RB ' = ', | |
09a47014 | 223 | if present (if you add the |
00388ebc SK |
224 | .RB ' = ' |
225 | but nothing behind it, it is interpreted as if no argument was | |
226 | present; this is a slight bug, see the | |
2b6fc908 KZ |
227 | .BR BUGS ). |
228 | Long options may be abbreviated, as long as the abbreviation is not | |
229 | ambiguous. | |
00388ebc | 230 | .PP |
09a47014 | 231 | Each parameter not starting with a |
00388ebc SK |
232 | .RB ' \- ', |
233 | and not a required argument of a previous option, is a non\-option | |
234 | parameter. Each parameter after a | |
235 | .RB ' \-\- ' | |
236 | parameter is always interpreted as a non\-option parameter. If the | |
237 | environment variable | |
09a47014 | 238 | .B POSIXLY_CORRECT |
00388ebc SK |
239 | is set, or if the short option string started with a |
240 | .RB ' + ', | |
241 | all remaining parameters are interpreted as non\-option parameters as | |
242 | soon as the first non\-option parameter is found. | |
2b6fc908 | 243 | .SH OUTPUT |
00388ebc SK |
244 | Output is generated for each element described in the previous |
245 | section. Output is done in the same order as the elements are | |
246 | specified in the input, except for non\-option parameters. Output | |
247 | can be done in | |
09a47014 | 248 | .I compatible |
2b6fc908 | 249 | .RI ( unquoted ) |
00388ebc SK |
250 | mode, or in such way that whitespace and other special characters |
251 | within arguments and non\-option parameters are preserved (see | |
2b6fc908 KZ |
252 | .BR QUOTING ). |
253 | When the output is processed in the shell script, it will seem to be | |
00388ebc SK |
254 | composed of distinct elements that can be processed one by one (by |
255 | using the shift command in most shell languages). This is imperfect | |
256 | in unquoted mode, as elements can be split at unexpected places if | |
257 | they contain whitespace or special characters. | |
258 | .PP | |
2b6fc908 | 259 | If there are problems parsing the parameters, for example because a |
00388ebc SK |
260 | required argument is not found or an option is not recognized, an |
261 | error will be reported on stderr, there will be no output for the | |
262 | offending element, and a non\-zero error status is returned. | |
263 | .PP | |
09a47014 | 264 | For a short option, a single |
00388ebc SK |
265 | .RB ' \- ' |
266 | and the option character are generated as one parameter. If the | |
267 | option has an argument, the next parameter will be the argument. If | |
268 | the option takes an optional argument, but none was found, the next | |
269 | parameter will be generated but be empty in quoting mode, but no | |
270 | second parameter will be generated in unquoted (compatible) mode. | |
09a47014 PB |
271 | Note that many other |
272 | .BR getopt (1) | |
0c1a6f88 | 273 | implementations do not support optional arguments. |
00388ebc | 274 | .PP |
09a47014 | 275 | If several short options were specified after a single |
00388ebc | 276 | .RB ' \- ', |
2b6fc908 | 277 | each will be present in the output as a separate parameter. |
00388ebc | 278 | .PP |
09a47014 | 279 | For a long option, |
00388ebc SK |
280 | .RB ' \-\- ' |
281 | and the full option name are generated as one parameter. This is | |
282 | done regardless whether the option was abbreviated or specified with | |
283 | a single | |
284 | .RB ' \- ' | |
285 | in the input. Arguments are handled as with short options. | |
286 | .PP | |
287 | Normally, no non\-option parameters output is generated until all | |
288 | options and their arguments have been generated. Then | |
289 | .RB ' \-\- ' | |
290 | is generated as a single parameter, and after it the non\-option | |
291 | parameters in the order they were found, each as a separate | |
292 | parameter. Only if the first character of the short options string | |
293 | was a | |
294 | .RB ' \- ', | |
295 | non\-option parameter output is generated at the place they are found | |
296 | in the input (this is not supported if the first format of the | |
2b6fc908 | 297 | .B SYNOPSIS |
b22550fa | 298 | is used; in that case all preceding occurrences of |
00388ebc | 299 | .RB ' \- ' |
09a47014 | 300 | and |
00388ebc | 301 | .RB ' + ' |
09a47014 | 302 | are ignored). |
2b6fc908 | 303 | .SH QUOTING |
00388ebc SK |
304 | In compatible mode, whitespace or 'special' characters in arguments |
305 | or non\-option parameters are not handled correctly. As the output | |
306 | is fed to the shell script, the script does not know how it is | |
307 | supposed to break the output into separate parameters. To circumvent | |
308 | this problem, this implementation offers quoting. The idea is that | |
309 | output is generated with quotes around each parameter. When this | |
310 | output is once again fed to the shell (usually by a shell | |
09a47014 | 311 | .B eval |
2b6fc908 | 312 | command), it is split correctly into separate parameters. |
00388ebc | 313 | .PP |
2b6fc908 KZ |
314 | Quoting is not enabled if the environment variable |
315 | .B GETOPT_COMPATIBLE | |
316 | is set, if the first form of the | |
317 | .B SYNOPSIS | |
318 | is used, or if the option | |
00388ebc | 319 | .RB ' \-u ' |
2b6fc908 | 320 | is found. |
00388ebc SK |
321 | .PP |
322 | Different shells use different quoting conventions. You can use the | |
323 | .RB ' \-s ' | |
324 | option to select the shell you are using. The following shells are | |
2b6fc908 | 325 | currently supported: |
00388ebc SK |
326 | .RB ' sh ', |
327 | .RB ' bash ', | |
328 | .RB ' csh ' | |
2b6fc908 | 329 | and |
00388ebc SK |
330 | .RB ' tcsh '. |
331 | Actually, only two 'flavors' are distinguished: sh\-like quoting | |
332 | conventions and csh\-like quoting conventions. Chances are that if | |
333 | you use another shell script language, one of these flavors can still | |
334 | be used. | |
2b6fc908 KZ |
335 | .SH "SCANNING MODES" |
336 | The first character of the short options string may be a | |
00388ebc | 337 | .RB ' \- ' |
2b6fc908 | 338 | or a |
00388ebc SK |
339 | .RB ' + ' |
340 | to indicate a special scanning mode. If the first calling form in | |
341 | the | |
09a47014 | 342 | .B SYNOPSIS |
2b6fc908 KZ |
343 | is used they are ignored; the environment variable |
344 | .B POSIXLY_CORRECT | |
345 | is still examined, though. | |
00388ebc | 346 | .PP |
09a47014 | 347 | If the first character is |
00388ebc | 348 | .RB ' + ', |
09a47014 | 349 | or if the environment variable |
2b6fc908 | 350 | .B POSIXLY_CORRECT |
e009d808 BS |
351 | is set, parsing stops as soon as the first non\-option parameter |
352 | (i.e. a parameter that does not start with a | |
00388ebc SK |
353 | .RB ' \- ') |
354 | is found that is not an option argument. The remaining parameters | |
355 | are all interpreted as non\-option parameters. | |
356 | .PP | |
2b6fc908 | 357 | If the first character is a |
00388ebc SK |
358 | .RB ' \- ', |
359 | non\-option parameters are outputted at the place where they are | |
360 | found; in normal operation, they are all collected at the end of | |
361 | output after a | |
362 | .RB ' \-\- ' | |
363 | parameter has been generated. Note that this | |
364 | .RB ' \-\- ' | |
365 | parameter is still generated, but it will always be the last | |
366 | parameter in this mode. | |
2b6fc908 | 367 | .SH COMPATIBILITY |
09a47014 | 368 | This version of |
2b6fc908 | 369 | .BR getopt (1) |
00388ebc SK |
370 | is written to be as compatible as possible to other versions. |
371 | Usually you can just replace them with this version without any | |
372 | modifications, and with some advantages. | |
373 | .PP | |
09a47014 | 374 | If the first character of the first parameter of getopt is not a |
00388ebc | 375 | .RB ' \- ', |
e009d808 BS |
376 | .B getopt |
377 | goes into compatibility mode. It will interpret its first | |
00388ebc | 378 | parameter as the string of short options, and all other arguments |
e009d808 BS |
379 | will be parsed. It will still do parameter shuffling (i.e. all |
380 | non\-option parameters are output at the end), unless the | |
00388ebc | 381 | environment variable |
09a47014 | 382 | .B POSIXLY_CORRECT |
2b6fc908 | 383 | is set. |
00388ebc | 384 | .PP |
09a47014 PB |
385 | The environment variable |
386 | .B GETOPT_COMPATIBLE | |
387 | forces | |
2b6fc908 | 388 | .B getopt |
00388ebc | 389 | into compatibility mode. Setting both this environment variable and |
2b6fc908 | 390 | .B POSIXLY_CORRECT |
00388ebc | 391 | offers 100% compatibility for 'difficult' programs. Usually, though, |
2b6fc908 | 392 | neither is needed. |
00388ebc | 393 | .PP |
09a47014 | 394 | In compatibility mode, leading |
00388ebc | 395 | .RB ' \- ' |
09a47014 | 396 | and |
00388ebc | 397 | .RB ' + ' |
2b6fc908 KZ |
398 | characters in the short options string are ignored. |
399 | .SH RETURN CODES | |
400 | .B getopt | |
09a47014 PB |
401 | returns error code |
402 | .B 0 | |
0c1a6f88 | 403 | for successful parsing, |
2b6fc908 KZ |
404 | .B 1 |
405 | if | |
406 | .BR getopt (3) | |
407 | returns errors, | |
09a47014 | 408 | .B 2 |
2b6fc908 KZ |
409 | if it does not understand its own parameters, |
410 | .B 3 | |
df1dddf9 | 411 | if an internal error occurs like out\-of\-memory, and |
2b6fc908 | 412 | .B 4 |
09a47014 | 413 | if it is called with |
df1dddf9 | 414 | .BR \-T . |
2b6fc908 KZ |
415 | .SH EXAMPLES |
416 | Example scripts for (ba)sh and (t)csh are provided with the | |
417 | .BR getopt (1) | |
09a47014 | 418 | distribution, and are optionally installed in |
e009d808 BS |
419 | .BR /usr/share/getopt/ |
420 | or | |
ad1d426a | 421 | .BR /usr/share/doc/ |
e009d808 | 422 | in the util-linux subdirectory. |
2b6fc908 KZ |
423 | .SH ENVIRONMENT |
424 | .IP POSIXLY_CORRECT | |
425 | This environment variable is examined by the | |
426 | .BR getopt (3) | |
00388ebc SK |
427 | routines. If it is set, parsing stops as soon as a parameter is |
428 | found that is not an option or an option argument. All remaining | |
df1dddf9 | 429 | parameters are also interpreted as non\-option parameters, regardless |
09a47014 | 430 | whether they start with a |
00388ebc | 431 | .RB ' \- '. |
2b6fc908 KZ |
432 | .IP GETOPT_COMPATIBLE |
433 | Forces | |
434 | .B getopt | |
435 | to use the first calling format as specified in the | |
436 | .BR SYNOPSIS . | |
437 | .SH BUGS | |
438 | .BR getopt (3) | |
00388ebc SK |
439 | can parse long options with optional arguments that are given an |
440 | empty optional argument (but can not do this for short options). | |
441 | This | |
2b6fc908 KZ |
442 | .BR getopt (1) |
443 | treats optional arguments that are empty as if they were not present. | |
00388ebc | 444 | .PP |
66ee8158 | 445 | The syntax if you do not want any short option variables at all is |
0c1a6f88 | 446 | not very intuitive (you have to set them explicitly to the empty |
66ee8158 | 447 | string). |
2b6fc908 | 448 | .SH AUTHOR |
00388ebc SK |
449 | .MT frodo@frodo.looijaard.name |
450 | Frodo Looijaard | |
451 | .ME | |
2b6fc908 KZ |
452 | .SH "SEE ALSO" |
453 | .BR getopt (3), | |
454 | .BR bash (1), | |
455 | .BR tcsh (1). | |
86d62711 | 456 | .SH AVAILABILITY |
601d12fb | 457 | The getopt command is part of the util-linux package and is available from |
00388ebc SK |
458 | .UR ftp://\:ftp.kernel.org\:/pub\:/linux\:/utils\:/util-linux/ |
459 | Linux Kernel Archive | |
460 | .UE . |