Un outil pour savoir si une commande est posix - retour accueil
git clone git://bebou.netlib.re/isposix
Log | Files | Refs | README |
getopts.html (21071B)
1 <!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved -->
2 <!DOCTYPE HTML>
3 <html lang="en">
4 <head>
5 <meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0">
6 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
7 <link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 -->
8 <!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved -->
9 <title>getopts</title>
10 </head>
11 <body bgcolor="white">
12 <div class="NAVHEADER">
13 <table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0">
14 <tr class="nav">
15 <td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/getconf.html" accesskey="P"><<<
16 Previous</a></td>
17 <td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td>
18 <td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/gettext.html" accesskey="N">Next
19 >>></a></td>
20 </tr>
21 </table>
22 <hr align="left" width="100%"></div>
23 <script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3">
24 <center><font size="2">The Open Group Base Specifications Issue 8<br>
25 IEEE Std 1003.1-2024<br>
26 Copyright © 2001-2024 The IEEE and The Open Group</font></center>
27 <hr size="2" noshade>
28 <a name="top" id="top"></a> <a name="getopts" id="getopts"></a> <a name="tag_20_53" id="tag_20_53"></a><!-- getopts -->
29 <h4 class="mansect"><a name="tag_20_53_01" id="tag_20_53_01"></a>NAME</h4>
30 <blockquote>getopts — parse utility options</blockquote>
31 <h4 class="mansect"><a name="tag_20_53_02" id="tag_20_53_02"></a>SYNOPSIS</h4>
32 <blockquote class="synopsis">
33 <p><code><tt>getopts</tt> <i>optstring name</i> <b>[</b><i>param</i><tt>...</tt><b>]</b></code></p>
34 </blockquote>
35 <h4 class="mansect"><a name="tag_20_53_03" id="tag_20_53_03"></a>DESCRIPTION</h4>
36 <blockquote>
37 <p>The <i>getopts</i> utility shall retrieve options and option-arguments from a list of parameters. It shall support the Utility
38 Syntax Guidelines 3 to 10, inclusive, described in XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax
39 Guidelines</i></a> .</p>
40 <p>When the shell is first invoked, the shell variable <i>OPTIND</i> shall be initialized to 1. Each time <i>getopts</i> is
41 invoked, it shall place the value of the next option found in the parameter list in the shell variable specified by the <i>name</i>
42 operand and the shell variable <i>OPTIND</i> shall be set as follows:</p>
43 <ul>
44 <li>
45 <p>When <i>getopts</i> successfully parses an option that takes an option-argument (that is, a character followed by <colon>
46 in <i>optstring</i>, and exit status is 0), the value of <i>OPTIND</i> shall be the integer index of the next element of the
47 parameter list (if any; see OPERANDS below) to be searched for an option character. Index 1 identifies the first element of the
48 parameter list.</p>
49 </li>
50 <li>
51 <p>When <i>getopts</i> reports end of options (that is, when exit status is 1), the value of <i>OPTIND</i> shall be the integer
52 index of the next element of the parameter list (if any).</p>
53 </li>
54 <li>
55 <p>In all other cases, the value of <i>OPTIND</i> is unspecified, but shall encode the information needed for the next invocation
56 of <i>getopts</i> to resume parsing options after the option just parsed.</p>
57 </li>
58 </ul>
59 <p>When the option requires an option-argument, the <i>getopts</i> utility shall place it in the shell variable <i>OPTARG .</i> If
60 no option was found, or if the option that was found does not have an option-argument, <i>OPTARG</i> shall be unset.</p>
61 <p>If an option character not contained in the <i>optstring</i> operand is found where an option character is expected, the shell
62 variable specified by <i>name</i> shall be set to the <question-mark> (<tt>'?'</tt>) character. In this case, if the first
63 character in <i>optstring</i> is a <colon> (<tt>':'</tt>), the shell variable <i>OPTARG</i> shall be set to the option
64 character found, but no output shall be written to standard error; otherwise, the shell variable <i>OPTARG</i> shall be unset and a
65 diagnostic message shall be written to standard error. This condition shall be considered to be an error detected in the way
66 arguments were presented to the invoking application, but shall not be an error in <i>getopts</i> processing.</p>
67 <p>If an option-argument is missing:</p>
68 <ul>
69 <li>
70 <p>If the first character of <i>optstring</i> is a <colon>, the shell variable specified by <i>name</i> shall be set to the
71 <colon> character and the shell variable <i>OPTARG</i> shall be set to the option character found.</p>
72 </li>
73 <li>
74 <p>Otherwise, the shell variable specified by <i>name</i> shall be set to the <question-mark> character, the shell variable
75 <i>OPTARG</i> shall be unset, and a diagnostic message shall be written to standard error. This condition shall be considered to be
76 an error detected in the way arguments were presented to the invoking application, but shall not be an error in <i>getopts</i>
77 processing; a diagnostic message shall be written as stated, but the exit status shall be zero.</p>
78 </li>
79 </ul>
80 <p>When the end of options is encountered, the <i>getopts</i> utility shall exit with a return value of one; the shell variable
81 <i>OPTIND</i> shall be set to the index of the argument containing the first operand in the parameter list, or the value 1 plus the
82 number of elements in the parameter list if there are no operands in the parameter list; the <i>name</i> variable shall be set to
83 the <question-mark> character. Any of the following shall identify the end of options: the first <tt>"--"</tt> element of the
84 parameter list that is not an option-argument, finding an element of the parameter list that is not an option-argument and does not
85 begin with a <tt>'-'</tt>, or encountering an error.</p>
86 <p>The shell variables <i>OPTIND</i> and <i>OPTARG</i> shall not be exported by default. An error in setting any of these variables
87 (such as if <i>name</i> has previously been marked <i>readonly</i>) shall be considered an error of <i>getopts</i> processing, and
88 shall result in a return value greater than one.</p>
89 <p>The <i>getopts</i> utility can affect <i>OPTIND ,</i> <i>OPTARG ,</i> and the shell variable specified by the <i>name</i>
90 operand, within the current shell execution environment; see <a href="../utilities/V3_chap02.html#tag_19_13"><i>2.13 Shell
91 Execution Environment</i></a> .</p>
92 <p>If the application sets <i>OPTIND</i> to the value 1, a new set of parameters can be used: either the current positional
93 parameters or new <i>param</i> values. Any other attempt to invoke <i>getopts</i> multiple times in a single shell execution
94 environment with parameters (positional parameters or <i>param</i> operands) that are not the same in all invocations, or with an
95 <i>OPTIND</i> value modified by the application to be a value other than 1, produces unspecified results.</p>
96 </blockquote>
97 <h4 class="mansect"><a name="tag_20_53_04" id="tag_20_53_04"></a>OPTIONS</h4>
98 <blockquote>
99 <p>None.</p>
100 </blockquote>
101 <h4 class="mansect"><a name="tag_20_53_05" id="tag_20_53_05"></a>OPERANDS</h4>
102 <blockquote>
103 <p>The following operands shall be supported:</p>
104 <dl compact>
105 <dd></dd>
106 <dt><i>optstring</i></dt>
107 <dd>A string containing the option characters recognized by the utility invoking <i>getopts</i>. If a character is followed by a
108 <colon>, the option shall be expected to have an argument, which should be supplied as a separate argument. Applications
109 should specify an option character and its option-argument as separate arguments, but <i>getopts</i> shall interpret the characters
110 following an option character requiring arguments as an argument whether or not this is done. An explicit null option-argument need
111 not be recognized if it is not supplied as a separate argument when <i>getopts</i> is invoked. (See also the <a href=
112 "../functions/getopt.html"><i>getopt</i>()</a> function defined in the System Interfaces volume of POSIX.1-2024.) The characters
113 <question-mark> and <colon> shall not be used as option characters by an application. The use of other option
114 characters that are not alphanumeric produces unspecified results. Whether or not the option-argument is supplied as a separate
115 argument from the option character, the value in <i>OPTARG</i> shall only be the characters of the option-argument. The first
116 character in <i>optstring</i> determines how <i>getopts</i> behaves if an option character is not known or an option-argument is
117 missing.</dd>
118 <dt><i>name</i></dt>
119 <dd>The name of a shell variable that shall be set by the <i>getopts</i> utility to the option character that was found.</dd>
120 </dl>
121 <p>By default, the list of parameters parsed by the <i>getopts</i> utility shall be the positional parameters currently set in the
122 invoking shell environment (<tt>"$@"</tt>). If <i>param</i> operands are given, they shall be parsed instead of the positional
123 parameters. Note that the next element of the parameter list need not exist; in this case, <i>OPTIND</i> will be set to
124 <tt>$#+1</tt> or the number of <i>param</i> operands plus 1.</p>
125 </blockquote>
126 <h4 class="mansect"><a name="tag_20_53_06" id="tag_20_53_06"></a>STDIN</h4>
127 <blockquote>
128 <p>Not used.</p>
129 </blockquote>
130 <h4 class="mansect"><a name="tag_20_53_07" id="tag_20_53_07"></a>INPUT FILES</h4>
131 <blockquote>
132 <p>None.</p>
133 </blockquote>
134 <h4 class="mansect"><a name="tag_20_53_08" id="tag_20_53_08"></a>ENVIRONMENT VARIABLES</h4>
135 <blockquote>
136 <p>The following environment variables shall affect the execution of <i>getopts</i>:</p>
137 <dl compact>
138 <dd></dd>
139 <dt><i>LANG</i></dt>
140 <dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href=
141 "../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization
142 variables used to determine the values of locale categories.)</dd>
143 <dt><i>LC_ALL</i></dt>
144 <dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd>
145 <dt><i>LC_CTYPE</i></dt>
146 <dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as
147 opposed to multi-byte characters in arguments and input files).</dd>
148 <dt><i>LC_MESSAGES</i></dt>
149 <dd><br>
150 Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd>
151 <dt><i>NLSPATH</i></dt>
152 <dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
153 Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border=
154 "0"></dd>
155 <dt><i>OPTIND</i></dt>
156 <dd>This variable shall be used by the <i>getopts</i> utility as the index of the next argument to be processed.</dd>
157 </dl>
158 </blockquote>
159 <h4 class="mansect"><a name="tag_20_53_09" id="tag_20_53_09"></a>ASYNCHRONOUS EVENTS</h4>
160 <blockquote>
161 <p>Default.</p>
162 </blockquote>
163 <h4 class="mansect"><a name="tag_20_53_10" id="tag_20_53_10"></a>STDOUT</h4>
164 <blockquote>
165 <p>Not used.</p>
166 </blockquote>
167 <h4 class="mansect"><a name="tag_20_53_11" id="tag_20_53_11"></a>STDERR</h4>
168 <blockquote>
169 <p>Whenever an error is detected and the first character in the <i>optstring</i> operand is not a <colon> (<tt>':'</tt>), a
170 diagnostic message shall be written to standard error with the following information in an unspecified format:</p>
171 <ul>
172 <li>
173 <p>The invoking program name shall be identified in the message. The invoking program name shall be the value of the shell special
174 parameter 0 (see <a href="../utilities/V3_chap02.html#tag_19_05_02"><i>2.5.2 Special Parameters</i></a> ) at the time the
175 <i>getopts</i> utility is invoked. A name equivalent to:</p>
176 <pre>
177 <tt>basename "$0"
178 </tt></pre>
179 <p>may be used.</p>
180 </li>
181 <li>
182 <p>If an option is found that was not specified in <i>optstring</i>, this error is identified and the invalid option character
183 shall be identified in the message.</p>
184 </li>
185 <li>
186 <p>If an option requiring an option-argument is found, but an option-argument is not found, this error shall be identified and the
187 invalid option character shall be identified in the message.</p>
188 </li>
189 </ul>
190 </blockquote>
191 <h4 class="mansect"><a name="tag_20_53_12" id="tag_20_53_12"></a>OUTPUT FILES</h4>
192 <blockquote>
193 <p>None.</p>
194 </blockquote>
195 <h4 class="mansect"><a name="tag_20_53_13" id="tag_20_53_13"></a>EXTENDED DESCRIPTION</h4>
196 <blockquote>
197 <p>None.</p>
198 </blockquote>
199 <h4 class="mansect"><a name="tag_20_53_14" id="tag_20_53_14"></a>EXIT STATUS</h4>
200 <blockquote>
201 <p>The following exit values shall be returned:</p>
202 <dl compact>
203 <dd></dd>
204 <dt> 0</dt>
205 <dd>An option, specified or unspecified by <i>optstring</i>, was found.</dd>
206 <dt> 1</dt>
207 <dd>The end of options was encountered.</dd>
208 <dt>>1</dt>
209 <dd>An error occurred.</dd>
210 </dl>
211 </blockquote>
212 <h4 class="mansect"><a name="tag_20_53_15" id="tag_20_53_15"></a>CONSEQUENCES OF ERRORS</h4>
213 <blockquote>
214 <p>Default.</p>
215 </blockquote>
216 <hr>
217 <div class="box"><em>The following sections are informative.</em></div>
218 <h4 class="mansect"><a name="tag_20_53_16" id="tag_20_53_16"></a>APPLICATION USAGE</h4>
219 <blockquote>
220 <p>This utility is required to be intrinsic. See <a href="../utilities/V3_chap01.html#tag_18_07"><i>1.7 Intrinsic Utilities</i></a>
221 for details.</p>
222 <p>Since <i>getopts</i> affects the current shell execution environment, it is generally provided as a shell regular built-in. If
223 it is called in a subshell or separate utility execution environment, such as one of the following:</p>
224 <pre>
225 <tt>(getopts abc value "$@")
226 nohup getopts ...
227 find . -exec getopts ... \;
228 </tt></pre>
229 <p>it does not affect the shell variables in the caller's environment.</p>
230 <p>Note that shell functions share <i>OPTIND</i> with the calling shell even though the positional parameters are changed. If the
231 calling shell and any of its functions uses <i>getopts</i> to parse arguments, the results are unspecified.</p>
232 </blockquote>
233 <h4 class="mansect"><a name="tag_20_53_17" id="tag_20_53_17"></a>EXAMPLES</h4>
234 <blockquote>
235 <p>The following example script parses and displays its arguments:</p>
236 <pre>
237 <tt>aflag=
238 bflag=
239 while getopts ab: name
240 do
241 case $name in
242 a) aflag=1;;
243 b) bflag=1
244 bval="$OPTARG";;
245 ?) printf "Usage: %s: [-a] [-b value] args\n" $0
246 exit 2;;
247 esac
248 done
249 if [ -n "$aflag" ]; then
250 printf "Option -a specified\n"
251 fi
252 if [ -n "$bflag" ]; then
253 printf 'Option -b "%s" specified\n' "$bval"
254 fi
255 shift $(($OPTIND - 1))
256 printf "Remaining arguments are: %s\n" "$*"
257 </tt></pre></blockquote>
258 <h4 class="mansect"><a name="tag_20_53_18" id="tag_20_53_18"></a>RATIONALE</h4>
259 <blockquote>
260 <p>The <i>getopts</i> utility was chosen in preference to the System V <i>getopt</i> utility because <i>getopts</i> handles
261 option-arguments containing <blank> characters.</p>
262 <p>The <i>OPTARG</i> variable is not mentioned in the ENVIRONMENT VARIABLES section because it does not affect the execution of
263 <i>getopts</i>; it is one of the few "output-only" variables used by the standard utilities.</p>
264 <p>The <colon> is not allowed as an option character because that is not historical behavior, and it violates the Utility
265 Syntax Guidelines. The <colon> is now specified to behave as in the KornShell version of the <i>getopts</i> utility; when
266 used as the first character in the <i>optstring</i> operand, it disables diagnostics concerning missing option-arguments and
267 unexpected option characters. This replaces the use of the <i>OPTERR</i> variable that was specified in an early proposal.</p>
268 <p>Although a leading <plus-sign> in <i>optstring</i> is required to have no effect on the behavior of <a href=
269 "../functions/getopt.html"><i>getopt</i>()</a>, this standard intentionally allows implementations of the <i>getopts</i> utility to
270 use a leading <plus-sign> as an extension that alters behavior. In fact, a <plus-sign> anywhere in the <i>optstring</i>
271 in the <i>getopts</i> utility produces unspecified behavior.</p>
272 <p>The formats of the diagnostic messages produced by the <i>getopts</i> utility and the <a href=
273 "../functions/getopt.html"><i>getopt</i>()</a> function are not fully specified because implementations with superior
274 ("friendlier") formats objected to the formats used by some historical implementations. The standard developers considered it
275 important that the information in the messages used be uniform between <i>getopts</i> and <a href=
276 "../functions/getopt.html"><i>getopt</i>()</a>. Exact duplication of the messages might not be possible, particularly if a utility
277 is built on another system that has a different <a href="../functions/getopt.html"><i>getopt</i>()</a> function, but the messages
278 must have specific information included so that the program name, invalid option character, and type of error can be distinguished
279 by a user.</p>
280 <p>Only a rare application program intercepts a <i>getopts</i> standard error message and wants to parse it. Therefore,
281 implementations are free to choose the most usable messages they can devise. The following formats are used by many historical
282 implementations:</p>
283 <pre>
284 <tt>"%s: illegal option -- %c\n", <</tt><i>program name</i><tt>>, <</tt><i>option character</i><tt>>
285 <br>
286 "%s: option requires an argument -- %c\n", <</tt><i>program name</i><tt>>, \
287 <</tt><i>option character</i><tt>>
288 </tt></pre>
289 <p>Historical shells with built-in versions of <a href="../functions/getopt.html"><i>getopt</i>()</a> or <i>getopts</i> have used
290 different formats, frequently not even indicating the option character found in error.</p>
291 </blockquote>
292 <h4 class="mansect"><a name="tag_20_53_19" id="tag_20_53_19"></a>FUTURE DIRECTIONS</h4>
293 <blockquote>
294 <p>None.</p>
295 </blockquote>
296 <h4 class="mansect"><a name="tag_20_53_20" id="tag_20_53_20"></a>SEE ALSO</h4>
297 <blockquote>
298 <p><a href="../utilities/V3_chap02.html#tag_19_05_02"><i>2.5.2 Special Parameters</i></a></p>
299 <p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href=
300 "../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p>
301 <p>XSH <a href="../functions/getopt.html#"><i>getopt</i></a></p>
302 </blockquote>
303 <h4 class="mansect"><a name="tag_20_53_21" id="tag_20_53_21"></a>CHANGE HISTORY</h4>
304 <blockquote>
305 <p>First released in Issue 4.</p>
306 </blockquote>
307 <h4 class="mansect"><a name="tag_20_53_22" id="tag_20_53_22"></a>Issue 6</h4>
308 <blockquote>
309 <p>The normative text is reworded to avoid use of the term "must" for application requirements.</p>
310 </blockquote>
311 <h4 class="mansect"><a name="tag_20_53_23" id="tag_20_53_23"></a>Issue 7</h4>
312 <blockquote>
313 <p>POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0092 [159] is applied.</p>
314 </blockquote>
315 <h4 class="mansect"><a name="tag_20_53_24" id="tag_20_53_24"></a>Issue 8</h4>
316 <blockquote>
317 <p>Austin Group Defect 191 is applied, adding a paragraph about leading <plus-sign> to the RATIONALE section.</p>
318 <p>Austin Group Defect 367 is applied, requiring that <i>getopts</i> distinguishes between encountering the end of options and an
319 error occurring, setting its exit status to one and greater than one, respectively.</p>
320 <p>Austin Group Defect 854 is applied, adding a note to the APPLICATION USAGE section that this utility is required to be
321 intrinsic.</p>
322 <p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p>
323 <p>Austin Group Defect 1442 is applied, changing the EXAMPLES section.</p>
324 <p>Austin Group Defect 1784 is applied, clarifying several aspects of <i>getopts</i> behavior and changing the value of
325 <i>OPTIND</i> to be unspecified in some circumstances.</p>
326 </blockquote>
327 <div class="box"><em>End of informative text.</em></div>
328 <hr>
329 <p> </p>
330 <a href="#top"><span class="topOfPage">return to top of page</span></a><br>
331 <hr size="2" noshade>
332 <center><font size="2">UNIX® is a registered Trademark of The Open Group.<br>
333 POSIX™ is a Trademark of The IEEE.<br>
334 Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br>
335 [ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
336 "../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a>
337 ]</font></center>
338 <hr size="2" noshade>
339 <div class="NAVHEADER">
340 <table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0">
341 <tr class="nav">
342 <td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/getconf.html" accesskey="P"><<<
343 Previous</a></td>
344 <td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td>
345 <td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/gettext.html" accesskey="N">Next
346 >>></a></td>
347 </tr>
348 </table>
349 <hr align="left" width="100%"></div>
350 </body>
351 </html>