getopts.1p (12882B)
- '\" et
- .TH GETOPTS "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH PROLOG
- This manual page is part of the POSIX Programmer's Manual.
- The Linux implementation of this interface may differ (consult
- the corresponding Linux manual page for details of Linux behavior),
- or the interface may not be implemented on Linux.
- .\"
- .SH NAME
- getopts
- \(em parse utility options
- .SH SYNOPSIS
- .LP
- .nf
- getopts \fIoptstring name \fB[\fIarg\fR...\fB]\fR
- .fi
- .SH DESCRIPTION
- The
- .IR getopts
- utility shall retrieve options and option-arguments from a list of
- parameters. It shall support the Utility Syntax Guidelines 3 to 10,
- inclusive, described in the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 12.2" ", " "Utility Syntax Guidelines".
- .P
- Each time it is invoked, the
- .IR getopts
- utility shall place the value of the next option in the shell variable
- specified by the
- .IR name
- operand and the index of the next argument to be processed in the shell
- variable
- .IR OPTIND .
- Whenever the shell is invoked,
- .IR OPTIND
- shall be initialized to 1.
- .P
- When the option requires an option-argument, the
- .IR getopts
- utility shall place it in the shell variable
- .IR OPTARG .
- If no option was found, or if the option that was found does not have
- an option-argument,
- .IR OPTARG
- shall be unset.
- .P
- If an option character not contained in the
- .IR optstring
- operand is found where an option character is expected, the shell
- variable specified by
- .IR name
- shall be set to the
- <question-mark>
- (\c
- .BR '?' )
- character. In this case, if the first character in
- .IR optstring
- is a
- <colon>
- (\c
- .BR ':' ),
- the shell variable
- .IR OPTARG
- shall be set to the option character found, but no output shall be
- written to standard error; otherwise, the shell variable
- .IR OPTARG
- shall be unset and a diagnostic message shall be written to standard
- error. This condition shall be considered to be an error detected in
- the way arguments were presented to the invoking application, but shall
- not be an error in
- .IR getopts
- processing.
- .P
- If an option-argument is missing:
- .IP " *" 4
- If the first character of
- .IR optstring
- is a
- <colon>,
- the shell variable specified by
- .IR name
- shall be set to the
- <colon>
- character and the shell variable
- .IR OPTARG
- shall be set to the option character found.
- .IP " *" 4
- Otherwise, the shell variable specified by
- .IR name
- shall be set to the
- <question-mark>
- character, the shell variable
- .IR OPTARG
- shall be unset, and a diagnostic message shall be written to standard
- error. This condition shall be considered to be an error detected in
- the way arguments were presented to the invoking application, but shall
- not be an error in
- .IR getopts
- processing; a diagnostic message shall be written as stated, but the
- exit status shall be zero.
- .P
- When the end of options is encountered, the
- .IR getopts
- utility shall exit with a return value greater than zero; the shell
- variable
- .IR OPTIND
- shall be set to the index of the first operand, or the value
- .BR \(dq$#\(dq +1
- if there are no operands; the
- .IR name
- variable shall be set to the
- <question-mark>
- character. Any of the following shall identify the end of options:
- the first
- .BR \(dq--\(dq
- argument that is not an option-argument, finding an argument that is
- not an option-argument and does not begin with a
- .BR '\-' ,
- or encountering an error.
- .P
- The shell variables
- .IR OPTIND
- and
- .IR OPTARG
- shall be local to the caller of
- .IR getopts
- and shall not be exported by default.
- .P
- The shell variable specified by the
- .IR name
- operand,
- .IR OPTIND ,
- and
- .IR OPTARG
- shall affect the current shell execution environment; see
- .IR "Section 2.12" ", " "Shell Execution Environment".
- .P
- If the application sets
- .IR OPTIND
- to the value 1, a new set of parameters can be used: either the
- current positional parameters or new
- .IR arg
- values. Any other attempt to invoke
- .IR getopts
- multiple times in a single shell execution environment with parameters
- (positional parameters or
- .IR arg
- operands) that are not the same in all invocations, or with an
- .IR OPTIND
- value modified to be a value other than 1, produces unspecified
- results.
- .SH OPTIONS
- None.
- .SH OPERANDS
- The following operands shall be supported:
- .IP "\fIoptstring\fR" 10
- A string containing the option characters recognized by the utility
- invoking
- .IR getopts .
- If a character is followed by a
- <colon>,
- the option shall be 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
- .IR getopts
- shall interpret the characters following an option character requiring
- arguments as an argument whether or not this is done. An explicit null
- option-argument need not be recognized if it is not supplied as a
- separate argument when
- .IR getopts
- is invoked. (See also the
- \fIgetopt\fR()
- function defined in the System Interfaces volume of POSIX.1\(hy2017.) The characters
- <question-mark>
- and
- <colon>
- shall 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
- .IR OPTARG
- shall be stripped of the option character and the
- .BR '\-' .
- The first character in
- .IR optstring
- determines how
- .IR getopts
- behaves if an option character is not known or an option-argument is
- missing.
- .IP "\fIname\fR" 10
- The name of a shell variable that shall be set by the
- .IR getopts
- utility to the option character that was found.
- .P
- The
- .IR getopts
- utility by default shall parse positional parameters passed to the
- invoking shell procedure. If
- .IR arg s
- are given, they shall be parsed instead of the positional parameters.
- .SH STDIN
- Not used.
- .SH "INPUT FILES"
- None.
- .SH "ENVIRONMENT VARIABLES"
- The following environment variables shall affect the execution of
- .IR getopts :
- .IP "\fILANG\fP" 10
- Provide a default value for the internationalization variables that are
- unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 8.2" ", " "Internationalization Variables"
- for the precedence of internationalization variables used to determine
- the values of locale categories.)
- .IP "\fILC_ALL\fP" 10
- If set to a non-empty string value, override the values of all the
- other internationalization variables.
- .IP "\fILC_CTYPE\fP" 10
- Determine the locale for the interpretation of sequences of bytes of
- text data as characters (for example, single-byte as opposed to
- multi-byte characters in arguments and input files).
- .IP "\fILC_MESSAGES\fP" 10
- .br
- Determine the locale that should be used to affect the format and
- contents of diagnostic messages written to standard error.
- .IP "\fINLSPATH\fP" 10
- Determine the location of message catalogs for the processing of
- .IR LC_MESSAGES .
- .IP "\fIOPTIND\fP" 10
- This variable shall be used by the
- .IR getopts
- utility as the index of the next argument to be processed.
- .SH "ASYNCHRONOUS EVENTS"
- Default.
- .SH STDOUT
- Not used.
- .SH STDERR
- Whenever an error is detected and the first character in the
- .IR optstring
- operand is not a
- <colon>
- (\c
- .BR ':' ),
- a diagnostic message shall be written to standard error with the
- following information in an unspecified format:
- .IP " *" 4
- The invoking program name shall be identified in the message. The
- invoking program name shall be the value of the shell special parameter
- 0 (see
- .IR "Section 2.5.2" ", " "Special Parameters")
- at the time the
- .IR getopts
- utility is invoked. A name equivalent to:
- .RS 4
- .sp
- .RS 4
- .nf
- basename "$0"
- .fi
- .P
- .RE
- .P
- may be used.
- .RE
- .IP " *" 4
- If an option is found that was not specified in
- .IR optstring ,
- this error is identified and the invalid option character shall be
- identified in the message.
- .IP " *" 4
- If an option requiring an option-argument is found, but an
- option-argument is not found, this error shall be identified and the
- invalid option character shall be identified in the message.
- .SH "OUTPUT FILES"
- None.
- .SH "EXTENDED DESCRIPTION"
- None.
- .SH "EXIT STATUS"
- The following exit values shall be returned:
- .IP "\00" 6
- An option, specified or unspecified by
- .IR optstring ,
- was found.
- .IP >0 6
- The end of options was encountered or an error occurred.
- .SH "CONSEQUENCES OF ERRORS"
- Default.
- .LP
- .IR "The following sections are informative."
- .SH "APPLICATION USAGE"
- Since
- .IR getopts
- affects the current shell execution environment, it is generally
- provided as a shell regular built-in. If it is called in a subshell or
- separate utility execution environment, such as one of the following:
- .sp
- .RS 4
- .nf
- (getopts abc value "$@")
- nohup getopts ...
- find . -exec getopts ... \e;
- .fi
- .P
- .RE
- .P
- it does not affect the shell variables in the caller's environment.
- .P
- Note that shell functions share
- .IR OPTIND
- with the calling shell even though the positional parameters are
- changed. If the calling shell and any of its functions uses
- .IR getopts
- to parse arguments, the results are unspecified.
- .SH EXAMPLES
- The following example script parses and displays its arguments:
- .sp
- .RS 4
- .nf
- 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\en" $0
- exit 2;;
- esac
- done
- if [ ! -z "$aflag" ]; then
- printf "Option -a specified\en"
- fi
- if [ ! -z "$bflag" ]; then
- printf \(aqOption -b "%s" specified\en\(aq "$bval"
- fi
- shift $(($OPTIND - 1))
- printf "Remaining arguments are: %s\en$*"
- .fi
- .P
- .RE
- .SH RATIONALE
- The
- .IR getopts
- utility was chosen in preference to the System V
- .IR getopt
- utility because
- .IR getopts
- handles option-arguments containing
- <blank>
- characters.
- .P
- The
- .IR OPTARG
- variable is not mentioned in the ENVIRONMENT VARIABLES section because
- it does not affect the execution of
- .IR getopts ;
- it is one of the few ``output-only'' variables used by the standard
- utilities.
- .P
- The
- <colon>
- is not allowed as an option character because that is not historical
- behavior, and it violates the Utility Syntax Guidelines. The
- <colon>
- is now specified to behave as in the KornShell version of the
- .IR getopts
- utility; when used as the first character in the
- .IR optstring
- operand, it disables diagnostics concerning missing option-arguments
- and unexpected option characters. This replaces the use of the
- .IR OPTERR
- variable that was specified in an early proposal.
- .P
- The formats of the diagnostic messages produced by the
- .IR getopts
- utility and the
- \fIgetopt\fR()
- function are not fully specified because implementations with superior
- (``friendlier'') formats objected to the formats used by some
- historical implementations. The standard developers considered it
- important that the information in the messages used be uniform between
- .IR getopts
- and
- \fIgetopt\fR().
- Exact duplication of the messages might not be possible, particularly
- if a utility is built on another system that has a different
- \fIgetopt\fR()
- function, but the messages must have specific information included so
- that the program name, invalid option character, and type of error can
- be distinguished by a user.
- .P
- Only a rare application program intercepts a
- .IR getopts
- standard error message and wants to parse it. Therefore,
- implementations are free to choose the most usable messages they can
- devise. The following formats are used by many historical
- implementations:
- .sp
- .RS 4
- .nf
- "%s: illegal option -- %c\en", <\fIprogram name\fP>, <\fIoption character\fP>
- .P
- "%s: option requires an argument -- %c\en", <\fIprogram name\fP>, \e
- <\fIoption character\fP>
- .fi
- .P
- .RE
- .P
- Historical shells with built-in versions of
- \fIgetopt\fR()
- or
- .IR getopts
- have used different formats, frequently not even indicating the option
- character found in error.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "Section 2.5.2" ", " "Special Parameters"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "Chapter 8" ", " "Environment Variables",
- .IR "Section 12.2" ", " "Utility Syntax Guidelines"
- .P
- The System Interfaces volume of POSIX.1\(hy2017,
- .IR "\fIgetopt\fR\^(\|)"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 by the Institute of
- Electrical and Electronics Engineers, Inc and The Open Group.
- In the event of any discrepancy between this version and the original IEEE and
- The Open Group Standard, the original IEEE and The Open Group Standard
- is the referee document. The original Standard can be obtained online at
- http://www.opengroup.org/unix/online.html .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .