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