383 lines
16 KiB
HTML
383 lines
16 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy, see www.w3.org">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group's rhtm tool v1.2.1 -->
|
|
<!-- Copyright (c) 2001 The Open Group, All Rights Reserved -->
|
|
<title>getopts</title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
|
</script>
|
|
|
|
<basefont size="3"> <a name="getopts"></a> <a name="tag_04_62"></a><!-- getopts -->
|
|
<!--header start-->
|
|
<center><font size="2">The Open Group Base Specifications Issue 6<br>
|
|
IEEE Std 1003.1-2001<br>
|
|
Copyright © 2001 The IEEE and The Open Group, All Rights reserved.</font></center>
|
|
|
|
<!--header end-->
|
|
<hr size="2" noshade>
|
|
<h4><a name="tag_04_62_01"></a>NAME</h4>
|
|
|
|
<blockquote>getopts - parse utility options</blockquote>
|
|
|
|
<h4><a name="tag_04_62_02"></a>SYNOPSIS</h4>
|
|
|
|
<blockquote class="synopsis">
|
|
<p><code><tt>getopts</tt> <i>optstring name</i> <b>[</b><i>arg</i><tt>...</tt><b>]</b></code></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_62_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>getopts</i> 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 IEEE Std 1003.1-2001, <a href=
|
|
"../basedefs/xbd_chap12.html#tag_12_02">Section 12.2, Utility Syntax Guidelines</a>.</p>
|
|
|
|
<p>Each time it is invoked, the <i>getopts</i> utility shall place the value of the next option in the shell variable specified by
|
|
the <i>name</i> operand and the index of the next argument to be processed in the shell variable <i>OPTIND .</i> Whenever the shell
|
|
is invoked, <i>OPTIND</i> shall be initialized to 1.</p>
|
|
|
|
<p>When the option requires an option-argument, the <i>getopts</i> utility shall place it in the shell variable <i>OPTARG .</i> If
|
|
no option was found, or if the option that was found does not have an option-argument, <i>OPTARG</i> shall be unset.</p>
|
|
|
|
<p>If an option character not contained in the <i>optstring</i> operand is found where an option character is expected, the shell
|
|
variable specified by <i>name</i> shall be set to the question-mark ( <tt>'?'</tt> ) character. In this case, if the first
|
|
character in <i>optstring</i> is a colon ( <tt>':'</tt> ), the shell variable <i>OPTARG</i> shall be set to the option character
|
|
found, but no output shall be written to standard error; otherwise, the shell variable <i>OPTARG</i> 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 <i>getopts</i> processing.</p>
|
|
|
|
<p>If an option-argument is missing:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<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 colon
|
|
character and the shell variable <i>OPTARG</i> shall be set to the option character found.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Otherwise, the shell variable specified by <i>name</i> shall be set to the question-mark character, the shell variable
|
|
<i>OPTARG</i> 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 <i>getopts</i>
|
|
processing; a diagnostic message shall be written as stated, but the exit status shall be zero.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>When the end of options is encountered, the <i>getopts</i> utility shall exit with a return value greater than zero; the shell
|
|
variable <i>OPTIND</i> shall be set to the index of the first non-option-argument, where the first <tt>"--"</tt> argument is
|
|
considered to be an option-argument if there are no other non-option-arguments appearing before it, or the value <tt>"$#"</tt> +1
|
|
if there are no non-option-arguments; the <i>name</i> variable shall be set to the question-mark character. Any of the following
|
|
shall identify the end of options: the special option <tt>"--"</tt> , finding an argument that does not begin with a <tt>'-'</tt> ,
|
|
or encountering an error.</p>
|
|
|
|
<p>The shell variables <i>OPTIND</i> and <i>OPTARG</i> shall be local to the caller of <i>getopts</i> and shall not be exported by
|
|
default.</p>
|
|
|
|
<p>The shell variable specified by the <i>name</i> operand, <i>OPTIND ,</i> and <i>OPTARG</i> shall affect the current shell
|
|
execution environment; see <a href="xcu_chap02.html#tag_02_12"><i>Shell Execution Environment</i></a> .</p>
|
|
|
|
<p>If the application sets <i>OPTIND</i> to the value 1, a new set of parameters can be used: either the current positional
|
|
parameters or new <i>arg</i> values. Any other attempt to invoke <i>getopts</i> multiple times in a single shell execution
|
|
environment with parameters (positional parameters or <i>arg</i> operands) that are not the same in all invocations, or with an
|
|
<i>OPTIND</i> value modified to be a value other than 1, produces unspecified results.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_62_04"></a>OPTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_62_05"></a>OPERANDS</h4>
|
|
|
|
<blockquote>
|
|
<p>The following operands shall be supported:</p>
|
|
|
|
<dl compact>
|
|
<dt><i>optstring</i></dt>
|
|
|
|
<dd>A string containing the option characters recognized by the utility invoking <i>getopts</i>. 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 <i>getopts</i> 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 <i>getopts</i> is invoked. (See also the <a href=
|
|
"../functions/getopt.html"><i>getopt</i>()</a> function defined in the System Interfaces volume of IEEE Std 1003.1-2001.)
|
|
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 <i>OPTARG</i> shall be stripped of the option character and the <tt>'-'</tt> . The first character
|
|
in <i>optstring</i> determines how <i>getopts</i> behaves if an option character is not known or an option-argument is
|
|
missing.</dd>
|
|
|
|
<dt><i>name</i></dt>
|
|
|
|
<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>
|
|
</dl>
|
|
|
|
<p>The <i>getopts</i> utility by default shall parse positional parameters passed to the invoking shell procedure. If <i>arg</i>s
|
|
are given, they shall be parsed instead of the positional parameters.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_62_06"></a>STDIN</h4>
|
|
|
|
<blockquote>
|
|
<p>Not used.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_62_07"></a>INPUT FILES</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_62_08"></a>ENVIRONMENT VARIABLES</h4>
|
|
|
|
<blockquote>
|
|
<p>The following environment variables shall affect the execution of <i>getopts</i>:</p>
|
|
|
|
<dl compact>
|
|
<dt><i>LANG</i></dt>
|
|
|
|
<dd>Provide a default value for the internationalization variables that are unset or null. (See the Base Definitions volume of
|
|
IEEE Std 1003.1-2001, <a href="../basedefs/xbd_chap08.html#tag_08_02">Section 8.2, Internationalization Variables</a> for
|
|
the precedence of internationalization variables used to determine the values of locale categories.)</dd>
|
|
|
|
<dt><i>LC_ALL</i></dt>
|
|
|
|
<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd>
|
|
|
|
<dt><i>LC_CTYPE</i></dt>
|
|
|
|
<dd>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).</dd>
|
|
|
|
<dt><i>LC_MESSAGES</i></dt>
|
|
|
|
<dd>Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard
|
|
error.</dd>
|
|
|
|
<dt><i>NLSPATH</i></dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
Determine the location of message catalogs for the processing of <i>LC_MESSAGES .</i> <img src="../images/opt-end.gif" alt=
|
|
"[Option End]" border="0"></dd>
|
|
|
|
<dt><i>OPTIND</i></dt>
|
|
|
|
<dd>This variable shall be used by the <i>getopts</i> utility as the index of the next argument to be processed.</dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_62_09"></a>ASYNCHRONOUS EVENTS</h4>
|
|
|
|
<blockquote>
|
|
<p>Default.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_62_10"></a>STDOUT</h4>
|
|
|
|
<blockquote>
|
|
<p>Not used.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_62_11"></a>STDERR</h4>
|
|
|
|
<blockquote>
|
|
<p>Whenever an error is detected and the first character in the <i>optstring</i> operand is not a colon ( <tt>':'</tt> ), a
|
|
diagnostic message shall be written to standard error with the following information in an unspecified format:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>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 <a href="xcu_chap02.html#tag_02_05_02"><i>Special Parameters</i></a> ) at the time the <i>getopts</i> utility is
|
|
invoked. A name equivalent to:</p>
|
|
|
|
<pre>
|
|
<tt>basename "$0"
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>may be used.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If an option is found that was not specified in <i>optstring</i>, this error is identified and the invalid option character
|
|
shall be identified in the message.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>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.</p>
|
|
</li>
|
|
</ul>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_62_12"></a>OUTPUT FILES</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_62_13"></a>EXTENDED DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_62_14"></a>EXIT STATUS</h4>
|
|
|
|
<blockquote>
|
|
<p>The following exit values shall be returned:</p>
|
|
|
|
<dl compact>
|
|
<dt> 0</dt>
|
|
|
|
<dd>An option, specified or unspecified by <i>optstring</i>, was found.</dd>
|
|
|
|
<dt>>0</dt>
|
|
|
|
<dd>The end of options was encountered or an error occurred.</dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_62_15"></a>CONSEQUENCES OF ERRORS</h4>
|
|
|
|
<blockquote>
|
|
<p>Default.</p>
|
|
</blockquote>
|
|
|
|
<hr>
|
|
<div class="box"><em>The following sections are informative.</em></div>
|
|
|
|
<h4><a name="tag_04_62_16"></a>APPLICATION USAGE</h4>
|
|
|
|
<blockquote>
|
|
<p>Since <i>getopts</i> 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:</p>
|
|
|
|
<pre>
|
|
<tt>(getopts abc value "$@")
|
|
nohup getopts ...
|
|
find . -exec getopts ... \;
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>it does not affect the shell variables in the caller's environment.</p>
|
|
|
|
<p>Note that shell functions share <i>OPTIND</i> with the calling shell even though the positional parameters are changed. If the
|
|
calling shell and any of its functions uses <i>getopts</i> to parse arguments, the results are unspecified.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_62_17"></a>EXAMPLES</h4>
|
|
|
|
<blockquote>
|
|
<p>The following example script parses and displays its arguments:</p>
|
|
|
|
<pre>
|
|
<tt>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\n" $0
|
|
exit 2;;
|
|
esac
|
|
done
|
|
if [ ! -z "$aflag" ]; then
|
|
printf "Option -a specified\n"
|
|
fi
|
|
if [ ! -z "$bflag" ]; then
|
|
printf 'Option -b "%s" specified\n' "$bval"
|
|
fi
|
|
shift $(($OPTIND - 1))
|
|
printf "Remaining arguments are: %s\n" "$*"
|
|
</tt>
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_62_18"></a>RATIONALE</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>getopts</i> utility was chosen in preference to the System V <i>getopt</i> utility because <i>getopts</i> handles
|
|
option-arguments containing <blank>s.</p>
|
|
|
|
<p>The <i>OPTARG</i> variable is not mentioned in the ENVIRONMENT VARIABLES section because it does not affect the execution of
|
|
<i>getopts</i>; it is one of the few "output-only" variables used by the standard utilities.</p>
|
|
|
|
<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 <i>getopts</i> utility; when used as the first
|
|
character in the <i>optstring</i> operand, it disables diagnostics concerning missing option-arguments and unexpected option
|
|
characters. This replaces the use of the <i>OPTERR</i> variable that was specified in an early proposal.</p>
|
|
|
|
<p>The formats of the diagnostic messages produced by the <i>getopts</i> utility and the <a href=
|
|
"../functions/getopt.html"><i>getopt</i>()</a> 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 <i>getopts</i> and <a href=
|
|
"../functions/getopt.html"><i>getopt</i>()</a>. Exact duplication of the messages might not be possible, particularly if a utility
|
|
is built on another system that has a different <a href="../functions/getopt.html"><i>getopt</i>()</a> 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>
|
|
|
|
<p>Only a rare application program intercepts a <i>getopts</i> 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:</p>
|
|
|
|
<pre>
|
|
<tt>"%s: illegal option -- %c\n", <</tt><i>program name</i><tt>>, <</tt><i>option character</i><tt>>
|
|
<br>
|
|
"%s: option requires an argument -- %c\n", <</tt><i>program name</i><tt>>, \
|
|
<</tt><i>option character</i><tt>>
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>Historical shells with built-in versions of <a href="../functions/getopt.html"><i>getopt</i>()</a> or <i>getopts</i> have used
|
|
different formats, frequently not even indicating the option character found in error.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_62_19"></a>FUTURE DIRECTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_62_20"></a>SEE ALSO</h4>
|
|
|
|
<blockquote>
|
|
<p><a href="xcu_chap02.html#tag_02_05_02"><i>Special Parameters</i></a> , the System Interfaces volume of
|
|
IEEE Std 1003.1-2001, <a href="../functions/getopt.html"><i>getopt</i>()</a></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_62_21"></a>CHANGE HISTORY</h4>
|
|
|
|
<blockquote>
|
|
<p>First released in Issue 4.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_62_22"></a>Issue 6</h4>
|
|
|
|
<blockquote>
|
|
<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p>
|
|
</blockquote>
|
|
|
|
<div class="box"><em>End of informative text.</em></div>
|
|
|
|
<hr>
|
|
<hr size="2" noshade>
|
|
<center><font size="2"><!--footer start-->
|
|
UNIX ® is a registered Trademark of The Open Group.<br>
|
|
POSIX ® is a registered Trademark of The IEEE.<br>
|
|
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
|
|
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
|
|
]</font></center>
|
|
|
|
<!--footer end-->
|
|
<hr size="2" noshade>
|
|
</body>
|
|
</html>
|
|
|