bc.html

IEEE 1003.1-2003, Single Unix Specification v3

Sine of argument in radians.</dd>

<dt><b>c</b>(&nbsp;<i>expression</i>&nbsp;)</dt>

<dd><br>
Cosine of argument in radians.</dd>

<dt><b>a</b>(&nbsp;<i>expression</i>&nbsp;)</dt>

<dd><br>
Arctangent of argument.</dd>

<dt><b>l</b>(&nbsp;<i>expression</i>&nbsp;)</dt>

<dd><br>
Natural logarithm of argument.</dd>

<dt><b>e</b>(&nbsp;<i>expression</i>&nbsp;)</dt>

<dd><br>
Exponential function of argument.</dd>

<dt><b>j</b>(&nbsp;<i>expression</i>,&nbsp;<i>expression</i>&nbsp;)</dt>

<dd><br>
Bessel function of integer order.</dd>
</dl>

<p>The scale of the result returned by these functions shall be the value of the <b>scale</b> register at the time the function is
invoked. The value of the <b>scale</b> register after these functions have completed their execution shall be the same value it had
upon invocation. The behavior is undefined if any of these functions is invoked with an argument outside the domain of the
mathematical function.</p>
</blockquote>

<h4><a name="tag_04_09_14"></a>EXIT STATUS</h4>

<blockquote>
<p>The following exit values shall be returned:</p>

<dl compact>
<dt>0</dt>

<dd>All input files were processed successfully.</dd>

<dt><i>unspecified</i></dt>

<dd>An error occurred.</dd>
</dl>
</blockquote>

<h4><a name="tag_04_09_15"></a>CONSEQUENCES OF ERRORS</h4>

<blockquote>
<p>If any <i>file</i> operand is specified and the named file cannot be accessed, <i>bc</i> shall write a diagnostic message to
standard error and terminate without any further action.</p>

<p>In an interactive invocation of <i>bc</i>, the utility should print an error message and recover following any error in the
input. In a non-interactive invocation of <i>bc</i>, invalid input causes undefined behavior.</p>
</blockquote>

<hr>
<div class="box"><em>The following sections are informative.</em></div>

<h4><a name="tag_04_09_16"></a>APPLICATION USAGE</h4>

<blockquote>
<p>Automatic variables in <i>bc</i> do not work in exactly the same way as in either C or PL/1.</p>

<p>For historical reasons, the exit status from <i>bc</i> cannot be relied upon to indicate that an error has occurred. Returning
zero after an error is possible. Therefore, <i>bc</i> should be used primarily by interactive users (who can react to error
messages) or by application programs that can somehow validate the answers returned as not including error messages.</p>

<p>The <i>bc</i> utility always uses the period ( <tt>'.'</tt> ) character to represent a radix point, regardless of any
decimal-point character specified as part of the current locale. In languages like C or <a href=
"../utilities/awk.html"><i>awk</i></a>, the period character is used in program source, so it can be portable and unambiguous,
while the locale-specific character is used in input and output. Because there is no distinction between source and input in
<i>bc</i>, this arrangement would not be possible. Using the locale-specific character in <i>bc</i>'s input would introduce
ambiguities into the language; consider the following example in a locale with a comma as the decimal-point character:</p>

<pre>
<tt>define f(a,b) {
    ...
}
...
<br>
f(1,2,3)
</tt>
</pre>

<p>Because of such ambiguities, the period character is used in input. Having input follow different conventions from output would
be confusing in either pipeline usage or interactive usage, so the period is also used in output.</p>
</blockquote>

<h4><a name="tag_04_09_17"></a>EXAMPLES</h4>

<blockquote>
<p>In the shell, the following assigns an approximation of the first ten digits of <tt>'<img src="../images/pi.gif" border=
"0">'</tt> to the variable <i>x</i>:</p>

<pre>
<tt>x=$(printf "%s\n" 'scale = 10; 104348/33215' | bc)
</tt>
</pre>

<p>The following <i>bc</i> program prints the same approximation of <tt>'<img src="../images/pi.gif" border="0">'</tt> , with a
label, to standard output:</p>

<pre>
<tt>scale = 10
"pi equals "
104348 / 33215
</tt>
</pre>

<p>The following defines a function to compute an approximate value of the exponential function (note that such a function is
predefined if the <b>-l</b> option is specified):</p>

<pre>
<tt>scale = 20
define e(x){
    auto a, b, c, i, s
    a = 1
    b = 1
    s = 1
    for (i = 1; 1 == 1; i++){
        a = a*x
        b = b*i
        c = a/b
        if (c == 0) {
             return(s)
        }
        s = s+c
    }
}
</tt>
</pre>

<p>The following prints approximate values of the exponential function of the first ten integers:</p>

<pre>
<tt>for (i = 1; i &lt;= 10; ++i) {
    e(i)
}
</tt>
</pre>
</blockquote>

<h4><a name="tag_04_09_18"></a>RATIONALE</h4>

<blockquote>
<p>The <i>bc</i> utility is implemented historically as a front-end processor for <i>dc</i>; <i>dc</i> was not selected to be part
of this volume of IEEE&nbsp;Std&nbsp;1003.1-2001 because <i>bc</i> was thought to have a more intuitive programmatic interface.
Current implementations that implement <i>bc</i> using <i>dc</i> are expected to be compliant.</p>

<p>The exit status for error conditions has been left unspecified for several reasons:</p>

<ul>
<li>
<p>The <i>bc</i> utility is used in both interactive and non-interactive situations. Different exit codes may be appropriate for
the two uses.</p>
</li>

<li>
<p>It is unclear when a non-zero exit should be given; divide-by-zero, undefined functions, and syntax errors are all
possibilities.</p>
</li>

<li>
<p>It is not clear what utility the exit status has.</p>
</li>

<li>
<p>In the 4.3 BSD, System V, and Ninth Edition implementations, <i>bc</i> works in conjunction with <i>dc</i>. The <i>dc</i>
utility is the parent, <i>bc</i> is the child. This was done to cleanly terminate <i>bc</i> if <i>dc</i> aborted.</p>
</li>
</ul>

<p>The decision to have <i>bc</i> exit upon encountering an inaccessible input file is based on the belief that <i>bc</i>
<i>file1</i> <i>file2</i> is used most often when at least <i>file1</i> contains data/function declarations/initializations. Having
<i>bc</i> continue with prerequisite files missing is probably not useful. There is no implication in the CONSEQUENCES OF ERRORS
section that <i>bc</i> must check all its files for accessibility before opening any of them.</p>

<p>There was considerable debate on the appropriateness of the language accepted by <i>bc</i>. Several reviewers preferred to see
either a pure subset of the C language or some changes to make the language more compatible with C. While the <i>bc</i> language
has some obvious similarities to C, it has never claimed to be compatible with any version of C. An interpreter for a subset of C
might be a very worthwhile utility, and it could potentially make <i>bc</i> obsolete. However, no such utility is known in
historical practice, and it was not within the scope of this volume of IEEE&nbsp;Std&nbsp;1003.1-2001 to define such a language and
utility. If and when they are defined, it may be appropriate to include them in a future version of IEEE&nbsp;Std&nbsp;1003.1. This
left the following alternatives:</p>

<ol>
<li>
<p>Exclude any calculator language from this volume of IEEE&nbsp;Std&nbsp;1003.1-2001.</p>

<p>The consensus of the standard developers was that a simple programmatic calculator language is very useful for both applications
and interactive users. The only arguments for excluding any calculator were that it would become obsolete if and when a
C-compatible one emerged, or that the absence would encourage the development of such a C-compatible one. These arguments did not
sufficiently address the needs of current application writers.</p>
</li>

<li>
<p>Standardize the historical <i>dc</i>, possibly with minor modifications.</p>

<p>The consensus of the standard developers was that <i>dc</i> is a fundamentally less usable language and that that would be far
too severe a penalty for avoiding the issue of being similar to but incompatible with C.</p>
</li>

<li>
<p>Standardize the historical <i>bc</i>, possibly with minor modifications.</p>

<p>This was the approach taken. Most of the proponents of changing the language would not have been satisfied until most or all of
the incompatibilities with C were resolved. Since most of the changes considered most desirable would break historical applications
and require significant modification to historical implementations, almost no modifications were made. The one significant
modification that was made was the replacement of the historical <i>bc</i> assignment operators <tt>"=+"</tt> , and so on, with the
more modern <tt>"+="</tt> , and so on. The older versions are considered to be fundamentally flawed because of the lexical
ambiguity in uses like <i>a</i>=-1.</p>

<p>In order to permit implementations to deal with backwards-compatibility as they see fit, the behavior of this one ambiguous
construct was made undefined. (At least three implementations have been known to support this change already, so the degree of
change involved should not be great.)</p>
</li>
</ol>

<p>The <tt>'%'</tt> operator is the mathematical remainder operator when <b>scale</b> is zero. The behavior of this operator for
other values of <b>scale</b> is from historical implementations of <i>bc</i>, and has been maintained for the sake of historical
applications despite its non-intuitive nature.</p>

<p>Historical implementations permit setting <b>ibase</b> and <b>obase</b> to a broader range of values. This includes values less
than 2, which were not seen as sufficiently useful to standardize. These implementations do not interpret input properly for values
of <b>ibase</b> that are greater than 16. This is because numeric constants are recognized syntactically, rather than lexically, as
described in this volume of IEEE&nbsp;Std&nbsp;1003.1-2001. They are built from lexical tokens of single hexadecimal digits and
periods. Since &lt;blank&gt;s between tokens are not visible at the syntactic level, it is not possible to recognize the
multi-digit &quot;digits&quot; used in the higher bases properly. The ability to recognize input in these bases was not considered useful
enough to require modifying these implementations. Note that the recognition of numeric constants at the syntactic level is not a
problem with conformance to this volume of IEEE&nbsp;Std&nbsp;1003.1-2001, as it does not impact the behavior of conforming
applications (and correct <i>bc</i> programs). Historical implementations also accept input with all of the digits <tt>'0'</tt> -
<tt>'9'</tt> and <tt>'A'</tt> - <tt>'F'</tt> regardless of the value of <b>ibase</b>; since digits with value greater than or equal
to <b>ibase</b> are not really appropriate, the behavior when they appear is undefined, except for the common case of:</p>

<pre>
<tt>ibase=8;
    /* Process in octal base. */
...
ibase=A
    /* Restore decimal base. */
</tt>
</pre>

<p>In some historical implementations, if the expression to be written is an uninitialized array element, a leading &lt;space&gt;
and/or up to four leading 0 characters may be output before the character zero. This behavior is considered a bug; it is unlikely
that any currently conforming application relies on:</p>

<pre>
<tt>echo 'b[3]' | bc
</tt>
</pre>

<p>returning 00000 rather than 0.</p>

<p>Exact calculation of the number of fractional digits to output for a given value in a base other than 10 can be computationally
expensive. Historical implementations use a faster approximation, and this is permitted. Note that the requirements apply only to
values of <b>obase</b> that this volume of IEEE&nbsp;Std&nbsp;1003.1-2001 requires implementations to support (in particular, not
to 1, 0, or negative bases, if an implementation supports them as an extension).</p>

<p>Historical implementations of <i>bc</i> did not allow array parameters to be passed as the last parameter to a function. New
implementations are encouraged to remove this restriction even though it is not required by the grammar.</p>
</blockquote>

<h4><a name="tag_04_09_19"></a>FUTURE DIRECTIONS</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_04_09_20"></a>SEE ALSO</h4>

<blockquote>
<p><a href="xcu_chap01.html#tag_01_10"><i>Grammar Conventions</i></a> , <a href="awk.html"><i>awk</i></a></p>
</blockquote>

<h4><a name="tag_04_09_21"></a>CHANGE HISTORY</h4>

<blockquote>
<p>First released in Issue 4.</p>
</blockquote>

<h4><a name="tag_04_09_22"></a>Issue 5</h4>

<blockquote>
<p>The FUTURE DIRECTIONS section is added.</p>
</blockquote>

<h4><a name="tag_04_09_23"></a>Issue 6</h4>

<blockquote>
<p>Updated to align with the IEEE&nbsp;P1003.2b draft standard, which included resolution of several interpretations of the
ISO&nbsp;POSIX-2:1993 standard.</p>

<p>The normative text is reworded to avoid use of the term &quot;must&quot; 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 &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>