xbd_chap04.html

IEEE 1003.1-2003, Single Unix Specification v3

<li>
<p>If the Trace Log option is supported, an active trace stream with a trace log that was created with the <a href=
"../functions/posix_trace_create_withlog.html"><i>posix_trace_create_withlog</i>()</a> function</p>
</li>
</ol>
</li>

<li>
<p>A pre-recorded trace stream is a trace stream that was opened from a trace log object using the <a href=
"../functions/posix_trace_open.html"><i>posix_trace_open</i>()</a> function.</p>
</li>
</ul>

<p>An active trace stream can loop. This behavior means that when the resources allocated by the trace system for the trace stream
are exhausted, the trace system reuses the resources associated with the oldest recorded trace events to record new trace
events.</p>

<p>If the Trace Log option is supported, an active trace stream with a trace log can be flushed. This operation causes the trace
system to write trace events from the trace stream to the associated trace log, following the defined policies or using an explicit
function call. After this operation, the trace system may reuse the resources associated with the flushed trace events.</p>

<p>An active trace stream with or without a trace log can be cleared. This operation shall cause all the resources associated with
this trace stream to be reinitialized. The trace stream shall behave as if it was returning from its creation, except that the
mapping of trace event type identifiers to trace event names shall not be cleared. If a trace log was associated with this trace
stream, the trace log shall also be reinitialized.</p>

<p>A trace log shall be recorded when the <a href="../functions/posix_trace_shutdown.html"><i>posix_trace_shutdown</i>()</a>
operation is invoked or during tracing, depending on the tracing strategy which is defined by a log policy. After the trace stream
has been shut down, the trace information can be retrieved from the associated trace log using the same interface used to retrieve
information from an active trace stream.</p>

<p>For a traced process, if the Trace Inherit option is supported and the trace stream's inheritance attribute is
_POSIX_TRACE_INHERIT, the initial targeted traced process shall be traced together with all of its future children. The
<i>posix_pid</i> member of each trace event in a trace stream shall be the process ID of the traced process.</p>

<p>Each trace point may be an implementation-defined action such as a context switch, or an application-programmed action such as a
call to a specific operating system service (for example, <a href="../functions/fork.html"><i>fork</i>()</a>) or a call to <a href=
"../functions/posix_trace_event.html"><i>posix_trace_event</i>()</a>.</p>

<p>Trace points may be filtered. The operation of the filter is to filter out (ignore) selected trace events. By default, no trace
events are filtered.</p>

<p>The results of the tracing operations can be analyzed and monitored by a trace controller process or a trace analyzer
process.</p>

<p>Only the trace controller process has control of the trace stream it has created. The control of the operation of a trace stream
is done using its corresponding trace stream identifier. The trace controller process is able to:</p>

<ul>
<li>
<p>Initialize the attributes of a trace stream</p>
</li>

<li>
<p>Create the trace stream</p>
</li>

<li>
<p>Start and stop tracing</p>
</li>

<li>
<p>Know the mapping of the traced process</p>
</li>

<li>
<p>If the Trace Event Filter option is supported, filter the type of trace events to be recorded</p>
</li>

<li>
<p>Shut the trace stream down</p>
</li>
</ul>

<p>A traced process may also be a trace controller process. Only the trace controller process can control its trace stream(s). A
trace stream created by a trace controller process shall be shut down if its controller process terminates or executes another
file.</p>

<p>A trace controller process may also be a trace analyzer process. Trace analysis can be done concurrently with the traced process
or can be done off-line, in the same or in a different platform.</p>

<h3><a name="tag_04_18"></a>Treatment of Error Conditions for Mathematical Functions</h3>

<p>For all the functions in the <a href="../basedefs/math.h.html"><i>&lt;math.h&gt;</i></a> header, an application wishing to check
for error situations should set <i>errno</i> to 0 and call <i>feclearexcept</i>(FE_ALL_EXCEPT) before calling the function. On
return, if <i>errno</i> is non-zero or <i>fetestexcept</i>( FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an
error has occurred.</p>

<p>The following error conditions are defined for all functions in the <a href="../basedefs/math.h.html"><i>&lt;math.h&gt;</i></a>
header.</p>

<h4><a name="tag_04_18_01"></a>Domain Error</h4>

<p>A &quot;domain error&quot; shall occur if an input argument is outside the domain over which the mathematical function is defined. The
description of each function lists any required domain errors; an implementation may define additional domain errors, provided that
such errors are consistent with the mathematical definition of the function.</p>

<p>On a domain error, the function shall return an implementation-defined value; if the integer expression (math_errhandling &amp;
MATH_ERRNO) is non-zero, <i>errno</i> shall be set to [EDOM]; if the integer expression (math_errhandling &amp; MATH_ERREXCEPT) is
non-zero, the &quot;invalid&quot; floating-point exception shall be raised.</p>

<h4><a name="tag_04_18_02"></a>Pole Error</h4>

<p>A &quot;pole error&quot; occurs if the mathematical result of the function is an exact infinity (for example, log(0.0)).</p>

<p>On a pole error, the function shall return the value of the macro HUGE_VAL, HUGE_VALF, or HUGE_VALL according to the return
type, with the same sign as the correct value of the function; if the integer expression (math_errhandling &amp; MATH_ERRNO) is
non-zero, <i>errno</i> shall be set to [ERANGE]; if the integer expression (math_errhandling &amp; MATH_ERREXCEPT) is non-zero, the
&quot;divide-by-zero&quot; floating-point exception shall be raised.</p>

<h4><a name="tag_04_18_03"></a>Range Error</h4>

<p>A &quot;range error&quot; shall occur if the finite mathematical result of the function cannot be represented in an object of the
specified type, due to extreme magnitude.</p>

<h5><a name="tag_04_18_03_01"></a>Result Overflows</h5>

<p>A floating result overflows if the magnitude of the mathematical result is finite but so large that the mathematical result
cannot be represented without extraordinary roundoff error in an object of the specified type. If a floating result overflows and
default rounding is in effect, then the function shall return the value of the macro HUGE_VAL, HUGE_VALF, or HUGE_VALL according to
the return type, with the same sign as the correct value of the function; if the integer expression (math_errhandling &amp;
MATH_ERRNO) is non-zero, <i>errno</i> shall be set to [ERANGE]; if the integer expression (math_errhandling &amp; MATH_ERREXCEPT)
is non-zero, the &quot;overflow&quot; floating-point exception shall be raised.</p>

<h5><a name="tag_04_18_03_02"></a>Result Underflows</h5>

<p>The result underflows if the magnitude of the mathematical result is so small that the mathematical result cannot be
represented, without extraordinary roundoff error, in an object of the specified type. If the result underflows, the function shall
return an implementation-defined value whose magnitude is no greater than the smallest normalized positive number in the specified
type; if the integer expression (math_errhandling &amp; MATH_ERRNO) is non-zero, whether <i>errno</i> is set to [ERANGE] is
implementation-defined; if the integer expression (math_errhandling &amp; MATH_ERREXCEPT) is non-zero, whether the &quot;underflow''
floating-point exception is raised is implementation-defined.</p>

<h3><a name="tag_04_19"></a>Treatment of NaN Arguments for the Mathematical Functions</h3>

<p>For functions called with a NaN argument, no errors shall occur and a NaN shall be returned, except where stated otherwise.</p>

<p>If a function with one or more NaN arguments returns a NaN result, the result should be the same as one of the NaN arguments
(after possible type conversion), except perhaps for the sign.</p>

<p>On implementations that support the IEC&nbsp;60559:1989 standard floating point, functions with signaling NaN argument(s) shall
be treated as if the function were called with an argument that is a required domain error and shall return a quiet NaN result,
except where stated otherwise. <basefont size="2"></p>

<dl>
<dt><b>Note:</b></dt>

<dd>The function might never see the signaling NaN, since it might trigger when the arguments are evaluated during the function
call.</dd>
</dl>

<basefont size="3"> 

<p>On implementations that support the IEC&nbsp;60559:1989 standard floating point, for those functions that do not have a
documented domain error, the following shall apply:</p>

<blockquote>These functions shall fail if: 

<dl compact>
<dt>Domain&nbsp;Error</dt>

<dd>Any argument is a signaling NaN.</dd>
</dl>

<p>Either, the integer expression (math_errhandling &amp; MATH_ERRNO) is non-zero and <i>errno</i> shall be set to [EDOM], or the
integer expression (math_errhandling &amp; MATH_ERREXCEPT) is non-zero and the invalid floating-point exception shall be
raised.</p>
</blockquote>

<h3><a name="tag_04_20"></a>Utility</h3>

<p>A utility program shall be either an executable file, such as might be produced by a compiler or linker system from computer
source code, or a file of shell source code, directly interpreted by the shell. The program may have been produced by the user,
provided by the system implementor, or acquired from an independent distributor.</p>

<p>The system may implement certain utilities as shell functions (see the Shell and Utilities volume of
IEEE&nbsp;Std&nbsp;1003.1-2001, <a href="../utilities/xcu_chap02.html#tag_02_09_05">Section 2.9.5, Function Definition Command</a>)
or built-in utilities, but only an application that is aware of the command search order described in the Shell and Utilities
volume of IEEE&nbsp;Std&nbsp;1003.1-2001, <a href="../utilities/xcu_chap02.html#tag_02_09_01_01">Section 2.9.1.1, Command Search
and Execution</a> or of performance characteristics can discern differences between the behavior of such a function or built-in
utility and that of an executable file.</p>

<h3><a name="tag_04_21"></a>Variable Assignment</h3>

<p>In the shell command language, a word consisting of the following parts:</p>

<blockquote>
<pre>
<i>varname</i><tt>=</tt><i>value</i>
</pre>
</blockquote>

<p>When used in a context where assignment is defined to occur and at no other time, the <i>value</i> (representing a word or
field) shall be assigned as the value of the variable denoted by <i>varname</i>. <basefont size="2"></p>

<dl>
<dt><b>Note:</b></dt>

<dd>For further information, see the Shell and Utilities volume of IEEE&nbsp;Std&nbsp;1003.1-2001, <a href=
"../utilities/xcu_chap02.html#tag_02_09_01">Section 2.9.1, Simple Commands</a>.</dd>
</dl>

<basefont size="3"> 

<p>The <i>varname</i> and <i>value</i> parts shall meet the requirements for a name and a word, respectively, except that they are
delimited by the embedded unquoted equals-sign, in addition to other delimiters. <basefont size="2"></p>

<dl>
<dt><b>Note:</b></dt>

<dd>Additional delimiters are described in the Shell and Utilities volume of IEEE&nbsp;Std&nbsp;1003.1-2001, <a href=
"../utilities/xcu_chap02.html#tag_02_03">Section 2.3, Token Recognition</a>.</dd>
</dl>

<basefont size="3"> 

<p>When a variable assignment is done, the variable shall be created if it did not already exist. If <i>value</i> is not specified,
the variable shall be given a null value. <basefont size="2"></p>

<dl>
<dt><b>Note:</b></dt>

<dd>An alternative form of variable assignment: 

<blockquote>
<pre>
<i>symbol</i><tt>=</tt><i>value</i>
</pre>
</blockquote>

<p>(where <i>symbol</i> is a valid word delimited by an equals-sign, but not a valid name) produces unspecified results. The form
<i>symbol</i>= <i>value</i> is used by the KornShell <i>name</i>[ <i>expression</i>]= <i>value</i> syntax.</p>
</dd>
</dl>

<basefont size="3"> 

<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>