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	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