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