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**, **scale**, and **seed** into stacks. 57 58 This has the effect that a copy of the current value of all four 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 (**Note**: the function **output(x,b)** exists in the extended math library. 83 See the **LIBRARY** section.) 84 85 However, since using this flag means that functions cannot set **ibase**, 86 **obase**, **scale**, or **seed** globally, functions that are made to do so 87 cannot work anymore. There are two possible use cases for that, and each has 88 a 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**, 98 **scale**, or **seed** globally for any other purpose, it could be split 99 into one to four functions (based on how many globals it sets) and each of 100 those functions could return the desired value for a global. 101 102 For functions that set **seed**, the value assigned to **seed** is not 103 propagated to parent functions. This means that the sequence of 104 pseudo-random numbers that they see will not be the same sequence of 105 pseudo-random numbers that any parent sees. This is only the case once 106 **seed** has been set. 107 108 If a function desires to not affect the sequence of pseudo-random numbers 109 of its parents, but wants to use the same **seed**, it can use the following 110 line: 111 112 seed = seed 113 114 If the behavior of this option is desired for every run of bc(1), then users 115 could make sure to define **BC_ENV_ARGS** and include this option (see the 116 **ENVIRONMENT VARIABLES** section for more details). 117 118 If **-s**, **-w**, or any equivalents are used, this option is ignored. 119 120 This is a **non-portable extension**. 121 122**-h**, **--help** 123 124: Prints a usage message and quits. 125 126**-i**, **--interactive** 127 128: Forces interactive mode. (See the **INTERACTIVE MODE** section.) 129 130 This is a **non-portable extension**. 131 132**-l**, **--mathlib** 133 134: Sets **scale** (see the **SYNTAX** section) to **20** and loads the included 135 math library and the extended math library before running any code, 136 including any expressions or files specified on the command line. 137 138 To learn what is in the libraries, see the **LIBRARY** section. 139 140**-P**, **--no-prompt** 141 142: Disables the prompt in TTY mode. (The prompt is only enabled in TTY mode. 143 See the **TTY MODE** section) This is mostly for those users that do not 144 want a prompt or are not used to having them in bc(1). Most of those users 145 would want to put this option in **BC_ENV_ARGS** (see the 146 **ENVIRONMENT VARIABLES** section). 147 148 This is a **non-portable extension**. 149 150**-q**, **--quiet** 151 152: Do not print copyright header. bc(1) will also suppress the header in 153 non-interactive mode. 154 155 This is mostly for compatibility with the [GNU bc(1)][2]. 156 157 This is a **non-portable extension**. 158 159**-s**, **--standard** 160 161: Process exactly the language defined by the [standard][1] and error if any 162 extensions are used. 163 164 This is a **non-portable extension**. 165 166**-v**, **-V**, **--version** 167 168: Print the version information (copyright header) and exit. 169 170 This is a **non-portable extension**. 171 172**-w**, **--warn** 173 174: Like **-s** and **--standard**, except that warnings (and not errors) are 175 printed for non-standard extensions and execution continues normally. 176 177 This is a **non-portable extension**. 178 179**-e** *expr*, **--expression**=*expr* 180 181: Evaluates *expr*. If multiple expressions are given, they are evaluated in 182 order. If files are given as well (see below), the expressions and files are 183 evaluated in the order given. This means that if a file is given before an 184 expression, the file is read in and evaluated first. 185 186 In other bc(1) implementations, this option causes the program to execute 187 the expressions and then exit. This bc(1) does not, unless the 188 **BC_EXPR_EXIT** is defined (see the **ENVIRONMENT VARIABLES** section). 189 190 This is a **non-portable extension**. 191 192**-f** *file*, **--file**=*file* 193 194: Reads in *file* and evaluates it, line by line, as though it were read 195 through **stdin**. If expressions are also given (see above), the 196 expressions are evaluated in the order given. 197 198 In other bc(1) implementations, this option causes the program to execute 199 the files and then exit. This bc(1) does not, unless the 200 **BC_EXPR_EXIT** is defined (see the **ENVIRONMENT VARIABLES** section). 201 202 This is a **non-portable extension**. 203 204All long options are **non-portable extensions**. 205 206# STDOUT 207 208Any non-error output is written to **stdout**. 209 210**Note**: Unlike other bc(1) implementations, this bc(1) will issue a fatal 211error (see the **EXIT STATUS** section) if it cannot write to **stdout**, so if 212**stdout** is closed, as in **bc <file> >&-**, it will quit with an error. This 213is done so that bc(1) can report problems when **stdout** is redirected to a 214file. 215 216If there are scripts that depend on the behavior of other bc(1) implementations, 217it is recommended that those scripts be changed to redirect **stdout** to 218**/dev/null**. 219 220# STDERR 221 222Any error output is written to **stderr**. 223 224**Note**: Unlike other bc(1) implementations, this bc(1) will issue a fatal 225error (see the **EXIT STATUS** section) if it cannot write to **stderr**, so if 226**stderr** is closed, as in **bc <file> 2>&-**, it will quit with an error. This 227is done so that bc(1) can exit with an error code when **stderr** is redirected 228to a file. 229 230If there are scripts that depend on the behavior of other bc(1) implementations, 231it is recommended that those scripts be changed to redirect **stderr** to 232**/dev/null**. 233 234# SYNTAX 235 236The syntax for bc(1) programs is mostly C-like, with some differences. This 237bc(1) follows the [POSIX standard][1], which is a much more thorough resource 238for the language this bc(1) accepts. This section is meant to be a summary and a 239listing of all the extensions to the standard. 240 241In the sections below, **E** means expression, **S** means statement, and **I** 242means identifier. 243 244Identifiers (**I**) start with a lowercase letter and can be followed by any 245number (up to **BC_NAME_MAX-1**) of lowercase letters (**a-z**), digits 246(**0-9**), and underscores (**\_**). The regex is **\[a-z\]\[a-z0-9\_\]\***. 247Identifiers with more than one character (letter) are a 248**non-portable extension**. 249 250**ibase** is a global variable determining how to interpret constant numbers. It 251is the "input" base, or the number base used for interpreting input numbers. 252**ibase** is initially **10**. If the **-s** (**--standard**) and **-w** 253(**--warn**) flags were not given on the command line, the max allowable value 254for **ibase** is **36**. Otherwise, it is **16**. The min allowable value for 255**ibase** is **2**. The max allowable value for **ibase** can be queried in 256bc(1) programs with the **maxibase()** built-in function. 257 258**obase** is a global variable determining how to output results. It is the 259"output" base, or the number base used for outputting numbers. **obase** is 260initially **10**. The max allowable value for **obase** is **BC_BASE_MAX** and 261can be queried in bc(1) programs with the **maxobase()** built-in function. The 262min allowable value for **obase** is **0**. If **obase** is **0**, values are 263output in scientific notation, and if **obase** is **1**, values are output in 264engineering notation. Otherwise, values are output in the specified base. 265 266Outputting in scientific and engineering notations are **non-portable 267extensions**. 268 269The *scale* of an expression is the number of digits in the result of the 270expression right of the decimal point, and **scale** is a global variable that 271sets the precision of any operations, with exceptions. **scale** is initially 272**0**. **scale** cannot be negative. The max allowable value for **scale** is 273**BC_SCALE_MAX** and can be queried in bc(1) programs with the **maxscale()** 274built-in function. 275 276bc(1) has both *global* variables and *local* variables. All *local* 277variables are local to the function; they are parameters or are introduced in 278the **auto** list of a function (see the **FUNCTIONS** section). If a variable 279is accessed which is not a parameter or in the **auto** list, it is assumed to 280be *global*. If a parent function has a *local* variable version of a variable 281that a child function considers *global*, the value of that *global* variable in 282the child function is the value of the variable in the parent function, not the 283value of the actual *global* variable. 284 285All of the above applies to arrays as well. 286 287The value of a statement that is an expression (i.e., any of the named 288expressions or operands) is printed unless the lowest precedence operator is an 289assignment operator *and* the expression is notsurrounded by parentheses. 290 291The value that is printed is also assigned to the special variable **last**. A 292single dot (**.**) may also be used as a synonym for **last**. These are 293**non-portable extensions**. 294 295Either semicolons or newlines may separate statements. 296 297## Comments 298 299There are two kinds of comments: 300 3011. Block comments are enclosed in **/\*** and **\*/**. 3022. Line comments go from **#** until, and not including, the next newline. This 303 is a **non-portable extension**. 304 305## Named Expressions 306 307The following are named expressions in bc(1): 308 3091. Variables: **I** 3102. Array Elements: **I[E]** 3113. **ibase** 3124. **obase** 3135. **scale** 3146. **seed** 3157. **last** or a single dot (**.**) 316 317Numbers 6 and 7 are **non-portable extensions**. 318 319The meaning of **seed** is dependent on the current pseudo-random number 320generator but is guaranteed to not change except for new major versions. 321 322The *scale* and sign of the value may be significant. 323 324If a previously used **seed** value is assigned to **seed** and used again, the 325pseudo-random number generator is guaranteed to produce the same sequence of 326pseudo-random numbers as it did when the **seed** value was previously used. 327 328The exact value assigned to **seed** is not guaranteed to be returned if 329**seed** is queried again immediately. However, if **seed** *does* return a 330different value, both values, when assigned to **seed**, are guaranteed to 331produce the same sequence of pseudo-random numbers. This means that certain 332values assigned to **seed** will *not* produce unique sequences of pseudo-random 333numbers. The value of **seed** will change after any use of the **rand()** and 334**irand(E)** operands (see the *Operands* subsection below), except if the 335parameter passed to **irand(E)** is **0**, **1**, or negative. 336 337There is no limit to the length (number of significant decimal digits) or 338*scale* of the value that can be assigned to **seed**. 339 340Variables and arrays do not interfere; users can have arrays named the same as 341variables. This also applies to functions (see the **FUNCTIONS** section), so a 342user can have a variable, array, and function that all have the same name, and 343they will not shadow each other, whether inside of functions or not. 344 345Named expressions are required as the operand of **increment**/**decrement** 346operators and as the left side of **assignment** operators (see the *Operators* 347subsection). 348 349## Operands 350 351The following are valid operands in bc(1): 352 3531. Numbers (see the *Numbers* subsection below). 3542. Array indices (**I[E]**). 3553. **(E)**: The value of **E** (used to change precedence). 3564. **sqrt(E)**: The square root of **E**. **E** must be non-negative. 3575. **length(E)**: The number of significant decimal digits in **E**. 3586. **length(I[])**: The number of elements in the array **I**. This is a 359 **non-portable extension**. 3607. **scale(E)**: The *scale* of **E**. 3618. **abs(E)**: The absolute value of **E**. This is a **non-portable 362 extension**. 3639. **I()**, **I(E)**, **I(E, E)**, and so on, where **I** is an identifier for 364 a non-**void** function (see the *Void Functions* subsection of the 365 **FUNCTIONS** section). The **E** argument(s) may also be arrays of the form 366 **I[]**, which will automatically be turned into array references (see the 367 *Array References* subsection of the **FUNCTIONS** section) if the 368 corresponding parameter in the function definition is an array reference. 36910. **read()**: Reads a line from **stdin** and uses that as an expression. The 370 result of that expression is the result of the **read()** operand. This is a 371 **non-portable extension**. 37211. **maxibase()**: The max allowable **ibase**. This is a **non-portable 373 extension**. 37412. **maxobase()**: The max allowable **obase**. This is a **non-portable 375 extension**. 37613. **maxscale()**: The max allowable **scale**. This is a **non-portable 377 extension**. 37814. **rand()**: A pseudo-random integer between **0** (inclusive) and 379 **BC_RAND_MAX** (inclusive). Using this operand will change the value of 380 **seed**. This is a **non-portable extension**. 38115. **irand(E)**: A pseudo-random integer between **0** (inclusive) and the 382 value of **E** (exclusive). If **E** is negative or is a non-integer 383 (**E**'s *scale* is not **0**), an error is raised, and bc(1) resets (see 384 the **RESET** section) while **seed** remains unchanged. If **E** is larger 385 than **BC_RAND_MAX**, the higher bound is honored by generating several 386 pseudo-random integers, multiplying them by appropriate powers of 387 **BC_RAND_MAX+1**, and adding them together. Thus, the size of integer that 388 can be generated with this operand is unbounded. Using this operand will 389 change the value of **seed**, unless the value of **E** is **0** or **1**. 390 In that case, **0** is returned, and **seed** is *not* changed. This is a 391 **non-portable extension**. 39216. **maxrand()**: The max integer returned by **rand()**. This is a 393 **non-portable extension**. 394 395The integers generated by **rand()** and **irand(E)** are guaranteed to be as 396unbiased as possible, subject to the limitations of the pseudo-random number 397generator. 398 399**Note**: The values returned by the pseudo-random number generator with 400**rand()** and **irand(E)** are guaranteed to *NOT* be cryptographically secure. 401This is a consequence of using a seeded pseudo-random number generator. However, 402they *are* guaranteed to be reproducible with identical **seed** values. 403 404## Numbers 405 406Numbers are strings made up of digits, uppercase letters, and at most **1** 407period for a radix. Numbers can have up to **BC_NUM_MAX** digits. Uppercase 408letters are equal to **9** + their position in the alphabet (i.e., **A** equals 409**10**, or **9+1**). If a digit or letter makes no sense with the current value 410of **ibase**, they are set to the value of the highest valid digit in **ibase**. 411 412Single-character numbers (i.e., **A** alone) take the value that they would have 413if they were valid digits, regardless of the value of **ibase**. This means that 414**A** alone always equals decimal **10** and **Z** alone always equals decimal 415**35**. 416 417In addition, bc(1) accepts numbers in scientific notation. These have the form 418**\<number\>e\<integer\>**. The power (the portion after the **e**) must be an 419integer. An example is **1.89237e9**, which is equal to **1892370000**. Negative 420exponents are also allowed, so **4.2890e-3** is equal to **0.0042890**. 421 422Using scientific notation is an error or warning if the **-s** or **-w**, 423respectively, command-line options (or equivalents) are given. 424 425**WARNING**: Both the number and the exponent in scientific notation are 426interpreted according to the current **ibase**, but the number is still 427multiplied by **10\^exponent** regardless of the current **ibase**. For example, 428if **ibase** is **16** and bc(1) is given the number string **FFeA**, the 429resulting decimal number will be **2550000000000**, and if bc(1) is given the 430number string **10e-4**, the resulting decimal number will be **0.0016**. 431 432Accepting input as scientific notation is a **non-portable extension**. 433 434## Operators 435 436The following arithmetic and logical operators can be used. They are listed in 437order of decreasing precedence. Operators in the same group have the same 438precedence. 439 440**++** **--** 441 442: Type: Prefix and Postfix 443 444 Associativity: None 445 446 Description: **increment**, **decrement** 447 448**-** **!** 449 450: Type: Prefix 451 452 Associativity: None 453 454 Description: **negation**, **boolean not** 455 456**\$** 457 458: Type: Postfix 459 460 Associativity: None 461 462 Description: **truncation** 463 464**\@** 465 466: Type: Binary 467 468 Associativity: Right 469 470 Description: **set precision** 471 472**\^** 473 474: Type: Binary 475 476 Associativity: Right 477 478 Description: **power** 479 480**\*** **/** **%** 481 482: Type: Binary 483 484 Associativity: Left 485 486 Description: **multiply**, **divide**, **modulus** 487 488**+** **-** 489 490: Type: Binary 491 492 Associativity: Left 493 494 Description: **add**, **subtract** 495 496**\<\<** **\>\>** 497 498: Type: Binary 499 500 Associativity: Left 501 502 Description: **shift left**, **shift right** 503 504**=** **\<\<=** **\>\>=** **+=** **-=** **\*=** **/=** **%=** **\^=** **\@=** 505 506: Type: Binary 507 508 Associativity: Right 509 510 Description: **assignment** 511 512**==** **\<=** **\>=** **!=** **\<** **\>** 513 514: Type: Binary 515 516 Associativity: Left 517 518 Description: **relational** 519 520**&&** 521 522: Type: Binary 523 524 Associativity: Left 525 526 Description: **boolean and** 527 528**||** 529 530: Type: Binary 531 532 Associativity: Left 533 534 Description: **boolean or** 535 536The operators will be described in more detail below. 537 538**++** **--** 539 540: The prefix and postfix **increment** and **decrement** operators behave 541 exactly like they would in C. They require a named expression (see the 542 *Named Expressions* subsection) as an operand. 543 544 The prefix versions of these operators are more efficient; use them where 545 possible. 546 547**-** 548 549: The **negation** operator returns **0** if a user attempts to negate any 550 expression with the value **0**. Otherwise, a copy of the expression with 551 its sign flipped is returned. 552 553**!** 554 555: The **boolean not** operator returns **1** if the expression is **0**, or 556 **0** otherwise. 557 558 This is a **non-portable extension**. 559 560**\$** 561 562: The **truncation** operator returns a copy of the given expression with all 563 of its *scale* removed. 564 565 This is a **non-portable extension**. 566 567**\@** 568 569: The **set precision** operator takes two expressions and returns a copy of 570 the first with its *scale* equal to the value of the second expression. That 571 could either mean that the number is returned without change (if the 572 *scale* of the first expression matches the value of the second 573 expression), extended (if it is less), or truncated (if it is more). 574 575 The second expression must be an integer (no *scale*) and non-negative. 576 577 This is a **non-portable extension**. 578 579**\^** 580 581: The **power** operator (not the **exclusive or** operator, as it would be in 582 C) takes two expressions and raises the first to the power of the value of 583 the second. 584 585 The second expression must be an integer (no *scale*), and if it is 586 negative, the first value must be non-zero. 587 588**\*** 589 590: The **multiply** operator takes two expressions, multiplies them, and 591 returns the product. If **a** is the *scale* of the first expression and 592 **b** is the *scale* of the second expression, the *scale* of the result is 593 equal to **min(a+b,max(scale,a,b))** where **min()** and **max()** return 594 the obvious values. 595 596**/** 597 598: The **divide** operator takes two expressions, divides them, and returns the 599 quotient. The *scale* of the result shall be the value of **scale**. 600 601 The second expression must be non-zero. 602 603**%** 604 605: The **modulus** operator takes two expressions, **a** and **b**, and 606 evaluates them by 1) Computing **a/b** to current **scale** and 2) Using the 607 result of step 1 to calculate **a-(a/b)\*b** to *scale* 608 **max(scale+scale(b),scale(a))**. 609 610 The second expression must be non-zero. 611 612**+** 613 614: The **add** operator takes two expressions, **a** and **b**, and returns the 615 sum, with a *scale* equal to the max of the *scale*s of **a** and **b**. 616 617**-** 618 619: The **subtract** operator takes two expressions, **a** and **b**, and 620 returns the difference, with a *scale* equal to the max of the *scale*s of 621 **a** and **b**. 622 623**\<\<** 624 625: The **left shift** operator takes two expressions, **a** and **b**, and 626 returns a copy of the value of **a** with its decimal point moved **b** 627 places to the right. 628 629 The second expression must be an integer (no *scale*) and non-negative. 630 631 This is a **non-portable extension**. 632 633**\>\>** 634 635: The **right shift** operator takes two expressions, **a** and **b**, and 636 returns a copy of the value of **a** with its decimal point moved **b** 637 places to the left. 638 639 The second expression must be an integer (no *scale*) and non-negative. 640 641 This is a **non-portable extension**. 642 643**=** **\<\<=** **\>\>=** **+=** **-=** **\*=** **/=** **%=** **\^=** **\@=** 644 645: The **assignment** operators take two expressions, **a** and **b** where 646 **a** is a named expression (see the *Named Expressions* subsection). 647 648 For **=**, **b** is copied and the result is assigned to **a**. For all 649 others, **a** and **b** are applied as operands to the corresponding 650 arithmetic operator and the result is assigned to **a**. 651 652 The **assignment** operators that correspond to operators that are 653 extensions are themselves **non-portable extensions**. 654 655**==** **\<=** **\>=** **!=** **\<** **\>** 656 657: The **relational** operators compare two expressions, **a** and **b**, and 658 if the relation holds, according to C language semantics, the result is 659 **1**. Otherwise, it is **0**. 660 661 Note that unlike in C, these operators have a lower precedence than the 662 **assignment** operators, which means that **a=b\>c** is interpreted as 663 **(a=b)\>c**. 664 665 Also, unlike the [standard][1] requires, these operators can appear anywhere 666 any other expressions can be used. This allowance is a 667 **non-portable extension**. 668 669**&&** 670 671: The **boolean and** operator takes two expressions and returns **1** if both 672 expressions are non-zero, **0** otherwise. 673 674 This is *not* a short-circuit operator. 675 676 This is a **non-portable extension**. 677 678**||** 679 680: The **boolean or** operator takes two expressions and returns **1** if one 681 of the expressions is non-zero, **0** otherwise. 682 683 This is *not* a short-circuit operator. 684 685 This is a **non-portable extension**. 686 687## Statements 688 689The following items are statements: 690 6911. **E** 6922. **{** **S** **;** ... **;** **S** **}** 6933. **if** **(** **E** **)** **S** 6944. **if** **(** **E** **)** **S** **else** **S** 6955. **while** **(** **E** **)** **S** 6966. **for** **(** **E** **;** **E** **;** **E** **)** **S** 6977. An empty statement 6988. **break** 6999. **continue** 70010. **quit** 70111. **halt** 70212. **limits** 70313. A string of characters, enclosed in double quotes 70414. **print** **E** **,** ... **,** **E** 70515. **I()**, **I(E)**, **I(E, E)**, and so on, where **I** is an identifier for 706 a **void** function (see the *Void Functions* subsection of the 707 **FUNCTIONS** section). The **E** argument(s) may also be arrays of the form 708 **I[]**, which will automatically be turned into array references (see the 709 *Array References* subsection of the **FUNCTIONS** section) if the 710 corresponding parameter in the function definition is an array reference. 711 712Numbers 4, 9, 11, 12, 14, and 15 are **non-portable extensions**. 713 714Also, as a **non-portable extension**, any or all of the expressions in the 715header of a for loop may be omitted. If the condition (second expression) is 716omitted, it is assumed to be a constant **1**. 717 718The **break** statement causes a loop to stop iterating and resume execution 719immediately following a loop. This is only allowed in loops. 720 721The **continue** statement causes a loop iteration to stop early and returns to 722the start of the loop, including testing the loop condition. This is only 723allowed in loops. 724 725The **if** **else** statement does the same thing as in C. 726 727The **quit** statement causes bc(1) to quit, even if it is on a branch that will 728not be executed (it is a compile-time command). 729 730The **halt** statement causes bc(1) to quit, if it is executed. (Unlike **quit** 731if it is on a branch of an **if** statement that is not executed, bc(1) does not 732quit.) 733 734The **limits** statement prints the limits that this bc(1) is subject to. This 735is like the **quit** statement in that it is a compile-time command. 736 737An expression by itself is evaluated and printed, followed by a newline. 738 739Both scientific notation and engineering notation are available for printing the 740results of expressions. Scientific notation is activated by assigning **0** to 741**obase**, and engineering notation is activated by assigning **1** to 742**obase**. To deactivate them, just assign a different value to **obase**. 743 744Scientific notation and engineering notation are disabled if bc(1) is run with 745either the **-s** or **-w** command-line options (or equivalents). 746 747Printing numbers in scientific notation and/or engineering notation is a 748**non-portable extension**. 749 750## Print Statement 751 752The "expressions" in a **print** statement may also be strings. If they are, there 753are backslash escape sequences that are interpreted specially. What those 754sequences are, and what they cause to be printed, are shown below: 755 756-------- ------- 757**\\a** **\\a** 758**\\b** **\\b** 759**\\\\** **\\** 760**\\e** **\\** 761**\\f** **\\f** 762**\\n** **\\n** 763**\\q** **"** 764**\\r** **\\r** 765**\\t** **\\t** 766-------- ------- 767 768Any other character following a backslash causes the backslash and character to 769be printed as-is. 770 771Any non-string expression in a print statement shall be assigned to **last**, 772like any other expression that is printed. 773 774## Order of Evaluation 775 776All expressions in a statment are evaluated left to right, except as necessary 777to maintain order of operations. This means, for example, assuming that **i** is 778equal to **0**, in the expression 779 780 a[i++] = i++ 781 782the first (or 0th) element of **a** is set to **1**, and **i** is equal to **2** 783at the end of the expression. 784 785This includes function arguments. Thus, assuming **i** is equal to **0**, this 786means that in the expression 787 788 x(i++, i++) 789 790the first argument passed to **x()** is **0**, and the second argument is **1**, 791while **i** is equal to **2** before the function starts executing. 792 793# FUNCTIONS 794 795Function definitions are as follows: 796 797``` 798define I(I,...,I){ 799 auto I,...,I 800 S;...;S 801 return(E) 802} 803``` 804 805Any **I** in the parameter list or **auto** list may be replaced with **I[]** to 806make a parameter or **auto** var an array, and any **I** in the parameter list 807may be replaced with **\*I[]** to make a parameter an array reference. Callers 808of functions that take array references should not put an asterisk in the call; 809they must be called with just **I[]** like normal array parameters and will be 810automatically converted into references. 811 812As a **non-portable extension**, the opening brace of a **define** statement may 813appear on the next line. 814 815As a **non-portable extension**, the return statement may also be in one of the 816following forms: 817 8181. **return** 8192. **return** **(** **)** 8203. **return** **E** 821 822The first two, or not specifying a **return** statement, is equivalent to 823**return (0)**, unless the function is a **void** function (see the *Void 824Functions* subsection below). 825 826## Void Functions 827 828Functions can also be **void** functions, defined as follows: 829 830``` 831define void I(I,...,I){ 832 auto I,...,I 833 S;...;S 834 return 835} 836``` 837 838They can only be used as standalone expressions, where such an expression would 839be printed alone, except in a print statement. 840 841Void functions can only use the first two **return** statements listed above. 842They can also omit the return statement entirely. 843 844The word "void" is not treated as a keyword; it is still possible to have 845variables, arrays, and functions named **void**. The word "void" is only 846treated specially right after the **define** keyword. 847 848This is a **non-portable extension**. 849 850## Array References 851 852For any array in the parameter list, if the array is declared in the form 853 854``` 855*I[] 856``` 857 858it is a **reference**. Any changes to the array in the function are reflected, 859when the function returns, to the array that was passed in. 860 861Other than this, all function arguments are passed by value. 862 863This is a **non-portable extension**. 864 865# LIBRARY 866 867All of the functions below, including the functions in the extended math 868library (see the *Extended Library* subsection below), are available when the 869**-l** or **--mathlib** command-line flags are given, except that the extended 870math library is not available when the **-s** option, the **-w** option, or 871equivalents are given. 872 873## Standard Library 874 875The [standard][1] defines the following functions for the math library: 876 877**s(x)** 878 879: Returns the sine of **x**, which is assumed to be in radians. 880 881 This is a transcendental function (see the *Transcendental Functions* 882 subsection below). 883 884**c(x)** 885 886: Returns the cosine of **x**, which is assumed to be in radians. 887 888 This is a transcendental function (see the *Transcendental Functions* 889 subsection below). 890 891**a(x)** 892 893: Returns the arctangent of **x**, in radians. 894 895 This is a transcendental function (see the *Transcendental Functions* 896 subsection below). 897 898**l(x)** 899 900: Returns the natural logarithm of **x**. 901 902 This is a transcendental function (see the *Transcendental Functions* 903 subsection below). 904 905**e(x)** 906 907: Returns the mathematical constant **e** raised to the power of **x**. 908 909 This is a transcendental function (see the *Transcendental Functions* 910 subsection below). 911 912**j(x, n)** 913 914: Returns the bessel integer order **n** (truncated) of **x**. 915 916 This is a transcendental function (see the *Transcendental Functions* 917 subsection below). 918 919## Extended Library 920 921The extended library is *not* loaded when the **-s**/**--standard** or 922**-w**/**--warn** options are given since they are not part of the library 923defined by the [standard][1]. 924 925The extended library is a **non-portable extension**. 926 927**p(x, y)** 928 929: Calculates **x** to the power of **y**, even if **y** is not an integer, and 930 returns the result to the current **scale**. 931 932 This is a transcendental function (see the *Transcendental Functions* 933 subsection below). 934 935**r(x, p)** 936 937: Returns **x** rounded to **p** decimal places according to the rounding mode 938 [round half away from **0**][3]. 939 940**ceil(x, p)** 941 942: Returns **x** rounded to **p** decimal places according to the rounding mode 943 [round away from **0**][6]. 944 945**f(x)** 946 947: Returns the factorial of the truncated absolute value of **x**. 948 949**perm(n, k)** 950 951: Returns the permutation of the truncated absolute value of **n** of the 952 truncated absolute value of **k**, if **k \<= n**. If not, it returns **0**. 953 954**comb(n, k)** 955 956: Returns the combination of the truncated absolute value of **n** of the 957 truncated absolute value of **k**, if **k \<= n**. If not, it returns **0**. 958 959**l2(x)** 960 961: Returns the logarithm base **2** of **x**. 962 963 This is a transcendental function (see the *Transcendental Functions* 964 subsection below). 965 966**l10(x)** 967 968: Returns the logarithm base **10** of **x**. 969 970 This is a transcendental function (see the *Transcendental Functions* 971 subsection below). 972 973**log(x, b)** 974 975: Returns the logarithm base **b** of **x**. 976 977 This is a transcendental function (see the *Transcendental Functions* 978 subsection below). 979 980**cbrt(x)** 981 982: Returns the cube root of **x**. 983 984**root(x, n)** 985 986: Calculates the truncated value of **n**, **r**, and returns the **r**th root 987 of **x** to the current **scale**. 988 989 If **r** is **0** or negative, this raises an error and causes bc(1) to 990 reset (see the **RESET** section). It also raises an error and causes bc(1) 991 to reset if **r** is even and **x** is negative. 992 993**pi(p)** 994 995: Returns **pi** to **p** decimal places. 996 997 This is a transcendental function (see the *Transcendental Functions* 998 subsection below). 999 1000**t(x)** 1001 1002: Returns the tangent of **x**, which is assumed to be in radians. 1003 1004 This is a transcendental function (see the *Transcendental Functions* 1005 subsection below). 1006 1007**a2(y, x)** 1008 1009: Returns the arctangent of **y/x**, in radians. If both **y** and **x** are 1010 equal to **0**, it raises an error and causes bc(1) to reset (see the 1011 **RESET** section). Otherwise, if **x** is greater than **0**, it returns 1012 **a(y/x)**. If **x** is less than **0**, and **y** is greater than or equal 1013 to **0**, it returns **a(y/x)+pi**. If **x** is less than **0**, and **y** 1014 is less than **0**, it returns **a(y/x)-pi**. If **x** is equal to **0**, 1015 and **y** is greater than **0**, it returns **pi/2**. If **x** is equal to 1016 **0**, and **y** is less than **0**, it returns **-pi/2**. 1017 1018 This function is the same as the **atan2()** function in many programming 1019 languages. 1020 1021 This is a transcendental function (see the *Transcendental Functions* 1022 subsection below). 1023 1024**sin(x)** 1025 1026: Returns the sine of **x**, which is assumed to be in radians. 1027 1028 This is an alias of **s(x)**. 1029 1030 This is a transcendental function (see the *Transcendental Functions* 1031 subsection below). 1032 1033**cos(x)** 1034 1035: Returns the cosine of **x**, which is assumed to be in radians. 1036 1037 This is an alias of **c(x)**. 1038 1039 This is a transcendental function (see the *Transcendental Functions* 1040 subsection below). 1041 1042**tan(x)** 1043 1044: Returns the tangent of **x**, which is assumed to be in radians. 1045 1046 If **x** is equal to **1** or **-1**, this raises an error and causes bc(1) 1047 to reset (see the **RESET** section). 1048 1049 This is an alias of **t(x)**. 1050 1051 This is a transcendental function (see the *Transcendental Functions* 1052 subsection below). 1053 1054**atan(x)** 1055 1056: Returns the arctangent of **x**, in radians. 1057 1058 This is an alias of **a(x)**. 1059 1060 This is a transcendental function (see the *Transcendental Functions* 1061 subsection below). 1062 1063**atan2(y, x)** 1064 1065: Returns the arctangent of **y/x**, in radians. If both **y** and **x** are 1066 equal to **0**, it raises an error and causes bc(1) to reset (see the 1067 **RESET** section). Otherwise, if **x** is greater than **0**, it returns 1068 **a(y/x)**. If **x** is less than **0**, and **y** is greater than or equal 1069 to **0**, it returns **a(y/x)+pi**. If **x** is less than **0**, and **y** 1070 is less than **0**, it returns **a(y/x)-pi**. If **x** is equal to **0**, 1071 and **y** is greater than **0**, it returns **pi/2**. If **x** is equal to 1072 **0**, and **y** is less than **0**, it returns **-pi/2**. 1073 1074 This function is the same as the **atan2()** function in many programming 1075 languages. 1076 1077 This is an alias of **a2(y, x)**. 1078 1079 This is a transcendental function (see the *Transcendental Functions* 1080 subsection below). 1081 1082**r2d(x)** 1083 1084: Converts **x** from radians to degrees and returns the result. 1085 1086 This is a transcendental function (see the *Transcendental Functions* 1087 subsection below). 1088 1089**d2r(x)** 1090 1091: Converts **x** from degrees to radians and returns the result. 1092 1093 This is a transcendental function (see the *Transcendental Functions* 1094 subsection below). 1095 1096**frand(p)** 1097 1098: Generates a pseudo-random number between **0** (inclusive) and **1** 1099 (exclusive) with the number of decimal digits after the decimal point equal 1100 to the truncated absolute value of **p**. If **p** is not **0**, then 1101 calling this function will change the value of **seed**. If **p** is **0**, 1102 then **0** is returned, and **seed** is *not* changed. 1103 1104**ifrand(i, p)** 1105 1106: Generates a pseudo-random number that is between **0** (inclusive) and the 1107 truncated absolute value of **i** (exclusive) with the number of decimal 1108 digits after the decimal point equal to the truncated absolute value of 1109 **p**. If the absolute value of **i** is greater than or equal to **2**, and 1110 **p** is not **0**, then calling this function will change the value of 1111 **seed**; otherwise, **0** is returned and **seed** is not changed. 1112 1113**srand(x)** 1114 1115: Returns **x** with its sign flipped with probability **0.5**. In other 1116 words, it randomizes the sign of **x**. 1117 1118**brand()** 1119 1120: Returns a random boolean value (either **0** or **1**). 1121 1122**ubytes(x)** 1123 1124: Returns the numbers of unsigned integer bytes required to hold the truncated 1125 absolute value of **x**. 1126 1127**sbytes(x)** 1128 1129: Returns the numbers of signed, two's-complement integer bytes required to 1130 hold the truncated value of **x**. 1131 1132**hex(x)** 1133 1134: Outputs the hexadecimal (base **16**) representation of **x**. 1135 1136 This is a **void** function (see the *Void Functions* subsection of the 1137 **FUNCTIONS** section). 1138 1139**binary(x)** 1140 1141: Outputs the binary (base **2**) representation of **x**. 1142 1143 This is a **void** function (see the *Void Functions* subsection of the 1144 **FUNCTIONS** section). 1145 1146**output(x, b)** 1147 1148: Outputs the base **b** representation of **x**. 1149 1150 This is a **void** function (see the *Void Functions* subsection of the 1151 **FUNCTIONS** section). 1152 1153**uint(x)** 1154 1155: Outputs the representation, in binary and hexadecimal, of **x** as an 1156 unsigned integer in as few power of two bytes as possible. Both outputs are 1157 split into bytes separated by spaces. 1158 1159 If **x** is not an integer or is negative, an error message is printed 1160 instead, but bc(1) is not reset (see the **RESET** section). 1161 1162 This is a **void** function (see the *Void Functions* subsection of the 1163 **FUNCTIONS** section). 1164 1165**int(x)** 1166 1167: Outputs the representation, in binary and hexadecimal, of **x** as a signed, 1168 two's-complement integer in as few power of two bytes as possible. Both 1169 outputs are split into bytes separated by spaces. 1170 1171 If **x** is not an integer, an error message is printed instead, but bc(1) 1172 is not reset (see the **RESET** section). 1173 1174 This is a **void** function (see the *Void Functions* subsection of the 1175 **FUNCTIONS** section). 1176 1177**uintn(x, n)** 1178 1179: Outputs the representation, in binary and hexadecimal, of **x** as an 1180 unsigned integer in **n** bytes. Both outputs are split into bytes separated 1181 by spaces. 1182 1183 If **x** is not an integer, is negative, or cannot fit into **n** bytes, an 1184 error message is printed instead, but bc(1) is not reset (see the **RESET** 1185 section). 1186 1187 This is a **void** function (see the *Void Functions* subsection of the 1188 **FUNCTIONS** section). 1189 1190**intn(x, n)** 1191 1192: Outputs the representation, in binary and hexadecimal, of **x** as a signed, 1193 two's-complement integer in **n** bytes. Both outputs are split into bytes 1194 separated by spaces. 1195 1196 If **x** is not an integer or cannot fit into **n** bytes, an error message 1197 is printed instead, but bc(1) is not reset (see the **RESET** section). 1198 1199 This is a **void** function (see the *Void Functions* subsection of the 1200 **FUNCTIONS** section). 1201 1202**uint8(x)** 1203 1204: Outputs the representation, in binary and hexadecimal, of **x** as an 1205 unsigned integer in **1** byte. Both outputs are split into bytes separated 1206 by spaces. 1207 1208 If **x** is not an integer, is negative, or cannot fit into **1** byte, an 1209 error message is printed instead, but bc(1) is not reset (see the **RESET** 1210 section). 1211 1212 This is a **void** function (see the *Void Functions* subsection of the 1213 **FUNCTIONS** section). 1214 1215**int8(x)** 1216 1217: Outputs the representation, in binary and hexadecimal, of **x** as a signed, 1218 two's-complement integer in **1** byte. Both outputs are split into bytes 1219 separated by spaces. 1220 1221 If **x** is not an integer or cannot fit into **1** byte, an error message 1222 is printed instead, but bc(1) is not reset (see the **RESET** section). 1223 1224 This is a **void** function (see the *Void Functions* subsection of the 1225 **FUNCTIONS** section). 1226 1227**uint16(x)** 1228 1229: Outputs the representation, in binary and hexadecimal, of **x** as an 1230 unsigned integer in **2** bytes. Both outputs are split into bytes separated 1231 by spaces. 1232 1233 If **x** is not an integer, is negative, or cannot fit into **2** bytes, an 1234 error message is printed instead, but bc(1) is not reset (see the **RESET** 1235 section). 1236 1237 This is a **void** function (see the *Void Functions* subsection of the 1238 **FUNCTIONS** section). 1239 1240**int16(x)** 1241 1242: Outputs the representation, in binary and hexadecimal, of **x** as a signed, 1243 two's-complement integer in **2** bytes. Both outputs are split into bytes 1244 separated by spaces. 1245 1246 If **x** is not an integer or cannot fit into **2** bytes, an error message 1247 is printed instead, but bc(1) is not reset (see the **RESET** section). 1248 1249 This is a **void** function (see the *Void Functions* subsection of the 1250 **FUNCTIONS** section). 1251 1252**uint32(x)** 1253 1254: Outputs the representation, in binary and hexadecimal, of **x** as an 1255 unsigned integer in **4** bytes. Both outputs are split into bytes separated 1256 by spaces. 1257 1258 If **x** is not an integer, is negative, or cannot fit into **4** bytes, an 1259 error message is printed instead, but bc(1) is not reset (see the **RESET** 1260 section). 1261 1262 This is a **void** function (see the *Void Functions* subsection of the 1263 **FUNCTIONS** section). 1264 1265**int32(x)** 1266 1267: Outputs the representation, in binary and hexadecimal, of **x** as a signed, 1268 two's-complement integer in **4** bytes. Both outputs are split into bytes 1269 separated by spaces. 1270 1271 If **x** is not an integer or cannot fit into **4** bytes, an error message 1272 is printed instead, but bc(1) is not reset (see the **RESET** section). 1273 1274 This is a **void** function (see the *Void Functions* subsection of the 1275 **FUNCTIONS** section). 1276 1277**uint64(x)** 1278 1279: Outputs the representation, in binary and hexadecimal, of **x** as an 1280 unsigned integer in **8** bytes. Both outputs are split into bytes separated 1281 by spaces. 1282 1283 If **x** is not an integer, is negative, or cannot fit into **8** bytes, an 1284 error message is printed instead, but bc(1) is not reset (see the **RESET** 1285 section). 1286 1287 This is a **void** function (see the *Void Functions* subsection of the 1288 **FUNCTIONS** section). 1289 1290**int64(x)** 1291 1292: Outputs the representation, in binary and hexadecimal, of **x** as a signed, 1293 two's-complement integer in **8** bytes. Both outputs are split into bytes 1294 separated by spaces. 1295 1296 If **x** is not an integer or cannot fit into **8** bytes, an error message 1297 is printed instead, but bc(1) is not reset (see the **RESET** section). 1298 1299 This is a **void** function (see the *Void Functions* subsection of the 1300 **FUNCTIONS** section). 1301 1302**hex_uint(x, n)** 1303 1304: Outputs the representation of the truncated absolute value of **x** as an 1305 unsigned integer in hexadecimal using **n** bytes. Not all of the value will 1306 be output if **n** is too small. 1307 1308 This is a **void** function (see the *Void Functions* subsection of the 1309 **FUNCTIONS** section). 1310 1311**binary_uint(x, n)** 1312 1313: Outputs the representation of the truncated absolute value of **x** as an 1314 unsigned integer in binary using **n** bytes. Not all of the value will be 1315 output if **n** is too small. 1316 1317 This is a **void** function (see the *Void Functions* subsection of the 1318 **FUNCTIONS** section). 1319 1320**output_uint(x, n)** 1321 1322: Outputs the representation of the truncated absolute value of **x** as an 1323 unsigned integer in the current **obase** (see the **SYNTAX** section) using 1324 **n** bytes. Not all of the value will be output if **n** is too small. 1325 1326 This is a **void** function (see the *Void Functions* subsection of the 1327 **FUNCTIONS** section). 1328 1329**output_byte(x, i)** 1330 1331: Outputs byte **i** of the truncated absolute value of **x**, where **0** is 1332 the least significant byte and **number_of_bytes - 1** is the most 1333 significant byte. 1334 1335 This is a **void** function (see the *Void Functions* subsection of the 1336 **FUNCTIONS** section). 1337 1338## Transcendental Functions 1339 1340All transcendental functions can return slightly inaccurate results (up to 1 1341[ULP][4]). This is unavoidable, and [this article][5] explains why it is 1342impossible and unnecessary to calculate exact results for the transcendental 1343functions. 1344 1345Because of the possible inaccuracy, I recommend that users call those functions 1346with the precision (**scale**) set to at least 1 higher than is necessary. If 1347exact results are *absolutely* required, users can double the precision 1348(**scale**) and then truncate. 1349 1350The transcendental functions in the standard math library are: 1351 1352* **s(x)** 1353* **c(x)** 1354* **a(x)** 1355* **l(x)** 1356* **e(x)** 1357* **j(x, n)** 1358 1359The transcendental functions in the extended math library are: 1360 1361* **l2(x)** 1362* **l10(x)** 1363* **log(x, b)** 1364* **pi(p)** 1365* **t(x)** 1366* **a2(y, x)** 1367* **sin(x)** 1368* **cos(x)** 1369* **tan(x)** 1370* **atan(x)** 1371* **atan2(y, x)** 1372* **r2d(x)** 1373* **d2r(x)** 1374 1375# RESET 1376 1377When bc(1) encounters an error or a signal that it has a non-default handler 1378for, it resets. This means that several things happen. 1379 1380First, any functions that are executing are stopped and popped off the stack. 1381The behavior is not unlike that of exceptions in programming languages. Then 1382the execution point is set so that any code waiting to execute (after all 1383functions returned) is skipped. 1384 1385Thus, when bc(1) resets, it skips any remaining code waiting to be executed. 1386Then, if it is interactive mode, and the error was not a fatal error (see the 1387**EXIT STATUS** section), it asks for more input; otherwise, it exits with the 1388appropriate return code. 1389 1390Note that this reset behavior is different from the GNU bc(1), which attempts to 1391start executing the statement right after the one that caused an error. 1392 1393# PERFORMANCE 1394 1395Most bc(1) implementations use **char** types to calculate the value of **1** 1396decimal digit at a time, but that can be slow. This bc(1) does something 1397different. 1398 1399It uses large integers to calculate more than **1** decimal digit at a time. If 1400built in a environment where **BC_LONG_BIT** (see the **LIMITS** section) is 1401**64**, then each integer has **9** decimal digits. If built in an environment 1402where **BC_LONG_BIT** is **32** then each integer has **4** decimal digits. This 1403value (the number of decimal digits per large integer) is called 1404**BC_BASE_DIGS**. 1405 1406The actual values of **BC_LONG_BIT** and **BC_BASE_DIGS** can be queried with 1407the **limits** statement. 1408 1409In addition, this bc(1) uses an even larger integer for overflow checking. This 1410integer type depends on the value of **BC_LONG_BIT**, but is always at least 1411twice as large as the integer type used to store digits. 1412 1413# LIMITS 1414 1415The following are the limits on bc(1): 1416 1417**BC_LONG_BIT** 1418 1419: The number of bits in the **long** type in the environment where bc(1) was 1420 built. This determines how many decimal digits can be stored in a single 1421 large integer (see the **PERFORMANCE** section). 1422 1423**BC_BASE_DIGS** 1424 1425: The number of decimal digits per large integer (see the **PERFORMANCE** 1426 section). Depends on **BC_LONG_BIT**. 1427 1428**BC_BASE_POW** 1429 1430: The max decimal number that each large integer can store (see 1431 **BC_BASE_DIGS**) plus **1**. Depends on **BC_BASE_DIGS**. 1432 1433**BC_OVERFLOW_MAX** 1434 1435: The max number that the overflow type (see the **PERFORMANCE** section) can 1436 hold. Depends on **BC_LONG_BIT**. 1437 1438**BC_BASE_MAX** 1439 1440: The maximum output base. Set at **BC_BASE_POW**. 1441 1442**BC_DIM_MAX** 1443 1444: The maximum size of arrays. Set at **SIZE_MAX-1**. 1445 1446**BC_SCALE_MAX** 1447 1448: The maximum **scale**. Set at **BC_OVERFLOW_MAX-1**. 1449 1450**BC_STRING_MAX** 1451 1452: The maximum length of strings. Set at **BC_OVERFLOW_MAX-1**. 1453 1454**BC_NAME_MAX** 1455 1456: The maximum length of identifiers. Set at **BC_OVERFLOW_MAX-1**. 1457 1458**BC_NUM_MAX** 1459 1460: The maximum length of a number (in decimal digits), which includes digits 1461 after the decimal point. Set at **BC_OVERFLOW_MAX-1**. 1462 1463**BC_RAND_MAX** 1464 1465: The maximum integer (inclusive) returned by the **rand()** operand. Set at 1466 **2\^BC_LONG_BIT-1**. 1467 1468Exponent 1469 1470: The maximum allowable exponent (positive or negative). Set at 1471 **BC_OVERFLOW_MAX**. 1472 1473Number of vars 1474 1475: The maximum number of vars/arrays. Set at **SIZE_MAX-1**. 1476 1477The actual values can be queried with the **limits** statement. 1478 1479These limits are meant to be effectively non-existent; the limits are so large 1480(at least on 64-bit machines) that there should not be any point at which they 1481become a problem. In fact, memory should be exhausted before these limits should 1482be hit. 1483 1484# ENVIRONMENT VARIABLES 1485 1486bc(1) recognizes the following environment variables: 1487 1488**POSIXLY_CORRECT** 1489 1490: If this variable exists (no matter the contents), bc(1) behaves as if 1491 the **-s** option was given. 1492 1493**BC_ENV_ARGS** 1494 1495: This is another way to give command-line arguments to bc(1). They should be 1496 in the same format as all other command-line arguments. These are always 1497 processed first, so any files given in **BC_ENV_ARGS** will be processed 1498 before arguments and files given on the command-line. This gives the user 1499 the ability to set up "standard" options and files to be used at every 1500 invocation. The most useful thing for such files to contain would be useful 1501 functions that the user might want every time bc(1) runs. 1502 1503 The code that parses **BC_ENV_ARGS** will correctly handle quoted arguments, 1504 but it does not understand escape sequences. For example, the string 1505 **"/home/gavin/some bc file.bc"** will be correctly parsed, but the string 1506 **"/home/gavin/some \"bc\" file.bc"** will include the backslashes. 1507 1508 The quote parsing will handle either kind of quotes, **'** or **"**. Thus, 1509 if you have a file with any number of single quotes in the name, you can use 1510 double quotes as the outside quotes, as in **"some 'bc' file.bc"**, and vice 1511 versa if you have a file with double quotes. However, handling a file with 1512 both kinds of quotes in **BC_ENV_ARGS** is not supported due to the 1513 complexity of the parsing, though such files are still supported on the 1514 command-line where the parsing is done by the shell. 1515 1516**BC_LINE_LENGTH** 1517 1518: If this environment variable exists and contains an integer that is greater 1519 than **1** and is less than **UINT16_MAX** (**2\^16-1**), bc(1) will output 1520 lines to that length, including the backslash (**\\**). The default line 1521 length is **70**. 1522 1523**BC_EXPR_EXIT** 1524 1525: If this variable exists (no matter the contents), bc(1) will exit 1526 immediately after executing expressions and files given by the **-e** and/or 1527 **-f** command-line options (and any equivalents). 1528 1529# EXIT STATUS 1530 1531bc(1) returns the following exit statuses: 1532 1533**0** 1534 1535: No error. 1536 1537**1** 1538 1539: A math error occurred. This follows standard practice of using **1** for 1540 expected errors, since math errors will happen in the process of normal 1541 execution. 1542 1543 Math errors include divide by **0**, taking the square root of a negative 1544 number, using a negative number as a bound for the pseudo-random number 1545 generator, attempting to convert a negative number to a hardware integer, 1546 overflow when converting a number to a hardware integer, and attempting to 1547 use a non-integer where an integer is required. 1548 1549 Converting to a hardware integer happens for the second operand of the power 1550 (**\^**), places (**\@**), left shift (**\<\<**), and right shift (**\>\>**) 1551 operators and their corresponding assignment operators. 1552 1553**2** 1554 1555: A parse error occurred. 1556 1557 Parse errors include unexpected **EOF**, using an invalid character, failing 1558 to find the end of a string or comment, using a token where it is invalid, 1559 giving an invalid expression, giving an invalid print statement, giving an 1560 invalid function definition, attempting to assign to an expression that is 1561 not a named expression (see the *Named Expressions* subsection of the 1562 **SYNTAX** section), giving an invalid **auto** list, having a duplicate 1563 **auto**/function parameter, failing to find the end of a code block, 1564 attempting to return a value from a **void** function, attempting to use a 1565 variable as a reference, and using any extensions when the option **-s** or 1566 any equivalents were given. 1567 1568**3** 1569 1570: A runtime error occurred. 1571 1572 Runtime errors include assigning an invalid number to **ibase**, **obase**, 1573 or **scale**; give a bad expression to a **read()** call, calling **read()** 1574 inside of a **read()** call, type errors, passing the wrong number of 1575 arguments to functions, attempting to call an undefined function, and 1576 attempting to use a **void** function call as a value in an expression. 1577 1578**4** 1579 1580: A fatal error occurred. 1581 1582 Fatal errors include memory allocation errors, I/O errors, failing to open 1583 files, attempting to use files that do not have only ASCII characters (bc(1) 1584 only accepts ASCII characters), attempting to open a directory as a file, 1585 and giving invalid command-line options. 1586 1587The exit status **4** is special; when a fatal error occurs, bc(1) always exits 1588and returns **4**, no matter what mode bc(1) is in. 1589 1590The other statuses will only be returned when bc(1) is not in interactive mode 1591(see the **INTERACTIVE MODE** section), since bc(1) resets its state (see the 1592**RESET** section) and accepts more input when one of those errors occurs in 1593interactive mode. This is also the case when interactive mode is forced by the 1594**-i** flag or **--interactive** option. 1595 1596These exit statuses allow bc(1) to be used in shell scripting with error 1597checking, and its normal behavior can be forced by using the **-i** flag or 1598**--interactive** option. 1599 1600# INTERACTIVE MODE 1601 1602Per the [standard][1], bc(1) has an interactive mode and a non-interactive mode. 1603Interactive mode is turned on automatically when both **stdin** and **stdout** 1604are hooked to a terminal, but the **-i** flag and **--interactive** option can 1605turn it on in other cases. 1606 1607In interactive mode, bc(1) attempts to recover from errors (see the **RESET** 1608section), and in normal execution, flushes **stdout** as soon as execution is 1609done for the current input. 1610 1611# TTY MODE 1612 1613If **stdin**, **stdout**, and **stderr** are all connected to a TTY, bc(1) turns 1614on "TTY mode." 1615 1616The prompt is enabled in TTY mode. 1617 1618TTY mode is different from interactive mode because interactive mode is required 1619in the [bc(1) specification][1], and interactive mode requires only **stdin** 1620and **stdout** to be connected to a terminal. 1621 1622# SIGNAL HANDLING 1623 1624Sending a **SIGINT** will cause bc(1) to stop execution of the current input. If 1625bc(1) is in TTY mode (see the **TTY MODE** section), it will reset (see the 1626**RESET** section). Otherwise, it will clean up and exit. 1627 1628Note that "current input" can mean one of two things. If bc(1) is processing 1629input from **stdin** in TTY mode, it will ask for more input. If bc(1) is 1630processing input from a file in TTY mode, it will stop processing the file and 1631start processing the next file, if one exists, or ask for input from **stdin** 1632if no other file exists. 1633 1634This means that if a **SIGINT** is sent to bc(1) as it is executing a file, it 1635can seem as though bc(1) did not respond to the signal since it will immediately 1636start executing the next file. This is by design; most files that users execute 1637when interacting with bc(1) have function definitions, which are quick to parse. 1638If a file takes a long time to execute, there may be a bug in that file. The 1639rest of the files could still be executed without problem, allowing the user to 1640continue. 1641 1642**SIGTERM** and **SIGQUIT** cause bc(1) to clean up and exit, and it uses the 1643default handler for all other signals. 1644 1645# SEE ALSO 1646 1647dc(1) 1648 1649# STANDARDS 1650 1651bc(1) is compliant with the [IEEE Std 1003.1-2017 (“POSIX.1-2017”)][1] 1652specification. The flags **-efghiqsvVw**, all long options, and the extensions 1653noted above are extensions to that specification. 1654 1655Note that the specification explicitly says that bc(1) only accepts numbers that 1656use a period (**.**) as a radix point, regardless of the value of 1657**LC_NUMERIC**. 1658 1659# BUGS 1660 1661None are known. Report bugs at https://git.yzena.com/gavin/bc. 1662 1663# AUTHORS 1664 1665Gavin D. Howard <yzena.tech@gmail.com> and contributors. 1666 1667[1]: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html 1668[2]: https://www.gnu.org/software/bc/ 1669[3]: https://en.wikipedia.org/wiki/Rounding#Round_half_away_from_zero 1670[4]: https://en.wikipedia.org/wiki/Unit_in_the_last_place 1671[5]: https://people.eecs.berkeley.edu/~wkahan/LOG10HAF.TXT 1672[6]: https://en.wikipedia.org/wiki/Rounding#Rounding_away_from_zero 1673