1GETOPTS(1P) POSIX Programmer's Manual GETOPTS(1P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
13 getopts — parse utility options
14
16 getopts optstring name [arg...]
17
19 The getopts utility shall retrieve options and option-arguments from a
20 list of parameters. It shall support the Utility Syntax Guidelines 3 to
21 10, inclusive, described in the Base Definitions volume of
22 POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines.
23 Each time it is invoked, the getopts utility shall place the value of
25 the next option in the shell variable specified by the name operand and
26 the index of the next argument to be processed in the shell variable
27 OPTIND. Whenever the shell is invoked, OPTIND shall be initialized to
28 1.
29 When the option requires an option-argument, the getopts utility shall
31 place it in the shell variable OPTARG. If no option was found, or if
32 the option that was found does not have an option-argument, OPTARG
33 shall be unset.
34 If an option character not contained in the optstring operand is found
36 where an option character is expected, the shell variable specified by
37 name shall be set to the <question-mark> ('?') character. In this
38 case, if the first character in optstring is a <colon> (':'), the shell
39 variable OPTARG shall be set to the option character found, but no out‐
40 put shall be written to standard error; otherwise, the shell variable
41 OPTARG shall be unset and a diagnostic message shall be written to
42 standard error. This condition shall be considered to be an error
43 detected in the way arguments were presented to the invoking applica‐
44 tion, but shall not be an error in getopts processing.
45 If an option-argument is missing:
47 * If the first character of optstring is a <colon>, the shell vari‐
49 able specified by name shall be set to the <colon> character and
50 the shell variable OPTARG shall be set to the option character
51 found.
52 * Otherwise, the shell variable specified by name shall be set to the
54 <question-mark> character, the shell variable OPTARG shall be
55 unset, and a diagnostic message shall be written to standard error.
56 This condition shall be considered to be an error detected in the
57 way arguments were presented to the invoking application, but shall
58 not be an error in getopts processing; a diagnostic message shall
59 be written as stated, but the exit status shall be zero.
60 When the end of options is encountered, the getopts utility shall exit
62 with a return value greater than zero; the shell variable OPTIND shall
63 be set to the index of the first operand, or the value "$#"+1 if there
64 are no operands; the name variable shall be set to the <question-mark>
65 character. Any of the following shall identify the end of options: the
66 first "−−" argument that is not an option-argument, finding an argument
67 that is not an option-argument and does not begin with a '−', or
68 encountering an error.
69 The shell variables OPTIND and OPTARG shall be local to the caller of
71 getopts and shall not be exported by default.
72 The shell variable specified by the name operand, OPTIND, and OPTARG
74 shall affect the current shell execution environment; see Section 2.12,
75 Shell Execution Environment.
76 If the application sets OPTIND to the value 1, a new set of parameters
78 can be used: either the current positional parameters or new arg val‐
79 ues. Any other attempt to invoke getopts multiple times in a single
80 shell execution environment with parameters (positional parameters or
81 arg operands) that are not the same in all invocations, or with an
82 OPTIND value modified to be a value other than 1, produces unspecified
83 results.
84
86 None.
87
89 The following operands shall be supported:
90 optstring A string containing the option characters recognized by the
92 utility invoking getopts. If a character is followed by a
93 <colon>, the option shall be expected to have an argument,
94 which should be supplied as a separate argument. Applications
95 should specify an option character and its option-argument as
96 separate arguments, but getopts shall interpret the charac‐
97 ters following an option character requiring arguments as an
98 argument whether or not this is done. An explicit null
99 option-argument need not be recognized if it is not supplied
100 as a separate argument when getopts is invoked. (See also the
101 getopt() function defined in the System Interfaces volume of
102 POSIX.1‐2008.) The characters <question-mark> and <colon>
103 shall not be used as option characters by an application. The
104 use of other option characters that are not alphanumeric pro‐
105 duces unspecified results. If the option-argument is not sup‐
106 plied as a separate argument from the option character, the
107 value in OPTARG shall be stripped of the option character and
108 the '−'. The first character in optstring determines how
109 getopts behaves if an option character is not known or an
110 option-argument is missing.
111 name The name of a shell variable that shall be set by the getopts
113 utility to the option character that was found.
114 The getopts utility by default shall parse positional parameters passed
116 to the invoking shell procedure. If args are given, they shall be
117 parsed instead of the positional parameters.
118
120 Not used.
121
123 None.
124
126 The following environment variables shall affect the execution of
127 getopts:
128 LANG Provide a default value for the internationalization vari‐
130 ables that are unset or null. (See the Base Definitions vol‐
131 ume of POSIX.1‐2008, Section 8.2, Internationalization Vari‐
132 ables for the precedence of internationalization variables
133 used to determine the values of locale categories.)
134 LC_ALL If set to a non-empty string value, override the values of
136 all the other internationalization variables.
137 LC_CTYPE Determine the locale for the interpretation of sequences of
139 bytes of text data as characters (for example, single-byte as
140 opposed to multi-byte characters in arguments and input
141 files).
142 LC_MESSAGES
144 Determine the locale that should be used to affect the format
145 and contents of diagnostic messages written to standard
146 error.
147 NLSPATH Determine the location of message catalogs for the processing
149 of LC_MESSAGES.
150 OPTIND This variable shall be used by the getopts utility as the
152 index of the next argument to be processed.
153
155 Default.
156
158 Not used.
159
161 Whenever an error is detected and the first character in the optstring
162 operand is not a <colon> (':'), a diagnostic message shall be written
163 to standard error with the following information in an unspecified for‐
164 mat:
165 * The invoking program name shall be identified in the message. The
167 invoking program name shall be the value of the shell special
168 parameter 0 (see Section 2.5.2, Special Parameters) at the time the
169 getopts utility is invoked. A name equivalent to:
170 basename "$0"
172 may be used.
174 * If an option is found that was not specified in optstring, this
176 error is identified and the invalid option character shall be iden‐
177 tified in the message.
178 * If an option requiring an option-argument is found, but an option-
180 argument is not found, this error shall be identified and the
181 invalid option character shall be identified in the message.
182
184 None.
185
187 None.
188
190 The following exit values shall be returned:
191 0 An option, specified or unspecified by optstring, was found.
193 >0 The end of options was encountered or an error occurred.
195
197 Default.
198 The following sections are informative.
200
202 Since getopts affects the current shell execution environment, it is
203 generally provided as a shell regular built-in. If it is called in a
204 subshell or separate utility execution environment, such as one of the
205 following:
206 (getopts abc value "$@")
208 nohup getopts ...
209 find . −exec getopts ... \;
210 it does not affect the shell variables in the caller's environment.
212 Note that shell functions share OPTIND with the calling shell even
214 though the positional parameters are changed. If the calling shell and
215 any of its functions uses getopts to parse arguments, the results are
216 unspecified.
217
219 The following example script parses and displays its arguments:
220 aflag=
222 bflag=
223 while getopts ab: name
224 do
225 case $name in
226 a) aflag=1;;
227 b) bflag=1
228 bval="$OPTARG";;
229 ?) printf "Usage: %s: [−a] [−b value] args\n" $0
230 exit 2;;
231 esac
232 done
233 if [ ! −z "$aflag" ]; then
234 printf "Option −a specified\n"
235 fi
236 if [ ! −z "$bflag" ]; then
237 printf 'Option −b "%s" specified\n' "$bval"
238 fi
239 shift $(($OPTIND − 1))
240 printf "Remaining arguments are: %s\n$*"
241
243 The getopts utility was chosen in preference to the System V getopt
244 utility because getopts handles option-arguments containing <blank>
245 characters.
246 The OPTARG variable is not mentioned in the ENVIRONMENT VARIABLES sec‐
248 tion because it does not affect the execution of getopts; it is one of
249 the few ``output-only'' variables used by the standard utilities.
250 The <colon> is not allowed as an option character because that is not
252 historical behavior, and it violates the Utility Syntax Guidelines. The
253 <colon> is now specified to behave as in the KornShell version of the
254 getopts utility; when used as the first character in the optstring op‐
255 erand, it disables diagnostics concerning missing option-arguments and
256 unexpected option characters. This replaces the use of the OPTERR vari‐
257 able that was specified in an early proposal.
258 The formats of the diagnostic messages produced by the getopts utility
260 and the getopt() function are not fully specified because implementa‐
261 tions with superior (``friendlier'') formats objected to the formats
262 used by some historical implementations. The standard developers con‐
263 sidered it important that the information in the messages used be uni‐
264 form between getopts and getopt(). Exact duplication of the messages
265 might not be possible, particularly if a utility is built on another
266 system that has a different getopt() function, but the messages must
267 have specific information included so that the program name, invalid
268 option character, and type of error can be distinguished by a user.
269 Only a rare application program intercepts a getopts standard error
271 message and wants to parse it. Therefore, implementations are free to
272 choose the most usable messages they can devise. The following formats
273 are used by many historical implementations:
274 "%s: illegal option −− %c\n", <program name>, <option character>
276 "%s: option requires an argument −− %c\n", <program name>, \
278 <option character>
279 Historical shells with built-in versions of getopt() or getopts have
281 used different formats, frequently not even indicating the option char‐
282 acter found in error.
283
285 None.
286
288 Section 2.5.2, Special Parameters
289 The Base Definitions volume of POSIX.1‐2008, Chapter 8, Environment
291 Variables, Section 12.2, Utility Syntax Guidelines
292 The System Interfaces volume of POSIX.1‐2008, getopt()
294
296 Portions of this text are reprinted and reproduced in electronic form
297 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
298 -- Portable Operating System Interface (POSIX), The Open Group Base
299 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
300 cal and Electronics Engineers, Inc and The Open Group. (This is
301 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
302 event of any discrepancy between this version and the original IEEE and
303 The Open Group Standard, the original IEEE and The Open Group Standard
304 is the referee document. The original Standard can be obtained online
305 at http://www.unix.org/online.html .
306 Any typographical or formatting errors that appear in this page are
308 most likely to have been introduced during the conversion of the source
309 files to man page format. To report such errors, see https://www.ker‐
310 nel.org/doc/man-pages/reporting_bugs.html .
311IEEE/The Open Group 2013 GETOPTS(1P)