getopts - Parses utility options
getopts optstring name [arg...]
Interfaces documented on this reference page conform to
industry standards as follows:
getopts: XCU5.0
Refer to the standards(5) reference page for more information
about industry standards and associated tags.
None
A string containing the option characters recognized by
the utility invoking getopts. If a character is followed
by a colon (:), the option is expected to have an argument,
which should be supplied as a separate argument.
Applications should specify an option character and its
option-argument as separate arguments, but getopts interprets
the characters following an option character requiring
arguments as an argument whether or not this is done.
An explicit null option-argument is not recognized if it
is not supplied as a separate argument when getopts is
invoked. The characters question-mark (?) and colon (:)
must not be used as option characters by an application.
The use of other option characters that are not alphanumeric
produces unspecified results. If the option-argument
is not supplied as a separate argument from the option
character, the value in OPTARG is stripped of the option
character and the hyphen (-). The first character in optstring
determines getopts behavior if an option character
is not known or an option-argument is missing. The name
of a shell variable that is set by the getopts utility to
the option character that was found.
The getopts utility by default parses positional parameters
passed to the invoking shell procedure. If args are
given, they are parsed instead of the positional parameters.
The getopts utility is used to retrieve flags and flagarguments
from a list of parameters.
Each time it is invoked, the getopts utility places the
value of the next flag in the shell variable specified by
the name operand and the index of the next argument to be
processed in the shell variable OPTIND. Whenever the
shell is invoked, OPTIND is initialized to 1.
When the flag requires a flag-argument, the getopts utility
places it in the shell variable OPTARG. If no flag is
found, or if the flag found does not have a flag-argument,
OPTARG is unset.
If a flag character not contained in the optstring operand
is found where a flag character is expected, the shell
variable specified by name is set to the question-mark (?)
character. In this case, if the first character in optstring
is a colon (:), the shell variable OPTARG is set to
the flag character found, but no output is written; otherwise,
the shell variable OPTARG is unset and a diagnostic
message written. This condition is considered to be an
error detected in the way arguments were presented to the
invoking application, but is not an error in getopts processing.
If a flag-argument is missing, then: If the first character
of optstring is a colon, the shell variable specified
by name is set to the colon (:) character and the shell
variable OPTARG is set to the flag character found. Otherwise,
the shell variable specified by name is set to the
question-mark (?) character, the shell variable OPTARG is
unset, and a diagnostic message is written to standard
error. This condition is considered to be an error
detected in the way arguments were presented to the invoking
application, but is not an error in getopts processing;
a diagnostic message is written as stated, but the
exit status is zero.
When the end of flags is encountered the getopts utility
exits with: A return value greater than zero The shell
variable OPTIND set to the index of the first non-flagargument,
where the first -- argument is considered to be
a flag-argument if there are no other non-flag-arguments
appearing before it, or the value $# + 1 if there are no
non-flag-arguments The name variable set to the questionmark
(?) character
Any of the following identifies the end of flags: The special
flag -- Finding an argument that does not begin with
a - Encountering an error
The shell variables OPTIND and OPTARG are local to the
caller of getopts and are not exported by default.
The shell variable specified by the name operand, OPTIND
and OPTARG affect the current shell execution environment.
If the application sets OPTIND to the value 1, a new set
of parameters can be used: either the current positional
parameters or new arg values. Any other attempt to invoke
getopts multiple times in a single shell execution environment
with parameters (positional parameters or flag
operands) that are not the same in all invocations, or
with an OPTIND value modified to be a value other than 1,
produces unspecified results.
If getopts is called in a subshell or separate utility
execution environment, such as one of the following it
will not affect the shell variables in the caller's environment:
(getopts abc value "$@") nohup getopts ... Shell
functions share OPTIND with the calling shell even
though the positional parameters are changed.
Functions that want to use getopts to parse their
arguments will usually want to save the value of
OPTIND on entry and restore it before returning.
However, there are cases when a function will want
to change OPTIND for the calling shell.
The getopts command is implemented as a shell built-in
command. It is only available to users of the Korn (ksh)
and POSIX shells.
A similar capability is available to Bourne and C shell
users with the getopt command.
The following exit values are returned: An option, specified
or unspecified by optstring, was found. Successful
completion. The end of options was encountered or an
error occurred.
The following example script parses and displays its arguments:
aflag= bflag= while getopts ab: name do
case $name in
a) aflag=1;;
b) bflag=1
bval="$OPTARG";;
?) printf "Usage: %s: [-a] [-b value] args\n" $0
exit 2;;
esac done if [ ! -z "$aflag" ]; then
printf "Option -a specified\n" fi if [ ! -z "$bflag"
]; then
printf 'Option -b "%s" specified\n' "$bval" fi shift
$(($OPTIND - 1)) printf "Remaining arguments are: %s\n"
"$*"
ENVIRONMENT VARIABLES [Toc] [Back] The following environment variables affect the execution
of getopts: Provides a default value for the internationalization
variables that are unset or null. If LANG is
unset or null, the corresponding value from the default
locale is used. If any of the internationalization variables
contain an invalid setting, the utility behaves as
if none of the variables had been defined. If set to a
non-empty string value, overrides the values of all the
other internationalization variables. Determines the
locale for the interpretation of sequences of bytes of
text data as characters (for example, single-byte as
opposed to multibyte characters in arguments and input
files). Determines the locale used to affect the format
and contents of diagnostic messages written to standard
error. Determines the location of message catalogues for
the processing of LC_MESSAGES. On exit, this variable
will contain the value of a flag-argumentm if one was
found, otherwise it is unset. This variable is used by
the getopts utility as the index of the next argument to
be processed.
Commands: getopt(1), ksh(1), sh(1p)
Routines: getopt(3)
Standards: standards(5)
getopts(1)
[ Back ] |
