1<!--- 2 3SPDX-License-Identifier: BSD-2-Clause 4 5Copyright (c) 2018-2020 Gavin D. Howard and contributors. 6 7Redistribution and use in source and binary forms, with or without 8modification, are permitted provided that the following conditions are met: 9 10* Redistributions of source code must retain the above copyright notice, this 11 list of conditions and the following disclaimer. 12 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. 16 17THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 18AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 19IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 21LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 22CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 23SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 24INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 25CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 26ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 27POSSIBILITY OF SUCH DAMAGE. 28 29--> 30 31# NAME 32 33bc - arbitrary-precision arithmetic language and calculator 34 35# SYNOPSIS 36 37**bc** [**-ghilPqsvVw**] [**--global-stacks**] [**--help**] [**--interactive**] [**--mathlib**] [**--no-prompt**] [**--quiet**] [**--standard**] [**--warn**] [**--version**] [**-e** *expr*] [**--expression**=*expr*...] [**-f** *file*...] [**-file**=*file*...] 38[*file*...] 39 40# DESCRIPTION 41 42bc(1) is an interactive processor for a language first standardized in 1991 by 43POSIX. (The current standard is [here][1].) The language provides unlimited 44precision decimal arithmetic and is somewhat C-like, but there are differences. 45Such differences will be noted in this document. 46 47After parsing and handling options, this bc(1) reads any files given on the 48command line and executes them before reading from **stdin**. 49 50# OPTIONS 51 52The following are the options that bc(1) accepts. 53 54**-g**, **--global-stacks** 55 56 Turns the globals **ibase**, **obase**, and **scale** into stacks. 57 58 This has the effect that a copy of the current value of all three are pushed 59 onto a stack for every function call, as well as popped when every function 60 returns. This means that functions can assign to any and all of those 61 globals without worrying that the change will affect other functions. 62 Thus, a hypothetical function named **output(x,b)** that simply printed 63 **x** in base **b** could be written like this: 64 65 define void output(x, b) { 66 obase=b 67 x 68 } 69 70 instead of like this: 71 72 define void output(x, b) { 73 auto c 74 c=obase 75 obase=b 76 x 77 obase=c 78 } 79 80 This makes writing functions much easier. 81 82 However, since using this flag means that functions cannot set **ibase**, 83 **obase**, or **scale** globally, functions that are made to do so cannot 84 work anymore. There are two possible use cases for that, and each has a 85 solution. 86 87 First, if a function is called on startup to turn bc(1) into a number 88 converter, it is possible to replace that capability with various shell 89 aliases. Examples: 90 91 alias d2o="bc -e ibase=A -e obase=8" 92 alias h2b="bc -e ibase=G -e obase=2" 93 94 Second, if the purpose of a function is to set **ibase**, **obase**, or 95 **scale** globally for any other purpose, it could be split into one to 96 three functions (based on how many globals it sets) and each of those 97 functions could return the desired value for a global. 98 99 If the behavior of this option is desired for every run of bc(1), then users 100 could make sure to define **BC_ENV_ARGS** and include this option (see the 101 **ENVIRONMENT VARIABLES** section for more details). 102 103 If **-s**, **-w**, or any equivalents are used, this option is ignored. 104 105 This is a **non-portable extension**. 106 107**-h**, **--help** 108 109: Prints a usage message and quits. 110 111**-i**, **--interactive** 112 113: Forces interactive mode. (See the **INTERACTIVE MODE** section.) 114 115 This is a **non-portable extension**. 116 117**-l**, **--mathlib** 118 119: Sets **scale** (see the **SYNTAX** section) to **20** and loads the included 120 math library before running any code, including any expressions or files 121 specified on the command line. 122 123 To learn what is in the library, see the **LIBRARY** section. 124 125**-P**, **--no-prompt** 126 127: Disables the prompt in TTY mode. (The prompt is only enabled in TTY mode. 128 See the **TTY MODE** section) This is mostly for those users that do not 129 want a prompt or are not used to having them in bc(1). Most of those users 130 would want to put this option in **BC_ENV_ARGS** (see the 131 **ENVIRONMENT VARIABLES** section). 132 133 This is a **non-portable extension**. 134 135**-q**, **--quiet** 136 137: Do not print copyright header. bc(1) will also suppress the header in 138 non-interactive mode. 139 140 This is mostly for compatibility with the [GNU bc(1)][2]. 141 142 This is a **non-portable extension**. 143 144**-s**, **--standard** 145 146: Process exactly the language defined by the [standard][1] and error if any 147 extensions are used. 148 149 This is a **non-portable extension**. 150 151**-v**, **-V**, **--version** 152 153: Print the version information (copyright header) and exit. 154 155 This is a **non-portable extension**. 156 157**-w**, **--warn** 158 159: Like **-s** and **--standard**, except that warnings (and not errors) are 160 printed for non-standard extensions and execution continues normally. 161 162 This is a **non-portable extension**. 163 164**-e** *expr*, **--expression**=*expr* 165 166: Evaluates *expr*. If multiple expressions are given, they are evaluated in 167 order. If files are given as well (see below), the expressions and files are 168 evaluated in the order given. This means that if a file is given before an 169 expression, the file is read in and evaluated first. 170 171 In other bc(1) implementations, this option causes the program to execute 172 the expressions and then exit. This bc(1) does not, unless the 173 **BC_EXPR_EXIT** is defined (see the **ENVIRONMENT VARIABLES** section). 174 175 This is a **non-portable extension**. 176 177**-f** *file*, **--file**=*file* 178 179: Reads in *file* and evaluates it, line by line, as though it were read 180 through **stdin**. If expressions are also given (see above), the 181 expressions are evaluated in the order given. 182 183 In other bc(1) implementations, this option causes the program to execute 184 the files and then exit. This bc(1) does not, unless the 185 **BC_EXPR_EXIT** is defined (see the **ENVIRONMENT VARIABLES** section). 186 187 This is a **non-portable extension**. 188 189All long options are **non-portable extensions**. 190 191# STDOUT 192 193Any non-error output is written to **stdout**. 194 195**Note**: Unlike other bc(1) implementations, this bc(1) will issue a fatal 196error (see the **EXIT STATUS** section) if it cannot write to **stdout**, so if 197**stdout** is closed, as in **bc <file> >&-**, it will quit with an error. This 198is done so that bc(1) can report problems when **stdout** is redirected to a 199file. 200 201If there are scripts that depend on the behavior of other bc(1) implementations, 202it is recommended that those scripts be changed to redirect **stdout** to 203**/dev/null**. 204 205# STDERR 206 207Any error output is written to **stderr**. 208 209**Note**: Unlike other bc(1) implementations, this bc(1) will issue a fatal 210error (see the **EXIT STATUS** section) if it cannot write to **stderr**, so if 211**stderr** is closed, as in **bc <file> 2>&-**, it will quit with an error. This 212is done so that bc(1) can exit with an error code when **stderr** is redirected 213to a file. 214 215If there are scripts that depend on the behavior of other bc(1) implementations, 216it is recommended that those scripts be changed to redirect **stderr** to 217**/dev/null**. 218 219# SYNTAX 220 221The syntax for bc(1) programs is mostly C-like, with some differences. This 222bc(1) follows the [POSIX standard][1], which is a much more thorough resource 223for the language this bc(1) accepts. This section is meant to be a summary and a 224listing of all the extensions to the standard. 225 226In the sections below, **E** means expression, **S** means statement, and **I** 227means identifier. 228 229Identifiers (**I**) start with a lowercase letter and can be followed by any 230number (up to **BC_NAME_MAX-1**) of lowercase letters (**a-z**), digits 231(**0-9**), and underscores (**\_**). The regex is **\[a-z\]\[a-z0-9\_\]\***. 232Identifiers with more than one character (letter) are a 233**non-portable extension**. 234 235**ibase** is a global variable determining how to interpret constant numbers. It 236is the "input" base, or the number base used for interpreting input numbers. 237**ibase** is initially **10**. If the **-s** (**--standard**) and **-w** 238(**--warn**) flags were not given on the command line, the max allowable value 239for **ibase** is **36**. Otherwise, it is **16**. The min allowable value for 240**ibase** is **2**. The max allowable value for **ibase** can be queried in 241bc(1) programs with the **maxibase()** built-in function. 242 243**obase** is a global variable determining how to output results. It is the 244"output" base, or the number base used for outputting numbers. **obase** is 245initially **10**. The max allowable value for **obase** is **BC_BASE_MAX** and 246can be queried in bc(1) programs with the **maxobase()** built-in function. The 247min allowable value for **obase** is **2**. Values are output in the specified 248base. 249 250The *scale* of an expression is the number of digits in the result of the 251expression right of the decimal point, and **scale** is a global variable that 252sets the precision of any operations, with exceptions. **scale** is initially 253**0**. **scale** cannot be negative. The max allowable value for **scale** is 254**BC_SCALE_MAX** and can be queried in bc(1) programs with the **maxscale()** 255built-in function. 256 257bc(1) has both *global* variables and *local* variables. All *local* 258variables are local to the function; they are parameters or are introduced in 259the **auto** list of a function (see the **FUNCTIONS** section). If a variable 260is accessed which is not a parameter or in the **auto** list, it is assumed to 261be *global*. If a parent function has a *local* variable version of a variable 262that a child function considers *global*, the value of that *global* variable in 263the child function is the value of the variable in the parent function, not the 264value of the actual *global* variable. 265 266All of the above applies to arrays as well. 267 268The value of a statement that is an expression (i.e., any of the named 269expressions or operands) is printed unless the lowest precedence operator is an 270assignment operator *and* the expression is notsurrounded by parentheses. 271 272The value that is printed is also assigned to the special variable **last**. A 273single dot (**.**) may also be used as a synonym for **last**. These are 274**non-portable extensions**. 275 276Either semicolons or newlines may separate statements. 277 278## Comments 279 280There are two kinds of comments: 281 2821. Block comments are enclosed in **/\*** and **\*/**. 2832. Line comments go from **#** until, and not including, the next newline. This 284 is a **non-portable extension**. 285 286## Named Expressions 287 288The following are named expressions in bc(1): 289 2901. Variables: **I** 2912. Array Elements: **I[E]** 2923. **ibase** 2934. **obase** 2945. **scale** 2956. **last** or a single dot (**.**) 296 297Number 6 is a **non-portable extension**. 298 299Variables and arrays do not interfere; users can have arrays named the same as 300variables. This also applies to functions (see the **FUNCTIONS** section), so a 301user can have a variable, array, and function that all have the same name, and 302they will not shadow each other, whether inside of functions or not. 303 304Named expressions are required as the operand of **increment**/**decrement** 305operators and as the left side of **assignment** operators (see the *Operators* 306subsection). 307 308## Operands 309 310The following are valid operands in bc(1): 311 3121. Numbers (see the *Numbers* subsection below). 3132. Array indices (**I[E]**). 3143. **(E)**: The value of **E** (used to change precedence). 3154. **sqrt(E)**: The square root of **E**. **E** must be non-negative. 3165. **length(E)**: The number of significant decimal digits in **E**. 3176. **length(I[])**: The number of elements in the array **I**. This is a 318 **non-portable extension**. 3197. **scale(E)**: The *scale* of **E**. 3208. **abs(E)**: The absolute value of **E**. This is a **non-portable 321 extension**. 3229. **I()**, **I(E)**, **I(E, E)**, and so on, where **I** is an identifier for 323 a non-**void** function (see the *Void Functions* subsection of the 324 **FUNCTIONS** section). The **E** argument(s) may also be arrays of the form 325 **I[]**, which will automatically be turned into array references (see the 326 *Array References* subsection of the **FUNCTIONS** section) if the 327 corresponding parameter in the function definition is an array reference. 32810. **read()**: Reads a line from **stdin** and uses that as an expression. The 329 result of that expression is the result of the **read()** operand. This is a 330 **non-portable extension**. 33111. **maxibase()**: The max allowable **ibase**. This is a **non-portable 332 extension**. 33312. **maxobase()**: The max allowable **obase**. This is a **non-portable 334 extension**. 33513. **maxscale()**: The max allowable **scale**. This is a **non-portable 336 extension**. 337 338## Numbers 339 340Numbers are strings made up of digits, uppercase letters, and at most **1** 341period for a radix. Numbers can have up to **BC_NUM_MAX** digits. Uppercase 342letters are equal to **9** + their position in the alphabet (i.e., **A** equals 343**10**, or **9+1**). If a digit or letter makes no sense with the current value 344of **ibase**, they are set to the value of the highest valid digit in **ibase**. 345 346Single-character numbers (i.e., **A** alone) take the value that they would have 347if they were valid digits, regardless of the value of **ibase**. This means that 348**A** alone always equals decimal **10** and **Z** alone always equals decimal 349**35**. 350 351## Operators 352 353The following arithmetic and logical operators can be used. They are listed in 354order of decreasing precedence. Operators in the same group have the same 355precedence. 356 357**++** **--** 358 359: Type: Prefix and Postfix 360 361 Associativity: None 362 363 Description: **increment**, **decrement** 364 365**-** **!** 366 367: Type: Prefix 368 369 Associativity: None 370 371 Description: **negation**, **boolean not** 372 373**\^** 374 375: Type: Binary 376 377 Associativity: Right 378 379 Description: **power** 380 381**\*** **/** **%** 382 383: Type: Binary 384 385 Associativity: Left 386 387 Description: **multiply**, **divide**, **modulus** 388 389**+** **-** 390 391: Type: Binary 392 393 Associativity: Left 394 395 Description: **add**, **subtract** 396 397**=** **+=** **-=** **\*=** **/=** **%=** **\^=** 398 399: Type: Binary 400 401 Associativity: Right 402 403 Description: **assignment** 404 405**==** **\<=** **\>=** **!=** **\<** **\>** 406 407: Type: Binary 408 409 Associativity: Left 410 411 Description: **relational** 412 413**&&** 414 415: Type: Binary 416 417 Associativity: Left 418 419 Description: **boolean and** 420 421**||** 422 423: Type: Binary 424 425 Associativity: Left 426 427 Description: **boolean or** 428 429The operators will be described in more detail below. 430 431**++** **--** 432 433: The prefix and postfix **increment** and **decrement** operators behave 434 exactly like they would in C. They require a named expression (see the 435 *Named Expressions* subsection) as an operand. 436 437 The prefix versions of these operators are more efficient; use them where 438 possible. 439 440**-** 441 442: The **negation** operator returns **0** if a user attempts to negate any 443 expression with the value **0**. Otherwise, a copy of the expression with 444 its sign flipped is returned. 445 446**!** 447 448: The **boolean not** operator returns **1** if the expression is **0**, or 449 **0** otherwise. 450 451 This is a **non-portable extension**. 452 453**\^** 454 455: The **power** operator (not the **exclusive or** operator, as it would be in 456 C) takes two expressions and raises the first to the power of the value of 457 the second. 458 459 The second expression must be an integer (no *scale*), and if it is 460 negative, the first value must be non-zero. 461 462**\*** 463 464: The **multiply** operator takes two expressions, multiplies them, and 465 returns the product. If **a** is the *scale* of the first expression and 466 **b** is the *scale* of the second expression, the *scale* of the result is 467 equal to **min(a+b,max(scale,a,b))** where **min()** and **max()** return 468 the obvious values. 469 470**/** 471 472: The **divide** operator takes two expressions, divides them, and returns the 473 quotient. The *scale* of the result shall be the value of **scale**. 474 475 The second expression must be non-zero. 476 477**%** 478 479: The **modulus** operator takes two expressions, **a** and **b**, and 480 evaluates them by 1) Computing **a/b** to current **scale** and 2) Using the 481 result of step 1 to calculate **a-(a/b)\*b** to *scale* 482 **max(scale+scale(b),scale(a))**. 483 484 The second expression must be non-zero. 485 486**+** 487 488: The **add** operator takes two expressions, **a** and **b**, and returns the 489 sum, with a *scale* equal to the max of the *scale*s of **a** and **b**. 490 491**-** 492 493: The **subtract** operator takes two expressions, **a** and **b**, and 494 returns the difference, with a *scale* equal to the max of the *scale*s of 495 **a** and **b**. 496 497**=** **+=** **-=** **\*=** **/=** **%=** **\^=** 498 499: The **assignment** operators take two expressions, **a** and **b** where 500 **a** is a named expression (see the *Named Expressions* subsection). 501 502 For **=**, **b** is copied and the result is assigned to **a**. For all 503 others, **a** and **b** are applied as operands to the corresponding 504 arithmetic operator and the result is assigned to **a**. 505 506**==** **\<=** **\>=** **!=** **\<** **\>** 507 508: The **relational** operators compare two expressions, **a** and **b**, and 509 if the relation holds, according to C language semantics, the result is 510 **1**. Otherwise, it is **0**. 511 512 Note that unlike in C, these operators have a lower precedence than the 513 **assignment** operators, which means that **a=b\>c** is interpreted as 514 **(a=b)\>c**. 515 516 Also, unlike the [standard][1] requires, these operators can appear anywhere 517 any other expressions can be used. This allowance is a 518 **non-portable extension**. 519 520**&&** 521 522: The **boolean and** operator takes two expressions and returns **1** if both 523 expressions are non-zero, **0** otherwise. 524 525 This is *not* a short-circuit operator. 526 527 This is a **non-portable extension**. 528 529**||** 530 531: The **boolean or** operator takes two expressions and returns **1** if one 532 of the expressions is non-zero, **0** otherwise. 533 534 This is *not* a short-circuit operator. 535 536 This is a **non-portable extension**. 537 538## Statements 539 540The following items are statements: 541 5421. **E** 5432. **{** **S** **;** ... **;** **S** **}** 5443. **if** **(** **E** **)** **S** 5454. **if** **(** **E** **)** **S** **else** **S** 5465. **while** **(** **E** **)** **S** 5476. **for** **(** **E** **;** **E** **;** **E** **)** **S** 5487. An empty statement 5498. **break** 5509. **continue** 55110. **quit** 55211. **halt** 55312. **limits** 55413. A string of characters, enclosed in double quotes 55514. **print** **E** **,** ... **,** **E** 55615. **I()**, **I(E)**, **I(E, E)**, and so on, where **I** is an identifier for 557 a **void** function (see the *Void Functions* subsection of the 558 **FUNCTIONS** section). The **E** argument(s) may also be arrays of the form 559 **I[]**, which will automatically be turned into array references (see the 560 *Array References* subsection of the **FUNCTIONS** section) if the 561 corresponding parameter in the function definition is an array reference. 562 563Numbers 4, 9, 11, 12, 14, and 15 are **non-portable extensions**. 564 565Also, as a **non-portable extension**, any or all of the expressions in the 566header of a for loop may be omitted. If the condition (second expression) is 567omitted, it is assumed to be a constant **1**. 568 569The **break** statement causes a loop to stop iterating and resume execution 570immediately following a loop. This is only allowed in loops. 571 572The **continue** statement causes a loop iteration to stop early and returns to 573the start of the loop, including testing the loop condition. This is only 574allowed in loops. 575 576The **if** **else** statement does the same thing as in C. 577 578The **quit** statement causes bc(1) to quit, even if it is on a branch that will 579not be executed (it is a compile-time command). 580 581The **halt** statement causes bc(1) to quit, if it is executed. (Unlike **quit** 582if it is on a branch of an **if** statement that is not executed, bc(1) does not 583quit.) 584 585The **limits** statement prints the limits that this bc(1) is subject to. This 586is like the **quit** statement in that it is a compile-time command. 587 588An expression by itself is evaluated and printed, followed by a newline. 589 590## Print Statement 591 592The "expressions" in a **print** statement may also be strings. If they are, there 593are backslash escape sequences that are interpreted specially. What those 594sequences are, and what they cause to be printed, are shown below: 595 596-------- ------- 597**\\a** **\\a** 598**\\b** **\\b** 599**\\\\** **\\** 600**\\e** **\\** 601**\\f** **\\f** 602**\\n** **\\n** 603**\\q** **"** 604**\\r** **\\r** 605**\\t** **\\t** 606-------- ------- 607 608Any other character following a backslash causes the backslash and character to 609be printed as-is. 610 611Any non-string expression in a print statement shall be assigned to **last**, 612like any other expression that is printed. 613 614## Order of Evaluation 615 616All expressions in a statment are evaluated left to right, except as necessary 617to maintain order of operations. This means, for example, assuming that **i** is 618equal to **0**, in the expression 619 620 a[i++] = i++ 621 622the first (or 0th) element of **a** is set to **1**, and **i** is equal to **2** 623at the end of the expression. 624 625This includes function arguments. Thus, assuming **i** is equal to **0**, this 626means that in the expression 627 628 x(i++, i++) 629 630the first argument passed to **x()** is **0**, and the second argument is **1**, 631while **i** is equal to **2** before the function starts executing. 632 633# FUNCTIONS 634 635Function definitions are as follows: 636 637``` 638define I(I,...,I){ 639 auto I,...,I 640 S;...;S 641 return(E) 642} 643``` 644 645Any **I** in the parameter list or **auto** list may be replaced with **I[]** to 646make a parameter or **auto** var an array, and any **I** in the parameter list 647may be replaced with **\*I[]** to make a parameter an array reference. Callers 648of functions that take array references should not put an asterisk in the call; 649they must be called with just **I[]** like normal array parameters and will be 650automatically converted into references. 651 652As a **non-portable extension**, the opening brace of a **define** statement may 653appear on the next line. 654 655As a **non-portable extension**, the return statement may also be in one of the 656following forms: 657 6581. **return** 6592. **return** **(** **)** 6603. **return** **E** 661 662The first two, or not specifying a **return** statement, is equivalent to 663**return (0)**, unless the function is a **void** function (see the *Void 664Functions* subsection below). 665 666## Void Functions 667 668Functions can also be **void** functions, defined as follows: 669 670``` 671define void I(I,...,I){ 672 auto I,...,I 673 S;...;S 674 return 675} 676``` 677 678They can only be used as standalone expressions, where such an expression would 679be printed alone, except in a print statement. 680 681Void functions can only use the first two **return** statements listed above. 682They can also omit the return statement entirely. 683 684The word "void" is not treated as a keyword; it is still possible to have 685variables, arrays, and functions named **void**. The word "void" is only 686treated specially right after the **define** keyword. 687 688This is a **non-portable extension**. 689 690## Array References 691 692For any array in the parameter list, if the array is declared in the form 693 694``` 695*I[] 696``` 697 698it is a **reference**. Any changes to the array in the function are reflected, 699when the function returns, to the array that was passed in. 700 701Other than this, all function arguments are passed by value. 702 703This is a **non-portable extension**. 704 705# LIBRARY 706 707All of the functions below are available when the **-l** or **--mathlib** 708command-line flags are given. 709 710## Standard Library 711 712The [standard][1] defines the following functions for the math library: 713 714**s(x)** 715 716: Returns the sine of **x**, which is assumed to be in radians. 717 718 This is a transcendental function (see the *Transcendental Functions* 719 subsection below). 720 721**c(x)** 722 723: Returns the cosine of **x**, which is assumed to be in radians. 724 725 This is a transcendental function (see the *Transcendental Functions* 726 subsection below). 727 728**a(x)** 729 730: Returns the arctangent of **x**, in radians. 731 732 This is a transcendental function (see the *Transcendental Functions* 733 subsection below). 734 735**l(x)** 736 737: Returns the natural logarithm of **x**. 738 739 This is a transcendental function (see the *Transcendental Functions* 740 subsection below). 741 742**e(x)** 743 744: Returns the mathematical constant **e** raised to the power of **x**. 745 746 This is a transcendental function (see the *Transcendental Functions* 747 subsection below). 748 749**j(x, n)** 750 751: Returns the bessel integer order **n** (truncated) of **x**. 752 753 This is a transcendental function (see the *Transcendental Functions* 754 subsection below). 755 756## Transcendental Functions 757 758All transcendental functions can return slightly inaccurate results (up to 1 759[ULP][4]). This is unavoidable, and [this article][5] explains why it is 760impossible and unnecessary to calculate exact results for the transcendental 761functions. 762 763Because of the possible inaccuracy, I recommend that users call those functions 764with the precision (**scale**) set to at least 1 higher than is necessary. If 765exact results are *absolutely* required, users can double the precision 766(**scale**) and then truncate. 767 768The transcendental functions in the standard math library are: 769 770* **s(x)** 771* **c(x)** 772* **a(x)** 773* **l(x)** 774* **e(x)** 775* **j(x, n)** 776 777# RESET 778 779When bc(1) encounters an error or a signal that it has a non-default handler 780for, it resets. This means that several things happen. 781 782First, any functions that are executing are stopped and popped off the stack. 783The behavior is not unlike that of exceptions in programming languages. Then 784the execution point is set so that any code waiting to execute (after all 785functions returned) is skipped. 786 787Thus, when bc(1) resets, it skips any remaining code waiting to be executed. 788Then, if it is interactive mode, and the error was not a fatal error (see the 789**EXIT STATUS** section), it asks for more input; otherwise, it exits with the 790appropriate return code. 791 792Note that this reset behavior is different from the GNU bc(1), which attempts to 793start executing the statement right after the one that caused an error. 794 795# PERFORMANCE 796 797Most bc(1) implementations use **char** types to calculate the value of **1** 798decimal digit at a time, but that can be slow. This bc(1) does something 799different. 800 801It uses large integers to calculate more than **1** decimal digit at a time. If 802built in a environment where **BC_LONG_BIT** (see the **LIMITS** section) is 803**64**, then each integer has **9** decimal digits. If built in an environment 804where **BC_LONG_BIT** is **32** then each integer has **4** decimal digits. This 805value (the number of decimal digits per large integer) is called 806**BC_BASE_DIGS**. 807 808The actual values of **BC_LONG_BIT** and **BC_BASE_DIGS** can be queried with 809the **limits** statement. 810 811In addition, this bc(1) uses an even larger integer for overflow checking. This 812integer type depends on the value of **BC_LONG_BIT**, but is always at least 813twice as large as the integer type used to store digits. 814 815# LIMITS 816 817The following are the limits on bc(1): 818 819**BC_LONG_BIT** 820 821: The number of bits in the **long** type in the environment where bc(1) was 822 built. This determines how many decimal digits can be stored in a single 823 large integer (see the **PERFORMANCE** section). 824 825**BC_BASE_DIGS** 826 827: The number of decimal digits per large integer (see the **PERFORMANCE** 828 section). Depends on **BC_LONG_BIT**. 829 830**BC_BASE_POW** 831 832: The max decimal number that each large integer can store (see 833 **BC_BASE_DIGS**) plus **1**. Depends on **BC_BASE_DIGS**. 834 835**BC_OVERFLOW_MAX** 836 837: The max number that the overflow type (see the **PERFORMANCE** section) can 838 hold. Depends on **BC_LONG_BIT**. 839 840**BC_BASE_MAX** 841 842: The maximum output base. Set at **BC_BASE_POW**. 843 844**BC_DIM_MAX** 845 846: The maximum size of arrays. Set at **SIZE_MAX-1**. 847 848**BC_SCALE_MAX** 849 850: The maximum **scale**. Set at **BC_OVERFLOW_MAX-1**. 851 852**BC_STRING_MAX** 853 854: The maximum length of strings. Set at **BC_OVERFLOW_MAX-1**. 855 856**BC_NAME_MAX** 857 858: The maximum length of identifiers. Set at **BC_OVERFLOW_MAX-1**. 859 860**BC_NUM_MAX** 861 862: The maximum length of a number (in decimal digits), which includes digits 863 after the decimal point. Set at **BC_OVERFLOW_MAX-1**. 864 865Exponent 866 867: The maximum allowable exponent (positive or negative). Set at 868 **BC_OVERFLOW_MAX**. 869 870Number of vars 871 872: The maximum number of vars/arrays. Set at **SIZE_MAX-1**. 873 874The actual values can be queried with the **limits** statement. 875 876These limits are meant to be effectively non-existent; the limits are so large 877(at least on 64-bit machines) that there should not be any point at which they 878become a problem. In fact, memory should be exhausted before these limits should 879be hit. 880 881# ENVIRONMENT VARIABLES 882 883bc(1) recognizes the following environment variables: 884 885**POSIXLY_CORRECT** 886 887: If this variable exists (no matter the contents), bc(1) behaves as if 888 the **-s** option was given. 889 890**BC_ENV_ARGS** 891 892: This is another way to give command-line arguments to bc(1). They should be 893 in the same format as all other command-line arguments. These are always 894 processed first, so any files given in **BC_ENV_ARGS** will be processed 895 before arguments and files given on the command-line. This gives the user 896 the ability to set up "standard" options and files to be used at every 897 invocation. The most useful thing for such files to contain would be useful 898 functions that the user might want every time bc(1) runs. 899 900 The code that parses **BC_ENV_ARGS** will correctly handle quoted arguments, 901 but it does not understand escape sequences. For example, the string 902 **"/home/gavin/some bc file.bc"** will be correctly parsed, but the string 903 **"/home/gavin/some \"bc\" file.bc"** will include the backslashes. 904 905 The quote parsing will handle either kind of quotes, **'** or **"**. Thus, 906 if you have a file with any number of single quotes in the name, you can use 907 double quotes as the outside quotes, as in **"some 'bc' file.bc"**, and vice 908 versa if you have a file with double quotes. However, handling a file with 909 both kinds of quotes in **BC_ENV_ARGS** is not supported due to the 910 complexity of the parsing, though such files are still supported on the 911 command-line where the parsing is done by the shell. 912 913**BC_LINE_LENGTH** 914 915: If this environment variable exists and contains an integer that is greater 916 than **1** and is less than **UINT16_MAX** (**2\^16-1**), bc(1) will output 917 lines to that length, including the backslash (**\\**). The default line 918 length is **70**. 919 920**BC_EXPR_EXIT** 921 922: If this variable exists (no matter the contents), bc(1) will exit 923 immediately after executing expressions and files given by the **-e** and/or 924 **-f** command-line options (and any equivalents). 925 926# EXIT STATUS 927 928bc(1) returns the following exit statuses: 929 930**0** 931 932: No error. 933 934**1** 935 936: A math error occurred. This follows standard practice of using **1** for 937 expected errors, since math errors will happen in the process of normal 938 execution. 939 940 Math errors include divide by **0**, taking the square root of a negative 941 number, attempting to convert a negative number to a hardware integer, 942 overflow when converting a number to a hardware integer, and attempting to 943 use a non-integer where an integer is required. 944 945 Converting to a hardware integer happens for the second operand of the power 946 (**\^**) operator and the corresponding assignment operator. 947 948**2** 949 950: A parse error occurred. 951 952 Parse errors include unexpected **EOF**, using an invalid character, failing 953 to find the end of a string or comment, using a token where it is invalid, 954 giving an invalid expression, giving an invalid print statement, giving an 955 invalid function definition, attempting to assign to an expression that is 956 not a named expression (see the *Named Expressions* subsection of the 957 **SYNTAX** section), giving an invalid **auto** list, having a duplicate 958 **auto**/function parameter, failing to find the end of a code block, 959 attempting to return a value from a **void** function, attempting to use a 960 variable as a reference, and using any extensions when the option **-s** or 961 any equivalents were given. 962 963**3** 964 965: A runtime error occurred. 966 967 Runtime errors include assigning an invalid number to **ibase**, **obase**, 968 or **scale**; give a bad expression to a **read()** call, calling **read()** 969 inside of a **read()** call, type errors, passing the wrong number of 970 arguments to functions, attempting to call an undefined function, and 971 attempting to use a **void** function call as a value in an expression. 972 973**4** 974 975: A fatal error occurred. 976 977 Fatal errors include memory allocation errors, I/O errors, failing to open 978 files, attempting to use files that do not have only ASCII characters (bc(1) 979 only accepts ASCII characters), attempting to open a directory as a file, 980 and giving invalid command-line options. 981 982The exit status **4** is special; when a fatal error occurs, bc(1) always exits 983and returns **4**, no matter what mode bc(1) is in. 984 985The other statuses will only be returned when bc(1) is not in interactive mode 986(see the **INTERACTIVE MODE** section), since bc(1) resets its state (see the 987**RESET** section) and accepts more input when one of those errors occurs in 988interactive mode. This is also the case when interactive mode is forced by the 989**-i** flag or **--interactive** option. 990 991These exit statuses allow bc(1) to be used in shell scripting with error 992checking, and its normal behavior can be forced by using the **-i** flag or 993**--interactive** option. 994 995# INTERACTIVE MODE 996 997Per the [standard][1], bc(1) has an interactive mode and a non-interactive mode. 998Interactive mode is turned on automatically when both **stdin** and **stdout** 999are hooked to a terminal, but the **-i** flag and **--interactive** option can 1000turn it on in other cases. 1001 1002In interactive mode, bc(1) attempts to recover from errors (see the **RESET** 1003section), and in normal execution, flushes **stdout** as soon as execution is 1004done for the current input. 1005 1006# TTY MODE 1007 1008If **stdin**, **stdout**, and **stderr** are all connected to a TTY, bc(1) turns 1009on "TTY mode." 1010 1011The prompt is enabled in TTY mode. 1012 1013TTY mode is different from interactive mode because interactive mode is required 1014in the [bc(1) specification][1], and interactive mode requires only **stdin** 1015and **stdout** to be connected to a terminal. 1016 1017# SIGNAL HANDLING 1018 1019Sending a **SIGINT** will cause bc(1) to stop execution of the current input. If 1020bc(1) is in TTY mode (see the **TTY MODE** section), it will reset (see the 1021**RESET** section). Otherwise, it will clean up and exit. 1022 1023Note that "current input" can mean one of two things. If bc(1) is processing 1024input from **stdin** in TTY mode, it will ask for more input. If bc(1) is 1025processing input from a file in TTY mode, it will stop processing the file and 1026start processing the next file, if one exists, or ask for input from **stdin** 1027if no other file exists. 1028 1029This means that if a **SIGINT** is sent to bc(1) as it is executing a file, it 1030can seem as though bc(1) did not respond to the signal since it will immediately 1031start executing the next file. This is by design; most files that users execute 1032when interacting with bc(1) have function definitions, which are quick to parse. 1033If a file takes a long time to execute, there may be a bug in that file. The 1034rest of the files could still be executed without problem, allowing the user to 1035continue. 1036 1037**SIGTERM** and **SIGQUIT** cause bc(1) to clean up and exit, and it uses the 1038default handler for all other signals. 1039 1040# SEE ALSO 1041 1042dc(1) 1043 1044# STANDARDS 1045 1046bc(1) is compliant with the [IEEE Std 1003.1-2017 (“POSIX.1-2017”)][1] 1047specification. The flags **-efghiqsvVw**, all long options, and the extensions 1048noted above are extensions to that specification. 1049 1050Note that the specification explicitly says that bc(1) only accepts numbers that 1051use a period (**.**) as a radix point, regardless of the value of 1052**LC_NUMERIC**. 1053 1054# BUGS 1055 1056None are known. Report bugs at https://git.yzena.com/gavin/bc. 1057 1058# AUTHORS 1059 1060Gavin D. Howard <yzena.tech@gmail.com> and contributors. 1061 1062[1]: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html 1063[2]: https://www.gnu.org/software/bc/ 1064[3]: https://en.wikipedia.org/wiki/Rounding#Round_half_away_from_zero 1065[4]: https://en.wikipedia.org/wiki/Unit_in_the_last_place 1066[5]: https://people.eecs.berkeley.edu/~wkahan/LOG10HAF.TXT 1067[6]: https://en.wikipedia.org/wiki/Rounding#Rounding_away_from_zero 1068