1GETOPTS(1P)                POSIX Programmer's Manual               GETOPTS(1P)
2
3
4

PROLOG

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

NAME

12       getopts — parse utility options
13

SYNOPSIS

15       getopts optstring name [arg...]
16

DESCRIPTION

18       The getopts utility shall retrieve options and option-arguments from  a
19       list of parameters. It shall support the Utility Syntax Guidelines 3 to
20       10,  inclusive,  described  in   the   Base   Definitions   volume   of
21       POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines.
22
23       Each  time  it is invoked, the getopts utility shall place the value of
24       the next option in the shell variable specified by the name operand and
25       the  index  of  the next argument to be processed in the shell variable
26       OPTIND.  Whenever the shell is invoked, OPTIND shall be initialized  to
27       1.
28
29       When  the option requires an option-argument, the getopts utility shall
30       place it in the shell variable OPTARG.  If no option was found,  or  if
31       the  option  that  was  found  does not have an option-argument, OPTARG
32       shall be unset.
33
34       If an option character not contained in the optstring operand is  found
35       where  an option character is expected, the shell variable specified by
36       name shall be set to the  <question-mark>  ('?')   character.  In  this
37       case, if the first character in optstring is a <colon> (':'), the shell
38       variable OPTARG shall be set to the option character found, but no out‐
39       put  shall  be written to standard error; otherwise, the shell variable
40       OPTARG shall be unset and a diagnostic  message  shall  be  written  to
41       standard  error.  This  condition  shall  be  considered to be an error
42       detected in the way arguments were presented to the  invoking  applica‐
43       tion, but shall not be an error in getopts processing.
44
45       If an option-argument is missing:
46
47        *  If  the  first character of optstring is a <colon>, the shell vari‐
48           able specified by name shall be set to the  <colon>  character  and
49           the  shell  variable  OPTARG  shall  be set to the option character
50           found.
51
52        *  Otherwise, the shell variable specified by name shall be set to the
53           <question-mark>  character,  the  shell  variable  OPTARG  shall be
54           unset, and a diagnostic message shall be written to standard error.
55           This  condition  shall be considered to be an error detected in the
56           way arguments were presented to the invoking application, but shall
57           not  be  an error in getopts processing; a diagnostic message shall
58           be written as stated, but the exit status shall be zero.
59
60       When the end of options is encountered, the getopts utility shall  exit
61       with  a return value greater than zero; the shell variable OPTIND shall
62       be set to the index of the first operand, or the value "$#"+1 if  there
63       are  no operands; the name variable shall be set to the <question-mark>
64       character. Any of the following shall identify the end of options:  the
65       first "--" argument that is not an option-argument, finding an argument
66       that is not an option-argument and  does  not  begin  with  a  '-',  or
67       encountering an error.
68
69       The  shell  variables OPTIND and OPTARG shall be local to the caller of
70       getopts and shall not be exported by default.
71
72       The shell variable specified by the name operand,  OPTIND,  and  OPTARG
73       shall affect the current shell execution environment; see Section 2.12,
74       Shell Execution Environment.
75
76       If the application sets OPTIND to the value 1, a new set of  parameters
77       can  be  used: either the current positional parameters or new arg val‐
78       ues. Any other attempt to invoke getopts multiple  times  in  a  single
79       shell  execution  environment with parameters (positional parameters or
80       arg operands) that are not the same in  all  invocations,  or  with  an
81       OPTIND  value modified to be a value other than 1, produces unspecified
82       results.
83

OPTIONS

85       None.
86

OPERANDS

88       The following operands shall be supported:
89
90       optstring A string containing the option characters recognized  by  the
91                 utility  invoking  getopts.   If a character is followed by a
92                 <colon>, the option shall be expected to  have  an  argument,
93                 which should be supplied as a separate argument. Applications
94                 should specify an option character and its option-argument as
95                 separate  arguments,  but getopts shall interpret the charac‐
96                 ters following an option character requiring arguments as  an
97                 argument  whether  or  not  this  is  done.  An explicit null
98                 option-argument need not be recognized if it is not  supplied
99                 as a separate argument when getopts is invoked. (See also the
100                 getopt() function defined in the System Interfaces volume  of
101                 POSIX.1‐2017.)  The  characters  <question-mark>  and <colon>
102                 shall not be used as option characters by an application. The
103                 use of other option characters that are not alphanumeric pro‐
104                 duces unspecified results. If the option-argument is not sup‐
105                 plied  as  a separate argument from the option character, the
106                 value in OPTARG shall be stripped of the option character and
107                 the  '-'.   The  first  character in optstring determines how
108                 getopts behaves if an option character is  not  known  or  an
109                 option-argument is missing.
110
111       name      The name of a shell variable that shall be set by the getopts
112                 utility to the option character that was found.
113
114       The getopts utility by default shall parse positional parameters passed
115       to  the  invoking  shell  procedure.  If  args are given, they shall be
116       parsed instead of the positional parameters.
117

STDIN

119       Not used.
120

INPUT FILES

122       None.
123

ENVIRONMENT VARIABLES

125       The following environment  variables  shall  affect  the  execution  of
126       getopts:
127
128       LANG      Provide  a  default  value for the internationalization vari‐
129                 ables that are unset or null. (See the Base Definitions  vol‐
130                 ume  of POSIX.1‐2017, Section 8.2, Internationalization Vari‐
131                 ables for the precedence  of  internationalization  variables
132                 used to determine the values of locale categories.)
133
134       LC_ALL    If  set  to  a non-empty string value, override the values of
135                 all the other internationalization variables.
136
137       LC_CTYPE  Determine the locale for the interpretation of  sequences  of
138                 bytes of text data as characters (for example, single-byte as
139                 opposed to  multi-byte  characters  in  arguments  and  input
140                 files).
141
142       LC_MESSAGES
143                 Determine the locale that should be used to affect the format
144                 and contents  of  diagnostic  messages  written  to  standard
145                 error.
146
147       NLSPATH   Determine the location of message catalogs for the processing
148                 of LC_MESSAGES.
149
150       OPTIND    This variable shall be used by the  getopts  utility  as  the
151                 index of the next argument to be processed.
152

ASYNCHRONOUS EVENTS

154       Default.
155

STDOUT

157       Not used.
158

STDERR

160       Whenever  an error is detected and the first character in the optstring
161       operand is not a <colon> (':'), a diagnostic message shall  be  written
162       to standard error with the following information in an unspecified for‐
163       mat:
164
165        *  The invoking program name shall be identified in the  message.  The
166           invoking  program  name  shall  be  the  value of the shell special
167           parameter 0 (see Section 2.5.2, Special Parameters) at the time the
168           getopts utility is invoked. A name equivalent to:
169
170
171               basename "$0"
172
173           may be used.
174
175        *  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
179        *  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

OUTPUT FILES

184       None.
185

EXTENDED DESCRIPTION

187       None.
188

EXIT STATUS

190       The following exit values shall be returned:
191
192        0    An option, specified or unspecified by optstring, was found.
193
194       >0    The end of options was encountered or an error occurred.
195

CONSEQUENCES OF ERRORS

197       Default.
198
199       The following sections are informative.
200

APPLICATION USAGE

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
207
208           (getopts abc value "$@")
209           nohup getopts ...
210           find . -exec getopts ... \;
211
212       it does not affect the shell variables in the caller's environment.
213
214       Note that shell functions share OPTIND  with  the  calling  shell  even
215       though  the positional parameters are changed. If the calling shell and
216       any of its functions uses getopts to parse arguments, the  results  are
217       unspecified.
218

EXAMPLES

220       The following example script parses and displays its arguments:
221
222
223           aflag=
224           bflag=
225           while getopts ab: name
226           do
227               case $name in
228               a)    aflag=1;;
229               b)    bflag=1
230                     bval="$OPTARG";;
231               ?)   printf "Usage: %s: [-a] [-b value] args\n" $0
232                     exit 2;;
233               esac
234           done
235           if [ ! -z "$aflag" ]; then
236               printf "Option -a specified\n"
237           fi
238           if [ ! -z "$bflag" ]; then
239               printf 'Option -b "%s" specified\n' "$bval"
240           fi
241           shift $(($OPTIND - 1))
242           printf "Remaining arguments are: %s\n$*"
243

RATIONALE

245       The  getopts  utility  was  chosen in preference to the System V getopt
246       utility because getopts  handles  option-arguments  containing  <blank>
247       characters.
248
249       The  OPTARG variable is not mentioned in the ENVIRONMENT VARIABLES sec‐
250       tion because it does not affect the execution of getopts; it is one  of
251       the few ``output-only'' variables used by the standard utilities.
252
253       The  <colon>  is not allowed as an option character because that is not
254       historical behavior, and it violates the Utility Syntax Guidelines. The
255       <colon>  is  now specified to behave as in the KornShell version of the
256       getopts utility; when used as the first character in the optstring  op‐
257       erand,  it disables diagnostics concerning missing option-arguments and
258       unexpected option characters. This replaces the use of the OPTERR vari‐
259       able that was specified in an early proposal.
260
261       The  formats of the diagnostic messages produced by the getopts utility
262       and the getopt() function are not fully specified  because  implementa‐
263       tions  with  superior  (``friendlier'') formats objected to the formats
264       used by some historical implementations. The standard  developers  con‐
265       sidered  it important that the information in the messages used be uni‐
266       form between getopts and getopt().  Exact duplication of  the  messages
267       might  not  be  possible, particularly if a utility is built on another
268       system that has a different getopt() function, but  the  messages  must
269       have  specific  information  included so that the program name, invalid
270       option character, and type of error can be distinguished by a user.
271
272       Only a rare application program intercepts  a  getopts  standard  error
273       message  and  wants to parse it. Therefore, implementations are free to
274       choose the most usable messages they can devise. The following  formats
275       are used by many historical implementations:
276
277
278           "%s: illegal option -- %c\n", <program name>, <option character>
279
280           "%s: option requires an argument -- %c\n", <program name>, \
281               <option character>
282
283       Historical  shells  with  built-in versions of getopt() or getopts have
284       used different formats, frequently not even indicating the option char‐
285       acter found in error.
286

FUTURE DIRECTIONS

288       None.
289

SEE ALSO

291       Section 2.5.2, Special Parameters
292
293       The  Base  Definitions  volume  of POSIX.1‐2017, Chapter 8, Environment
294       Variables, Section 12.2, Utility Syntax Guidelines
295
296       The System Interfaces volume of POSIX.1‐2017, getopt()
297
299       Portions of this text are reprinted and reproduced in  electronic  form
300       from  IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
301       table Operating System Interface (POSIX), The Open Group Base  Specifi‐
302       cations  Issue  7, 2018 Edition, Copyright (C) 2018 by the Institute of
303       Electrical and Electronics Engineers, Inc and The Open Group.   In  the
304       event of any discrepancy between this version and the original IEEE and
305       The Open Group Standard, the original IEEE and The Open Group  Standard
306       is  the  referee document. The original Standard can be obtained online
307       at http://www.opengroup.org/unix/online.html .
308
309       Any typographical or formatting errors that appear  in  this  page  are
310       most likely to have been introduced during the conversion of the source
311       files to man page format. To report such errors,  see  https://www.ker
312       nel.org/doc/man-pages/reporting_bugs.html .
313
314
315
316IEEE/The Open Group                  2017                          GETOPTS(1P)
Impressum