]>
Commit | Line | Data |
---|---|---|
d7091d84 CW |
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 | ||
7 | .BR getopt " [options] [" -- "] optstring parameters" | |
8 | ||
9 | .BR getopt " [options] " -o | --options " optstring [options] [" -- "] parameters" | |
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 | |
27 | .I -o|--options optstring | |
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). | |
35 | The second part will start at the first non-option parameter | |
36 | that is not an option argument, or after the first occurence of | |
37 | .RB ` -- '. | |
38 | If no | |
39 | .RB ` -o ' | |
40 | or | |
41 | .RB ` --options ' | |
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 | |
49 | .RB ` - ', | |
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) | |
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 | |
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 | |
77 | .RB ( -T ) | |
78 | can be used. | |
79 | .SH OPTIONS | |
80 | .IP "-a, --alternative" | |
81 | Allow long options to start with a single | |
82 | .RB ` - '. | |
83 | .IP "-h, --help" | |
84 | Output a small usage guide and exit succesfully. No other output is generated. | |
85 | .IP "-l, --longoptions longopts" | |
86 | The long (multi-character) options to be recognized. | |
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 | |
91 | are cummulative. | |
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. | |
96 | .IP "-n, --name progname" | |
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. | |
102 | .IP "-o, --options shortopts" | |
103 | The short (one-character) options to be recognized. If this options is not | |
104 | found, the first parameter of | |
105 | .B getopt | |
106 | that does not start with | |
107 | a | |
108 | .RB ` - ' | |
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 | |
118 | .RB ` - ' | |
119 | to influence the way | |
120 | options are parsed and output is generated (see section | |
121 | .B SCANNING MODES | |
122 | for details). | |
123 | .IP "-q, --quiet" | |
124 | Disable error reporting by getopt(3). | |
125 | .IP "-Q, --quiet-output" | |
126 | Do not generate normal output. Errors are still reported by | |
127 | .BR getopt (3), | |
128 | unless you also use | |
129 | .IR -q . | |
130 | .IP "-s, --shell shell" | |
131 | Set quoting conventions to those of shell. If no -s argument is found, | |
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 '. | |
140 | .IP "-u, --unquoted" | |
141 | Do not quote the output. Note that whitespace and special (shell-dependent) | |
142 | characters can cause havoc in this mode (like they do with other | |
143 | .BR getopt (1) | |
144 | implementations). | |
145 | .IP "-T --test" | |
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 | |
155 | .RB ` -- ' | |
156 | and error status 0. | |
157 | .IP "-V, --version" | |
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, | |
182 | or a non-option parameter. | |
183 | ||
184 | A simple short option is a | |
185 | .RB ` - ' | |
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 | |
194 | .RB ` - ', | |
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 | |
199 | .RB ` -- ' | |
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 | |
217 | .RB ` - ', | |
218 | and not a required argument of | |
219 | a previous option, is a non-option parameter. Each parameter after | |
220 | a | |
221 | .RB ` -- ' | |
222 | parameter is always interpreted as a non-option parameter. | |
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 | |
229 | as non-option parameters as soon as the first non-option parameter is | |
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 | |
235 | for non-option parameters. Output can be done in | |
236 | .I compatible | |
237 | .RI ( unquoted ) | |
238 | mode, or in such way that whitespace and other special characters within | |
239 | arguments and non-option parameters are preserved (see | |
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 | |
250 | element, and a non-zero error status is returned. | |
251 | ||
252 | For a short option, a single | |
253 | .RB ` - ' | |
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 | |
265 | .RB ` - ', | |
266 | each will be present in the output as a separate parameter. | |
267 | ||
268 | For a long option, | |
269 | .RB ` -- ' | |
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 | |
273 | .RB ` - ' | |
274 | in the input. Arguments are handled as with short options. | |
275 | ||
276 | Normally, no non-option parameters output is generated until all options | |
277 | and their arguments have been generated. Then | |
278 | .RB ` -- ' | |
279 | is generated as a | |
280 | single parameter, and after it the non-option parameters in the order | |
281 | they were found, each as a separate parameter. | |
282 | Only if the first character of the short options string was a | |
283 | .RB ` - ', | |
284 | non-option parameter output is generated at the place they are found in the | |
285 | input (this is not supported if the first format of the | |
286 | .B SYNOPSIS | |
287 | is used; in that case all preceding occurences of | |
288 | .RB ` - ' | |
289 | and | |
290 | .RB ` + ' | |
291 | are ignored). | |
292 | .SH QUOTING | |
293 | In compatible mode, whitespace or 'special' characters in arguments or | |
294 | non-option parameters are not handled correctly. As the output is | |
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 | |
308 | .RB ` -u ' | |
309 | is found. | |
310 | ||
311 | Different shells use different quoting conventions. You can use the | |
312 | .RB ` -s ' | |
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 '. | |
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 | |
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 | |
326 | .RB ` - ' | |
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 | |
340 | is set, parsing stops as soon as the first non-option parameter | |
341 | (ie. a parameter that does not start with a | |
342 | .RB ` - ') | |
343 | is found that | |
344 | is not an option argument. The remaining parameters are all interpreted as | |
345 | non-option parameters. | |
346 | ||
347 | If the first character is a | |
348 | .RB ` - ', | |
349 | non-option parameters are outputed at the place where they are found; in normal | |
350 | operation, they are all collected at the end of output after a | |
351 | .RB ` -- ' | |
352 | parameter has been generated. Note that this | |
353 | .RB ` -- ' | |
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 | |
364 | .RB ` - ', | |
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 | |
367 | will still do parameter shuffling (ie. all non-option parameters are outputed | |
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 | |
382 | .RB ` - ' | |
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 | |
398 | if an internal error occurs like out-of-memory, and | |
399 | .B 4 | |
400 | if it is called with | |
401 | .BR -T . | |
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 | |
416 | parameters are also interpreted as non-option parameters, regardless | |
417 | whether they start with a | |
418 | .RB ` - '. | |
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. | |
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 | ||
435 | .SH AUTHOR | |
436 | Frodo Looijaard <frodol@dds.nl> | |
437 | .SH "SEE ALSO" | |
438 | .BR getopt (3), | |
439 | .BR bash (1), | |
440 | .BR tcsh (1). | |
441 |