306 lines
15 KiB
HTML
306 lines
15 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>Utility Conventions</title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
|
</script>
|
|
|
|
<basefont size="3"> <!--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>
|
|
<h2><a name="tag_12"></a>Utility Conventions</h2>
|
|
|
|
<h3><a name="tag_12_01"></a>Utility Argument Syntax</h3>
|
|
|
|
<p>This section describes the argument syntax of the standard utilities and introduces terminology used throughout
|
|
IEEE Std 1003.1-2001 for describing the arguments processed by the utilities.</p>
|
|
|
|
<p>Within IEEE Std 1003.1-2001, a special notation is used for describing the syntax of a utility's arguments. Unless
|
|
otherwise noted, all utility descriptions use this notation, which is illustrated by this example (see the Shell and Utilities
|
|
volume of IEEE Std 1003.1-2001, <a href="../utilities/xcu_chap02.html#tag_02_09_01">Section 2.9.1, Simple
|
|
Commands</a>):</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
<tt>utility_name</tt><b>[</b><tt>-a</tt><b>][</b><tt>-b</tt><b>][</b><tt>-c</tt> <i>option_argument</i><b>]
|
|
[</b><tt>-d|-e</tt><b>][</b><tt>-f</tt><i>option_argument</i><b>][</b><i>operand</i><tt>...</tt><b>]</b>
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p>The notation used for the SYNOPSIS sections imposes requirements on the implementors of the standard utilities and provides a
|
|
simple reference for the application developer or system user.</p>
|
|
|
|
<ol>
|
|
<li>
|
|
<p>The utility in the example is named <i>utility_name</i>. It is followed by options, option-arguments, and operands. The
|
|
arguments that consist of hyphens and single letters or digits, such as <tt>'a'</tt> , are known as "options" (or, historically,
|
|
"flags"). Certain options are followed by an "option-argument", as shown with [ <b>-c</b> <i>option_argument</i>]. The
|
|
arguments following the last options and option-arguments are named "operands".</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Option-arguments are sometimes shown separated from their options by <blank>s, sometimes directly adjacent. This reflects
|
|
the situation that in some cases an option-argument is included within the same argument string as the option; in most cases it is
|
|
the next argument. The Utility Syntax Guidelines in <a href="#tag_12_02">Utility Syntax Guidelines</a> require that the option be a
|
|
separate argument from its option-argument, but there are some exceptions in IEEE Std 1003.1-2001 to ensure continued
|
|
operation of historical applications:</p>
|
|
|
|
<ol type="a">
|
|
<li>
|
|
<p>If the SYNOPSIS of a standard utility shows a <space> between an option and option-argument (as with [ <b>-c</b>
|
|
<i>option_argument</i>] in the example), a conforming application shall use separate arguments for that option and its
|
|
option-argument.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If a <space> is not shown (as with [ <b>-f</b> <i>option_argument</i>] in the example), a conforming application shall
|
|
place an option and its option-argument directly adjacent in the same argument string, without intervening <blank>s.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Notwithstanding the preceding requirements on conforming applications, a conforming implementation shall permit an application
|
|
to specify options and option-arguments as a single argument or as separate arguments whether or not a <space> is shown on
|
|
the synopsis line, <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt=
|
|
"[Option Start]" border="0"> except in those cases (marked with the XSI portability warning) where an option-argument is
|
|
optional and no separation can be used. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>A standard utility may also be implemented to operate correctly when the required separation into multiple arguments is violated
|
|
by a non-conforming application.</p>
|
|
</li>
|
|
</ol>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Options are usually listed in alphabetical order unless this would make the utility description more confusing. There are no
|
|
implied relationships between the options based upon the order in which they appear, unless otherwise stated in the OPTIONS
|
|
section, or unless the exception in Guideline 11 of <a href="#tag_12_02">Utility Syntax Guidelines</a> applies. If an option that
|
|
does not have option-arguments is repeated, the results are undefined, unless otherwise stated.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Frequently, names of parameters that require substitution by actual values are shown with embedded underscores. Alternatively,
|
|
parameters are shown as follows:</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
<tt><</tt><i>parameter name</i><tt>>
|
|
</tt>
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p>The angle brackets are used for the symbolic grouping of a phrase representing a single parameter and conforming applications
|
|
shall not include them in data submitted to the utility.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>When a utility has only a few permissible options, they are sometimes shown individually, as in the example. Utilities with many
|
|
flags generally show all of the individual flags (that do not take option-arguments) grouped, as in:</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
<tt>utility_name</tt> <b>[</b><tt>-abcDxyz</tt><b>][</b><tt>-p</tt> <i>arg</i><b>][</b><i>operand</i><b>]</b>
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p>Utilities with very complex arguments may be shown as follows:</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
<tt>utility_name</tt> <b>[</b><tt>options</tt><b>][</b><i>operands</i><b>]</b>
|
|
</pre>
|
|
</blockquote>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Unless otherwise specified, whenever an operand or option-argument is, or contains, a numeric value:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>The number is interpreted as a decimal integer.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Numerals in the range 0 to 2147483647 are syntactically recognized as numeric values.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>When the utility description states that it accepts negative numbers as operands or option-arguments, numerals in the range
|
|
-2147483647 to 2147483647 are syntactically recognized as numeric values.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Ranges greater than those listed here are allowed.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>This does not mean that all numbers within the allowable range are necessarily semantically correct. A standard utility that
|
|
accepts an option-argument or operand that is to be interpreted as a number, and for which a range of values smaller than that
|
|
shown above is permitted by the IEEE Std 1003.1-2001, describes that smaller range along with the description of the
|
|
option-argument or operand. If an error is generated, the utility's diagnostic message shall indicate that the value is out of the
|
|
supported range, not that it is syntactically incorrect.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Arguments or option-arguments enclosed in the <tt>'['</tt> and <tt>']'</tt> notation are optional and can be omitted. Conforming
|
|
applications shall not include the <tt>'['</tt> and <tt>']'</tt> symbols in data submitted to the utility.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Arguments separated by the <tt>'|'</tt> vertical bar notation are mutually-exclusive. Conforming applications shall not include
|
|
the <tt>'|'</tt> symbol in data submitted to the utility. Alternatively, mutually-exclusive options and operands may be listed with
|
|
multiple synopsis lines. For example:</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
<tt>utility_name -d</tt><b>[</b><tt>-a</tt><b>][</b><tt>-c</tt> <i>option_argument</i><b>][</b><i>operand</i><tt>...</tt><b>]</b>
|
|
<tt>utility_name</tt><b>[</b><tt>-a</tt><b>][</b><tt>-b</tt><b>][</b><i>operand</i><tt>...</tt><b>]</b>
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p>When multiple synopsis lines are given for a utility, it is an indication that the utility has mutually-exclusive arguments.
|
|
These mutually-exclusive arguments alter the functionality of the utility so that only certain other arguments are valid in
|
|
combination with one of the mutually-exclusive arguments. Only one of the mutually-exclusive arguments is allowed for invocation of
|
|
the utility. Unless otherwise stated in an accompanying OPTIONS section, the relationships between arguments depicted in the
|
|
SYNOPSIS sections are mandatory requirements placed on conforming applications. The use of conflicting mutually-exclusive arguments
|
|
produces undefined results, unless a utility description specifies otherwise. When an option is shown without the <tt>'['</tt> and
|
|
<tt>']'</tt> brackets, it means that option is required for that version of the SYNOPSIS. However, it is not required to be the
|
|
first argument, as shown in the example above, unless otherwise stated.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Ellipses ( <tt>"..."</tt> ) are used to denote that one or more occurrences of an option or operand are allowed. When an option
|
|
or an operand followed by ellipses is enclosed in brackets, zero or more options or operands can be specified. The forms:</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
<tt>utility_name -f</tt> <i>option_argument</i><tt>...</tt><b>[</b><i>operand</i><tt>...</tt><b>]</b>
|
|
<tt>utility_name</tt> <b>[</b><tt>-g</tt> <i>option_argument</i><b>]</b><tt>...</tt><b>[</b><i>operand</i><tt>...</tt><b>]</b>
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p>indicate that multiple occurrences of the option and its option-argument preceding the ellipses are valid, with semantics as
|
|
indicated in the OPTIONS section of the utility. (See also Guideline 11 in <a href="#tag_12_02">Utility Syntax Guidelines</a> .) In
|
|
the first example, each option-argument requires a preceding <b>-f</b> and at least one <b>-f</b> <i>option_argument</i> must be
|
|
given.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>When the synopsis line is too long to be printed on a single line in the Shell and Utilities volume of
|
|
IEEE Std 1003.1-2001, the indented lines following the initial line are continuation lines. An actual use of the command
|
|
would appear on a single logical line.</p>
|
|
</li>
|
|
</ol>
|
|
|
|
<h3><a name="tag_12_02"></a>Utility Syntax Guidelines</h3>
|
|
|
|
<p>The following guidelines are established for the naming of utilities and for the specification of options, option-arguments, and
|
|
operands. The <a href="../functions/getopt.html"><i>getopt</i>()</a> function in the System Interfaces volume of
|
|
IEEE Std 1003.1-2001 assists utilities in handling options and operands that conform to these guidelines.</p>
|
|
|
|
<p>Operands and option-arguments can contain characters not specified in the portable character set.</p>
|
|
|
|
<p>The guidelines are intended to provide guidance to the authors of future utilities, such as those written specific to a local
|
|
system or that are components of a larger application. Some of the standard utilities do not conform to all of these guidelines; in
|
|
those cases, the OPTIONS sections describe the deviations.</p>
|
|
|
|
<dl compact>
|
|
<dt><b>Guideline 1:</b></dt>
|
|
|
|
<dd>Utility names should be between two and nine characters, inclusive.</dd>
|
|
|
|
<dt><b>Guideline 2:</b></dt>
|
|
|
|
<dd>Utility names should include lowercase letters (the <b>lower</b> character classification) and digits only from the portable
|
|
character set.</dd>
|
|
|
|
<dt><b>Guideline 3:</b></dt>
|
|
|
|
<dd>Each option name should be a single alphanumeric character (the <b>alnum</b> character classification) from the portable
|
|
character set. The <b>-W</b> (capital-W) option shall be reserved for vendor options.
|
|
|
|
<p>Multi-digit options should not be allowed.</p>
|
|
</dd>
|
|
|
|
<dt><b>Guideline 4:</b></dt>
|
|
|
|
<dd>All options should be preceded by the <tt>'-'</tt> delimiter character.</dd>
|
|
|
|
<dt><b>Guideline 5:</b></dt>
|
|
|
|
<dd>Options without option-arguments should be accepted when grouped behind one <tt>'-'</tt> delimiter.</dd>
|
|
|
|
<dt><b>Guideline 6:</b></dt>
|
|
|
|
<dd>Each option and option-argument should be a separate argument, except as noted in <a href="#tag_12_01">Utility Argument
|
|
Syntax</a> , item (2).</dd>
|
|
|
|
<dt><b>Guideline 7:</b></dt>
|
|
|
|
<dd>Option-arguments should not be optional.</dd>
|
|
|
|
<dt><b>Guideline 8:</b></dt>
|
|
|
|
<dd>When multiple option-arguments are specified to follow a single option, they should be presented as a single argument, using
|
|
commas within that argument or <blank>s within that argument to separate them.</dd>
|
|
|
|
<dt><b>Guideline 9:</b></dt>
|
|
|
|
<dd>All options should precede operands on the command line.</dd>
|
|
|
|
<dt><b>Guideline 10:</b></dt>
|
|
|
|
<dd>The argument <b>--</b> should be accepted as a delimiter indicating the end of options. Any following arguments should be
|
|
treated as operands, even if they begin with the <tt>'-'</tt> character. The <b>--</b> argument should not be used as an option or
|
|
as an operand.</dd>
|
|
|
|
<dt><b>Guideline 11:</b></dt>
|
|
|
|
<dd>The order of different options relative to one another should not matter, unless the options are documented as
|
|
mutually-exclusive and such an option is documented to override any incompatible options preceding it. If an option that has
|
|
option-arguments is repeated, the option and option-argument combinations should be interpreted in the order specified on the
|
|
command line.</dd>
|
|
|
|
<dt><b>Guideline 12:</b></dt>
|
|
|
|
<dd>The order of operands may matter and position-related interpretations should be determined on a utility-specific basis.</dd>
|
|
|
|
<dt><b>Guideline 13:</b></dt>
|
|
|
|
<dd>For utilities that use operands to represent files to be opened for either reading or writing, the <tt>'-'</tt> operand should
|
|
be used only to mean standard input (or standard output when it is clear from context that an output file is being specified).</dd>
|
|
</dl>
|
|
|
|
<p>The utilities in the Shell and Utilities volume of IEEE Std 1003.1-2001 that claim conformance to these guidelines
|
|
shall conform completely to these guidelines as if these guidelines contained the term "shall" instead of "should". On some
|
|
implementations, the utilities accept usage in violation of these guidelines for backwards-compatibility as well as accepting the
|
|
required form.</p>
|
|
|
|
<p>It is recommended that all future utilities and applications use these guidelines to enhance user portability. The fact that
|
|
some historical utilities could not be changed (to avoid breaking existing applications) should not deter this future goal.</p>
|
|
|
|
<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>
|
|
|