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