xbd_chap01.html

IEEE 1003.1-2003, Single Unix Specification v3

<h4><a name="tag_01_01_03"></a>Normative References</h4>

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

<h4><a name="tag_01_01_04"></a>Terminology</h4>

<p>The meanings specified in IEEE&nbsp;Std&nbsp;1003.1-2001 for the words <i>shall</i>, <i>should</i>, and <i>may</i> are mandated
by ISO/IEC directives.</p>

<p>In the Rationale (Informative) volume of IEEE&nbsp;Std&nbsp;1003.1-2001, the words <i>shall</i>, <i>should</i>, and <i>may</i>
are sometimes used to illustrate similar usages in IEEE&nbsp;Std&nbsp;1003.1-2001. However, the rationale itself does not specify
anything regarding implementations or applications.</p>

<h4><a name="tag_01_01_05"></a>conformance document</h4>

<p>As a practical matter, the conformance document is effectively part of the system documentation. Conformance documents are
distinguished by IEEE&nbsp;Std&nbsp;1003.1-2001 so that they can be referred to distinctly.</p>

<h4><a name="tag_01_01_06"></a>implementation-defined</h4>

<p>This definition is analogous to that of the ISO&nbsp;C standard and, together with &quot;undefined&quot; and &quot;unspecified&quot;, provides a
range of specification of freedom allowed to the interface implementor.</p>

<h4><a name="tag_01_01_07"></a>may</h4>

<p>The use of <i>may</i> has been limited as much as possible, due both to confusion stemming from its ordinary English meaning and
to objections regarding the desirability of having as few options as possible and those as clearly specified as possible.</p>

<p>The usage of <i>can</i> and <i>may</i> were selected to contrast optional application behavior (can) against optional
implementation behavior (may).</p>

<h4><a name="tag_01_01_08"></a>shall</h4>

<p>Declarative sentences are sometimes used in IEEE&nbsp;Std&nbsp;1003.1-2001 as if they included the word <i>shall</i>, and
facilities thus specified are no less required. For example, the two statements:</p>

<ol>
<li>
<p>The <i>foo</i>() function shall return zero.</p>
</li>

<li>
<p>The <i>foo</i>() function returns zero.</p>
</li>
</ol>

<p>are meant to be exactly equivalent.</p>

<h4><a name="tag_01_01_09"></a>should</h4>

<p>In IEEE&nbsp;Std&nbsp;1003.1-2001, the word <i>should</i> does not usually apply to the implementation, but rather to the
application. Thus, the important words regarding implementations are <i>shall</i>, which indicates requirements, and <i>may</i>,
which indicates options.</p>

<h4><a name="tag_01_01_10"></a>obsolescent</h4>

<p>The term &quot;obsolescent&quot; means &quot;do not use this feature in new applications&quot;. The obsolescence concept is not an ideal
solution, but was used as a method of increasing consensus: many more objections would be heard from the user community if some of
these historical features were suddenly withdrawn without the grace period obsolescence implies. The phrase &quot;may be considered for
withdrawal in future revisions&quot; implies that the result of that consideration might in fact keep those features indefinitely if
the predominance of applications do not migrate away from them quickly.</p>

<h4><a name="tag_01_01_11"></a>legacy</h4>

<p>The term &quot;legacy&quot; was added for compatibility with the Single UNIX Specification. It means &quot;this feature is historic and
optional; do not use this feature in new applications. There are alternative interfaces that are more suitable.&quot;. It is used
exclusively for XSI extensions, and includes facilities that were mandatory in previous versions of the base document but are
optional in this revision. This is a way to &quot;sunset&quot; the usage of certain functions. Application writers should not rely on the
existence of these facilities in new applications, but should follow the migration path detailed in the APPLICATION USAGE sections
of the relevant pages.</p>

<p>The terms &quot;legacy&quot; and &quot;obsolescent&quot; are different: a feature marked LEGACY is not recommended for new work and need not be
present on an implementation (if the XSI Legacy Option Group is not supported). A feature noted as obsolescent is supported by all
implementations, but may be removed in a future revision; new applications should not use these features.</p>

<h4><a name="tag_01_01_12"></a>system documentation</h4>

<p>The system documentation should normally describe the whole of the implementation, including any extensions provided by the
implementation. Such documents normally contain information at least as detailed as the specifications in
IEEE&nbsp;Std&nbsp;1003.1-2001. Few requirements are made on the system documentation, but the term is needed to avoid a dangling
pointer where the conformance document is permitted to point to the system documentation.</p>

<h4><a name="tag_01_01_13"></a>undefined</h4>

<p>See <i>implementation-defined</i>.</p>

<h4><a name="tag_01_01_14"></a>unspecified</h4>

<p>See <i>implementation-defined</i>.</p>

<p>The definitions for &quot;unspecified&quot; and &quot;undefined&quot; appear nearly identical at first examination, but are not. The term
&quot;unspecified&quot; means that a conforming application may deal with the unspecified behavior, and it should not care what the outcome
is. The term &quot;undefined&quot; says that a conforming application should not do it because no definition is provided for what it does
(and implicitly it would care what the outcome was if it tried it). It is important to remember, however, that if the syntax
permits the statement at all, it must have some outcome in a real implementation.</p>

<p>Thus, the terms &quot;undefined&quot; and &quot;unspecified&quot; apply to the way the application should think about the feature. In terms of
the implementation, it is always &quot;defined''-there is always some result, even if it is an error. The implementation is free to
choose the behavior it prefers.</p>

<p>This also implies that an implementation, or another standard, could specify or define the result in a useful fashion. The terms
apply to IEEE&nbsp;Std&nbsp;1003.1-2001 specifically.</p>

<p>The term &quot;implementation-defined&quot; implies requirements for documentation that are not required for &quot;undefined&quot; (or
&quot;unspecified&quot;). Where there is no need for a conforming program to know the definition, the term &quot;undefined&quot; is used, even
though &quot;implementation-defined&quot; could also have been used in this context. There could be a fourth term, specifying &quot;this
standard does not say what this does; it is acceptable to define it in an implementation, but it does not need to be documented&quot;,
and undefined would then be used very rarely for the few things for which any definition is not useful. In particular,
implementation-defined is used where it is believed that certain classes of application will need to know such details to determine
whether the application can be successfully ported to the implementation. Such applications are not always strictly portable, but
nevertheless are common and useful; often the requirements met by the application cannot be met without dealing with the issues
implied by &quot;implementation-defined&quot;.</p>

<p>In many places IEEE&nbsp;Std&nbsp;1003.1-2001 is silent about the behavior of some possible construct. For example, a variable
may be defined for a specified range of values and behaviors are described for those values; nothing is said about what happens if
the variable has any other value. That kind of silence can imply an error in the standard, but it may also imply that the standard
was intentionally silent and that any behavior is permitted. There is a natural tendency to infer that if the standard is silent, a
behavior is prohibited. That is not the intent. Silence is intended to be equivalent to the term &quot;unspecified&quot;.</p>

<p>The term &quot;application&quot; is not defined in IEEE&nbsp;Std&nbsp;1003.1-2001; it is assumed to be a part of general computer
science terminology.</p>

<p>Three terms used within IEEE&nbsp;Std&nbsp;1003.1-2001 overlap in meaning: &quot;macro&quot;, &quot;symbolic name&quot;, and &quot;symbolic
constant&quot;.</p>

<h4><a name="tag_01_01_15"></a>macro</h4>

<p>This usually describes a C preprocessor symbol, the result of the <b>#define</b> operator, with or without an argument. It may
also be used to describe similar mechanisms in editors and text processors.</p>

<h4><a name="tag_01_01_16"></a>symbolic name</h4>

<p>This can also refer to a C preprocessor symbol (without arguments), but is also used to refer to the names for characters in
character sets. In addition, it is sometimes used to refer to host names and even filenames.</p>

<h4><a name="tag_01_01_17"></a>symbolic constant</h4>

<p>This also refers to a C preprocessor symbol (also without arguments).</p>

<p>In most cases, the difference in semantic content is negligible to nonexistent. Readers should not attempt to read any meaning
into the various usages of these terms.</p>

<h4><a name="tag_01_01_18"></a>Portability</h4>

<p>To aid the identification of options within IEEE&nbsp;Std&nbsp;1003.1-2001, a notation consisting of margin codes and shading is
used. This is based on the notation used in previous revisions of The Open Group's Base specifications.</p>

<p>The benefit of this approach is a reduction in the number of <i>if</i> statements within the running text, that makes the text
easier to read, and also an identification to the programmer that they need to ensure that their target platforms support the
underlying options. For example, if functionality is marked with THR in the margin, it will be available on all systems supporting
the Threads option, but may not be available on some others.</p>

<h5><a name="tag_01_01_18_01"></a>Codes</h5>

<p>This section includes codes for options defined in the Base Definitions volume of IEEE&nbsp;Std&nbsp;1003.1-2001, <a href=
"../basedefs/xbd_chap02.html#tag_02_01_06">Section 2.1.6, Options</a>, and the following additional codes for other purposes:</p>

<dl compact>
<dt>CX</dt>

<dd>This margin code is used to denote extensions beyond the ISO&nbsp;C standard. For interfaces that are duplicated between
IEEE&nbsp;Std&nbsp;1003.1-2001 and the ISO&nbsp;C standard, a CX introduction block describes the nature of the duplication, with
any extensions appropriately CX marked and shaded. 

<p>Where an interface is added to an ISO&nbsp;C standard header, within the header the interface has an appropriate margin marker
and shading (for example, CX, XSI, TSF, and so on) and the same marking appears on the reference page in the SYNOPSIS section. This
enables a programmer to easily identify that the interface is extending an ISO&nbsp;C standard header.</p>
</dd>

<dt>MX</dt>

<dd>This margin code is used to denote IEC&nbsp;60559:1989 standard floating-point extensions.</dd>

<dt>OB</dt>

<dd>This margin code is used to denote obsolescent behavior and thus flag a possible future applications portability warning.</dd>

<dt>OH</dt>

<dd>The Single UNIX Specification has historically tried to reduce the number of headers an application has had to include when
using a particular interface. Sometimes this was fewer than the base standard, and hence a notation is used to flag which headers
are optional if you are using a system supporting the XSI extension.</dd>

<dt>XSI</dt>

<dd>This code is used to denote interfaces and facilities within interfaces only required on systems supporting the XSI extension.
This is introduced to support the Single UNIX Specification.</dd>

<dt>XSR</dt>

<dd>This code is used to denote interfaces and facilities within interfaces only required on systems supporting STREAMS. This is
introduced to support the Single UNIX Specification, although it is defined in a way so that it can stand alone from the XSI
notation.</dd>
</dl>

<h5><a name="tag_01_01_18_02"></a>Margin Code Notation</h5>

<p>Since some features may depend on one or more options, or require more than one option, a notation is used. Where a feature
requires support of a single option, a single margin code will occur in the margin. If it depends on two options and both are
required, then the codes will appear with a &lt;space&gt; separator. If either of two options are required, then a logical OR is
denoted using the <tt>'|'</tt> symbol. If more than two codes are used, a special notation is used.</p>


<hr size="2" noshade>
<center><font size="2"><!--footer start-->
UNIX &reg; is a registered Trademark of The Open Group.<br>
POSIX &reg; 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>