Differences between version 3 and revision by previous author of getopt(1).
Other diffs: Previous Major Revision, Previous Revision, or view the Annotated Edit History
| Newer page: | version 3 | Last edited on Sunday, November 2, 2003 6:37:06 pm | by CraigBox | Revert |
| Older page: | version 1 | Last edited on Tuesday, June 4, 2002 12:22:04 am | by perry | Revert |
@@ -1,196 +1,47 @@
-GETOPT
-!!!GETOPT
-NAME
-SYNOPSIS
-DESCRIPTION
-OPTIONS
-PARSING
-OUTPUT
-QUOTING
-SCANNING MODES
-COMPATIBILITY
-RETURN CODES
-EXAMPLES
-ENVIRONMENT
-BUGS
-AUTHOR
-SEE ALSO
-----
!!NAME
+getopt - parse command options (enhanced)
-getopt - parse command options (enhanced)
!!SYNOPSIS
+__getopt__ optstring parameters %%%
+__getopt__ [[options] [[__--__] optstring parameters %%%
+__getopt__ [[options] __-o__|__--options__ optstring [[options] [[__--__] parameters
-__getopt__ optstring parameters
-
-__getopt__ [[options] [[__--__] optstring
-parameters
-
-
-__getopt__ [[options] __-o__|__--options__ optstring
-[[options] [[__--__] parameters
!!DESCRIPTION
+__getopt__ is used to break up (''parse'') options in command lines for easy parsing by shell procedures, and to check for legal options. It uses the GNU getopt(3) routines to do this.
-__getopt__ is used to break up
(''parse
'')
options in
-command lines for easy parsing by shell procedures
, and to
-check for legal options
. It uses
the GNU
-getopt(3) routines to do this
.
+The parameters
__getopt__ is called with can be divided into two parts: options which modify the way getopt will parse
(''options
'' and ''-o|--
options optstring''
in
+the __SYNOPSIS)
,__
and the parameters which are
to be parsed (''parameters'' in the __SYNOPSIS)
.__ The second part will start at
the first non-option parameter
+that is not an option argument, or after the first occurence of `__--__'. If no `__-o__' or `__--options__' option is found in the first part, the first parameter of the second part is used as the short options string
.
+If the environment variable __GETOPT_COMPATIBLE__ is set, or if its first parameter is not an option (does not start with a `__-__', this is the first format in the
+__SYNOPSIS), getopt__ will generate output that is compatible with that of other versions of getopt(1). It will still do parameter shuffling and recognize optional arguments (see section __COMPATIBILITY__ for more information).
-The parameters __
getopt__ is called
with can be divided
-into two parts: options which modify
the way getopt will
-parse
(''options'' and ''-o|--options optstring'' in
-SYNOPSIS
),__ and
the parameters which are to be
-parsed (''parameters''
in the __SYNOPSIS).__ The
-second part will start at the first non-option parameter
-that
is not an
option argument, or after the first occurence
-of `
__--
__'. If no `__-o__' or `__--options__'
-option is found in the first part, the first parameter of
-the second part is
used as the short options
-string
.
+Traditional implementations of
getopt(1) are unable to cope
with whitespace and other (shell-specific) special characters in arguments and non-option parameters. To solve this problem, this implementation
can generate quoted output which must once again
be interpreted by
the shell
(usually by using
the __eval__ command
). This has the effect of preserving those characters
, but you must call
__getopt__ in a way that is no longer compatible with other versions (
the second or third format
in the __SYNOPSIS).__ To
+determine whether this enhanced version of getopt(1)
is installed, a special test
option (
__-T
__) can be
used.
-
-If the environment variable __GETOPT_COMPATIBLE__ is set,
-or if its first parameter is not an option (does not start
-with a `__-__', this is the first format in the
-__SYNOPSIS), getopt__ will generate output that is
-compatible with that of other versions of getopt(1).
-It will still do parameter shuffling and recognize optional
-arguments (see section __COMPATIBILITY__ for more
-information).
-
-
-Traditional implementations of getopt(1) are unable
-to cope with whitespace and other (shell-specific) special
-characters in arguments and non-option parameters. To solve
-this problem, this implementation can generate quoted output
-which must once again be interpreted by the shell (usually
-by using the __eval__ command). This has the effect of
-preserving those characters, but you must call __getopt__
-in a way that is no longer compatible with other versions
-(the second or third format in the __SYNOPSIS).__ To
-determine whether this enhanced version of getopt(1)
-is installed, a special test option (__-T__) can be
-used.
!!OPTIONS
+; __-a, --alternative__ : Allow long options to start with a single `__-__'.
+; __-h, --help__ : Output a small usage guide and exit succesfully. No other output is generated.
+; __-l, --longoptions longopts__ : The long (multi-character) options to be recognized. More than one option name may be specified at once, by separating the names with commas. This option may be given more than once, the ''longopts'' are cummulative. Each long option name in ''longopts'' may be followed by one colon to indicate it has a required argument,and by two colons to indicate it has an optional argument.
+; __-n, --name progname__ : The name that will be used by the getopt(3) routines when it reports errors. Note that errors of getopt(1) are still reported as coming from getopt.
+; __-o, --options shortopts__ : The short (one-character) options to be recognized. If this options is not found, the first parameter of __getopt__ that does not start with a `__-__' (and is not an option argument) is used as the short options string. Each short option character in ''shortopts'' may be followed by one colon to indicate it has a required argument, and by two colons to indicate it has an optional argument. The first character of shortopts may be `__+__' or `__-__' to influence the way options are parsed and output is generated (see section __SCANNING MODES__ for details).
+; __-q, --quiet__ : Disable error reporting by getopt(3).
+; __-Q, --quiet-output__ : Do not generate normal output. Errors are still reported by getopt(3), unless you also use ''-q''.
+; __-s, --shell shell__ : Set quoting conventions to those of shell. If no -s argument is found, the BASH conventions are used. Valid arguments are currently `__sh__' `__bash__', `__csh__', and `__tcsh__'.
+; __-u, --unquoted__ : Do not quote the output. Note that whitespace and special (shell-dependent) characters can cause havoc in this mode (like they do with other getopt(1) implementations).
+; __-T --test__ : Test if your getopt(1) is this enhanced version or an old version. This generates no output, and sets the error status to 4. Other implementations of getopt(1), and this version if the environment variable __GETOPT_COMPATIBLE__ is set, will return `__--__' and error status 0.
+; __-V, --version__ : Output version information and exit succesfully. No other output is generated.
--a, --alternative
-
-
-Allow long options to start with a single
-`__-__'.
-
-
--h, --help
-
-
-Output a small usage guide and exit succesfully. No other
-output is generated.
-
-
--l, --longoptions longopts
-
-
-The long (multi-character) options to be recognized. More
-than one option name may be specified at once, by separating
-the names with commas. This option may be given more than
-once, the ''longopts'' are cummulative. Each long option
-name in ''longopts'' may be followed by one colon to
-indicate it has a required argument,and by two colons to
-indicate it has an optional argument.
-
-
--n, --name progname
-
-
-The name that will be used by the getopt(3) routines
-when it reports errors. Note that errors of getopt(1)
-are still reported as coming from getopt.
-
-
--o, --options shortopts
-
-
-The short (one-character) options to be recognized. If this
-options is not found, the first parameter of __getopt__
-that does not start with a `__-__' (and is not an option
-argument) is used as the short options string. Each short
-option character in ''shortopts'' may be followed by one
-colon to indicate it has a required argument, and by two
-colons to indicate it has an optional argument. The first
-character of shortopts may be `__+__' or `__-__' to
-influence the way options are parsed and output is generated
-(see section __SCANNING MODES__ for
-details).
-
-
--q, --quiet
-
-
-Disable error reporting by getopt(3).
-
-
--Q, --quiet-output
-
-
-Do not generate normal output. Errors are still reported by
-getopt(3), unless you also use
-''-q''.
-
-
--s, --shell shell
-
-
-Set quoting conventions to those of shell. If no -s argument
-is found, the BASH conventions are used.
-Valid arguments are currently `__sh__' `__bash__',
-`__csh__', and `__tcsh__'.
-
-
--u, --unquoted
-
-
-Do not quote the output. Note that whitespace and special
-(shell-dependent) characters can cause havoc in this mode
-(like they do with other getopt(1)
-implementations).
-
-
--T --test
-
-
-Test if your getopt(1) is this enhanced version or an
-old version. This generates no output, and sets the error
-status to 4. Other implementations of getopt(1), and
-this version if the environment variable
-__GETOPT_COMPATIBLE__ is set, will return `__--__' and
-error status 0.
-
-
--V, --version
-
-
-Output version information and exit succesfully. No other
-output is generated.
!!PARSING
-
-
-
-
-the output that is generated. These parameters were
-
-
-
-
-
-
+This section specifies the format of the second part of the parameters of __getopt__ (the ''parameters'' in the __SYNOPSIS__). The next section (__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 __getopt__ (see the __EXAMPLES__). All parsing is done by the GNU getopt(3) routines.
The parameters are parsed from left to right. Each parameter
is classified as a short option, a long option, an argument
@@ -291,10 +142,10 @@
(this is not supported if the first format of the
__SYNOPSIS__ is used; in that case all preceding
occurences of `__-__' and `__+__' are
ignored).
-!!QUOTING
+!!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
@@ -346,10 +197,10 @@
output after a `__--__' parameter has been generated.
Note that this `__--__' parameter is still generated, but
it will always be the last parameter in this
mode.
-!!COMPATIBILITY
+!!COMPATIBILITY
This version of getopt(1) is written to be as
compatible as possible to other versions. Usually you can
just replace them with this version without any
@@ -374,10 +225,10 @@
In compatibility mode, leading `__-__' and `__+__'
characters in the short options string are
ignored.
-!!RETURN CODES
+!!RETURN CODES
__getopt__ returns error code __0__ for succesful
parsing, __1__ if getopt(3) returns errors,
__2__ if it does not understand its own parameters,
@@ -388,46 +239,25 @@
Example scripts for (ba)sh and (t)csh are provided with the
getopt(1) distribution, and are optionally installed
in __/usr/share/doc/util-linux/examples .__
+
!!ENVIRONMENT
+; __[POSIXLY_CORRECT]__: This environment variable is examined by the getopt(3) routines. If it is set, parsing stops as soon as a parameter is found that is not an option or an option argument. All remaining parameters are also interpreted as non-option parameters, regardless whether they start with a `__-__'.
+; __GETOPT_COMPATIBLE__: Forces __getopt__ to use the first calling format as specified in the __SYNOPSIS__.
-POSIXLY_CORRECT
-
-This environment variable is examined by the
-getopt(3) routines. If it is set, parsing stops as
-soon as a parameter is found that is not an option or an
-option argument. All remaining parameters are also
-interpreted as non-option parameters, regardless whether
-they start with a `__-__'.
-
-
-GETOPT_COMPATIBLE
-
-
-Forces __getopt__ to use the first calling format as
-specified in the __SYNOPSIS__.
!!BUGS
+getopt(3) can parse long options with optional arguments that are given an empty optional argument (but can not do this for short options). This getopt(1) treats
+optional arguments that are empty as if they were not present.
-getopt(3) can parse long options with optional
-arguments that are given an empty optional argument (but can
-do this for
short options). This 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 explicitely to the empty string
).
-The syntax if you do not want any short option variables at
-all is not very intuitive (you have to set them explicitely
-to the empty string).
!!AUTHOR
+Frodo Looijaard
-Frodo Looijaard
!!SEE ALSO
-
-
-
-----
+getopt(3), bash(1), tcsh(1).
