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

Diff of /getopt/trunk/getopt.1

Parent Directory | Revision Log | View Patch Patch

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

 Legend:



Removed from v.262
 


changed lines


 
Added in v.365
 Legend:



Removed from v.262
 


changed lines


 
Added in v.365
-Removed from v.262
+Added in v.365

frodo@frodo.looijaard.name	ViewVC Help
Powered by ViewVC 1.1.26