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