3 SPDX-License-Identifier: BSD-2-Clause
5 Copyright (c) 2018-2021 Gavin D. Howard and contributors.
7 Redistribution and use in source and binary forms, with or without
8 modification, are permitted provided that the following conditions are met:
10 * Redistributions of source code must retain the above copyright notice, this
11 list of conditions and the following disclaimer.
13 * Redistributions in binary form must reproduce the above copyright notice,
14 this list of conditions and the following disclaimer in the documentation
15 and/or other materials provided with the distribution.
17 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
18 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20 ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
21 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
22 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
23 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
24 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
25 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
26 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
27 POSSIBILITY OF SUCH DAMAGE.
33 bc - arbitrary-precision decimal arithmetic language and calculator
37 **bc** [**-ghilPqRsvVw**] [**-\-global-stacks**] [**-\-help**] [**-\-interactive**] [**-\-mathlib**] [**-\-no-prompt**] [**-\-no-read-prompt**] [**-\-quiet**] [**-\-standard**] [**-\-warn**] [**-\-version**] [**-e** *expr*] [**-\-expression**=*expr*...] [**-f** *file*...] [**-\-file**=*file*...] [*file*...]
41 bc(1) is an interactive processor for a language first standardized in 1991 by
42 POSIX. (The current standard is [here][1].) The language provides unlimited
43 precision decimal arithmetic and is somewhat C-like, but there are differences.
44 Such differences will be noted in this document.
46 After parsing and handling options, this bc(1) reads any files given on the
47 command line and executes them before reading from **stdin**.
49 This bc(1) is a drop-in replacement for *any* bc(1), including (and especially)
52 **Note**: If running this bc(1) on *any* script meant for another bc(1) gives a
53 parse error, it is probably because a word this bc(1) reserves as a keyword is
54 used as the name of a function, variable, or array. To fix that, use the
55 command-line option **-r** *keyword*, where *keyword* is the keyword that is
56 used as a name in the script. For more information, see the **OPTIONS** section.
58 If parsing scripts meant for other bc(1) implementations still does not work,
59 that is a bug and should be reported. See the **BUGS** section.
63 The following are the options that bc(1) accepts.
65 **-g**, **-\-global-stacks**
67 : Turns the globals **ibase**, **obase**, and **scale** into stacks.
69 This has the effect that a copy of the current value of all three are pushed
70 onto a stack for every function call, as well as popped when every function
71 returns. This means that functions can assign to any and all of those
72 globals without worrying that the change will affect other functions.
73 Thus, a hypothetical function named **output(x,b)** that simply printed
74 **x** in base **b** could be written like this:
76 define void output(x, b) {
83 define void output(x, b) {
91 This makes writing functions much easier.
93 However, since using this flag means that functions cannot set **ibase**,
94 **obase**, or **scale** globally, functions that are made to do so cannot
95 work anymore. There are two possible use cases for that, and each has a
98 First, if a function is called on startup to turn bc(1) into a number
99 converter, it is possible to replace that capability with various shell
102 alias d2o="bc -e ibase=A -e obase=8"
103 alias h2b="bc -e ibase=G -e obase=2"
105 Second, if the purpose of a function is to set **ibase**, **obase**, or
106 **scale** globally for any other purpose, it could be split into one to
107 three functions (based on how many globals it sets) and each of those
108 functions could return the desired value for a global.
110 If the behavior of this option is desired for every run of bc(1), then users
111 could make sure to define **BC_ENV_ARGS** and include this option (see the
112 **ENVIRONMENT VARIABLES** section for more details).
114 If **-s**, **-w**, or any equivalents are used, this option is ignored.
116 This is a **non-portable extension**.
120 : Prints a usage message and quits.
122 **-i**, **-\-interactive**
124 : Forces interactive mode. (See the **INTERACTIVE MODE** section.)
126 This is a **non-portable extension**.
128 **-L**, **-\-no-line-length**
130 : Disables line length checking and prints numbers without backslashes and
131 newlines. In other words, this option sets **BC_LINE_LENGTH** to **0** (see
132 the **ENVIRONMENT VARIABLES** section).
134 This is a **non-portable extension**.
136 **-l**, **-\-mathlib**
138 : Sets **scale** (see the **SYNTAX** section) to **20** and loads the included
139 math library before running any code, including any expressions or files
140 specified on the command line.
142 To learn what is in the library, see the **LIBRARY** section.
144 **-P**, **-\-no-prompt**
146 : Disables the prompt in TTY mode. (The prompt is only enabled in TTY mode.
147 See the **TTY MODE** section.) This is mostly for those users that do not
148 want a prompt or are not used to having them in bc(1). Most of those users
149 would want to put this option in **BC_ENV_ARGS** (see the
150 **ENVIRONMENT VARIABLES** section).
152 These options override the **BC_PROMPT** and **BC_TTY_MODE** environment
153 variables (see the **ENVIRONMENT VARIABLES** section).
155 This is a **non-portable extension**.
157 **-R**, **-\-no-read-prompt**
159 : Disables the read prompt in TTY mode. (The read prompt is only enabled in
160 TTY mode. See the **TTY MODE** section.) This is mostly for those users that
161 do not want a read prompt or are not used to having them in bc(1). Most of
162 those users would want to put this option in **BC_ENV_ARGS** (see the
163 **ENVIRONMENT VARIABLES** section). This option is also useful in hash bang
164 lines of bc(1) scripts that prompt for user input.
166 This option does not disable the regular prompt because the read prompt is
167 only used when the **read()** built-in function is called.
169 These options *do* override the **BC_PROMPT** and **BC_TTY_MODE**
170 environment variables (see the **ENVIRONMENT VARIABLES** section), but only
173 This is a **non-portable extension**.
175 **-r** *keyword*, **-\-redefine**=*keyword*
177 : Redefines *keyword* in order to allow it to be used as a function, variable,
178 or array name. This is useful when this bc(1) gives parse errors when
179 parsing scripts meant for other bc(1) implementations.
181 The keywords this bc(1) allows to be redefined are:
199 If any of those keywords are used as a function, variable, or array name in
200 a script, use this option with the keyword as the argument. If multiple are
201 used, use this option for all of them; it can be used multiple times.
203 Keywords are *not* redefined when parsing the builtin math library (see the
204 **LIBRARY** section).
206 It is a fatal error to redefine keywords mandated by the POSIX standard. It
207 is a fatal error to attempt to redefine words that this bc(1) does not
212 : This option is for compatibility with the [GNU bc(1)][2]; it is a no-op.
213 Without this option, GNU bc(1) prints a copyright header. This bc(1) only
214 prints the copyright header if one or more of the **-v**, **-V**, or
215 **-\-version** options are given.
217 This is a **non-portable extension**.
219 **-s**, **-\-standard**
221 : Process exactly the language defined by the [standard][1] and error if any
224 This is a **non-portable extension**.
226 **-v**, **-V**, **-\-version**
228 : Print the version information (copyright header) and exit.
230 This is a **non-portable extension**.
234 : Like **-s** and **-\-standard**, except that warnings (and not errors) are
235 printed for non-standard extensions and execution continues normally.
237 This is a **non-portable extension**.
239 **-z**, **-\-leading-zeroes**
241 : Makes bc(1) print all numbers greater than **-1** and less than **1**, and
242 not equal to **0**, with a leading zero.
244 This can be set for individual numbers with the **plz(x)**, plznl(x)**,
245 **pnlz(x)**, and **pnlznl(x)** functions in the extended math library (see
246 the **LIBRARY** section).
248 This is a **non-portable extension**.
250 **-e** *expr*, **-\-expression**=*expr*
252 : Evaluates *expr*. If multiple expressions are given, they are evaluated in
253 order. If files are given as well (see below), the expressions and files are
254 evaluated in the order given. This means that if a file is given before an
255 expression, the file is read in and evaluated first.
257 If this option is given on the command-line (i.e., not in **BC_ENV_ARGS**,
258 see the **ENVIRONMENT VARIABLES** section), then after processing all
259 expressions and files, bc(1) will exit, unless **-** (**stdin**) was given
260 as an argument at least once to **-f** or **-\-file**, whether on the
261 command-line or in **BC_ENV_ARGS**. However, if any other **-e**,
262 **-\-expression**, **-f**, or **-\-file** arguments are given after **-f-**
263 or equivalent is given, bc(1) will give a fatal error and exit.
265 This is a **non-portable extension**.
267 **-f** *file*, **-\-file**=*file*
269 : Reads in *file* and evaluates it, line by line, as though it were read
270 through **stdin**. If expressions are also given (see above), the
271 expressions are evaluated in the order given.
273 If this option is given on the command-line (i.e., not in **BC_ENV_ARGS**,
274 see the **ENVIRONMENT VARIABLES** section), then after processing all
275 expressions and files, bc(1) will exit, unless **-** (**stdin**) was given
276 as an argument at least once to **-f** or **-\-file**. However, if any other
277 **-e**, **-\-expression**, **-f**, or **-\-file** arguments are given after
278 **-f-** or equivalent is given, bc(1) will give a fatal error and exit.
280 This is a **non-portable extension**.
282 All long options are **non-portable extensions**.
286 If no files or expressions are given by the **-f**, **-\-file**, **-e**, or
287 **-\-expression** options, then bc(1) read from **stdin**.
289 However, there are a few caveats to this.
291 First, **stdin** is evaluated a line at a time. The only exception to this is if
292 the parse cannot complete. That means that starting a string without ending it
293 or starting a function, **if** statement, or loop without ending it will also
294 cause bc(1) to not execute.
296 Second, after an **if** statement, bc(1) doesn't know if an **else** statement
297 will follow, so it will not execute until it knows there will not be an **else**
302 Any non-error output is written to **stdout**. In addition, if history (see the
303 **HISTORY** section) and the prompt (see the **TTY MODE** section) are enabled,
304 both are output to **stdout**.
306 **Note**: Unlike other bc(1) implementations, this bc(1) will issue a fatal
307 error (see the **EXIT STATUS** section) if it cannot write to **stdout**, so if
308 **stdout** is closed, as in **bc <file> >&-**, it will quit with an error. This
309 is done so that bc(1) can report problems when **stdout** is redirected to a
312 If there are scripts that depend on the behavior of other bc(1) implementations,
313 it is recommended that those scripts be changed to redirect **stdout** to
318 Any error output is written to **stderr**.
320 **Note**: Unlike other bc(1) implementations, this bc(1) will issue a fatal
321 error (see the **EXIT STATUS** section) if it cannot write to **stderr**, so if
322 **stderr** is closed, as in **bc <file> 2>&-**, it will quit with an error. This
323 is done so that bc(1) can exit with an error code when **stderr** is redirected
326 If there are scripts that depend on the behavior of other bc(1) implementations,
327 it is recommended that those scripts be changed to redirect **stderr** to
332 The syntax for bc(1) programs is mostly C-like, with some differences. This
333 bc(1) follows the [POSIX standard][1], which is a much more thorough resource
334 for the language this bc(1) accepts. This section is meant to be a summary and a
335 listing of all the extensions to the standard.
337 In the sections below, **E** means expression, **S** means statement, and **I**
340 Identifiers (**I**) start with a lowercase letter and can be followed by any
341 number (up to **BC_NAME_MAX-1**) of lowercase letters (**a-z**), digits
342 (**0-9**), and underscores (**\_**). The regex is **\[a-z\]\[a-z0-9\_\]\***.
343 Identifiers with more than one character (letter) are a
344 **non-portable extension**.
346 **ibase** is a global variable determining how to interpret constant numbers. It
347 is the "input" base, or the number base used for interpreting input numbers.
348 **ibase** is initially **10**. If the **-s** (**-\-standard**) and **-w**
349 (**-\-warn**) flags were not given on the command line, the max allowable value
350 for **ibase** is **36**. Otherwise, it is **16**. The min allowable value for
351 **ibase** is **2**. The max allowable value for **ibase** can be queried in
352 bc(1) programs with the **maxibase()** built-in function.
354 **obase** is a global variable determining how to output results. It is the
355 "output" base, or the number base used for outputting numbers. **obase** is
356 initially **10**. The max allowable value for **obase** is **BC_BASE_MAX** and
357 can be queried in bc(1) programs with the **maxobase()** built-in function. The
358 min allowable value for **obase** is **2**. Values are output in the specified
361 The *scale* of an expression is the number of digits in the result of the
362 expression right of the decimal point, and **scale** is a global variable that
363 sets the precision of any operations, with exceptions. **scale** is initially
364 **0**. **scale** cannot be negative. The max allowable value for **scale** is
365 **BC_SCALE_MAX** and can be queried in bc(1) programs with the **maxscale()**
368 bc(1) has both *global* variables and *local* variables. All *local*
369 variables are local to the function; they are parameters or are introduced in
370 the **auto** list of a function (see the **FUNCTIONS** section). If a variable
371 is accessed which is not a parameter or in the **auto** list, it is assumed to
372 be *global*. If a parent function has a *local* variable version of a variable
373 that a child function considers *global*, the value of that *global* variable in
374 the child function is the value of the variable in the parent function, not the
375 value of the actual *global* variable.
377 All of the above applies to arrays as well.
379 The value of a statement that is an expression (i.e., any of the named
380 expressions or operands) is printed unless the lowest precedence operator is an
381 assignment operator *and* the expression is notsurrounded by parentheses.
383 The value that is printed is also assigned to the special variable **last**. A
384 single dot (**.**) may also be used as a synonym for **last**. These are
385 **non-portable extensions**.
387 Either semicolons or newlines may separate statements.
391 There are two kinds of comments:
393 1. Block comments are enclosed in **/\*** and **\*/**.
394 2. Line comments go from **#** until, and not including, the next newline. This
395 is a **non-portable extension**.
399 The following are named expressions in bc(1):
402 2. Array Elements: **I[E]**
406 6. **last** or a single dot (**.**)
408 Number 6 is a **non-portable extension**.
410 Variables and arrays do not interfere; users can have arrays named the same as
411 variables. This also applies to functions (see the **FUNCTIONS** section), so a
412 user can have a variable, array, and function that all have the same name, and
413 they will not shadow each other, whether inside of functions or not.
415 Named expressions are required as the operand of **increment**/**decrement**
416 operators and as the left side of **assignment** operators (see the *Operators*
421 The following are valid operands in bc(1):
423 1. Numbers (see the *Numbers* subsection below).
424 2. Array indices (**I[E]**).
425 3. **(E)**: The value of **E** (used to change precedence).
426 4. **sqrt(E)**: The square root of **E**. **E** must be non-negative.
427 5. **length(E)**: The number of significant decimal digits in **E**. Returns
428 **1** for **0** with no decimal places. If given a string, the length of the
429 string is returned. Passing a string to **length(E)** is a **non-portable
431 6. **length(I[])**: The number of elements in the array **I**. This is a
432 **non-portable extension**.
433 7. **scale(E)**: The *scale* of **E**.
434 8. **abs(E)**: The absolute value of **E**. This is a **non-portable
436 9. **modexp(E, E, E)**: Modular exponentiation, where the first expression is
437 the base, the second is the exponent, and the third is the modulus. All
438 three values must be integers. The second argument must be non-negative. The
439 third argument must be non-zero. This is a **non-portable extension**.
440 10. **divmod(E, E, I[])**: Division and modulus in one operation. This is for
441 optimization. The first expression is the dividend, and the second is the
442 divisor, which must be non-zero. The return value is the quotient, and the
443 modulus is stored in index **0** of the provided array (the last argument).
444 This is a **non-portable extension**.
445 11. **asciify(E)**: If **E** is a string, returns a string that is the first
446 letter of its argument. If it is a number, calculates the number mod **256**
447 and returns that number as a one-character string. This is a **non-portable
449 12. **I()**, **I(E)**, **I(E, E)**, and so on, where **I** is an identifier for
450 a non-**void** function (see the *Void Functions* subsection of the
451 **FUNCTIONS** section). The **E** argument(s) may also be arrays of the form
452 **I[]**, which will automatically be turned into array references (see the
453 *Array References* subsection of the **FUNCTIONS** section) if the
454 corresponding parameter in the function definition is an array reference.
455 13. **read()**: Reads a line from **stdin** and uses that as an expression. The
456 result of that expression is the result of the **read()** operand. This is a
457 **non-portable extension**.
458 14. **maxibase()**: The max allowable **ibase**. This is a **non-portable
460 15. **maxobase()**: The max allowable **obase**. This is a **non-portable
462 16. **maxscale()**: The max allowable **scale**. This is a **non-portable
464 17. **line_length()**: The line length set with **BC_LINE_LENGTH** (see the
465 **ENVIRONMENT VARIABLES** section). This is a **non-portable extension**.
466 18. **global_stacks()**: **0** if global stacks are not enabled with the **-g**
467 or **-\-global-stacks** options, non-zero otherwise. See the **OPTIONS**
468 section. This is a **non-portable extension**.
469 19. **leading_zero()**: **0** if leading zeroes are not enabled with the **-z**
470 or **--leading-zeroes** options, non-zero otherwise. See the **OPTIONS**
471 section. This is a **non-portable extension**.
475 Numbers are strings made up of digits, uppercase letters, and at most **1**
476 period for a radix. Numbers can have up to **BC_NUM_MAX** digits. Uppercase
477 letters are equal to **9** + their position in the alphabet (i.e., **A** equals
478 **10**, or **9+1**). If a digit or letter makes no sense with the current value
479 of **ibase**, they are set to the value of the highest valid digit in **ibase**.
481 Single-character numbers (i.e., **A** alone) take the value that they would have
482 if they were valid digits, regardless of the value of **ibase**. This means that
483 **A** alone always equals decimal **10** and **Z** alone always equals decimal
488 The following arithmetic and logical operators can be used. They are listed in
489 order of decreasing precedence. Operators in the same group have the same
494 : Type: Prefix and Postfix
498 Description: **increment**, **decrement**
506 Description: **negation**, **boolean not**
514 Description: **power**
522 Description: **multiply**, **divide**, **modulus**
530 Description: **add**, **subtract**
532 **=** **+=** **-=** **\*=** **/=** **%=** **\^=**
538 Description: **assignment**
540 **==** **\<=** **\>=** **!=** **\<** **\>**
546 Description: **relational**
554 Description: **boolean and**
562 Description: **boolean or**
564 The operators will be described in more detail below.
568 : The prefix and postfix **increment** and **decrement** operators behave
569 exactly like they would in C. They require a named expression (see the
570 *Named Expressions* subsection) as an operand.
572 The prefix versions of these operators are more efficient; use them where
577 : The **negation** operator returns **0** if a user attempts to negate any
578 expression with the value **0**. Otherwise, a copy of the expression with
579 its sign flipped is returned.
583 : The **boolean not** operator returns **1** if the expression is **0**, or
586 This is a **non-portable extension**.
590 : The **power** operator (not the **exclusive or** operator, as it would be in
591 C) takes two expressions and raises the first to the power of the value of
592 the second. The *scale* of the result is equal to **scale**.
594 The second expression must be an integer (no *scale*), and if it is
595 negative, the first value must be non-zero.
599 : The **multiply** operator takes two expressions, multiplies them, and
600 returns the product. If **a** is the *scale* of the first expression and
601 **b** is the *scale* of the second expression, the *scale* of the result is
602 equal to **min(a+b,max(scale,a,b))** where **min()** and **max()** return
607 : The **divide** operator takes two expressions, divides them, and returns the
608 quotient. The *scale* of the result shall be the value of **scale**.
610 The second expression must be non-zero.
614 : The **modulus** operator takes two expressions, **a** and **b**, and
615 evaluates them by 1) Computing **a/b** to current **scale** and 2) Using the
616 result of step 1 to calculate **a-(a/b)\*b** to *scale*
617 **max(scale+scale(b),scale(a))**.
619 The second expression must be non-zero.
623 : The **add** operator takes two expressions, **a** and **b**, and returns the
624 sum, with a *scale* equal to the max of the *scale*s of **a** and **b**.
628 : The **subtract** operator takes two expressions, **a** and **b**, and
629 returns the difference, with a *scale* equal to the max of the *scale*s of
632 **=** **+=** **-=** **\*=** **/=** **%=** **\^=**
634 : The **assignment** operators take two expressions, **a** and **b** where
635 **a** is a named expression (see the *Named Expressions* subsection).
637 For **=**, **b** is copied and the result is assigned to **a**. For all
638 others, **a** and **b** are applied as operands to the corresponding
639 arithmetic operator and the result is assigned to **a**.
641 **==** **\<=** **\>=** **!=** **\<** **\>**
643 : The **relational** operators compare two expressions, **a** and **b**, and
644 if the relation holds, according to C language semantics, the result is
645 **1**. Otherwise, it is **0**.
647 Note that unlike in C, these operators have a lower precedence than the
648 **assignment** operators, which means that **a=b\>c** is interpreted as
651 Also, unlike the [standard][1] requires, these operators can appear anywhere
652 any other expressions can be used. This allowance is a
653 **non-portable extension**.
657 : The **boolean and** operator takes two expressions and returns **1** if both
658 expressions are non-zero, **0** otherwise.
660 This is *not* a short-circuit operator.
662 This is a **non-portable extension**.
666 : The **boolean or** operator takes two expressions and returns **1** if one
667 of the expressions is non-zero, **0** otherwise.
669 This is *not* a short-circuit operator.
671 This is a **non-portable extension**.
675 The following items are statements:
678 2. **{** **S** **;** ... **;** **S** **}**
679 3. **if** **(** **E** **)** **S**
680 4. **if** **(** **E** **)** **S** **else** **S**
681 5. **while** **(** **E** **)** **S**
682 6. **for** **(** **E** **;** **E** **;** **E** **)** **S**
683 7. An empty statement
689 13. A string of characters, enclosed in double quotes
690 14. **print** **E** **,** ... **,** **E**
691 15. **stream** **E** **,** ... **,** **E**
692 16. **I()**, **I(E)**, **I(E, E)**, and so on, where **I** is an identifier for
693 a **void** function (see the *Void Functions* subsection of the
694 **FUNCTIONS** section). The **E** argument(s) may also be arrays of the form
695 **I[]**, which will automatically be turned into array references (see the
696 *Array References* subsection of the **FUNCTIONS** section) if the
697 corresponding parameter in the function definition is an array reference.
699 Numbers 4, 9, 11, 12, 14, 15, and 16 are **non-portable extensions**.
701 Also, as a **non-portable extension**, any or all of the expressions in the
702 header of a for loop may be omitted. If the condition (second expression) is
703 omitted, it is assumed to be a constant **1**.
705 The **break** statement causes a loop to stop iterating and resume execution
706 immediately following a loop. This is only allowed in loops.
708 The **continue** statement causes a loop iteration to stop early and returns to
709 the start of the loop, including testing the loop condition. This is only
712 The **if** **else** statement does the same thing as in C.
714 The **quit** statement causes bc(1) to quit, even if it is on a branch that will
715 not be executed (it is a compile-time command).
717 The **halt** statement causes bc(1) to quit, if it is executed. (Unlike **quit**
718 if it is on a branch of an **if** statement that is not executed, bc(1) does not
721 The **limits** statement prints the limits that this bc(1) is subject to. This
722 is like the **quit** statement in that it is a compile-time command.
724 An expression by itself is evaluated and printed, followed by a newline.
728 If strings appear as a statement by themselves, they are printed without a
731 In addition to appearing as a lone statement by themselves, strings can be
732 assigned to variables and array elements. They can also be passed to functions
733 in variable parameters.
735 If any statement that expects a string is given a variable that had a string
736 assigned to it, the statement acts as though it had received a string.
738 If any math operation is attempted on a string or a variable or array element
739 that has been assigned a string, an error is raised, and bc(1) resets (see the
742 Assigning strings to variables and array elements and passing them to functions
743 are **non-portable extensions**.
747 The "expressions" in a **print** statement may also be strings. If they are, there
748 are backslash escape sequences that are interpreted specially. What those
749 sequences are, and what they cause to be printed, are shown below:
769 Any other character following a backslash causes the backslash and character to
772 Any non-string expression in a print statement shall be assigned to **last**,
773 like any other expression that is printed.
777 The "expressions in a **stream** statement may also be strings.
779 If a **stream** statement is given a string, it prints the string as though the
780 string had appeared as its own statement. In other words, the **stream**
781 statement prints strings normally, without a newline.
783 If a **stream** statement is given a number, a copy of it is truncated and its
784 absolute value is calculated. The result is then printed as though **obase** is
785 **256** and each digit is interpreted as an 8-bit ASCII character, making it a
788 ## Order of Evaluation
790 All expressions in a statment are evaluated left to right, except as necessary
791 to maintain order of operations. This means, for example, assuming that **i** is
792 equal to **0**, in the expression
796 the first (or 0th) element of **a** is set to **1**, and **i** is equal to **2**
797 at the end of the expression.
799 This includes function arguments. Thus, assuming **i** is equal to **0**, this
800 means that in the expression
804 the first argument passed to **x()** is **0**, and the second argument is **1**,
805 while **i** is equal to **2** before the function starts executing.
809 Function definitions are as follows:
819 Any **I** in the parameter list or **auto** list may be replaced with **I[]** to
820 make a parameter or **auto** var an array, and any **I** in the parameter list
821 may be replaced with **\*I[]** to make a parameter an array reference. Callers
822 of functions that take array references should not put an asterisk in the call;
823 they must be called with just **I[]** like normal array parameters and will be
824 automatically converted into references.
826 As a **non-portable extension**, the opening brace of a **define** statement may
827 appear on the next line.
829 As a **non-portable extension**, the return statement may also be in one of the
833 2. **return** **(** **)**
836 The first two, or not specifying a **return** statement, is equivalent to
837 **return (0)**, unless the function is a **void** function (see the *Void
838 Functions* subsection below).
842 Functions can also be **void** functions, defined as follows:
845 define void I(I,...,I){
852 They can only be used as standalone expressions, where such an expression would
853 be printed alone, except in a print statement.
855 Void functions can only use the first two **return** statements listed above.
856 They can also omit the return statement entirely.
858 The word "void" is not treated as a keyword; it is still possible to have
859 variables, arrays, and functions named **void**. The word "void" is only
860 treated specially right after the **define** keyword.
862 This is a **non-portable extension**.
866 For any array in the parameter list, if the array is declared in the form
872 it is a **reference**. Any changes to the array in the function are reflected,
873 when the function returns, to the array that was passed in.
875 Other than this, all function arguments are passed by value.
877 This is a **non-portable extension**.
881 All of the functions below are available when the **-l** or **-\-mathlib**
882 command-line flags are given.
886 The [standard][1] defines the following functions for the math library:
890 : Returns the sine of **x**, which is assumed to be in radians.
892 This is a transcendental function (see the *Transcendental Functions*
897 : Returns the cosine of **x**, which is assumed to be in radians.
899 This is a transcendental function (see the *Transcendental Functions*
904 : Returns the arctangent of **x**, in radians.
906 This is a transcendental function (see the *Transcendental Functions*
911 : Returns the natural logarithm of **x**.
913 This is a transcendental function (see the *Transcendental Functions*
918 : Returns the mathematical constant **e** raised to the power of **x**.
920 This is a transcendental function (see the *Transcendental Functions*
925 : Returns the bessel integer order **n** (truncated) of **x**.
927 This is a transcendental function (see the *Transcendental Functions*
930 ## Transcendental Functions
932 All transcendental functions can return slightly inaccurate results (up to 1
933 [ULP][4]). This is unavoidable, and [this article][5] explains why it is
934 impossible and unnecessary to calculate exact results for the transcendental
937 Because of the possible inaccuracy, I recommend that users call those functions
938 with the precision (**scale**) set to at least 1 higher than is necessary. If
939 exact results are *absolutely* required, users can double the precision
940 (**scale**) and then truncate.
942 The transcendental functions in the standard math library are:
953 When bc(1) encounters an error or a signal that it has a non-default handler
954 for, it resets. This means that several things happen.
956 First, any functions that are executing are stopped and popped off the stack.
957 The behavior is not unlike that of exceptions in programming languages. Then
958 the execution point is set so that any code waiting to execute (after all
959 functions returned) is skipped.
961 Thus, when bc(1) resets, it skips any remaining code waiting to be executed.
962 Then, if it is interactive mode, and the error was not a fatal error (see the
963 **EXIT STATUS** section), it asks for more input; otherwise, it exits with the
964 appropriate return code.
966 Note that this reset behavior is different from the GNU bc(1), which attempts to
967 start executing the statement right after the one that caused an error.
971 Most bc(1) implementations use **char** types to calculate the value of **1**
972 decimal digit at a time, but that can be slow. This bc(1) does something
975 It uses large integers to calculate more than **1** decimal digit at a time. If
976 built in a environment where **BC_LONG_BIT** (see the **LIMITS** section) is
977 **64**, then each integer has **9** decimal digits. If built in an environment
978 where **BC_LONG_BIT** is **32** then each integer has **4** decimal digits. This
979 value (the number of decimal digits per large integer) is called
982 The actual values of **BC_LONG_BIT** and **BC_BASE_DIGS** can be queried with
983 the **limits** statement.
985 In addition, this bc(1) uses an even larger integer for overflow checking. This
986 integer type depends on the value of **BC_LONG_BIT**, but is always at least
987 twice as large as the integer type used to store digits.
991 The following are the limits on bc(1):
995 : The number of bits in the **long** type in the environment where bc(1) was
996 built. This determines how many decimal digits can be stored in a single
997 large integer (see the **PERFORMANCE** section).
1001 : The number of decimal digits per large integer (see the **PERFORMANCE**
1002 section). Depends on **BC_LONG_BIT**.
1006 : The max decimal number that each large integer can store (see
1007 **BC_BASE_DIGS**) plus **1**. Depends on **BC_BASE_DIGS**.
1011 : The max number that the overflow type (see the **PERFORMANCE** section) can
1012 hold. Depends on **BC_LONG_BIT**.
1016 : The maximum output base. Set at **BC_BASE_POW**.
1020 : The maximum size of arrays. Set at **SIZE_MAX-1**.
1024 : The maximum **scale**. Set at **BC_OVERFLOW_MAX-1**.
1028 : The maximum length of strings. Set at **BC_OVERFLOW_MAX-1**.
1032 : The maximum length of identifiers. Set at **BC_OVERFLOW_MAX-1**.
1036 : The maximum length of a number (in decimal digits), which includes digits
1037 after the decimal point. Set at **BC_OVERFLOW_MAX-1**.
1041 : The maximum allowable exponent (positive or negative). Set at
1042 **BC_OVERFLOW_MAX**.
1046 : The maximum number of vars/arrays. Set at **SIZE_MAX-1**.
1048 The actual values can be queried with the **limits** statement.
1050 These limits are meant to be effectively non-existent; the limits are so large
1051 (at least on 64-bit machines) that there should not be any point at which they
1052 become a problem. In fact, memory should be exhausted before these limits should
1055 # ENVIRONMENT VARIABLES
1057 bc(1) recognizes the following environment variables:
1061 : If this variable exists (no matter the contents), bc(1) behaves as if
1062 the **-s** option was given.
1066 : This is another way to give command-line arguments to bc(1). They should be
1067 in the same format as all other command-line arguments. These are always
1068 processed first, so any files given in **BC_ENV_ARGS** will be processed
1069 before arguments and files given on the command-line. This gives the user
1070 the ability to set up "standard" options and files to be used at every
1071 invocation. The most useful thing for such files to contain would be useful
1072 functions that the user might want every time bc(1) runs.
1074 The code that parses **BC_ENV_ARGS** will correctly handle quoted arguments,
1075 but it does not understand escape sequences. For example, the string
1076 **"/home/gavin/some bc file.bc"** will be correctly parsed, but the string
1077 **"/home/gavin/some \"bc\" file.bc"** will include the backslashes.
1079 The quote parsing will handle either kind of quotes, **'** or **"**. Thus,
1080 if you have a file with any number of single quotes in the name, you can use
1081 double quotes as the outside quotes, as in **"some 'bc' file.bc"**, and vice
1082 versa if you have a file with double quotes. However, handling a file with
1083 both kinds of quotes in **BC_ENV_ARGS** is not supported due to the
1084 complexity of the parsing, though such files are still supported on the
1085 command-line where the parsing is done by the shell.
1089 : If this environment variable exists and contains an integer that is greater
1090 than **1** and is less than **UINT16_MAX** (**2\^16-1**), bc(1) will output
1091 lines to that length, including the backslash (**\\**). The default line
1094 The special value of **0** will disable line length checking and print
1095 numbers without regard to line length and without backslashes and newlines.
1099 : If this environment variable exists and contains an integer, then a non-zero
1100 value activates the copyright banner when bc(1) is in interactive mode,
1101 while zero deactivates it.
1103 If bc(1) is not in interactive mode (see the **INTERACTIVE MODE** section),
1104 then this environment variable has no effect because bc(1) does not print
1105 the banner when not in interactive mode.
1107 This environment variable overrides the default, which can be queried with
1108 the **-h** or **-\-help** options.
1112 : If bc(1) is not in interactive mode (see the **INTERACTIVE MODE** section),
1113 then this environment variable has no effect because bc(1) exits on
1114 **SIGINT** when not in interactive mode.
1116 However, when bc(1) is in interactive mode, then if this environment
1117 variable exists and contains an integer, a non-zero value makes bc(1) reset
1118 on **SIGINT**, rather than exit, and zero makes bc(1) exit. If this
1119 environment variable exists and is *not* an integer, then bc(1) will exit on
1122 This environment variable overrides the default, which can be queried with
1123 the **-h** or **-\-help** options.
1127 : If TTY mode is *not* available (see the **TTY MODE** section), then this
1128 environment variable has no effect.
1130 However, when TTY mode is available, then if this environment variable
1131 exists and contains an integer, then a non-zero value makes bc(1) use TTY
1132 mode, and zero makes bc(1) not use TTY mode.
1134 This environment variable overrides the default, which can be queried with
1135 the **-h** or **-\-help** options.
1139 : If TTY mode is *not* available (see the **TTY MODE** section), then this
1140 environment variable has no effect.
1142 However, when TTY mode is available, then if this environment variable
1143 exists and contains an integer, a non-zero value makes bc(1) use a prompt,
1144 and zero or a non-integer makes bc(1) not use a prompt. If this environment
1145 variable does not exist and **BC_TTY_MODE** does, then the value of the
1146 **BC_TTY_MODE** environment variable is used.
1148 This environment variable and the **BC_TTY_MODE** environment variable
1149 override the default, which can be queried with the **-h** or **-\-help**
1154 bc(1) returns the following exit statuses:
1162 : A math error occurred. This follows standard practice of using **1** for
1163 expected errors, since math errors will happen in the process of normal
1166 Math errors include divide by **0**, taking the square root of a negative
1167 number, attempting to convert a negative number to a hardware integer,
1168 overflow when converting a number to a hardware integer, overflow when
1169 calculating the size of a number, and attempting to use a non-integer where
1170 an integer is required.
1172 Converting to a hardware integer happens for the second operand of the power
1173 (**\^**) operator and the corresponding assignment operator.
1177 : A parse error occurred.
1179 Parse errors include unexpected **EOF**, using an invalid character, failing
1180 to find the end of a string or comment, using a token where it is invalid,
1181 giving an invalid expression, giving an invalid print statement, giving an
1182 invalid function definition, attempting to assign to an expression that is
1183 not a named expression (see the *Named Expressions* subsection of the
1184 **SYNTAX** section), giving an invalid **auto** list, having a duplicate
1185 **auto**/function parameter, failing to find the end of a code block,
1186 attempting to return a value from a **void** function, attempting to use a
1187 variable as a reference, and using any extensions when the option **-s** or
1188 any equivalents were given.
1192 : A runtime error occurred.
1194 Runtime errors include assigning an invalid number to any global (**ibase**,
1195 **obase**, or **scale**), giving a bad expression to a **read()** call,
1196 calling **read()** inside of a **read()** call, type errors, passing the
1197 wrong number of arguments to functions, attempting to call an undefined
1198 function, and attempting to use a **void** function call as a value in an
1203 : A fatal error occurred.
1205 Fatal errors include memory allocation errors, I/O errors, failing to open
1206 files, attempting to use files that do not have only ASCII characters (bc(1)
1207 only accepts ASCII characters), attempting to open a directory as a file,
1208 and giving invalid command-line options.
1210 The exit status **4** is special; when a fatal error occurs, bc(1) always exits
1211 and returns **4**, no matter what mode bc(1) is in.
1213 The other statuses will only be returned when bc(1) is not in interactive mode
1214 (see the **INTERACTIVE MODE** section), since bc(1) resets its state (see the
1215 **RESET** section) and accepts more input when one of those errors occurs in
1216 interactive mode. This is also the case when interactive mode is forced by the
1217 **-i** flag or **-\-interactive** option.
1219 These exit statuses allow bc(1) to be used in shell scripting with error
1220 checking, and its normal behavior can be forced by using the **-i** flag or
1221 **-\-interactive** option.
1225 Per the [standard][1], bc(1) has an interactive mode and a non-interactive mode.
1226 Interactive mode is turned on automatically when both **stdin** and **stdout**
1227 are hooked to a terminal, but the **-i** flag and **-\-interactive** option can
1228 turn it on in other situations.
1230 In interactive mode, bc(1) attempts to recover from errors (see the **RESET**
1231 section), and in normal execution, flushes **stdout** as soon as execution is
1232 done for the current input. bc(1) may also reset on **SIGINT** instead of exit,
1233 depending on the contents of, or default for, the **BC_SIGINT_RESET**
1234 environment variable (see the **ENVIRONMENT VARIABLES** section).
1238 If **stdin**, **stdout**, and **stderr** are all connected to a TTY, then "TTY
1239 mode" is considered to be available, and thus, bc(1) can turn on TTY mode,
1240 subject to some settings.
1242 If there is the environment variable **BC_TTY_MODE** in the environment (see the
1243 **ENVIRONMENT VARIABLES** section), then if that environment variable contains a
1244 non-zero integer, bc(1) will turn on TTY mode when **stdin**, **stdout**, and
1245 **stderr** are all connected to a TTY. If the **BC_TTY_MODE** environment
1246 variable exists but is *not* a non-zero integer, then bc(1) will not turn TTY
1249 If the environment variable **BC_TTY_MODE** does *not* exist, the default
1250 setting is used. The default setting can be queried with the **-h** or
1251 **-\-help** options.
1253 TTY mode is different from interactive mode because interactive mode is required
1254 in the [bc(1) specification][1], and interactive mode requires only **stdin**
1255 and **stdout** to be connected to a terminal.
1259 If TTY mode is available, then a prompt can be enabled. Like TTY mode itself, it
1260 can be turned on or off with an environment variable: **BC_PROMPT** (see the
1261 **ENVIRONMENT VARIABLES** section).
1263 If the environment variable **BC_PROMPT** exists and is a non-zero integer, then
1264 the prompt is turned on when **stdin**, **stdout**, and **stderr** are connected
1265 to a TTY and the **-P** and **-\-no-prompt** options were not used. The read
1266 prompt will be turned on under the same conditions, except that the **-R** and
1267 **-\-no-read-prompt** options must also not be used.
1269 However, if **BC_PROMPT** does not exist, the prompt can be enabled or disabled
1270 with the **BC_TTY_MODE** environment variable, the **-P** and **-\-no-prompt**
1271 options, and the **-R** and **-\-no-read-prompt** options. See the **ENVIRONMENT
1272 VARIABLES** and **OPTIONS** sections for more details.
1276 Sending a **SIGINT** will cause bc(1) to do one of two things.
1278 If bc(1) is not in interactive mode (see the **INTERACTIVE MODE** section), or
1279 the **BC_SIGINT_RESET** environment variable (see the **ENVIRONMENT VARIABLES**
1280 section), or its default, is either not an integer or it is zero, bc(1) will
1283 However, if bc(1) is in interactive mode, and the **BC_SIGINT_RESET** or its
1284 default is an integer and non-zero, then bc(1) will stop executing the current
1285 input and reset (see the **RESET** section) upon receiving a **SIGINT**.
1287 Note that "current input" can mean one of two things. If bc(1) is processing
1288 input from **stdin** in interactive mode, it will ask for more input. If bc(1)
1289 is processing input from a file in interactive mode, it will stop processing the
1290 file and start processing the next file, if one exists, or ask for input from
1291 **stdin** if no other file exists.
1293 This means that if a **SIGINT** is sent to bc(1) as it is executing a file, it
1294 can seem as though bc(1) did not respond to the signal since it will immediately
1295 start executing the next file. This is by design; most files that users execute
1296 when interacting with bc(1) have function definitions, which are quick to parse.
1297 If a file takes a long time to execute, there may be a bug in that file. The
1298 rest of the files could still be executed without problem, allowing the user to
1301 **SIGTERM** and **SIGQUIT** cause bc(1) to clean up and exit, and it uses the
1302 default handler for all other signals.
1306 This bc(1) ships with support for adding error messages for different locales
1307 and thus, supports **LC_MESSAGES**.
1315 bc(1) is compliant with the [IEEE Std 1003.1-2017 (“POSIX.1-2017”)][1]
1316 specification. The flags **-efghiqsvVw**, all long options, and the extensions
1317 noted above are extensions to that specification.
1319 Note that the specification explicitly says that bc(1) only accepts numbers that
1320 use a period (**.**) as a radix point, regardless of the value of
1323 This bc(1) supports error messages for different locales, and thus, it supports
1328 None are known. Report bugs at https://git.yzena.com/gavin/bc.
1332 Gavin D. Howard <gavin@yzena.com> and contributors.
1334 [1]: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html
1335 [2]: https://www.gnu.org/software/bc/
1336 [3]: https://en.wikipedia.org/wiki/Rounding#Round_half_away_from_zero
1337 [4]: https://en.wikipedia.org/wiki/Unit_in_the_last_place
1338 [5]: https://people.eecs.berkeley.edu/~wkahan/LOG10HAF.TXT
1339 [6]: https://en.wikipedia.org/wiki/Rounding#Rounding_away_from_zero