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