path: root/man1p/bc.1p

.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "BC" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" bc 
.SH NAME
bc \- arbitrary-precision arithmetic language
.SH SYNOPSIS
.LP
\fBbc\fP \fB[\fP\fB-l\fP\fB] [\fP\fIfile\fP \fB...\fP\fB]\fP
.SH DESCRIPTION
.LP
The \fIbc\fP utility shall implement an arbitrary precision calculator.
It shall take input from any files given, then read
from the standard input. If the standard input and standard output
to \fIbc\fP are attached to a terminal, the invocation of
\fIbc\fP shall be considered to be \fIinteractive\fP, causing behavioral
constraints described in the following sections.
.SH OPTIONS
.LP
The \fIbc\fP utility shall conform to the Base Definitions volume
of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
.LP
The following option shall be supported:
.TP 7
\fB-l\fP
(The letter ell.) Define the math functions and initialize \fIscale\fP
to 20, instead of the default zero; see the EXTENDED
DESCRIPTION section.
.sp
.SH OPERANDS
.LP
The following operand shall be supported:
.TP 7
\fIfile\fP
A pathname of a text file containing \fIbc\fP program statements.
After all \fIfile\fPs have been read, \fIbc\fP shall read
the standard input.
.sp
.SH STDIN
.LP
See the INPUT FILES section.
.SH INPUT FILES
.LP
Input files shall be text files containing a sequence of comments,
statements, and function definitions that shall be executed
as they are read.
.SH ENVIRONMENT VARIABLES
.LP
The following environment variables shall affect the execution of
\fIbc\fP:
.TP 7
\fILANG\fP
Provide a default value for the internationalization variables that
are unset or null. (See the Base Definitions volume of
IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables
for
the precedence of internationalization variables used to determine
the values of locale categories.)
.TP 7
\fILC_ALL\fP
If set to a non-empty string value, override the values of all the
other internationalization variables.
.TP 7
\fILC_CTYPE\fP
Determine the locale for the interpretation of sequences of bytes
of text data as characters (for example, single-byte as
opposed to multi-byte characters in arguments and input files).
.TP 7
\fILC_MESSAGES\fP
Determine the locale that should be used to affect the format and
contents of diagnostic messages written to standard
error.
.TP 7
\fINLSPATH\fP
Determine the location of message catalogs for the processing of \fILC_MESSAGES
\&.\fP 
.sp
.SH ASYNCHRONOUS EVENTS
.LP
Default.
.SH STDOUT
.LP
The output of the \fIbc\fP utility shall be controlled by the program
read, and consist of zero or more lines containing the
value of all executed expressions without assignments. The radix and
precision of the output shall be controlled by the values of
the \fBobase\fP and \fBscale\fP variables; see the EXTENDED DESCRIPTION
section.
.SH STDERR
.LP
The standard error shall be used only for diagnostic messages.
.SH OUTPUT FILES
.LP
None.
.SH EXTENDED DESCRIPTION
.SS Grammar
.LP
The grammar in this section and the lexical conventions in the following
section shall together describe the syntax for
\fIbc\fP programs. The general conventions for this style of grammar
are described in \fIGrammar Conventions\fP . A valid program can be
represented as the non-terminal symbol
\fBprogram\fP in the grammar. This formal syntax shall take precedence
over the text syntax description.
.sp
.RS
.nf

\fB%token    EOF NEWLINE STRING LETTER NUMBER
.sp

%token    MUL_OP
/*        '*', '/', '%'                           */
.sp

%token    ASSIGN_OP
/*        '=', '+=', '-=', '*=', '/=', '%=', '^=' */
.sp

%token    REL_OP
/*        '==', '<=', '>=', '!=', '<', '>'        */
.sp

%token    INCR_DECR
/*        '++', '--'                              */
.sp

%token    Define    Break    Quit    Length
/*        'define', 'break', 'quit', 'length'     */
.sp

%token    Return    For    If    While    Sqrt
/*        'return', 'for', 'if', 'while', 'sqrt'  */
.sp

%token    Scale    Ibase    Obase    Auto
/*        'scale', 'ibase', 'obase', 'auto'       */
.sp

%start    program
.sp

%%
.sp

program              : EOF
                     | input_item program
                     ;
.sp

input_item           : semicolon_list NEWLINE
                     | function
                     ;
.sp

semicolon_list       : /* empty */
                     | statement
                     | semicolon_list ';' statement
                     | semicolon_list ';'
                     ;
.sp

statement_list       : /* empty */
                     | statement
                     | statement_list NEWLINE
                     | statement_list NEWLINE statement
                     | statement_list ';'
                     | statement_list ';' statement
                     ;
.sp

statement            : expression
                     | STRING
                     | Break
                     | Quit
                     | Return
                     | Return '(' return_expression ')'
                     | For '(' expression ';'
                           relational_expression ';'
                           expression ')' statement
                     | If '(' relational_expression ')' statement
                     | While '(' relational_expression ')' statement
                     | '{' statement_list '}'
                     ;
.sp

function             : Define LETTER '(' opt_parameter_list ')'
                           '{' NEWLINE opt_auto_define_list
                           statement_list '}'
                     ;
.sp

opt_parameter_list   : /* empty */
                     | parameter_list
                     ;
.sp

parameter_list       : LETTER
                     | define_list ',' LETTER
                     ;
.sp

opt_auto_define_list : /* empty */
                     | Auto define_list NEWLINE
                     | Auto define_list ';'
                     ;
.sp

define_list          : LETTER
                     | LETTER '[' ']'
                     | define_list ',' LETTER
                     | define_list ',' LETTER '[' ']'
                     ;
.sp

opt_argument_list    : /* empty */
                     | argument_list
                     ;
.sp

argument_list        : expression
                     | LETTER '[' ']' ',' argument_list
                     ;
.sp

relational_expression : expression
                     | expression REL_OP expression
                     ;
.sp

return_expression    : /* empty */
                     | expression
                     ;
.sp

expression           : named_expression
                     | NUMBER
                     | '(' expression ')'
                     | LETTER '(' opt_argument_list ')'
                     | '-' expression
                     | expression '+' expression
                     | expression '-' expression
                     | expression MUL_OP expression
                     | expression '^' expression
                     | INCR_DECR named_expression
                     | named_expression INCR_DECR
                     | named_expression ASSIGN_OP expression
                     | Length '(' expression ')'
                     | Sqrt '(' expression ')'
                     | Scale '(' expression ')'
                     ;
.sp

named_expression     : LETTER
                     | LETTER '[' expression ']'
                     | Scale
                     | Ibase
                     | Obase
                     ;
\fP
.fi
.RE
.SS Lexical Conventions in bc
.LP
The lexical conventions for \fIbc\fP programs, with respect to the
preceding grammar, shall be as follows:
.IP " 1." 4
Except as noted, \fIbc\fP shall recognize the longest possible token
or delimiter beginning at a given point.
.LP
.IP " 2." 4
A comment shall consist of any characters beginning with the two adjacent
characters \fB"/*"\fP and terminated by the next
occurrence of the two adjacent characters \fB"*/"\fP . Comments shall
have no effect except to delimit lexical tokens.
.LP
.IP " 3." 4
The <newline> shall be recognized as the token \fBNEWLINE\fP.
.LP
.IP " 4." 4
The token \fBSTRING\fP shall represent a string constant; it shall
consist of any characters beginning with the double-quote
character ( \fB' )'\fP and terminated by another occurrence of the
double-quote character. The value of the string is the
sequence of all characters between, but not including, the two double-quote
characters. All characters shall be taken literally
from the input, and there is no way to specify a string containing
a double-quote character. The length of the value of each string
shall be limited to {BC_STRING_MAX} bytes.
.LP
.IP " 5." 4
A <blank> shall have no effect except as an ordinary character if
it appears within a \fBSTRING\fP token, or to delimit a
lexical token other than \fBSTRING\fP.
.LP
.IP " 6." 4
The combination of a backslash character immediately followed by a
<newline> shall have no effect other than to delimit
lexical tokens with the following exceptions:
.RS
.IP " *" 3
It shall be interpreted as the character sequence \fB"\\<newline>"\fP
in \fBSTRING\fP tokens.
.LP
.IP " *" 3
It shall be ignored as part of a multi-line \fBNUMBER\fP token.
.LP
.RE
.LP
.IP " 7." 4
The token \fBNUMBER\fP shall represent a numeric constant. It shall
be recognized by the following grammar:
.sp
.RS
.nf

\fBNUMBER  : integer
        | '.' integer
        | integer '.'
        | integer '.' integer
        ;
.sp

integer : digit
        | integer digit
        ;
.sp

digit   : 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7
        | 8 | 9 | A | B | C | D | E | F
        ;
\fP
.fi
.RE
.LP
.IP " 8." 4
The value of a \fBNUMBER\fP token shall be interpreted as a numeral
in the base specified by the value of the internal register
\fBibase\fP (described below). Each of the \fBdigit\fP characters
shall have the value from 0 to 15 in the order listed here, and
the period character shall represent the radix point. The behavior
is undefined if digits greater than or equal to the value of
\fBibase\fP appear in the token. However, note the exception for single-digit
values being assigned to \fBibase\fP and
\fBobase\fP themselves, in Operations in bc .
.LP
.IP " 9." 4
The following keywords shall be recognized as tokens:
.TS C
center; lw(15) lw(15) lw(15) lw(15) lw(15).
T{
\fB
.br
auto
.br
break
.br
define
.br
\fP
T}	T{
\fB
.br
ibase
.br
if
.br
for
.br
\fP
T}	T{
\fB
.br
length
.br
obase
.br
quit
.br
\fP
T}	T{
\fB
.br
return
.br
scale
.br
sqrt
.br
\fP
T}	T{
\fB
.br
while
.br
\fP
T}
.TE
.LP
.IP "10." 4
Any of the following characters occurring anywhere except within a
keyword shall be recognized as the token \fBLETTER\fP:
.sp
.RS
.nf

\fBa b c d e f g h i j k l m n o p q r s t u v w x y z
\fP
.fi
.RE
.LP
.IP "11." 4
The following single-character and two-character sequences shall be
recognized as the token \fBASSIGN_OP\fP:
.sp
.RS
.nf

\fB=   +=   -=   *=   /=   %=   ^=
\fP
.fi
.RE
.LP
.IP "12." 4
If an \fB'='\fP character, as the beginning of a token, is followed
by a \fB'-'\fP character with no intervening
delimiter, the behavior is undefined.
.LP
.IP "13." 4
The following single-characters shall be recognized as the token \fBMUL_OP\fP:
.sp
.RS
.nf

\fB*   /   %
\fP
.fi
.RE
.LP
.IP "14." 4
The following single-character and two-character sequences shall be
recognized as the token \fBREL_OP\fP:
.sp
.RS
.nf

\fB==   <=   >=   !=   <   >
\fP
.fi
.RE
.LP
.IP "15." 4
The following two-character sequences shall be recognized as the token
\fBINCR_DECR\fP:
.sp
.RS
.nf

\fB++   --
\fP
.fi
.RE
.LP
.IP "16." 4
The following single characters shall be recognized as tokens whose
names are the character:
.sp
.RS
.nf

\fB<newline>  (  )  ,  +  -  ;  [  ]  ^  {  }
\fP
.fi
.RE
.LP
.IP "17." 4
The token \fBEOF\fP is returned when the end of input is reached.
.LP
.SS Operations in bc
.LP
There are three kinds of identifiers: ordinary identifiers, array
identifiers, and function identifiers. All three types consist
of single lowercase letters. Array identifiers shall be followed by
square brackets ( \fB"[]"\fP ). An array subscript is
required except in an argument or auto list. Arrays are singly dimensioned
and can contain up to {BC_DIM_MAX} elements. Indexing
shall begin at zero so an array is indexed from 0 to {BC_DIM_MAX}-1.
Subscripts shall be truncated to integers. The application
shall ensure that function identifiers are followed by parentheses,
possibly enclosing arguments. The three types of identifiers do
not conflict.
.LP
The following table summarizes the rules for precedence and associativity
of all operators. Operators on the same line shall
have the same precedence; rows are in order of decreasing precedence.
.sp
.ce 1
\fBTable: Operators in \fIbc\fP\fP
.TS C
center; l l.
\fBOperator\fP	\fBAssociativity\fP
++, --	N/A
unary -	N/A
^	Right to left
*, /, %	Left to right
+, binary -	Left to right
=, +=, -=, *=, /=, %=, ^=	Right to left
==, <=, >=, !=, <, >	None
.TE
.LP
Each expression or named expression has a \fIscale\fP, which is the
number of decimal digits that shall be maintained as the
fractional portion of the expression.
.LP
\fINamed expressions\fP are places where values are stored. Named
expressions shall be valid on the left side of an assignment.
The value of a named expression shall be the value stored in the place
named. Simple identifiers and array elements are named
expressions; they have an initial value of zero and an initial scale
of zero.
.LP
The internal registers \fBscale\fP, \fBibase\fP, and \fBobase\fP are
all named expressions. The scale of an expression
consisting of the name of one of these registers shall be zero; values
assigned to any of these registers are truncated to
integers. The \fBscale\fP register shall contain a global value used
in computing the scale of expressions (as described below).
The value of the register \fBscale\fP is limited to 0 <= \fBscale\fP
<= {BC_SCALE_MAX} and shall have a default value of
zero. The \fBibase\fP and \fBobase\fP registers are the input and
output number radix, respectively. The value of \fBibase\fP
shall be limited to:
.sp
.RS
.nf

\fB2 <= ibase <= 16
\fP
.fi
.RE
.LP
The value of \fBobase\fP shall be limited to:
.sp
.RS
.nf

\fB2 <= obase <= {BC_BASE_MAX}
\fP
.fi
.RE
.LP
When either \fBibase\fP or \fBobase\fP is assigned a single \fBdigit\fP
value from the list in Lexical Conventions in bc , the value shall
be assumed in hexadecimal. (For example, \fBibase\fP=A sets to
base ten, regardless of the current \fBibase\fP value.) Otherwise,
the behavior is undefined when digits greater than or equal to
the value of \fBibase\fP appear in the input. Both \fBibase\fP and
\fBobase\fP shall have initial values of 10.
.LP
Internal computations shall be conducted as if in decimal, regardless
of the input and output bases, to the specified number of
decimal digits. When an exact result is not achieved (for example,
\fBscale\fP=0;\ 3.2/1)\fB,\fP the result shall be
truncated.
.LP
For all values of \fBobase\fP specified by this volume of IEEE\ Std\ 1003.1-2001,
\fIbc\fP shall output numeric values
by performing each of the following steps in order:
.IP " 1." 4
If the value is less than zero, a hyphen ( \fB'-'\fP ) character shall
be output.
.LP
.IP " 2." 4
One of the following is output, depending on the numerical value:
.RS
.IP " *" 3
If the absolute value of the numerical value is greater than or equal
to one, the integer portion of the value shall be output
as a series of digits appropriate to \fBobase\fP (as described below),
most significant digit first. The most significant non-zero
digit shall be output next, followed by each successively less significant
digit.
.LP
.IP " *" 3
If the absolute value of the numerical value is less than one but
greater than zero and the scale of the numerical value is
greater than zero, it is unspecified whether the character 0 is output.
.LP
.IP " *" 3
If the numerical value is zero, the character 0 shall be output.
.LP
.RE
.LP
.IP " 3." 4
If the scale of the value is greater than zero and the numeric value
is not zero, a period character shall be output, followed
by a series of digits appropriate to \fBobase\fP (as described below)
representing the most significant portion of the fractional
part of the value. If \fIs\fP represents the scale of the value being
output, the number of digits output shall be \fIs\fP if
\fBobase\fP is 10, less than or equal to \fIs\fP if \fBobase\fP is
greater than 10, or greater than or equal to \fIs\fP if
\fBobase\fP is less than 10. For \fBobase\fP values other than 10,
this should be the number of digits needed to represent a
precision of 10**\fIs\fP.
.LP
.LP
For \fBobase\fP values from 2 to 16, valid digits are the first \fBobase\fP
of the single characters:
.sp
.RS
.nf

\fB0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F
\fP
.fi
.RE
.LP
which represent the values zero to 15, inclusive, respectively.
.LP
For bases greater than 16, each digit shall be written as a separate
multi-digit decimal number. Each digit except the most
significant fractional digit shall be preceded by a single <space>.
For bases from 17 to 100, \fIbc\fP shall write two-digit
decimal numbers; for bases from 101 to 1000, three-digit decimal strings,
and so on. For example, the decimal number 1024 in base
25 would be written as:
.sp
.RS
.nf

\fB 01 15 24
\fP
.fi
.RE
.LP
and in base 125, as:
.sp
.RS
.nf

\fB 008 024
\fP
.fi
.RE
.LP
Very large numbers shall be split across lines with 70 characters
per line in the POSIX locale; other locales may split at
different character boundaries. Lines that are continued shall end
with a backslash ( \fB'\\'\fP ).
.LP
A function call shall consist of a function name followed by parentheses
containing a comma-separated list of expressions, which
are the function arguments. A whole array passed as an argument shall
be specified by the array name followed by empty square
brackets. All function arguments shall be passed by value. As a result,
changes made to the formal parameters shall have no effect
on the actual arguments. If the function terminates by executing a
\fBreturn\fP statement, the value of the function shall be the
value of the expression in the parentheses of the \fBreturn\fP statement
or shall be zero if no expression is provided or if there
is no \fBreturn\fP statement.
.LP
The result of \fBsqrt\fP( \fIexpression\fP) shall be the square root
of the expression. The result shall be truncated in the
least significant decimal place. The scale of the result shall be
the scale of the expression or the value of \fBscale\fP,
whichever is larger.
.LP
The result of \fBlength\fP( \fIexpression\fP) shall be the total number
of significant decimal digits in the expression. The
scale of the result shall be zero.
.LP
The result of \fBscale\fP( \fIexpression\fP) shall be the scale of
the expression. The scale of the result shall be zero.
.LP
A numeric constant shall be an expression. The scale shall be the
number of digits that follow the radix point in the input
representing the constant, or zero if no radix point appears.
.LP
The sequence (\ \fIexpression\fP\ ) shall be an expression with the
same value and scale as \fIexpression\fP. The
parentheses can be used to alter the normal precedence.
.LP
The semantics of the unary and binary operators are as follows:
.TP 7
-\fIexpression\fP
.sp
The result shall be the negative of the \fIexpression\fP. The scale
of the result shall be the scale of \fIexpression\fP.
.sp
.LP
The unary increment and decrement operators shall not modify the scale
of the named expression upon which they operate. The
scale of the result shall be the scale of that named expression.
.TP 7
++\fInamed-expression\fP
.sp
The named expression shall be incremented by one. The result shall
be the value of the named expression after incrementing.
.TP 7
--\fInamed-expression\fP
.sp
The named expression shall be decremented by one. The result shall
be the value of the named expression after decrementing.
.TP 7
\fInamed-expression\fP++
.sp
The named expression shall be incremented by one. The result shall
be the value of the named expression before incrementing.
.TP 7
\fInamed-expression\fP--
.sp
The named expression shall be decremented by one. The result shall
be the value of the named expression before decrementing.
.sp
.LP
The exponentiation operator, circumflex ( \fB'^'\fP ), shall bind
right to left.
.TP 7
\fIexpression\fP^\fIexpression\fP
.sp
The result shall be the first \fIexpression\fP raised to the power
of the second \fIexpression\fP. If the second expression is
not an integer, the behavior is undefined. If \fIa\fP is the scale
of the left expression and \fIb\fP is the absolute value of
the right expression, the scale of the result shall be: 
.sp
.RS
.nf

\fBif b >= 0 min(a * b, max(scale, a)) if b < 0 scale
\fP
.fi
.RE
.sp
The multiplicative operators ( \fB'*'\fP , \fB'/'\fP , \fB'%'\fP )
shall bind left to right. 
.TP 7
\fIexpression\fP*\fIexpression\fP
.sp
The result shall be the product of the two expressions. If \fIa\fP
and \fIb\fP are the scales of the two expressions, then the
scale of the result shall be: 
.sp
.RS
.nf

\fBmin(a+b,max(scale,a,b))
\fP
.fi
.RE
.TP 7
\fIexpression\fP/\fIexpression\fP
.sp
The result shall be the quotient of the two expressions. The scale
of the result shall be the value of \fBscale\fP.
.TP 7
\fIexpression\fP%\fIexpression\fP
.sp
For expressions \fIa\fP and \fIb\fP, \fIa\fP% \fIb\fP shall be evaluated
equivalent to the steps: 
.RS
.IP " 1." 4
Compute \fIa\fP/ \fIb\fP to current scale.
.LP
.IP " 2." 4
Use the result to compute:
.sp
.RS
.nf

\fBa - (a / b) * b
\fP
.fi
.RE
.LP
to scale:
.sp
.RS
.nf

\fBmax(scale + scale(b), scale(a))
\fP
.fi
.RE
.LP
.RE
The scale of the result shall be: 
.sp
.RS
.nf

\fBmax(scale + scale(b), scale(a))
\fP
.fi
.RE
.LP
When \fBscale\fP is zero, the \fB'%'\fP operator is the mathematical
remainder operator.
.sp
.LP
The additive operators ( \fB'+'\fP , \fB'-'\fP ) shall bind left to
right.
.TP 7
\fIexpression\fP+\fIexpression\fP
.sp
The result shall be the sum of the two expressions. The scale of the
result shall be the maximum of the scales of the
expressions.
.TP 7
\fIexpression\fP-\fIexpression\fP
.sp
The result shall be the difference of the two expressions. The scale
of the result shall be the maximum of the scales of the
expressions.
.sp
.LP
The assignment operators ( \fB'='\fP , \fB"+="\fP , \fB"-="\fP , \fB"*="\fP
, \fB"/="\fP , \fB"%="\fP ,
\fB"^="\fP ) shall bind right to left.
.TP 7
\fInamed-expression\fP=\fIexpression\fP
.sp
This expression shall result in assigning the value of the expression
on the right to the named expression on the left. The scale
of both the named expression and the result shall be the scale of
\fIexpression\fP.
.sp
.LP
The compound assignment forms:
.sp
.RS
.nf

\fInamed-expression\fP \fB<\fP\fIoperator\fP\fB>=\fP \fIexpression\fP
.fi
.RE
.LP
shall be equivalent to:
.sp
.RS
.nf

\fInamed-expression\fP\fB=\fP\fInamed-expression\fP \fB<\fP\fIoperator\fP\fB>\fP \fIexpression\fP
.fi
.RE
.LP
except that the \fInamed-expression\fP shall be evaluated only once.
.LP
Unlike all other operators, the relational operators ( \fB'<'\fP ,
\fB'>'\fP , \fB"<="\fP , \fB">="\fP ,
\fB"=="\fP , \fB"!="\fP ) shall be only valid as the object of an
\fBif\fP, \fBwhile\fP, or inside a \fBfor\fP
statement.
.TP 7
\fIexpression1\fP<\fIexpression2\fP
.sp
The relation shall be true if the value of \fIexpression1\fP is strictly
less than the value of \fIexpression2\fP.
.TP 7
\fIexpression1\fP>\fIexpression2\fP
.sp
The relation shall be true if the value of \fIexpression1\fP is strictly
greater than the value of \fIexpression2\fP.
.TP 7
\fIexpression1\fP<=\fIexpression2\fP
.sp
The relation shall be true if the value of \fIexpression1\fP is less
than or equal to the value of \fIexpression2\fP.
.TP 7
\fIexpression1\fP>=\fIexpression2\fP
.sp
The relation shall be true if the value of \fIexpression1\fP is greater
than or equal to the value of \fIexpression2\fP.
.TP 7
\fIexpression1\fP==\fIexpression2\fP
.sp
The relation shall be true if the values of \fIexpression1\fP and
\fIexpression2\fP are equal.
.TP 7
\fIexpression1\fP!=\fIexpression2\fP
.sp
The relation shall be true if the values of \fIexpression1\fP and
\fIexpression2\fP are unequal.
.sp
.LP
There are only two storage classes in \fIbc\fP: global and automatic
(local). Only identifiers that are local to a function
need be declared with the \fBauto\fP command. The arguments to a function
shall be local to the function. All other identifiers
are assumed to be global and available to all functions. All identifiers,
global and local, have initial values of zero.
Identifiers declared as auto shall be allocated on entry to the function
and released on returning from the function. They
therefore do not retain values between function calls. Auto arrays
shall be specified by the array name followed by empty square
brackets. On entry to a function, the old values of the names that
appear as parameters and as automatic variables shall be pushed
onto a stack. Until the function returns, reference to these names
shall refer only to the new values.
.LP
References to any of these names from other functions that are called
from this function also refer to the new value until one
of those functions uses the same name for a local variable.
.LP
When a statement is an expression, unless the main operator is an
assignment, execution of the statement shall write the value
of the expression followed by a <newline>.
.LP
When a statement is a string, execution of the statement shall write
the value of the string.
.LP
Statements separated by semicolons or <newline>s shall be executed
sequentially. In an interactive invocation of
\fIbc\fP, each time a <newline> is read that satisfies the grammatical
production:
.sp
.RS
.nf

\fBinput_item : semicolon_list NEWLINE
\fP
.fi
.RE
.LP
the sequential list of statements making up the \fBsemicolon_list\fP
shall be executed immediately and any output produced by
that execution shall be written without any delay due to buffering.
.LP
In an \fBif\fP statement ( \fBif\fP( \fIrelation\fP) \fIstatement\fP),
the \fIstatement\fP shall be executed if the
relation is true.
.LP
The \fBwhile\fP statement ( \fBwhile\fP( \fIrelation\fP) \fIstatement\fP)
implements a loop in which the \fIrelation\fP is
tested; each time the \fIrelation\fP is true, the \fIstatement\fP
shall be executed and the \fIrelation\fP retested. When the
\fIrelation\fP is false, execution shall resume after \fIstatement\fP.
.LP
A \fBfor\fP statement( \fBfor\fP( \fIexpression\fP; \fIrelation\fP;
\fIexpression\fP) \fIstatement\fP) shall be the same
as:
.sp
.RS
.nf

\fIfirst-expression\fP\fBwhile (\fP\fIrelation\fP\fB) {
   \fP \fIstatement\fP \fB  \fP \fIlast-expression\fP\fB}
\fP
.fi
.RE
The application shall ensure that all three expressions are present.
.LP
The \fBbreak\fP statement shall cause termination of a \fBfor\fP or
\fBwhile\fP statement.
.LP
The \fBauto\fP statement ( \fBauto\fP \fIidentifier\fP \fB[\fP, \fIidentifier\fP
\fB]\fP ...) shall cause the values of
the identifiers to be pushed down. The identifiers can be ordinary
identifiers or array identifiers. Array identifiers shall be
specified by following the array name by empty square brackets. The
application shall ensure that the \fBauto\fP statement is the
first statement in a function definition.
.LP
A \fBdefine\fP statement:
.sp
.RS
.nf

\fBdefine\fP \fILETTER\fP \fB(\fP \fIopt_parameter_list\fP \fB) {
   \fP \fIopt_auto_define_list\fP \fB  \fP \fIstatement_list\fP\fB}
\fP
.fi
.RE
.LP
defines a function named \fBLETTER\fP. If a function named \fBLETTER\fP
was previously defined, the \fBdefine\fP statement
shall replace the previous definition. The expression:
.sp
.RS
.nf

\fBLETTER (\fP \fIopt_argument_list\fP \fB)
\fP
.fi
.RE
.LP
shall invoke the function named \fBLETTER\fP. The behavior is undefined
if the number of arguments in the invocation does not
match the number of parameters in the definition. Functions shall
be defined before they are invoked. A function shall be
considered to be defined within its own body, so recursive calls are
valid. The values of numeric constants within a function shall
be interpreted in the base specified by the value of the \fBibase\fP
register when the function is invoked.
.LP
The \fBreturn\fP statements ( \fBreturn\fP and \fBreturn\fP( \fIexpression\fP))
shall cause termination of a function,
popping of its auto variables, and specification of the result of
the function. The first form shall be equivalent to
\fBreturn\fP(0). The value and scale of the result returned by the
function shall be the value and scale of the expression
returned.
.LP
The \fBquit\fP statement ( \fBquit\fP) shall stop execution of a \fIbc\fP
program at the point where the statement occurs in
the input, even if it occurs in a function definition, or in an \fBif\fP,
\fBfor\fP, or \fBwhile\fP statement.
.LP
The following functions shall be defined when the \fB-l\fP option
is specified:
.TP 7
\fBs\fP(\ \fIexpression\fP\ )
.sp
Sine of argument in radians.
.TP 7
\fBc\fP(\ \fIexpression\fP\ )
.sp
Cosine of argument in radians.
.TP 7
\fBa\fP(\ \fIexpression\fP\ )
.sp
Arctangent of argument.
.TP 7
\fBl\fP(\ \fIexpression\fP\ )
.sp
Natural logarithm of argument.
.TP 7
\fBe\fP(\ \fIexpression\fP\ )
.sp
Exponential function of argument.
.TP 7
\fBj\fP(\ \fIexpression\fP,\ \fIexpression\fP\ )
.sp
Bessel function of integer order.
.sp
.LP
The scale of the result returned by these functions shall be the value
of the \fBscale\fP register at the time the function is
invoked. The value of the \fBscale\fP 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.
.SH EXIT STATUS
.LP
The following exit values shall be returned:
.TP 7
0
All input files were processed successfully.
.TP 7
\fIunspecified\fP
An error occurred.
.sp
.SH CONSEQUENCES OF ERRORS
.LP
If any \fIfile\fP operand is specified and the named file cannot be
accessed, \fIbc\fP shall write a diagnostic message to
standard error and terminate without any further action.
.LP
In an interactive invocation of \fIbc\fP, the utility should print
an error message and recover following any error in the
input. In a non-interactive invocation of \fIbc\fP, invalid input
causes undefined behavior.
.LP
\fIThe following sections are informative.\fP
.SH APPLICATION USAGE
.LP
Automatic variables in \fIbc\fP do not work in exactly the same way
as in either C or PL/1.
.LP
For historical reasons, the exit status from \fIbc\fP cannot be relied
upon to indicate that an error has occurred. Returning
zero after an error is possible. Therefore, \fIbc\fP 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.
.LP
The \fIbc\fP utility always uses the period ( \fB'.'\fP ) character
to represent a radix point, regardless of any
decimal-point character specified as part of the current locale. In
languages like C or \fIawk\fP, 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
\fIbc\fP, this arrangement would not be possible. Using the locale-specific
character in \fIbc\fP's input would introduce
ambiguities into the language; consider the following example in a
locale with a comma as the decimal-point character:
.sp
.RS
.nf

\fBdefine f(a,b) {
    ...
}
\&...
.sp

f(1,2,3)
\fP
.fi
.RE
.LP
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.
.SH EXAMPLES
.LP
In the shell, the following assigns an approximation of the first
ten digits of \fB'pi'\fP to the variable \fIx\fP:
.sp
.RS
.nf

\fBx=$(printf "%s\\n" 'scale = 10; 104348/33215' | bc)
\fP
.fi
.RE
.LP
The following \fIbc\fP program prints the same approximation of \fB'pi'\fP
, with a
label, to standard output:
.sp
.RS
.nf

\fBscale = 10
"pi equals "
104348 / 33215
\fP
.fi
.RE
.LP
The following defines a function to compute an approximate value of
the exponential function (note that such a function is
predefined if the \fB-l\fP option is specified):
.sp
.RS
.nf

\fBscale = 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
    }
}
\fP
.fi
.RE
.LP
The following prints approximate values of the exponential function
of the first ten integers:
.sp
.RS
.nf

\fBfor (i = 1; i <= 10; ++i) {
    e(i)
}
\fP
.fi
.RE
.SH RATIONALE
.LP
The \fIbc\fP utility is implemented historically as a front-end processor
for \fIdc\fP; \fIdc\fP was not selected to be part
of this volume of IEEE\ Std\ 1003.1-2001 because \fIbc\fP was thought
to have a more intuitive programmatic interface.
Current implementations that implement \fIbc\fP using \fIdc\fP are
expected to be compliant.
.LP
The exit status for error conditions has been left unspecified for
several reasons:
.IP " *" 3
The \fIbc\fP utility is used in both interactive and non-interactive
situations. Different exit codes may be appropriate for
the two uses.
.LP
.IP " *" 3
It is unclear when a non-zero exit should be given; divide-by-zero,
undefined functions, and syntax errors are all
possibilities.
.LP
.IP " *" 3
It is not clear what utility the exit status has.
.LP
.IP " *" 3
In the 4.3 BSD, System V, and Ninth Edition implementations, \fIbc\fP
works in conjunction with \fIdc\fP. The \fIdc\fP
utility is the parent, \fIbc\fP is the child. This was done to cleanly
terminate \fIbc\fP if \fIdc\fP aborted.
.LP
.LP
The decision to have \fIbc\fP exit upon encountering an inaccessible
input file is based on the belief that \fIbc\fP
\fIfile1\fP \fIfile2\fP is used most often when at least \fIfile1\fP
contains data/function declarations/initializations. Having
\fIbc\fP continue with prerequisite files missing is probably not
useful. There is no implication in the CONSEQUENCES OF ERRORS
section that \fIbc\fP must check all its files for accessibility before
opening any of them.
.LP
There was considerable debate on the appropriateness of the language
accepted by \fIbc\fP. 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 \fIbc\fP 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
\fIbc\fP obsolete. However, no such utility is known in
historical practice, and it was not within the scope of this volume
of IEEE\ Std\ 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\ Std\ 1003.1. This
left the following alternatives:
.IP " 1." 4
Exclude any calculator language from this volume of IEEE\ Std\ 1003.1-2001.
.LP
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.
.LP
.IP " 2." 4
Standardize the historical \fIdc\fP, possibly with minor modifications.
.LP
The consensus of the standard developers was that \fIdc\fP 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.
.LP
.IP " 3." 4
Standardize the historical \fIbc\fP, possibly with minor modifications.
.LP
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 \fIbc\fP
assignment operators \fB"=+"\fP , and so on, with the
more modern \fB"+="\fP , and so on. The older versions are considered
to be fundamentally flawed because of the lexical
ambiguity in uses like \fIa\fP=-1.
.LP
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.)
.LP
.LP
The \fB'%'\fP operator is the mathematical remainder operator when
\fBscale\fP is zero. The behavior of this operator for
other values of \fBscale\fP is from historical implementations of
\fIbc\fP, and has been maintained for the sake of historical
applications despite its non-intuitive nature.
.LP
Historical implementations permit setting \fBibase\fP and \fBobase\fP
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 \fBibase\fP that are greater than 16. This is because numeric constants
are recognized syntactically, rather than lexically, as
described in this volume of IEEE\ Std\ 1003.1-2001. They are built
from lexical tokens of single hexadecimal digits and
periods. Since <blank>s between tokens are not visible at the syntactic
level, it is not possible to recognize the
multi-digit "digits" 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\ Std\ 1003.1-2001,
as it does not impact the behavior of conforming
applications (and correct \fIbc\fP programs). Historical implementations
also accept input with all of the digits \fB'0'\fP -
\fB'9'\fP and \fB'A'\fP - \fB'F'\fP regardless of the value of \fBibase\fP;
since digits with value greater than or equal
to \fBibase\fP are not really appropriate, the behavior when they
appear is undefined, except for the common case of:
.sp
.RS
.nf

\fBibase=8;
    /* Process in octal base. */
\&...
ibase=A
    /* Restore decimal base. */
\fP
.fi
.RE
.LP
In some historical implementations, if the expression to be written
is an uninitialized array element, a leading <space>
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:
.sp
.RS
.nf

\fBecho 'b[3]' | bc
\fP
.fi
.RE
.LP
returning 00000 rather than 0.
.LP
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 \fBobase\fP that this volume of IEEE\ Std\ 1003.1-2001 requires
implementations to support (in particular, not
to 1, 0, or negative bases, if an implementation supports them as
an extension).
.LP
Historical implementations of \fIbc\fP 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.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIGrammar Conventions\fP , \fIawk\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .