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