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

Annotation of /getopt/trunk/getopt.1

Parent Directory Parent Directory | Revision Log Revision Log


Revision 324 - (hide annotations)
Thu Jul 19 15:01:21 2012 UTC (11 years, 8 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 frodo 259 .TH GETOPT 1 "May 31, 1997" Linux ""
2     .SH NAME
3     getopt \- parse command options (enhanced)
4     .SH SYNOPSIS
5 frodo 324 .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 frodo 259 .SH DESCRIPTION
21     .B getopt
22 frodo 324 is used to break up
23 frodo 259 .RI ( parse )
24     options in command lines for easy parsing by
25     shell procedures, and to check for legal options.
26 frodo 324 It uses the
27 frodo 259 .SM GNU
28 frodo 324 .BR getopt (3)
29 frodo 259 routines to do this.
30    
31 frodo 324 The parameters
32 frodo 259 .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 frodo 324 .BR \-o | \-\-options
38     .I optstring
39     in the
40     .BR SYNOPSIS ),
41 frodo 259 and the parameters which are to be
42     parsed
43     .RI ( parameters
44 frodo 324 in the
45     .BR SYNOPSIS ).
46 frodo 259 The second part will start at the first non\-option parameter
47 frodo 324 that is not an option argument, or after the first occurrence of
48 frodo 259 .RB ` \-\- '.
49 frodo 324 If no
50     .RB ` \-o '
51     or
52     .RB ` \-\-options '
53 frodo 259 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 frodo 324 is set, or if its first parameter
59 frodo 259 is not an option (does not start with a
60     .RB ` \- ',
61 frodo 324 this is the first format in the
62     .BR SYNOPSIS ),
63 frodo 259 .B getopt
64 frodo 324 will generate output that is compatible with that of other versions of
65     .BR getopt (1).
66 frodo 259 It will still do parameter shuffling and recognize optional
67     arguments (see section
68     .B COMPATIBILITY
69 frodo 324 for more information).
70 frodo 259
71     Traditional implementations of
72     .BR getopt (1)
73     are unable to cope with whitespace and other (shell\-specific) special characters
74 frodo 324 in arguments and non\-option parameters. To solve this problem, this
75 frodo 259 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 frodo 324 you must call
81 frodo 259 .B getopt
82 frodo 324 in a way that is no longer compatible with other versions (the second
83     or third format in the
84     .BR SYNOPSIS ).
85 frodo 259 To determine whether this enhanced version of
86     .BR getopt (1)
87     is installed, a special test option
88 frodo 324 .RB ( \-T )
89 frodo 259 can be used.
90     .SH OPTIONS
91 frodo 324 .TP
92     .BR \-a , " \-\-alternative"
93     Allow long options to start with a single
94 frodo 259 .RB ` \- '.
95 frodo 324 .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 frodo 259 More than one option name
102 frodo 324 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 frodo 259 are cumulative.
106     Each long option name
107 frodo 324 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 frodo 259 .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 frodo 324 .TP
118     .BR \-o , " \-\-options \fIshortopts\fP"
119 frodo 262 The short (one\-character) options to be recognized. If this option is not
120 frodo 324 found, the first parameter of
121     .B getopt
122 frodo 259 that does not start with
123 frodo 324 a
124     .RB ` \- '
125 frodo 259 (and is not an option argument) is used as the short options string.
126     Each short option character
127 frodo 324 in
128     .I shortopts
129 frodo 259 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 frodo 324 The first character of shortopts may be
132     .RB ` + '
133 frodo 259 or
134 frodo 324 .RB ` \- '
135 frodo 259 to influence the way
136 frodo 324 options are parsed and output is generated (see section
137 frodo 259 .B SCANNING MODES
138     for details).
139 frodo 324 .TP
140     .BR \-q , " \-\-quiet"
141 frodo 259 Disable error reporting by getopt(3).
142 frodo 324 .TP
143     .BR \-Q , " \-\-quiet\-output"
144 frodo 259 Do not generate normal output. Errors are still reported by
145 frodo 324 .BR getopt (3),
146     unless you also use
147 frodo 259 .IR \-q .
148 frodo 324 .TP
149     .BR \-s , " \-\-shell \fIshell\fP"
150 frodo 259 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 frodo 324 .TP
160     .BR \-u , " \-\-unquoted"
161 frodo 259 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 frodo 324 .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 frodo 259 .BR getopt (1),
172     and this version if the environment variable
173     .B GETOPT_COMPATIBLE
174     is set,
175 frodo 324 will return
176     .RB ` \-\- '
177 frodo 259 and error status 0.
178 frodo 324 .TP
179     .BR \-V , " \-\-version"
180     Output version information and exit successfully. No other output is generated.
181 frodo 259 .SH PARSING
182     This section specifies the format of the second part of the parameters of
183     .B getopt
184 frodo 324 (the
185     .I parameters
186     in the
187     .BR SYNOPSIS ).
188     The next section
189     .RB ( OUTPUT )
190     describes the output that is
191 frodo 259 generated. These parameters were typically the parameters a shell function
192 frodo 324 was called with.
193 frodo 259 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 frodo 324 .B getopt
196     (see the
197     .BR EXAMPLES ).
198     All parsing is done by the GNU
199     .BR getopt (3)
200     routines.
201 frodo 259
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 frodo 324 A simple short option is a
207     .RB ` \- '
208 frodo 259 followed by a short option character. If
209     the option has a required argument, it may be written directly after the option
210 frodo 324 character or as the next parameter (ie. separated by whitespace on the
211 frodo 259 command line). If the
212     option has an optional argument, it must be written directly after the
213     option character if present.
214    
215 frodo 324 It is possible to specify several short options after one
216     .RB ` \- ',
217 frodo 259 as long as all (except possibly the last) do not have required or optional
218     arguments.
219    
220 frodo 324 A long option normally begins with
221     .RB ` \-\- '
222 frodo 259 followed by the long option name.
223     If the option has a required argument, it may be written directly after
224 frodo 324 the long option name, separated by
225     .RB ` = ',
226     or as the next argument (ie. separated by whitespace on the command line).
227 frodo 259 If the option has an optional argument, it must
228 frodo 324 be written directly after the long option name, separated by
229     .RB ` = ',
230     if present (if you add the
231     .RB ` = '
232 frodo 259 but nothing behind it, it is interpreted
233 frodo 324 as if no argument was present; this is a slight bug, see the
234 frodo 259 .BR BUGS ).
235     Long options may be abbreviated, as long as the abbreviation is not
236     ambiguous.
237    
238 frodo 324 Each parameter not starting with a
239     .RB ` \- ',
240 frodo 259 and not a required argument of
241     a previous option, is a non\-option parameter. Each parameter after
242 frodo 324 a
243     .RB ` \-\- '
244 frodo 259 parameter is always interpreted as a non\-option parameter.
245 frodo 324 If the environment variable
246     .B POSIXLY_CORRECT
247 frodo 259 is set, or if the short
248 frodo 324 option string started with a
249     .RB ` + ',
250 frodo 259 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 frodo 324 Output is generated for each element described in the previous section.
255 frodo 259 Output is done
256     in the same order as the elements are specified in the input, except
257 frodo 324 for non\-option parameters. Output can be done in
258     .I compatible
259 frodo 259 .RI ( unquoted )
260     mode, or in such way that whitespace and other special characters within
261 frodo 324 arguments and non\-option parameters are preserved (see
262 frodo 259 .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 frodo 324 For a short option, a single
275     .RB ` \- '
276 frodo 259 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 frodo 324 Note that many other
283     .BR getopt (1)
284     implementations do not support optional arguments.
285 frodo 259
286 frodo 324 If several short options were specified after a single
287     .RB ` \- ',
288 frodo 259 each will be present in the output as a separate parameter.
289    
290 frodo 324 For a long option,
291     .RB ` \-\- '
292 frodo 259 and the full option name are generated as one
293     parameter. This is done regardless whether the option was abbreviated or
294 frodo 324 specified with a single
295     .RB ` \- '
296 frodo 259 in the input. Arguments are handled as with short options.
297    
298     Normally, no non\-option parameters output is generated until all options
299 frodo 324 and their arguments have been generated. Then
300     .RB ` \-\- '
301 frodo 259 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 frodo 324 Only if the first character of the short options string was a
305 frodo 259 .RB ` \- ',
306 frodo 324 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 frodo 259 .B SYNOPSIS
309 frodo 262 is used; in that case all preceding occurrences of
310 frodo 259 .RB ` \- '
311 frodo 324 and
312 frodo 259 .RB ` + '
313 frodo 324 are ignored).
314 frodo 259 .SH QUOTING
315     In compatible mode, whitespace or 'special' characters in arguments or
316 frodo 324 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 frodo 259 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 frodo 324 again fed to the shell (usually by a shell
322     .B eval
323 frodo 259 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 frodo 324 Different shells use different quoting conventions. You can use the
334 frodo 259 .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 frodo 324 .RB ` csh '
340 frodo 259 and
341     .RB ` tcsh '.
342 frodo 324 Actually, only two `flavors' are distinguished: sh\-like quoting conventions
343 frodo 259 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 frodo 324 .B SYNOPSIS
354 frodo 259 is used they are ignored; the environment variable
355     .B POSIXLY_CORRECT
356     is still examined, though.
357    
358 frodo 324 If the first character is
359 frodo 259 .RB ` + ',
360 frodo 324 or if the environment variable
361 frodo 259 .B POSIXLY_CORRECT
362 frodo 324 is set, parsing stops as soon as the first non\-option parameter
363     (ie. a parameter that does not start with a
364 frodo 259 .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 frodo 324 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 frodo 259 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 frodo 324 This version of
380 frodo 259 .BR getopt (1)
381 frodo 324 is written to be as compatible as possible to
382 frodo 259 other versions. Usually you can just replace them with this version
383     without any modifications, and with some advantages.
384    
385 frodo 324 If the first character of the first parameter of getopt is not a
386     .RB ` \- ',
387 frodo 259 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 frodo 324 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 frodo 259 is set.
393    
394 frodo 324 The environment variable
395     .B GETOPT_COMPATIBLE
396     forces
397 frodo 259 .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 frodo 324 In compatibility mode, leading
404 frodo 259 .RB ` \- '
405 frodo 324 and
406 frodo 259 .RB ` + '
407     characters in the short options string are ignored.
408     .SH RETURN CODES
409     .B getopt
410 frodo 324 returns error code
411     .B 0
412     for successful parsing,
413 frodo 259 .B 1
414     if
415     .BR getopt (3)
416     returns errors,
417 frodo 324 .B 2
418 frodo 259 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 frodo 324 if it is called with
423 frodo 259 .BR \-T .
424     .SH EXAMPLES
425     Example scripts for (ba)sh and (t)csh are provided with the
426     .BR getopt (1)
427 frodo 324 distribution, and are optionally installed in
428     .B /usr/local/share/getopt
429     or
430     .BR /usr/share/getopt .
431    
432 frodo 259 .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 frodo 324 is found that is not an option or an option argument. All remaining
439 frodo 259 parameters are also interpreted as non\-option parameters, regardless
440 frodo 324 whether they start with a
441 frodo 259 .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 frodo 324 argument (but can not do this for short options). This
451 frodo 259 .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 frodo 324 not very intuitive (you have to set them explicitly to the empty
456 frodo 259 string).
457    
458     .SH AUTHOR
459 frodo 263 Frodo Looijaard <frodo@frodo.looijaard.name>
460 frodo 259 .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