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