xcu_chap01.html

IEEE 1003.1-2003, Single Unix Specification v3

such as {ULONG_MAX} (from the ISO C standard). Therefore, applications desiring to tailor themselves to the values on a
particular implementation need to be ready for possibly huge values; it may not be a good idea to allocate blindly a buffer for an
input line based on the value of {LINE_MAX}, for instance. However, unlike the System Interfaces volume of
IEEE Std 1003.1-2001, there is no set of limits that return a special indication meaning "unbounded". The
implementation should always return an actual number, even if the number is very large.</p>

<p>The statement:</p>

<blockquote>
<pre>
&quot;It is not guaranteed that the application ...''
</pre>
</blockquote>

<p>is an indication that many of these limits are designed to ensure that implementors design their utilities without arbitrary
constraints related to unimaginative programming. There are certainly conditions under which combinations of options can cause
failures that would not render an implementation non-conforming. For example, {EXPR_NEST_MAX} and {ARG_MAX} could collide when
expressions are large; combinations of {BC_SCALE_MAX} and {BC_DIM_MAX} could exceed virtual memory.</p>

<p>In the Shell and Utilities volume of IEEE&nbsp;Std&nbsp;1003.1-2001, the notion of a limit being guaranteed for the process
lifetime, as it is in the System Interfaces volume of IEEE&nbsp;Std&nbsp;1003.1-2001, is not as useful to a shell script. The <a
href="../utilities/getconf.html"><i>getconf</i></a> utility is probably a process itself, so the guarantee would be without value.
Therefore, the Shell and Utilities volume of IEEE&nbsp;Std&nbsp;1003.1-2001 requires the guarantee to be for the session lifetime.
This will mean that many vendors will either return very conservative values or possibly implement <a href=
"../utilities/getconf.html"><i>getconf</i></a> as a built-in.</p>

<p>It may seem confusing to have limits that apply only to a single utility grouped into one global section. However, the
alternative, which would be to disperse them out into their utility description sections, would cause great difficulty when <a
href="../functions/sysconf.html"><i>sysconf</i>()</a> and <a href="../utilities/getconf.html"><i>getconf</i></a> were described.
Therefore, the standard developers chose the global approach.</p>

<p>Each language binding could provide symbol names that are slightly different from those shown here. For example, the C-Language
Binding option adds a leading underscore to the symbols as a prefix.</p>

<p>The following comments describe selection criteria for the symbols and their values:</p>

<dl compact>
<dt>{ARG_MAX}</dt>

<dd>
This is defined by the System Interfaces volume of IEEE&nbsp;Std&nbsp;1003.1-2001. Unfortunately, it is very difficult for a
conforming application to deal with this value, as it does not know how much of its argument space is being consumed by the
environment variables of the user.<br>
</dd>

<dt>{BC_BASE_MAX}</dt>

<dt>{BC_DIM_MAX}</dt>

<dt>{BC_SCALE_MAX}</dt>

<dd>
These were originally one value, {BC_SCALE_MAX}, but it was unreasonable to link all three concepts into one limit.</dd>

<dt>{CHILD_MAX}</dt>

<dd>
This is defined by the System Interfaces volume of IEEE&nbsp;Std&nbsp;1003.1-2001.</dd>

<dt>{COLL_WEIGHTS_MAX}</dt>

<dd>
The weights assigned to <b>order</b> can be considered as &quot;passes&quot; through the collation algorithm.</dd>

<dt>{EXPR_NEST_MAX}</dt>

<dd>
The value for expression nesting was borrowed from the ISO&nbsp;C standard.</dd>

<dt>{LINE_MAX}</dt>

<dd>
This is a global limit that affects all utilities, unless otherwise noted. The {MAX_CANON} value from the System Interfaces volume
of IEEE&nbsp;Std&nbsp;1003.1-2001 may further limit input lines from terminals. The {LINE_MAX} value was the subject of much debate
and is a compromise between those who wished to have unlimited lines and those who understood that many historical utilities were
written with fixed buffers. Frequently, utility writers selected the UNIX system constant BUFSIZ to allocate these buffers;
therefore, some utilities were limited to 512 bytes for I/O lines, while others achieved 4096 bytes or greater. 

<p>It should be noted that {LINE_MAX} applies only to input line length; there is no requirement in IEEE&nbsp;Std&nbsp;1003.1-2001
that limits the length of output lines. Utilities such as <a href="../utilities/awk.html"><i>awk</i></a>, <a href=
"../utilities/sed.html"><i>sed</i></a>, and <a href="../utilities/paste.html"><i>paste</i></a> could theoretically construct lines
longer than any of the input lines they received, depending on the options used or the instructions from the application. They are
not required to truncate their output to {LINE_MAX}. It is the responsibility of the application to deal with this. If the output
of one of those utilities is to be piped into another of the standard utilities, line length restrictions will have to be
considered; the <a href="../utilities/fold.html"><i>fold</i></a> utility, among others, could be used to ensure that only
reasonable line lengths reach utilities or applications.</p>
</dd>

<dt>{LINK_MAX}</dt>

<dd>
This is defined by the System Interfaces volume of IEEE&nbsp;Std&nbsp;1003.1-2001.</dd>

<dt>{MAX_CANON}</dt>

<dt>{MAX_INPUT}</dt>

<dt>{NAME_MAX}</dt>

<dt>{NGROUPS_MAX}</dt>

<dt>{OPEN_MAX}</dt>

<dt>{PATH_MAX}</dt>

<dt>{PIPE_BUF}</dt>

<dd>
These limits are defined by the System Interfaces volume of IEEE&nbsp;Std&nbsp;1003.1-2001. Note that the byte lengths described by
some of these values continue to represent bytes, even if the applicable character set uses a multi-byte encoding.</dd>

<dt>{RE_DUP_MAX}</dt>

<dd>
The value selected is consistent with historical practice. Although the name implies that it applies to all REs, only BREs use the
interval notation <b>\{</b><i>m,n</i><b>\}</b> addressed by this limit.</dd>

<dt>{POSIX2_SYMLINKS}</dt>

<dd>
The {POSIX2_SYMLINKS} variable indicates that the underlying operating system supports the creation of symbolic links in specific
directories. Many of the utilities defined in IEEE&nbsp;Std&nbsp;1003.1-2001 that deal with symbolic links do not depend on this
value. For example, a utility that follows symbolic links (or does not, as the case may be) will only be affected by a symbolic
link if it encounters one. Presumably, a file system that does not support symbolic links will not contain any. This variable does
affect such utilities as <a href="../utilities/ln.html"><i>ln</i></a> <b>-s</b> and <a href="../utilities/pax.html"><i>pax</i></a>
that attempt to create symbolic links. 

<p>{POSIX2_SYMLINKS} was developed even though there is no comparable configuration value for the system interfaces.</p>
</dd>
</dl>

<p>There are different limits associated with command lines and input to utilities, depending on the method of invocation. In the
case of a C program <i>exec</i>-ing a utility, {ARG_MAX} is the underlying limit. In the case of the shell reading a script and
<i>exec</i>-ing a utility, {LINE_MAX} limits the length of lines the shell is required to process, and {ARG_MAX} will still be a
limit. If a user is entering a command on a terminal to the shell, requesting that it invoke the utility, {MAX_INPUT} may restrict
the length of the line that can be given to the shell to a value below {LINE_MAX}.</p>

<p>When an option is supported, <a href="../utilities/getconf.html"><i>getconf</i></a> returns a value of 1. For example, when C
development is supported:</p>

<blockquote>
<pre>
<tt>if [ "$(getconf POSIX2_C_DEV)" -eq 1 ]; then
    echo C supported
fi
</tt>
</pre>
</blockquote>

<p>The <a href="../functions/sysconf.html"><i>sysconf</i>()</a> function in the C-Language Binding option would return 1.</p>

<p>The following comments describe selection criteria for the symbols and their values:</p>

<dl compact>
<dt>POSIX2_C_BIND</dt>

<dt>POSIX2_C_DEV</dt>

<dt>POSIX2_FORT_DEV</dt>

<dt>POSIX2_FORT_RUN</dt>

<dt>POSIX2_SW_DEV</dt>

<dt>POSIX2_UPE</dt>

<dd>
It is possible for some (usually privileged) operations to remove utilities that support these options or otherwise to render these
options unsupported. The header files, the <a href="../functions/sysconf.html"><i>sysconf</i>()</a> function, or the <a href=
"../utilities/getconf.html"><i>getconf</i></a> utility will not necessarily detect such actions, in which case they should not be
considered as rendering the implementation non-conforming. A test suite should not attempt tests such as: 

<pre>
<tt>rm /usr/bin/c99
getconf POSIX2_C_DEV
</tt>
</pre>
</dd>

<dt>POSIX2_LOCALEDEF</dt>

<dd>
This symbol was introduced to allow implementations to restrict supported locales to only those supplied by the
implementation.</dd>
</dl>

<p>IEEE&nbsp;Std 1003.1-2001/Cor&nbsp;1-2002, item XCU/TC1/D6/2 is applied, deleting the entry for {POSIX2_VERSION} since it is not
a utility limit minimum value.</p>

<p>IEEE&nbsp;Std 1003.1-2001/Cor&nbsp;1-2002, item XCU/TC1/D6/3 is applied, changing the text in Utility Limits from: &quot;utility
(see <a href="../utilities/getconf.html"><i>getconf</i></a>) through the <a href="../functions/sysconf.html"><i>sysconf</i>()</a>
function defined in the System Interfaces volume of IEEE&nbsp;Std&nbsp;1003.1-2001. The literal names shown in Table 1-3 apply only
to the <a href="../utilities/getconf.html"><i>getconf</i></a> utility; the high-level language binding describes the exact form of
each name to be used by the interfaces in that binding.&quot; to: &quot;utility (see <a href=
"../utilities/getconf.html"><i>getconf</i></a>).&quot;.</p>

<h4><a name="tag_02_01_10"></a>Grammar Conventions</h4>

<p>There is no additional rationale provided for this section.</p>

<h4><a name="tag_02_01_11"></a>Utility Description Defaults</h4>

<p>This section is arranged with headings in the same order as all the utility descriptions. It is a collection of related and
unrelated information concerning:</p>

<ol>
<li>
<p>The default actions of utilities</p>
</li>

<li>
<p>The meanings of notations used in IEEE&nbsp;Std&nbsp;1003.1-2001 that are specific to individual utility sections</p>
</li>
</ol>

<p>Although this material may seem out of place here, it is important that this information appear before any of the utilities to
be described later.</p>

<h5><a name="tag_02_01_11_01"></a>NAME</h5>

<p>There is no additional rationale provided for this section.</p>

<h5><a name="tag_02_01_11_02"></a>SYNOPSIS</h5>

<p>There is no additional rationale provided for this section.</p>

<h5><a name="tag_02_01_11_03"></a>DESCRIPTION</h5>

<p>There is no additional rationale provided for this section.</p>

<h5><a name="tag_02_01_11_04"></a>OPTIONS</h5>

<p>Although it has not always been possible, the standard developers tried to avoid repeating information to reduce the risk that
duplicate explanations could each be modified differently.</p>

<p>The need to recognize <b>--</b> is required because conforming applications need to shield their operands from any arbitrary
options that the implementation may provide as an extension. For example, if the standard utility <i>foo</i> is listed as taking no
options, and the application needed to give it a pathname with a leading hyphen, it could safely do it as:</p>

<pre>
<tt>foo -- -myfile
</tt>
</pre>

<p>and avoid any problems with <b>-m</b> used as an extension.</p>

<h5><a name="tag_02_01_11_05"></a>OPERANDS</h5>

<p>The usage of <b>-</b> is never shown in the SYNOPSIS. Similarly, the usage of <b>--</b> is never shown.</p>

<p>The requirement for processing operands in command-line order is to avoid a &quot;WeirdNIX&quot; utility that might choose to sort the
input files alphabetically, by size, or by directory order. Although this might be acceptable for some utilities, in general the
programmer has a right to know exactly what order will be chosen.</p>

<p>Some of the standard utilities take multiple <i>file</i> operands and act as if they were processing the concatenation of those
files. For example:</p>

<blockquote>
<pre>
<tt>asa file1 file2
</tt>
</pre>
</blockquote>

<p>and:</p>

<blockquote>
<pre>
<tt>cat file1 file2 | asa
</tt>
</pre>
</blockquote>

<p>have similar results when questions of file access, errors, and performance are ignored. Other utilities such as <a href=
"../utilities/grep.html"><i>grep</i></a> or <a href="../utilities/wc.html"><i>wc</i></a> have completely different results in these
two cases. This latter type of utility is always identified in its DESCRIPTION or OPERANDS sections, whereas the former is not.
Although it might be possible to create a general assertion about the former case, the following points must be addressed:</p>

<ul>
<li>
<p>Access times for the files might be different in the operand case <i>versus</i> the <a href=
"../utilities/cat.html"><i>cat</i></a> case.</p>
</li>

<li>
<p>The utility may have error messages that are cognizant of the input filename, and this added value should not be suppressed. (As
an example, <a href="../utilities/awk.html"><i>awk</i></a> sets a variable with the filename at each file boundary.)</p>
</li>
</ul>

<h5><a name="tag_02_01_11_06"></a>STDIN</h5>

<p>There is no additional rationale provided for this section.</p>

<h5><a name="tag_02_01_11_07"></a>INPUT FILES</h5>

<p>A conforming application cannot assume the following three commands are equivalent:</p>

<pre>
<tt>tail -n +2 file
(sed -n 1q; cat) &lt; file
cat file | (sed -n 1q; cat)
</tt>
</pre>