PROLOG
This manual page is part of the POSIX Programmer's Manual. The Linux implementation of this interface may differ (consult the corresponding Linux manual page for details of Linux behavior), or the interface may not be implemented on Linux.NAME
bc — arbitrary-precision arithmetic languageSYNOPSIS
bc [-l] [file...]
DESCRIPTION
The bc 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 bc are attached to a terminal, the invocation of bc shall be considered to be interactive, causing behavioral constraints described in the following sections.OPTIONS
The bc utility shall conform to the Base Definitions volume of POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines. The following option shall be supported:- -l
- (The letter ell.) Define the math functions and initialize scale to 20, instead of the default zero; see the EXTENDED DESCRIPTION section.
OPERANDS
The following operand shall be supported:- file
- A pathname of a text file containing bc program statements. After all files have been read, bc shall read the standard input.
STDIN
See the INPUT FILES section.INPUT FILES
Input files shall be text files containing a sequence of comments, statements, and function definitions that shall be executed as they are read.ENVIRONMENT VARIABLES
The following environment variables shall affect the execution of bc:- LANG
- Provide a default value for the internationalization variables that are unset or null. (See the Base Definitions volume of POSIX.1‐2017, Section 8.2, Internationalization Variables for the precedence of internationalization variables used to determine the values of locale categories.)
- LC_ALL
- If set to a non-empty string value, override the values of all the other internationalization variables.
- LC_CTYPE
- 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).
- LC_MESSAGES
-
Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.
- NLSPATH
- Determine the location of message catalogs for the processing of LC_MESSAGES.
ASYNCHRONOUS EVENTS
Default.STDOUT
The output of the bc 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 obase and scale variables; see the EXTENDED DESCRIPTION section.STDERR
The standard error shall be used only for diagnostic messages.OUTPUT FILES
None.EXTENDED DESCRIPTION
Grammar
The grammar in this section and the lexical conventions in the following section shall together describe the syntax for bc programs. The general conventions for this style of grammar are described in Section 1.3, Grammar Conventions. A valid program can be represented as the non-terminal symbol program in the grammar. This formal syntax shall take precedence over the text syntax description.%token EOF NEWLINE STRING LETTER NUMBER
%token MUL_OP /* '*', '/', '%' */
%token ASSIGN_OP /* '=', '+=', '-=', '*=', '/=', '%=', '^=' */
%token REL_OP /* '==', '<=', '>=', '!=', '<', '>' */
%token INCR_DECR /* '++', '--' */
%token Define Break Quit Length /* 'define', 'break', 'quit', 'length' */
%token Return For If While Sqrt /* 'return', 'for', 'if', 'while', 'sqrt' */
%token Scale Ibase Obase Auto /* 'scale', 'ibase', 'obase', 'auto' */
%start program
%%
program : EOF
| input_item program
;
input_item : semicolon_list NEWLINE
| function
;
semicolon_list : /* empty */
| statement
| semicolon_list ';' statement
| semicolon_list ';'
;
statement_list : /* empty */
| statement
| statement_list NEWLINE
| statement_list NEWLINE statement
| statement_list ';'
| statement_list ';' statement
;
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 '}'
;
function : Define LETTER '(' opt_parameter_list ')'
'{' NEWLINE opt_auto_define_list
statement_list '}'
;
opt_parameter_list : /* empty */
| parameter_list
;
parameter_list : LETTER
| define_list ',' LETTER
;
opt_auto_define_list : /* empty */
| Auto define_list NEWLINE
| Auto define_list ';'
;
define_list : LETTER
| LETTER '[' ']'
| define_list ',' LETTER
| define_list ',' LETTER '[' ']'
;
opt_argument_list : /* empty */
| argument_list
;
argument_list : expression
| LETTER '[' ']' ',' argument_list
;
relational_expression : expression
| expression REL_OP expression
;
return_expression : /* empty */
| expression
;
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 ')'
;
named_expression : LETTER
| LETTER '[' expression ']'
| Scale
| Ibase
| Obase
;
Lexical Conventions in bc
The lexical conventions for bc programs, with respect to the preceding grammar, shall be as follows:- 1.
- Except as noted, bc shall recognize the longest possible token or delimiter beginning at a given point.
- 2.
- A comment shall consist of any characters beginning with the two adjacent characters "/*" and terminated by the next occurrence of the two adjacent characters "*/". Comments shall have no effect except to delimit lexical tokens.
- 3.
- The <newline> shall be recognized as the token NEWLINE.
- 4.
- The token STRING shall represent a string constant; it shall consist of any characters beginning with the double-quote character ('"') 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.
- 5.
- A <blank> shall have no effect except as an ordinary character if it appears within a STRING token, or to delimit a lexical token other than STRING.
- 6.
- 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:
- *
- It shall be interpreted as the character sequence "\<newline>" in STRING tokens.
- *
- It shall be ignored as part of a multi-line NUMBER token.
- 7.
- The token NUMBER shall represent a numeric constant. It shall be recognized by the following grammar:
NUMBER : integer
| '.' integer
| integer '.'
| integer '.' integer
;
integer : digit
| integer digit
;
digit : 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7
| 8 | 9 | A | B | C | D | E | F
;
- 8.
- The value of a NUMBER token shall be interpreted as a numeral in the base specified by the value of the internal register ibase (described below). Each of the digit 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 ibase appear in the token. However, note the exception for single-digit values being assigned to ibase and obase themselves, in Operations in bc.
- 9.
- The following keywords shall be recognized as tokens:
auto break define ibase if for length obase quit return scale sqrt while
- 10.
- Any of the following characters occurring anywhere except within a keyword shall be recognized as the token LETTER:
a 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
- 11.
- The following single-character and two-character sequences shall be recognized as the token ASSIGN_OP:
= += -= *= /= %= ^=
- 12.
- If an '=' character, as the beginning of a token, is followed by a '-' character with no intervening delimiter, the behavior is undefined.
- 13.
- The following single-characters shall be recognized as the token MUL_OP:
* / %
- 14.
- The following single-character and two-character sequences shall be recognized as the token REL_OP:
== <= >= != < >
- 15.
- The following two-character sequences shall be recognized as the token INCR_DECR:
++ --
- 16.
- The following single characters shall be recognized as tokens whose names are the character:
<newline> ( ) , + - ; [ ] ^ { }
- 17.
- The token EOF is returned when the end of input is reached.
Operations in bc
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 ("[]"). 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. 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.| Operator | Associativity |
| ++, -- | N/A |
| unary - | N/A |
| ^ | Right to left |
| *, /, % | Left to right |
| +, binary - | Left to right |
| =, +=, -=, *=, /=, %=, ^= | Right to left |
| ==, <=, >=, !=, <, > | None |
2 ≤ ibase ≤ 16
2 ≤ obase ≤ {BC_BASE_MAX}
- 1.
- If the value is less than zero, a <hyphen-minus> ('-') character shall be output.
- 2.
- One of the following is output, depending on the numerical value:
- *
- 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 obase (as described below), most significant digit first. The most significant non-zero digit shall be output next, followed by each successively less significant digit.
- *
- 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.
- *
- If the numerical value is zero, the character 0 shall be output.
- 3.
- 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 obase (as described below) representing the most significant portion of the fractional part of the value. If s represents the scale of the value being output, the number of digits output shall be s if obase is 10, less than or equal to s if obase is greater than 10, or greater than or equal to s if obase is less than 10. For obase values other than 10, this should be the number of digits needed to represent a precision of 10 s.
0 1 2 3 4 5 6 7 8 9 A B C D E F
01 15 24
008 024
- -expression
-
The result shall be the negative of the expression. The scale of the result shall be the scale of expression.
- ++named-expression
-
The named expression shall be incremented by one. The result shall be the value of the named expression after incrementing.
- --named-expression
-
The named expression shall be decremented by one. The result shall be the value of the named expression after decrementing.
- named-expression++
-
The named expression shall be incremented by one. The result shall be the value of the named expression before incrementing.
- named-expression--
-
The named expression shall be decremented by one. The result shall be the value of the named expression before decrementing.
- expression^expression
-
The result shall be the first expression raised to the power of the second expression. If the second expression is not an integer, the behavior is undefined. If a is the scale of the left expression and b is the absolute value of the right expression, the scale of the result shall be:
if b >= 0 min(a * b, max(scale, a)) if b < 0 scale
- expression*expression
-
The result shall be the product of the two expressions. If a and b are the scales of the two expressions, then the scale of the result shall be:
min(a+b,max(scale,a,b))
- expression/expression
-
The result shall be the quotient of the two expressions. The scale of the result shall be the value of scale.
- expression%expression
-
For expressions a and b, a%b shall be evaluated equivalent to the steps:
- 1.
- Compute a/b to current scale.
- 2.
- Use the result to compute:
a - (a / b) * b
max(scale + scale(b), scale(a))
max(scale + scale(b), scale(a))
- expression+expression
-
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.
- expression-expression
-
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.
- named-expression=expression
-
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 expression.
named-expression <operator>= expression
named-expression=named-expression <operator> expression
- expression1<expression2
-
The relation shall be true if the value of expression1 is strictly less than the value of expression2.
- expression1>expression2
-
The relation shall be true if the value of expression1 is strictly greater than the value of expression2.
- expression1<=expression2
-
The relation shall be true if the value of expression1 is less than or equal to the value of expression2.
- expression1>=expression2
-
The relation shall be true if the value of expression1 is greater than or equal to the value of expression2.
- expression1==expression2
-
The relation shall be true if the values of expression1 and expression2 are equal.
- expression1!=expression2
-
The relation shall be true if the values of expression1 and expression2 are unequal.
input_item : semicolon_list NEWLINE
first-expression
while ( relation) {
statement
last-expression
}
define LETTER ( opt_parameter_list ) {
opt_auto_define_list
statement_list
}
LETTER ( opt_argument_list )
- s( expression )
-
Sine of argument in radians.
- c( expression )
-
Cosine of argument in radians.
- a( expression )
-
Arctangent of argument.
- l( expression )
-
Natural logarithm of argument.
- e( expression )
-
Exponential function of argument.
- j( expression1, expression2 )
-
Bessel function of expression2 of the first kind of integer order expression1.
EXIT STATUS
The following exit values shall be returned:- 0
- All input files were processed successfully.
- unspecified
- An error occurred.
CONSEQUENCES OF ERRORS
If any file operand is specified and the named file cannot be accessed, bc shall write a diagnostic message to standard error and terminate without any further action. In an interactive invocation of bc, the utility should print an error message and recover following any error in the input. In a non-interactive invocation of bc, invalid input causes undefined behavior. The following sections are informative.APPLICATION USAGE
Automatic variables in bc do not work in exactly the same way as in either C or PL/1. For historical reasons, the exit status from bc cannot be relied upon to indicate that an error has occurred. Returning zero after an error is possible. Therefore, bc 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. The bc utility always uses the <period> ('.') character to represent a radix point, regardless of any decimal-point character specified as part of the current locale. In languages like C or awk, 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 bc, this arrangement would not be possible. Using the locale-specific character in bc's input would introduce ambiguities into the language; consider the following example in a locale with a <comma> as the decimal-point character:
define f(a,b) {
...
}
...
f(1,2,3)
EXAMPLES
In the shell, the following assigns an approximation of the first ten digits of 'π' to the variable x:x=$(printf "%s\n" 'scale = 10; 104348/33215' | bc)
scale = 10 "pi equals " 104348 / 33215
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
}
}
for (i = 1; i <= 10; ++i) {
e(i)
}
RATIONALE
The bc utility is implemented historically as a front-end processor for dc; dc was not selected to be part of this volume of POSIX.1‐2017 because bc was thought to have a more intuitive programmatic interface. Current implementations that implement bc using dc are expected to be compliant. The exit status for error conditions has been left unspecified for several reasons:- *
- The bc utility is used in both interactive and non-interactive situations. Different exit codes may be appropriate for the two uses.
- *
- It is unclear when a non-zero exit should be given; divide-by-zero, undefined functions, and syntax errors are all possibilities.
- *
- It is not clear what utility the exit status has.
- *
- In the 4.3 BSD, System V, and Ninth Edition implementations, bc works in conjunction with dc. The dc utility is the parent, bc is the child. This was done to cleanly terminate bc if dc aborted.
- 1.
- Exclude any calculator language from this volume of POSIX.1‐2017.
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
developers.
- 2.
- Standardize the historical dc, possibly with minor modifications.
The consensus of the standard developers was that dc 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.
- 3.
- Standardize the historical bc, possibly with minor modifications.
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
bc assignment operators "=+", and so on, with the more
modern "+=", and so on. The older versions are considered to
be fundamentally flawed because of the lexical ambiguity in uses like
a=-1.
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.)
The '%' operator is the mathematical remainder operator when scale
is zero. The behavior of this operator for other values of scale is
from historical implementations of bc, and has been maintained for the
sake of historical applications despite its non-intuitive nature.
Historical implementations permit setting ibase and obase 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 ibase that are greater than 16. This is
because numeric constants are recognized syntactically, rather than lexically,
as described in this volume of POSIX.1‐2017. They are built from
lexical tokens of single hexadecimal digits and <period> characters.
Since <blank> characters 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 POSIX.1‐2017, as it does not impact
the behavior of conforming applications (and correct bc programs).
Historical implementations also accept input with all of the digits
'0'-'9' and 'A'-'F' regardless of the value of
ibase; since digits with value greater than or equal to ibase
are not really appropriate, the behavior when they appear is undefined, except
for the common case of:
ibase=8;
/* Process in octal base. */
...
ibase=A
/* Restore decimal base. */
echo 'b[3]' | bc
FUTURE DIRECTIONS
None.SEE ALSO
Section 1.3, Grammar Conventions, awk The Base Definitions volume of POSIX.1‐2017, Chapter 8, Environment Variables, Section 12.2, Utility Syntax GuidelinesCOPYRIGHT
Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 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 . Any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. To report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .| 2017 | IEEE/The Open Group |