Penguin
Recent Changes
Annotated edit history of getopt(1) version 3, including all changes. View license author blame.
Rev Author # Line
1 perry 1 !!NAME
2
3 getopt - parse command options (enhanced)
2 CraigBox 4
1 perry 5 !!SYNOPSIS
6
3 CraigBox 7 __getopt__ optstring parameters %%%
8 __getopt__ [[options] [[__--__] optstring parameters %%%
2 CraigBox 9 __getopt__ [[options] __-o__|__--options__ optstring [[options] [[__--__] parameters
1 perry 10
11
12 !!DESCRIPTION
13
2 CraigBox 14 __getopt__ is used to break up (''parse'') options in command lines for easy parsing by shell procedures, and to check for legal options. It uses the GNU getopt(3) routines to do this.
1 perry 15
2 CraigBox 16 The parameters __getopt__ is called with can be divided into two parts: options which modify the way getopt will parse (''options'' and ''-o|--options optstring'' in
17 the __SYNOPSIS),__ and the parameters which are to be parsed (''parameters'' in the __SYNOPSIS).__ The second part will start at the first non-option parameter
18 that is not an option argument, or after the first occurence of `__--__'. If no `__-o__' or `__--options__' option is found in the first part, the first parameter of the second part is used as the short options string.
1 perry 19
2 CraigBox 20 If the environment variable __GETOPT_COMPATIBLE__ is set, or if its first parameter is not an option (does not start with a `__-__', this is the first format in the
21 __SYNOPSIS), getopt__ will generate output that is compatible with that of other versions of getopt(1). It will still do parameter shuffling and recognize optional arguments (see section __COMPATIBILITY__ for more information).
1 perry 22
2 CraigBox 23 Traditional implementations of getopt(1) are unable to cope with whitespace and other (shell-specific) special characters in arguments and non-option parameters. To solve this problem, this implementation can generate quoted output which must once again be interpreted by the shell (usually by using the __eval__ command). This has the effect of preserving those characters, but you must call __getopt__ in a way that is no longer compatible with other versions (the second or third format in the __SYNOPSIS).__ To
24 determine whether this enhanced version of getopt(1) is installed, a special test option (__-T__) can be used.
1 perry 25
26 !!OPTIONS
27
2 CraigBox 28 ; __-a, --alternative__ : Allow long options to start with a single `__-__'.
29 ; __-h, --help__ : Output a small usage guide and exit succesfully. No other output is generated.
30 ; __-l, --longoptions longopts__ : The long (multi-character) options to be recognized. More than one option name may be specified at once, by separating the names with commas. This option may be given more than once, the ''longopts'' are cummulative. Each long option name in ''longopts'' may be followed by one colon to indicate it has a required argument,and by two colons to indicate it has an optional argument.
31 ; __-n, --name progname__ : The name that will be used by the getopt(3) routines when it reports errors. Note that errors of getopt(1) are still reported as coming from getopt.
3 CraigBox 32 ; __-o, --options shortopts__ : The short (one-character) options to be recognized. If this options is not found, the first parameter of __getopt__ that does not start with a `__-__' (and is not an option argument) is used as the short options string. Each short option character in ''shortopts'' may be followed by one colon to indicate it has a required argument, and by two colons to indicate it has an optional argument. The first character of shortopts may be `__+__' or `__-__' to influence the way options are parsed and output is generated (see section __SCANNING MODES__ for details).
2 CraigBox 33 ; __-q, --quiet__ : Disable error reporting by getopt(3).
34 ; __-Q, --quiet-output__ : Do not generate normal output. Errors are still reported by getopt(3), unless you also use ''-q''.
35 ; __-s, --shell shell__ : Set quoting conventions to those of shell. If no -s argument is found, the BASH conventions are used. Valid arguments are currently `__sh__' `__bash__', `__csh__', and `__tcsh__'.
3 CraigBox 36 ; __-u, --unquoted__ : Do not quote the output. Note that whitespace and special (shell-dependent) characters can cause havoc in this mode (like they do with other getopt(1) implementations).
2 CraigBox 37 ; __-T --test__ : Test if your getopt(1) is this enhanced version or an old version. This generates no output, and sets the error status to 4. Other implementations of getopt(1), and this version if the environment variable __GETOPT_COMPATIBLE__ is set, will return `__--__' and error status 0.
38 ; __-V, --version__ : Output version information and exit succesfully. No other output is generated.
1 perry 39
40 !!PARSING
41
2 CraigBox 42 This section specifies the format of the second part of the parameters of __getopt__ (the ''parameters'' in the __SYNOPSIS__). The next section (__OUTPUT__) describes
43 the output that is generated. These parameters were typically the parameters a shell function was called with. Care must be taken that each parameter the shell function was called with corresponds to exactly one parameter in the parameter list of __getopt__ (see the __EXAMPLES__). All parsing is done by the GNU getopt(3) routines.
1 perry 44
45
46 The parameters are parsed from left to right. Each parameter
47 is classified as a short option, a long option, an argument
48 to an option, or a non-option parameter.
49
50
51 A simple short option is a `__-__' followed by a short
52 option character. If the option has a required argument, it
53 may be written directly after the option character or as the
54 next parameter (ie. separated by whitespace on the command
55 line). If the option has an optional argument, it must be
56 written directly after the option character if
57 present.
58
59
60 It is possible to specify several short options after one
61 `__-__', as long as all (except possibly the last) do not
62 have required or optional arguments.
63
64
65 A long option normally begins with `__--__' followed by
66 the long option name. If the option has a required argument,
67 it may be written directly after the long option name,
68 separated by `__=__', or as the next argument (ie.
69 separated by whitespace on the command line). If the option
70 has an optional argument, it must be written directly after
71 the long option name, separated by `__=__', if present
72 (if you add the `__=__' but nothing behind it, it is
73 interpreted as if no argument was present; this is a slight
74 bug, see the __BUGS__). Long options may be abbreviated,
75 as long as the abbreviation is not ambiguous.
76
77
78 Each parameter not starting with a `__-__', and not a
79 required argument of a previous option, is a non-option
80 parameter. Each parameter after a `__--__' parameter is
81 always interpreted as a non-option parameter. If the
82 environment variable __POSIXLY_CORRECT__ is set, or if
83 the short option string started with a `__+__', all
84 remaining parameters are interpreted as non-option
85 parameters as soon as the first non-option parameter is
86 found.
87 !!OUTPUT
88
89
90 Output is generated for each element described in the
91 previous section. Output is done in the same order as the
92 elements are specified in the input, except for non-option
93 parameters. Output can be done in ''compatible''
94 (''unquoted'') mode, or in such way that whitespace and
95 other special characters within arguments and non-option
96 parameters are preserved (see __QUOTING__). When the
97 output is processed in the shell script, it will seem to be
98 composed of distinct elements that can be processed one by
99 one (by using the shift command in most shell languages).
100 This is imperfect in unquoted mode, as elements can be split
101 at unexpected places if they contain whitespace or special
102 characters.
103
104
105 If there are problems parsing the parameters, for example
106 because a required argument is not found or an option is not
107 recognized, an error will be reported on stderr, there will
108 be no output for the offending element, and a non-zero error
109 status is returned.
110
111
112 For a short option, a single `__-__' and the option
113 character are generated as one parameter. If the option has
114 an argument, the next parameter will be the argument. If the
115 option takes an optional argument, but none was found, the
116 next parameter will be generated but be empty in quoting
117 mode, but no second parameter will be generated in unquoted
118 (compatible) mode. Note that many other getopt(1)
119 implemetations do not support optional
120 arguments.
121
122
123 If several short options were specified after a single
124 `__-__', each will be present in the output as a separate
125 parameter.
126
127
128 For a long option, `__--__' and the full option name are
129 generated as one parameter. This is done regardless whether
130 the option was abbreviated or specified with a single
131 `__-__' in the input. Arguments are handled as with short
132 options.
133
134
135 Normally, no non-option parameters output is generated until
136 all options and their arguments have been generated. Then
137 `__--__' is generated as a single parameter, and after it
138 the non-option parameters in the order they were found, each
139 as a separate parameter. Only if the first character of the
140 short options string was a `__-__', non-option parameter
141 output is generated at the place they are found in the input
142 (this is not supported if the first format of the
143 __SYNOPSIS__ is used; in that case all preceding
144 occurences of `__-__' and `__+__' are
145 ignored).
146
2 CraigBox 147 !!QUOTING
1 perry 148
149 In compatible mode, whitespace or 'special' characters in
150 arguments or non-option parameters are not handled
151 correctly. As the output is fed to the shell script, the
152 script does not know how it is supposed to break the output
153 into separate parameters. To circumvent this problem, this
154 implementation offers quoting. The idea is that output is
155 generated with quotes around each parameter. When this
156 output is once again fed to the shell (usually by a shell
157 __eval__ command), it is split correctly into separate
158 parameters.
159
160
161 Quoting is not enabled if the environment variable
162 __GETOPT_COMPATIBLE__ is set, if the first form of the
163 __SYNOPSIS__ is used, or if the option `__-u__' is
164 found.
165
166
167 Different shells use different quoting conventions. You can
168 use the `__-s__' option to select the shell you are
169 using. The following shells are currently supported:
170 `__sh__', `__bash__', `__csh__' and `__tcsh__'.
171 Actually, only two `flavors' are distinguished: sh-like
172 quoting conventions and csh-like quoting conventions.
173 Chances are that if you use another shell script language,
174 one of these flavors can still be used.
175 !!SCANNING MODES
176
177
178 The first character of the short options string may be a
179 `__-__' or a `__+__' to indicate a special scanning
180 mode. If the first calling form in the __SYNOPSIS__ is
181 used they are ignored; the environment variable
182 __POSIXLY_CORRECT__ is still examined,
183 though.
184
185
186 If the first character is `__+__', or if the environment
187 variable __POSIXLY_CORRECT__ is set, parsing stops as
188 soon as the first non-option parameter (ie. a parameter that
189 does not start with a `__-__') is found that is not an
190 option argument. The remaining parameters are all
191 interpreted as non-option parameters.
192
193
194 If the first character is a `__-__', non-option
195 parameters are outputed at the place where they are found;
196 in normal operation, they are all collected at the end of
197 output after a `__--__' parameter has been generated.
198 Note that this `__--__' parameter is still generated, but
199 it will always be the last parameter in this
200 mode.
201
2 CraigBox 202 !!COMPATIBILITY
1 perry 203
204 This version of getopt(1) is written to be as
205 compatible as possible to other versions. Usually you can
206 just replace them with this version without any
207 modifications, and with some advantages.
208
209
210 If the first character of the first parameter of getopt is
211 not a `__-__', getopt goes into compatibility mode. It
212 will interpret its first parameter as the string of short
213 options, and all other arguments will be parsed. It will
214 still do parameter shuffling (ie. all non-option parameters
215 are outputed at the end), unless the environment variable
216 __POSIXLY_CORRECT__ is set.
217
218
219 The environment variable __GETOPT_COMPATIBLE__ forces
220 __getopt__ into compatibility mode. Setting both this
221 environment variable and __POSIXLY_CORRECT__ offers 100%
222 compatibility for `difficult' programs. Usually, though,
223 neither is needed.
224
225
226 In compatibility mode, leading `__-__' and `__+__'
227 characters in the short options string are
228 ignored.
229
2 CraigBox 230 !!RETURN CODES
1 perry 231
232 __getopt__ returns error code __0__ for succesful
233 parsing, __1__ if getopt(3) returns errors,
234 __2__ if it does not understand its own parameters,
235 __3__ if an internal error occurs like out-of-memory, and
236 __4__ if it is called with __-T__.
237 !!EXAMPLES
238
239
240 Example scripts for (ba)sh and (t)csh are provided with the
241 getopt(1) distribution, and are optionally installed
242 in __/usr/share/doc/util-linux/examples .__
2 CraigBox 243
1 perry 244 !!ENVIRONMENT
245
2 CraigBox 246 ; __[POSIXLY_CORRECT]__: This environment variable is examined by the getopt(3) routines. If it is set, parsing stops as soon as a parameter is found that is not an option or an option argument. All remaining parameters are also interpreted as non-option parameters, regardless whether they start with a `__-__'.
247 ; __GETOPT_COMPATIBLE__: Forces __getopt__ to use the first calling format as specified in the __SYNOPSIS__.
1 perry 248
249
250 !!BUGS
251
2 CraigBox 252 getopt(3) can parse long options with optional arguments that are given an empty optional argument (but can not do this for short options). This getopt(1) treats
253 optional arguments that are empty as if they were not present.
1 perry 254
2 CraigBox 255 The syntax if you do not want any short option variables at all is not very intuitive (you have to set them explicitely to the empty string).
1 perry 256
257 !!AUTHOR
258
2 CraigBox 259 Frodo Looijaard
1 perry 260
261 !!SEE ALSO
262
2 CraigBox 263 getopt(3), bash(1), tcsh(1).
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.

PHP Warning

lib/blame.php:177: Warning: Invalid argument supplied for foreach() (...repeated 13 times)