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
11

NAME

13       getopts — parse utility options
14

SYNOPSIS

16       getopts optstring name [arg...]
17

DESCRIPTION

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
24       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
30       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
35       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
46       If an option-argument is missing:
47
48        *  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
53        *  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
61       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
70       The  shell  variables OPTIND and OPTARG shall be local to the caller of
71       getopts and shall not be exported by default.
72
73       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
77       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

OPTIONS

86       None.
87

OPERANDS

89       The following operands shall be supported:
90
91       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
112       name      The name of a shell variable that shall be set by the getopts
113                 utility to the option character that was found.
114
115       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

STDIN

120       Not used.
121

INPUT FILES

123       None.
124

ENVIRONMENT VARIABLES

126       The following environment  variables  shall  affect  the  execution  of
127       getopts:
128
129       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
135       LC_ALL    If  set  to  a non-empty string value, override the values of
136                 all the other internationalization variables.
137
138       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
143       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
148       NLSPATH   Determine the location of message catalogs for the processing
149                 of LC_MESSAGES.
150
151       OPTIND    This variable shall be used by the  getopts  utility  as  the
152                 index of the next argument to be processed.
153

ASYNCHRONOUS EVENTS

155       Default.
156

STDOUT

158       Not used.
159

STDERR

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
166        *  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
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           (getopts abc value "$@")
208           nohup getopts ...
209           find . −exec getopts ... \;
210
211       it does not affect the shell variables in the caller's environment.
212
213       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

EXAMPLES

219       The following example script parses and displays its arguments:
220
221           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

RATIONALE

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
247       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
251       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
259       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
270       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
275           "%s: illegal option −− %c\n", <program name>, <option character>
276
277           "%s: option requires an argument −− %c\n", <program name>, \
278               <option character>
279
280       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

FUTURE DIRECTIONS

285       None.
286

SEE ALSO

288       Section 2.5.2, Special Parameters
289
290       The  Base  Definitions  volume  of POSIX.1‐2008, Chapter 8, Environment
291       Variables, Section 12.2, Utility Syntax Guidelines
292
293       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
307       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 .
311
312
313
314IEEE/The Open Group                  2013                          GETOPTS(1P)
Impressum