getopt/trunk/getopt.1

.TH GETOPT 1 "May 31, 1997" Linux ""
.SH NAME
getopt \- parse command options (enhanced)
.SH SYNOPSIS
.B getopt
.I optstring parameters
.br
.B getopt
.RI [ options ]
.RB [ \-\- ]
.I optstring parameters
.br
.B getopt
.RI [ options ]
.BR \-o | \-\-options
.I optstring
.RI [ options ]
.RB [ \-\- ]
.I parameters
.SH DESCRIPTION
.B getopt
is used to break up
.RI ( parse )
options in command lines for easy parsing by
shell procedures, and to check for legal options.
It uses the
.SM GNU
.BR getopt (3)
routines to do this.

The parameters
.B getopt
is called with can be divided into two parts: options
which modify the way getopt will parse
.RI ( options
and
.BR \-o | \-\-options
.I optstring
in the
.BR SYNOPSIS ),
and the parameters which are to be
parsed
.RI ( parameters
in the
.BR SYNOPSIS ).
The second part will start at the first non\-option parameter
that is not an option argument, or after the first occurrence of
.RB ` \-\- '.
If no
.RB ` \-o '
or
.RB ` \-\-options '
option is found in the first part, the first
parameter of the second part is used as the short options string.

If the environment variable
.B GETOPT_COMPATIBLE
is set, or if its first parameter
is not an option (does not start with a
.RB ` \- ',
this is the first format in the
.BR SYNOPSIS ),
.B getopt
will generate output that is compatible with that of other versions of
.BR getopt (1).
It will still do parameter shuffling and recognize optional
arguments (see section
.B COMPATIBILITY
for more information).

Traditional implementations of
.BR 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
.B eval
command). This has the effect of preserving those characters, but
you must call
.B getopt
in a way that is no longer compatible with other versions (the second
or third format in the
.BR SYNOPSIS ).
To determine whether this enhanced version of
.BR getopt (1)
is installed, a special test option
.RB ( \-T )
can be used.
.SH OPTIONS
.TP
.BR \-a , " \-\-alternative"
Allow long options to start with a single
.RB ` \- '.
.TP
.BR \-h , " \-\-help"
Output a small usage guide and exit successfully. No other output is generated.
.TP
.BR \-l , " \-\-longoptions \fIlongopts\fP"
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
.I longopts
are cumulative.
Each long option name
in
.I 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.
.TP
.BR \-n , " \-\-name \fIprogname\fP"
The name that will be used by the
.BR getopt (3)
routines when it reports errors. Note that errors of
.BR getopt (1)
are still reported as coming from getopt.
.TP
.BR \-o , " \-\-options \fIshortopts\fP"
The short (one\-character) options to be recognized. If this option is not
found, the first parameter of
.B getopt
that does not start with
a
.RB ` \- '
(and is not an option argument) is used as the short options string.
Each short option character
in
.I 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
.RB ` + '
or
.RB ` \- '
to influence the way
options are parsed and output is generated (see section
.B SCANNING MODES
for details).
.TP
.BR \-q , " \-\-quiet"
Disable error reporting by getopt(3).
.TP
.BR  \-Q , " \-\-quiet\-output"
Do not generate normal output. Errors are still reported by
.BR getopt (3),
unless you also use
.IR \-q .
.TP
.BR \-s , " \-\-shell \fIshell\fP"
Set quoting conventions to those of shell. If no \-s argument is found,
the
.SM BASH
conventions are used. Valid arguments are currently
.RB ` sh '
.RB ` bash ',
.RB ` csh ',
and
.RB ` tcsh '.
.TP
.BR \-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
.BR getopt (1)
implementations).
.TP
.BR \-T , " \-\-test"
Test if your
.BR getopt (1)
is this enhanced version or an old version. This generates no output,
and sets the error status to 4. Other implementations of
.BR getopt (1),
and this version if the environment variable
.B GETOPT_COMPATIBLE
is set,
will return
.RB ` \-\- '
and error status 0.
.TP
.BR \-V , " \-\-version"
Output version information and exit successfully. No other output is generated.
.SH PARSING
This section specifies the format of the second part of the parameters of
.B getopt
(the
.I parameters
in the
.BR SYNOPSIS ).
The next section
.RB ( OUTPUT )
describes 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
.B getopt
(see the
.BR EXAMPLES ).
All parsing is done by the GNU
.BR getopt (3)
routines.

The parameters are parsed from left to right. Each parameter is classified as a
short option, a long option, an argument to an option,
or a non\-option parameter.

A simple short option is a
.RB ` \- '
followed by a short option character. If
the option has a required argument, it may be written directly after the option
character or as the next parameter (ie. separated by whitespace on the
command line). If the
option has an optional argument, it must be written directly after the
option character if present.

It is possible to specify several short options after one
.RB ` \- ',
as long as all (except possibly the last) do not have required or optional
arguments.

A long option normally begins with
.RB ` \-\- '
followed by the long option name.
If the option has a required argument, it may be written directly after
the long option name, separated by
.RB ` = ',
or as the next argument (ie. separated by whitespace on the command line).
If the option has an optional argument, it must
be written directly after the long option name, separated by
.RB ` = ',
if present (if you add the
.RB ` = '
but nothing behind it, it is interpreted
as if no argument was present; this is a slight bug, see the
.BR BUGS ).
Long options may be abbreviated, as long as the abbreviation is not
ambiguous.

Each parameter not starting with a
.RB ` \- ',
and not a required argument of
a previous option, is a non\-option parameter. Each parameter after
a
.RB ` \-\- '
parameter is always interpreted as a non\-option parameter.
If the environment variable
.B POSIXLY_CORRECT
is set, or if the short
option string started with a
.RB ` + ',
all remaining parameters are interpreted
as non\-option parameters as soon as the first non\-option parameter is
found.
.SH OUTPUT
Output is generated for each element described in the previous section.
Output is done
in the same order as the elements are specified in the input, except
for non\-option parameters. Output can be done in
.I compatible
.RI ( unquoted )
mode, or in such way that whitespace and other special characters within
arguments and non\-option parameters are preserved (see
.BR QUOTING ).
When the output is processed in the shell script, it will seem to be
composed of distinct elements that can be processed one by one (by using the
shift command in most shell languages). This is imperfect in unquoted mode,
as elements can be split at unexpected places if they contain whitespace
or special characters.

If there are problems parsing the parameters, for example because a
required argument is not found or an option is not recognized, an error
will be reported on stderr, there will be no output for the offending
element, and a non\-zero error status is returned.

For a short option, a single
.RB ` \- '
and the option character are generated
as one parameter. If the option has an argument, the next
parameter will be the argument. If the option takes an optional argument,
but none was found, the next parameter will be generated but be empty in
quoting mode,
but no second parameter will be generated in unquoted (compatible) mode.
Note that many other
.BR getopt (1)
implementations do not support optional arguments.

If several short options were specified after a single
.RB ` \- ',
each will be present in the output as a separate parameter.

For a long option,
.RB ` \-\- '
and the full option name are generated as one
parameter. This is done regardless whether the option was abbreviated or
specified with a single
.RB ` \- '
in the input. Arguments are handled as with short options.

Normally, no non\-option parameters output is generated until all options
and their arguments have been generated. Then
.RB ` \-\- '
is generated as a
single parameter, and after it the non\-option parameters in the order
they were found, each as a separate parameter.
Only if the first character of the short options string was a
.RB ` \- ',
non\-option parameter output is generated at the place they are found in the
input (this is not supported if the first format of the
.B SYNOPSIS
is used; in that case all preceding occurrences of
.RB ` \- '
and
.RB ` + '
are ignored).
.SH QUOTING
In compatible mode, whitespace or 'special' characters in arguments or
non\-option parameters are not handled correctly. As the output is
fed to the shell script, the script does not know how it is supposed to break
the output into separate parameters.  To circumvent this
problem, this implementation offers quoting. The idea is that output
is generated with quotes around each parameter. When this output is once
again fed to the shell (usually by a shell
.B eval
command), it is split correctly into separate parameters.

Quoting is not enabled if the environment variable
.B GETOPT_COMPATIBLE
is set, if the first form of the
.B SYNOPSIS
is used, or if the option
.RB ` \-u '
is found.

Different shells use different quoting conventions. You can use the
.RB ` \-s '
option to select the shell you are using. The following shells are
currently supported:
.RB ` sh ',
.RB ` bash ',
.RB ` csh '
and
.RB ` tcsh '.
Actually, only two `flavors' are distinguished: sh\-like quoting conventions
and csh\-like quoting conventions. Chances are that if you use another shell
script language, one of these flavors can still be used.

.SH "SCANNING MODES"
The first character of the short options string may be a
.RB ` \- '
or a
.RB ` + '
to indicate a special scanning mode. If the first calling form
in the
.B SYNOPSIS
is used they are ignored; the environment variable
.B POSIXLY_CORRECT
is still examined, though.

If the first character is
.RB ` + ',
or if the environment variable
.B POSIXLY_CORRECT
is set, parsing stops as soon as the first non\-option parameter
(ie. a parameter that does not start with a
.RB ` \- ')
is found that
is not an option argument. The remaining parameters are all interpreted as
non\-option parameters.

If the first character is a
.RB ` \- ',
non\-option parameters are outputted at the place where they are found; in normal
operation, they are all collected at the end of output after a
.RB ` \-\- '
parameter has been generated. Note that this
.RB ` \-\- '
parameter is still generated, but it will always be the last parameter in
this mode.
.SH COMPATIBILITY
This version of
.BR getopt (1)
is written to be as compatible as possible to
other versions. Usually you can just replace them with this version
without any modifications, and with some advantages.

If the first character of the first parameter of getopt is not a
.RB ` \- ',
getopt goes into compatibility mode. It will interpret its first parameter as
the string of short options, and all other arguments will be parsed. It
will still do parameter shuffling (ie. all non\-option parameters are outputted
at the end), unless the environment variable
.B POSIXLY_CORRECT
is set.

The environment variable
.B GETOPT_COMPATIBLE
forces
.B getopt
into compatibility mode. Setting both this environment variable and
.B POSIXLY_CORRECT
offers 100% compatibility for `difficult' programs. Usually, though,
neither is needed.

In compatibility mode, leading
.RB ` \- '
and
.RB ` + '
characters in the short options string are ignored.
.SH RETURN CODES
.B getopt
returns error code
.B 0
for successful parsing,
.B 1
if
.BR getopt (3)
returns errors,
.B 2
if it does not understand its own parameters,
.B 3
if an internal error occurs like out\-of\-memory, and
.B 4
if it is called with
.BR \-T .
.SH EXAMPLES
Example scripts for (ba)sh and (t)csh are provided with the
.BR getopt (1)
distribution, and are optionally installed in
.B /usr/local/share/getopt
or
.BR /usr/share/getopt .

.SH ENVIRONMENT
.IP POSIXLY_CORRECT
This environment variable is examined by the
.BR 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
.RB ` \- '.
.IP GETOPT_COMPATIBLE
Forces
.B getopt
to use the first calling format as specified in the
.BR SYNOPSIS .
.SH BUGS
.BR 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
.BR getopt (1)
treats optional arguments that are empty as if they were not present.

The syntax if you do not want any short option variables at all is
not very intuitive (you have to set them explicitly to the empty
string).

.SH AUTHOR
Frodo Looijaard <frodo@frodo.looijaard.name>
.SH "SEE ALSO"
.BR getopt (3),
.BR bash (1),
.BR tcsh (1).

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