/[public]/getopt/trunk/getopt.1
ViewVC logotype

Contents of /getopt/trunk/getopt.1

Parent Directory Parent Directory | Revision Log Revision Log


Revision 324 - (show annotations)
Thu Jul 19 15:01:21 2012 UTC (7 years, 3 months ago) by frodo
File size: 13728 byte(s)
(Frodo) Updated manpage (sync with util-linux 2.23), moved docs to /usr/share
        (instead of /usr/lib)

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

frodo@frodo.looijaard.name
ViewVC Help
Powered by ViewVC 1.1.26