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 49This bc(1) is a drop-in replacement for *any* bc(1), including (and 50especially) the GNU bc(1). It also has many extensions and extra features beyond 51other implementations. 52 53**Note**: If running this bc(1) on *any* script meant for another bc(1) gives a 54parse error, it is probably because a word this bc(1) reserves as a keyword is 55used as the name of a function, variable, or array. To fix that, use the 56command-line option **-r** *keyword*, where *keyword* is the keyword that is 57used as a name in the script. For more information, see the **OPTIONS** section. 58 59If parsing scripts meant for other bc(1) implementations still does not work, 60that is a bug and should be reported. See the **BUGS** section. 61 62# OPTIONS 63 64The following are the options that bc(1) accepts. 65 66**-g**, **-\-global-stacks** 67 68: Turns the globals **ibase**, **obase**, **scale**, and **seed** into stacks. 69 70 This has the effect that a copy of the current value of all four are pushed 71 onto a stack for every function call, as well as popped when every function 72 returns. This means that functions can assign to any and all of those 73 globals without worrying that the change will affect other functions. 74 Thus, a hypothetical function named **output(x,b)** that simply printed 75 **x** in base **b** could be written like this: 76 77 define void output(x, b) { 78 obase=b 79 x 80 } 81 82 instead of like this: 83 84 define void output(x, b) { 85 auto c 86 c=obase 87 obase=b 88 x 89 obase=c 90 } 91 92 This makes writing functions much easier. 93 94 (**Note**: the function **output(x,b)** exists in the extended math library. 95 See the **LIBRARY** section.) 96 97 However, since using this flag means that functions cannot set **ibase**, 98 **obase**, **scale**, or **seed** globally, functions that are made to do so 99 cannot work anymore. There are two possible use cases for that, and each has 100 a solution. 101 102 First, if a function is called on startup to turn bc(1) into a number 103 converter, it is possible to replace that capability with various shell 104 aliases. Examples: 105 106 alias d2o="bc -e ibase=A -e obase=8" 107 alias h2b="bc -e ibase=G -e obase=2" 108 109 Second, if the purpose of a function is to set **ibase**, **obase**, 110 **scale**, or **seed** globally for any other purpose, it could be split 111 into one to four functions (based on how many globals it sets) and each of 112 those functions could return the desired value for a global. 113 114 For functions that set **seed**, the value assigned to **seed** is not 115 propagated to parent functions. This means that the sequence of 116 pseudo-random numbers that they see will not be the same sequence of 117 pseudo-random numbers that any parent sees. This is only the case once 118 **seed** has been set. 119 120 If a function desires to not affect the sequence of pseudo-random numbers 121 of its parents, but wants to use the same **seed**, it can use the following 122 line: 123 124 seed = seed 125 126 If the behavior of this option is desired for every run of bc(1), then users 127 could make sure to define **BC_ENV_ARGS** and include this option (see the 128 **ENVIRONMENT VARIABLES** section for more details). 129 130 If **-s**, **-w**, or any equivalents are used, this option is ignored. 131 132 This is a **non-portable extension**. 133 134**-h**, **-\-help** 135 136: Prints a usage message and quits. 137 138**-i**, **-\-interactive** 139 140: Forces interactive mode. (See the **INTERACTIVE MODE** section.) 141 142 This is a **non-portable extension**. 143 144**-l**, **-\-mathlib** 145 146: Sets **scale** (see the **SYNTAX** section) to **20** and loads the included 147 math library and the extended math library before running any code, 148 including any expressions or files specified on the command line. 149 150 To learn what is in the libraries, see the **LIBRARY** section. 151 152**-P**, **-\-no-prompt** 153 154: Disables the prompt in TTY mode. (The prompt is only enabled in TTY mode. 155 See the **TTY MODE** section.) This is mostly for those users that do not 156 want a prompt or are not used to having them in bc(1). Most of those users 157 would want to put this option in **BC_ENV_ARGS** (see the 158 **ENVIRONMENT VARIABLES** section). 159 160 These options override the **BC_PROMPT** and **BC_TTY_MODE** environment 161 variables (see the **ENVIRONMENT VARIABLES** section). 162 163 This is a **non-portable extension**. 164 165**-R**, **-\-no-read-prompt** 166 167: Disables the read prompt in TTY mode. (The read prompt is only enabled in 168 TTY mode. See the **TTY MODE** section.) This is mostly for those users that 169 do not want a read prompt or are not used to having them in bc(1). Most of 170 those users would want to put this option in **BC_ENV_ARGS** (see the 171 **ENVIRONMENT VARIABLES** section). This option is also useful in hash bang 172 lines of bc(1) scripts that prompt for user input. 173 174 This option does not disable the regular prompt because the read prompt is 175 only used when the **read()** built-in function is called. 176 177 These options *do* override the **BC_PROMPT** and **BC_TTY_MODE** 178 environment variables (see the **ENVIRONMENT VARIABLES** section), but only 179 for the read prompt. 180 181 This is a **non-portable extension**. 182 183**-r** *keyword*, **-\-redefine**=*keyword* 184 185: Redefines *keyword* in order to allow it to be used as a function, variable, 186 or array name. This is useful when this bc(1) gives parse errors when 187 parsing scripts meant for other bc(1) implementations. 188 189 The keywords this bc(1) allows to be redefined are: 190 191 * **abs** 192 * **asciify** 193 * **continue** 194 * **divmod** 195 * **else** 196 * **halt** 197 * **irand** 198 * **last** 199 * **limits** 200 * **maxibase** 201 * **maxobase** 202 * **maxrand** 203 * **maxscale** 204 * **modexp** 205 * **print** 206 * **rand** 207 * **read** 208 * **seed** 209 * **stream** 210 211 If any of those keywords are used as a function, variable, or array name in 212 a script, use this option with the keyword as the argument. If multiple are 213 used, use this option for all of them; it can be used multiple times. 214 215 Keywords are *not* redefined when parsing the builtin math library (see the 216 **LIBRARY** section). 217 218 It is a fatal error to redefine keywords mandated by the POSIX standard. It 219 is a fatal error to attempt to redefine words that this bc(1) does not 220 reserve as keywords. 221 222**-q**, **-\-quiet** 223 224: This option is for compatibility with the [GNU bc(1)][2]; it is a no-op. 225 Without this option, GNU bc(1) prints a copyright header. This bc(1) only 226 prints the copyright header if one or more of the **-v**, **-V**, or 227 **-\-version** options are given. 228 229 This is a **non-portable extension**. 230 231**-s**, **-\-standard** 232 233: Process exactly the language defined by the [standard][1] and error if any 234 extensions are used. 235 236 This is a **non-portable extension**. 237 238**-v**, **-V**, **-\-version** 239 240: Print the version information (copyright header) and exit. 241 242 This is a **non-portable extension**. 243 244**-w**, **-\-warn** 245 246: Like **-s** and **-\-standard**, except that warnings (and not errors) are 247 printed for non-standard extensions and execution continues normally. 248 249 This is a **non-portable extension**. 250 251**-e** *expr*, **-\-expression**=*expr* 252 253: Evaluates *expr*. If multiple expressions are given, they are evaluated in 254 order. If files are given as well (see below), the expressions and files are 255 evaluated in the order given. This means that if a file is given before an 256 expression, the file is read in and evaluated first. 257 258 If this option is given on the command-line (i.e., not in **BC_ENV_ARGS**, 259 see the **ENVIRONMENT VARIABLES** section), then after processing all 260 expressions and files, bc(1) will exit, unless **-** (**stdin**) was given 261 as an argument at least once to **-f** or **-\-file**, whether on the 262 command-line or in **BC_ENV_ARGS**. However, if any other **-e**, 263 **-\-expression**, **-f**, or **-\-file** arguments are given after **-f-** 264 or equivalent is given, bc(1) will give a fatal error and exit. 265 266 This is a **non-portable extension**. 267 268**-f** *file*, **-\-file**=*file* 269 270: Reads in *file* and evaluates it, line by line, as though it were read 271 through **stdin**. If expressions are also given (see above), the 272 expressions are evaluated in the order given. 273 274 If this option is given on the command-line (i.e., not in **BC_ENV_ARGS**, 275 see the **ENVIRONMENT VARIABLES** section), then after processing all 276 expressions and files, bc(1) will exit, unless **-** (**stdin**) was given 277 as an argument at least once to **-f** or **-\-file**. However, if any other 278 **-e**, **-\-expression**, **-f**, or **-\-file** arguments are given after 279 **-f-** or equivalent is given, bc(1) will give a fatal error and exit. 280 281 This is a **non-portable extension**. 282 283All long options are **non-portable extensions**. 284 285# STDIN 286 287If no files or expressions are given by the **-f**, **-\-file**, **-e**, or 288**-\-expression** options, then bc(1) read from **stdin**. 289 290However, there are a few caveats to this. 291 292First, **stdin** is evaluated a line at a time. The only exception to this is if 293the parse cannot complete. That means that starting a string without ending it 294or starting a function, **if** statement, or loop without ending it will also 295cause bc(1) to not execute. 296 297Second, after an **if** statement, bc(1) doesn't know if an **else** statement 298will follow, so it will not execute until it knows there will not be an **else** 299statement. 300 301# STDOUT 302 303Any non-error output is written to **stdout**. In addition, if history (see the 304**HISTORY** section) and the prompt (see the **TTY MODE** section) are enabled, 305both are output to **stdout**. 306 307**Note**: Unlike other bc(1) implementations, this bc(1) will issue a fatal 308error (see the **EXIT STATUS** section) if it cannot write to **stdout**, so if 309**stdout** is closed, as in **bc <file> >&-**, it will quit with an error. This 310is done so that bc(1) can report problems when **stdout** is redirected to a 311file. 312 313If there are scripts that depend on the behavior of other bc(1) implementations, 314it is recommended that those scripts be changed to redirect **stdout** to 315**/dev/null**. 316 317# STDERR 318 319Any error output is written to **stderr**. 320 321**Note**: Unlike other bc(1) implementations, this bc(1) will issue a fatal 322error (see the **EXIT STATUS** section) if it cannot write to **stderr**, so if 323**stderr** is closed, as in **bc <file> 2>&-**, it will quit with an error. This 324is done so that bc(1) can exit with an error code when **stderr** is redirected 325to a file. 326 327If there are scripts that depend on the behavior of other bc(1) implementations, 328it is recommended that those scripts be changed to redirect **stderr** to 329**/dev/null**. 330 331# SYNTAX 332 333The syntax for bc(1) programs is mostly C-like, with some differences. This 334bc(1) follows the [POSIX standard][1], which is a much more thorough resource 335for the language this bc(1) accepts. This section is meant to be a summary and a 336listing of all the extensions to the standard. 337 338In the sections below, **E** means expression, **S** means statement, and **I** 339means identifier. 340 341Identifiers (**I**) start with a lowercase letter and can be followed by any 342number (up to **BC_NAME_MAX-1**) of lowercase letters (**a-z**), digits 343(**0-9**), and underscores (**\_**). The regex is **\[a-z\]\[a-z0-9\_\]\***. 344Identifiers with more than one character (letter) are a 345**non-portable extension**. 346 347**ibase** is a global variable determining how to interpret constant numbers. It 348is the "input" base, or the number base used for interpreting input numbers. 349**ibase** is initially **10**. If the **-s** (**-\-standard**) and **-w** 350(**-\-warn**) flags were not given on the command line, the max allowable value 351for **ibase** is **36**. Otherwise, it is **16**. The min allowable value for 352**ibase** is **2**. The max allowable value for **ibase** can be queried in 353bc(1) programs with the **maxibase()** built-in function. 354 355**obase** is a global variable determining how to output results. It is the 356"output" base, or the number base used for outputting numbers. **obase** is 357initially **10**. The max allowable value for **obase** is **BC_BASE_MAX** and 358can be queried in bc(1) programs with the **maxobase()** built-in function. The 359min allowable value for **obase** is **0**. If **obase** is **0**, values are 360output in scientific notation, and if **obase** is **1**, values are output in 361engineering notation. Otherwise, values are output in the specified base. 362 363Outputting in scientific and engineering notations are **non-portable 364extensions**. 365 366The *scale* of an expression is the number of digits in the result of the 367expression right of the decimal point, and **scale** is a global variable that 368sets the precision of any operations, with exceptions. **scale** is initially 369**0**. **scale** cannot be negative. The max allowable value for **scale** is 370**BC_SCALE_MAX** and can be queried in bc(1) programs with the **maxscale()** 371built-in function. 372 373bc(1) has both *global* variables and *local* variables. All *local* 374variables are local to the function; they are parameters or are introduced in 375the **auto** list of a function (see the **FUNCTIONS** section). If a variable 376is accessed which is not a parameter or in the **auto** list, it is assumed to 377be *global*. If a parent function has a *local* variable version of a variable 378that a child function considers *global*, the value of that *global* variable in 379the child function is the value of the variable in the parent function, not the 380value of the actual *global* variable. 381 382All of the above applies to arrays as well. 383 384The value of a statement that is an expression (i.e., any of the named 385expressions or operands) is printed unless the lowest precedence operator is an 386assignment operator *and* the expression is notsurrounded by parentheses. 387 388The value that is printed is also assigned to the special variable **last**. A 389single dot (**.**) may also be used as a synonym for **last**. These are 390**non-portable extensions**. 391 392Either semicolons or newlines may separate statements. 393 394## Comments 395 396There are two kinds of comments: 397 3981. Block comments are enclosed in **/\*** and **\*/**. 3992. Line comments go from **#** until, and not including, the next newline. This 400 is a **non-portable extension**. 401 402## Named Expressions 403 404The following are named expressions in bc(1): 405 4061. Variables: **I** 4072. Array Elements: **I[E]** 4083. **ibase** 4094. **obase** 4105. **scale** 4116. **seed** 4127. **last** or a single dot (**.**) 413 414Numbers 6 and 7 are **non-portable extensions**. 415 416The meaning of **seed** is dependent on the current pseudo-random number 417generator but is guaranteed to not change except for new major versions. 418 419The *scale* and sign of the value may be significant. 420 421If a previously used **seed** value is assigned to **seed** and used again, the 422pseudo-random number generator is guaranteed to produce the same sequence of 423pseudo-random numbers as it did when the **seed** value was previously used. 424 425The exact value assigned to **seed** is not guaranteed to be returned if 426**seed** is queried again immediately. However, if **seed** *does* return a 427different value, both values, when assigned to **seed**, are guaranteed to 428produce the same sequence of pseudo-random numbers. This means that certain 429values assigned to **seed** will *not* produce unique sequences of pseudo-random 430numbers. The value of **seed** will change after any use of the **rand()** and 431**irand(E)** operands (see the *Operands* subsection below), except if the 432parameter passed to **irand(E)** is **0**, **1**, or negative. 433 434There is no limit to the length (number of significant decimal digits) or 435*scale* of the value that can be assigned to **seed**. 436 437Variables and arrays do not interfere; users can have arrays named the same as 438variables. This also applies to functions (see the **FUNCTIONS** section), so a 439user can have a variable, array, and function that all have the same name, and 440they will not shadow each other, whether inside of functions or not. 441 442Named expressions are required as the operand of **increment**/**decrement** 443operators and as the left side of **assignment** operators (see the *Operators* 444subsection). 445 446## Operands 447 448The following are valid operands in bc(1): 449 4501. Numbers (see the *Numbers* subsection below). 4512. Array indices (**I[E]**). 4523. **(E)**: The value of **E** (used to change precedence). 4534. **sqrt(E)**: The square root of **E**. **E** must be non-negative. 4545. **length(E)**: The number of significant decimal digits in **E**. Returns 455 **1** for **0** with no decimal places. If given a string, the length of the 456 string is returned. Passing a string to **length(E)** is a **non-portable 457 extension**. 4586. **length(I[])**: The number of elements in the array **I**. This is a 459 **non-portable extension**. 4607. **scale(E)**: The *scale* of **E**. 4618. **abs(E)**: The absolute value of **E**. This is a **non-portable 462 extension**. 4639. **modexp(E, E, E)**: Modular exponentiation, where the first expression is 464 the base, the second is the exponent, and the third is the modulus. All 465 three values must be integers. The second argument must be non-negative. The 466 third argument must be non-zero. This is a **non-portable extension**. 46710. **divmod(E, E, I[])**: Division and modulus in one operation. This is for 468 optimization. The first expression is the dividend, and the second is the 469 divisor, which must be non-zero. The return value is the quotient, and the 470 modulus is stored in index **0** of the provided array (the last argument). 471 This is a **non-portable extension**. 47211. **asciify(E)**: If **E** is a string, returns a string that is the first 473 letter of its argument. If it is a number, calculates the number mod **256** 474 and returns that number as a one-character string. This is a **non-portable 475 extension**. 47612. **I()**, **I(E)**, **I(E, E)**, and so on, where **I** is an identifier for 477 a non-**void** function (see the *Void Functions* subsection of the 478 **FUNCTIONS** section). The **E** argument(s) may also be arrays of the form 479 **I[]**, which will automatically be turned into array references (see the 480 *Array References* subsection of the **FUNCTIONS** section) if the 481 corresponding parameter in the function definition is an array reference. 48213. **read()**: Reads a line from **stdin** and uses that as an expression. The 483 result of that expression is the result of the **read()** operand. This is a 484 **non-portable extension**. 48514. **maxibase()**: The max allowable **ibase**. This is a **non-portable 486 extension**. 48715. **maxobase()**: The max allowable **obase**. This is a **non-portable 488 extension**. 48916. **maxscale()**: The max allowable **scale**. This is a **non-portable 490 extension**. 49117. **rand()**: A pseudo-random integer between **0** (inclusive) and 492 **BC_RAND_MAX** (inclusive). Using this operand will change the value of 493 **seed**. This is a **non-portable extension**. 49418. **irand(E)**: A pseudo-random integer between **0** (inclusive) and the 495 value of **E** (exclusive). If **E** is negative or is a non-integer 496 (**E**'s *scale* is not **0**), an error is raised, and bc(1) resets (see 497 the **RESET** section) while **seed** remains unchanged. If **E** is larger 498 than **BC_RAND_MAX**, the higher bound is honored by generating several 499 pseudo-random integers, multiplying them by appropriate powers of 500 **BC_RAND_MAX+1**, and adding them together. Thus, the size of integer that 501 can be generated with this operand is unbounded. Using this operand will 502 change the value of **seed**, unless the value of **E** is **0** or **1**. 503 In that case, **0** is returned, and **seed** is *not* changed. This is a 504 **non-portable extension**. 50519. **maxrand()**: The max integer returned by **rand()**. This is a 506 **non-portable extension**. 507 508The integers generated by **rand()** and **irand(E)** are guaranteed to be as 509unbiased as possible, subject to the limitations of the pseudo-random number 510generator. 511 512**Note**: The values returned by the pseudo-random number generator with 513**rand()** and **irand(E)** are guaranteed to *NOT* be cryptographically secure. 514This is a consequence of using a seeded pseudo-random number generator. However, 515they *are* guaranteed to be reproducible with identical **seed** values. This 516means that the pseudo-random values from bc(1) should only be used where a 517reproducible stream of pseudo-random numbers is *ESSENTIAL*. In any other case, 518use a non-seeded pseudo-random number generator. 519 520## Numbers 521 522Numbers are strings made up of digits, uppercase letters, and at most **1** 523period for a radix. Numbers can have up to **BC_NUM_MAX** digits. Uppercase 524letters are equal to **9** + their position in the alphabet (i.e., **A** equals 525**10**, or **9+1**). If a digit or letter makes no sense with the current value 526of **ibase**, they are set to the value of the highest valid digit in **ibase**. 527 528Single-character numbers (i.e., **A** alone) take the value that they would have 529if they were valid digits, regardless of the value of **ibase**. This means that 530**A** alone always equals decimal **10** and **Z** alone always equals decimal 531**35**. 532 533In addition, bc(1) accepts numbers in scientific notation. These have the form 534**\<number\>e\<integer\>**. The exponent (the portion after the **e**) must be 535an integer. An example is **1.89237e9**, which is equal to **1892370000**. 536Negative exponents are also allowed, so **4.2890e-3** is equal to **0.0042890**. 537 538Using scientific notation is an error or warning if the **-s** or **-w**, 539respectively, command-line options (or equivalents) are given. 540 541**WARNING**: Both the number and the exponent in scientific notation are 542interpreted according to the current **ibase**, but the number is still 543multiplied by **10\^exponent** regardless of the current **ibase**. For example, 544if **ibase** is **16** and bc(1) is given the number string **FFeA**, the 545resulting decimal number will be **2550000000000**, and if bc(1) is given the 546number string **10e-4**, the resulting decimal number will be **0.0016**. 547 548Accepting input as scientific notation is a **non-portable extension**. 549 550## Operators 551 552The following arithmetic and logical operators can be used. They are listed in 553order of decreasing precedence. Operators in the same group have the same 554precedence. 555 556**++** **-\-** 557 558: Type: Prefix and Postfix 559 560 Associativity: None 561 562 Description: **increment**, **decrement** 563 564**-** **!** 565 566: Type: Prefix 567 568 Associativity: None 569 570 Description: **negation**, **boolean not** 571 572**\$** 573 574: Type: Postfix 575 576 Associativity: None 577 578 Description: **truncation** 579 580**\@** 581 582: Type: Binary 583 584 Associativity: Right 585 586 Description: **set precision** 587 588**\^** 589 590: Type: Binary 591 592 Associativity: Right 593 594 Description: **power** 595 596**\*** **/** **%** 597 598: Type: Binary 599 600 Associativity: Left 601 602 Description: **multiply**, **divide**, **modulus** 603 604**+** **-** 605 606: Type: Binary 607 608 Associativity: Left 609 610 Description: **add**, **subtract** 611 612**\<\<** **\>\>** 613 614: Type: Binary 615 616 Associativity: Left 617 618 Description: **shift left**, **shift right** 619 620**=** **\<\<=** **\>\>=** **+=** **-=** **\*=** **/=** **%=** **\^=** **\@=** 621 622: Type: Binary 623 624 Associativity: Right 625 626 Description: **assignment** 627 628**==** **\<=** **\>=** **!=** **\<** **\>** 629 630: Type: Binary 631 632 Associativity: Left 633 634 Description: **relational** 635 636**&&** 637 638: Type: Binary 639 640 Associativity: Left 641 642 Description: **boolean and** 643 644**||** 645 646: Type: Binary 647 648 Associativity: Left 649 650 Description: **boolean or** 651 652The operators will be described in more detail below. 653 654**++** **-\-** 655 656: The prefix and postfix **increment** and **decrement** operators behave 657 exactly like they would in C. They require a named expression (see the 658 *Named Expressions* subsection) as an operand. 659 660 The prefix versions of these operators are more efficient; use them where 661 possible. 662 663**-** 664 665: The **negation** operator returns **0** if a user attempts to negate any 666 expression with the value **0**. Otherwise, a copy of the expression with 667 its sign flipped is returned. 668 669**!** 670 671: The **boolean not** operator returns **1** if the expression is **0**, or 672 **0** otherwise. 673 674 This is a **non-portable extension**. 675 676**\$** 677 678: The **truncation** operator returns a copy of the given expression with all 679 of its *scale* removed. 680 681 This is a **non-portable extension**. 682 683**\@** 684 685: The **set precision** operator takes two expressions and returns a copy of 686 the first with its *scale* equal to the value of the second expression. That 687 could either mean that the number is returned without change (if the 688 *scale* of the first expression matches the value of the second 689 expression), extended (if it is less), or truncated (if it is more). 690 691 The second expression must be an integer (no *scale*) and non-negative. 692 693 This is a **non-portable extension**. 694 695**\^** 696 697: The **power** operator (not the **exclusive or** operator, as it would be in 698 C) takes two expressions and raises the first to the power of the value of 699 the second. The *scale* of the result is equal to **scale**. 700 701 The second expression must be an integer (no *scale*), and if it is 702 negative, the first value must be non-zero. 703 704**\*** 705 706: The **multiply** operator takes two expressions, multiplies them, and 707 returns the product. If **a** is the *scale* of the first expression and 708 **b** is the *scale* of the second expression, the *scale* of the result is 709 equal to **min(a+b,max(scale,a,b))** where **min()** and **max()** return 710 the obvious values. 711 712**/** 713 714: The **divide** operator takes two expressions, divides them, and returns the 715 quotient. The *scale* of the result shall be the value of **scale**. 716 717 The second expression must be non-zero. 718 719**%** 720 721: The **modulus** operator takes two expressions, **a** and **b**, and 722 evaluates them by 1) Computing **a/b** to current **scale** and 2) Using the 723 result of step 1 to calculate **a-(a/b)\*b** to *scale* 724 **max(scale+scale(b),scale(a))**. 725 726 The second expression must be non-zero. 727 728**+** 729 730: The **add** operator takes two expressions, **a** and **b**, and returns the 731 sum, with a *scale* equal to the max of the *scale*s of **a** and **b**. 732 733**-** 734 735: The **subtract** operator takes two expressions, **a** and **b**, and 736 returns the difference, with a *scale* equal to the max of the *scale*s of 737 **a** and **b**. 738 739**\<\<** 740 741: The **left shift** operator takes two expressions, **a** and **b**, and 742 returns a copy of the value of **a** with its decimal point moved **b** 743 places to the right. 744 745 The second expression must be an integer (no *scale*) and non-negative. 746 747 This is a **non-portable extension**. 748 749**\>\>** 750 751: The **right shift** operator takes two expressions, **a** and **b**, and 752 returns a copy of the value of **a** with its decimal point moved **b** 753 places to the left. 754 755 The second expression must be an integer (no *scale*) and non-negative. 756 757 This is a **non-portable extension**. 758 759**=** **\<\<=** **\>\>=** **+=** **-=** **\*=** **/=** **%=** **\^=** **\@=** 760 761: The **assignment** operators take two expressions, **a** and **b** where 762 **a** is a named expression (see the *Named Expressions* subsection). 763 764 For **=**, **b** is copied and the result is assigned to **a**. For all 765 others, **a** and **b** are applied as operands to the corresponding 766 arithmetic operator and the result is assigned to **a**. 767 768 The **assignment** operators that correspond to operators that are 769 extensions are themselves **non-portable extensions**. 770 771**==** **\<=** **\>=** **!=** **\<** **\>** 772 773: The **relational** operators compare two expressions, **a** and **b**, and 774 if the relation holds, according to C language semantics, the result is 775 **1**. Otherwise, it is **0**. 776 777 Note that unlike in C, these operators have a lower precedence than the 778 **assignment** operators, which means that **a=b\>c** is interpreted as 779 **(a=b)\>c**. 780 781 Also, unlike the [standard][1] requires, these operators can appear anywhere 782 any other expressions can be used. This allowance is a 783 **non-portable extension**. 784 785**&&** 786 787: The **boolean and** operator takes two expressions and returns **1** if both 788 expressions are non-zero, **0** otherwise. 789 790 This is *not* a short-circuit operator. 791 792 This is a **non-portable extension**. 793 794**||** 795 796: The **boolean or** operator takes two expressions and returns **1** if one 797 of the expressions is non-zero, **0** otherwise. 798 799 This is *not* a short-circuit operator. 800 801 This is a **non-portable extension**. 802 803## Statements 804 805The following items are statements: 806 8071. **E** 8082. **{** **S** **;** ... **;** **S** **}** 8093. **if** **(** **E** **)** **S** 8104. **if** **(** **E** **)** **S** **else** **S** 8115. **while** **(** **E** **)** **S** 8126. **for** **(** **E** **;** **E** **;** **E** **)** **S** 8137. An empty statement 8148. **break** 8159. **continue** 81610. **quit** 81711. **halt** 81812. **limits** 81913. A string of characters, enclosed in double quotes 82014. **print** **E** **,** ... **,** **E** 82115. **stream** **E** **,** ... **,** **E** 82216. **I()**, **I(E)**, **I(E, E)**, and so on, where **I** is an identifier for 823 a **void** function (see the *Void Functions* subsection of the 824 **FUNCTIONS** section). The **E** argument(s) may also be arrays of the form 825 **I[]**, which will automatically be turned into array references (see the 826 *Array References* subsection of the **FUNCTIONS** section) if the 827 corresponding parameter in the function definition is an array reference. 828 829Numbers 4, 9, 11, 12, 14, 15, and 16 are **non-portable extensions**. 830 831Also, as a **non-portable extension**, any or all of the expressions in the 832header of a for loop may be omitted. If the condition (second expression) is 833omitted, it is assumed to be a constant **1**. 834 835The **break** statement causes a loop to stop iterating and resume execution 836immediately following a loop. This is only allowed in loops. 837 838The **continue** statement causes a loop iteration to stop early and returns to 839the start of the loop, including testing the loop condition. This is only 840allowed in loops. 841 842The **if** **else** statement does the same thing as in C. 843 844The **quit** statement causes bc(1) to quit, even if it is on a branch that will 845not be executed (it is a compile-time command). 846 847The **halt** statement causes bc(1) to quit, if it is executed. (Unlike **quit** 848if it is on a branch of an **if** statement that is not executed, bc(1) does not 849quit.) 850 851The **limits** statement prints the limits that this bc(1) is subject to. This 852is like the **quit** statement in that it is a compile-time command. 853 854An expression by itself is evaluated and printed, followed by a newline. 855 856Both scientific notation and engineering notation are available for printing the 857results of expressions. Scientific notation is activated by assigning **0** to 858**obase**, and engineering notation is activated by assigning **1** to 859**obase**. To deactivate them, just assign a different value to **obase**. 860 861Scientific notation and engineering notation are disabled if bc(1) is run with 862either the **-s** or **-w** command-line options (or equivalents). 863 864Printing numbers in scientific notation and/or engineering notation is a 865**non-portable extension**. 866 867## Strings 868 869If strings appear as a statement by themselves, they are printed without a 870trailing newline. 871 872In addition to appearing as a lone statement by themselves, strings can be 873assigned to variables and array elements. They can also be passed to functions 874in variable parameters. 875 876If any statement that expects a string is given a variable that had a string 877assigned to it, the statement acts as though it had received a string. 878 879If any math operation is attempted on a string or a variable or array element 880that has been assigned a string, an error is raised, and bc(1) resets (see the 881**RESET** section). 882 883Assigning strings to variables and array elements and passing them to functions 884are **non-portable extensions**. 885 886## Print Statement 887 888The "expressions" in a **print** statement may also be strings. If they are, there 889are backslash escape sequences that are interpreted specially. What those 890sequences are, and what they cause to be printed, are shown below: 891 892**\\a**: **\\a** 893 894**\\b**: **\\b** 895 896**\\\\**: **\\** 897 898**\\e**: **\\** 899 900**\\f**: **\\f** 901 902**\\n**: **\\n** 903 904**\\q**: **"** 905 906**\\r**: **\\r** 907 908**\\t**: **\\t** 909 910Any other character following a backslash causes the backslash and character to 911be printed as-is. 912 913Any non-string expression in a print statement shall be assigned to **last**, 914like any other expression that is printed. 915 916## Stream Statement 917 918The "expressions in a **stream** statement may also be strings. 919 920If a **stream** statement is given a string, it prints the string as though the 921string had appeared as its own statement. In other words, the **stream** 922statement prints strings normally, without a newline. 923 924If a **stream** statement is given a number, a copy of it is truncated and its 925absolute value is calculated. The result is then printed as though **obase** is 926**256** and each digit is interpreted as an 8-bit ASCII character, making it a 927byte stream. 928 929## Order of Evaluation 930 931All expressions in a statment are evaluated left to right, except as necessary 932to maintain order of operations. This means, for example, assuming that **i** is 933equal to **0**, in the expression 934 935 a[i++] = i++ 936 937the first (or 0th) element of **a** is set to **1**, and **i** is equal to **2** 938at the end of the expression. 939 940This includes function arguments. Thus, assuming **i** is equal to **0**, this 941means that in the expression 942 943 x(i++, i++) 944 945the first argument passed to **x()** is **0**, and the second argument is **1**, 946while **i** is equal to **2** before the function starts executing. 947 948# FUNCTIONS 949 950Function definitions are as follows: 951 952``` 953define I(I,...,I){ 954 auto I,...,I 955 S;...;S 956 return(E) 957} 958``` 959 960Any **I** in the parameter list or **auto** list may be replaced with **I[]** to 961make a parameter or **auto** var an array, and any **I** in the parameter list 962may be replaced with **\*I[]** to make a parameter an array reference. Callers 963of functions that take array references should not put an asterisk in the call; 964they must be called with just **I[]** like normal array parameters and will be 965automatically converted into references. 966 967As a **non-portable extension**, the opening brace of a **define** statement may 968appear on the next line. 969 970As a **non-portable extension**, the return statement may also be in one of the 971following forms: 972 9731. **return** 9742. **return** **(** **)** 9753. **return** **E** 976 977The first two, or not specifying a **return** statement, is equivalent to 978**return (0)**, unless the function is a **void** function (see the *Void 979Functions* subsection below). 980 981## Void Functions 982 983Functions can also be **void** functions, defined as follows: 984 985``` 986define void I(I,...,I){ 987 auto I,...,I 988 S;...;S 989 return 990} 991``` 992 993They can only be used as standalone expressions, where such an expression would 994be printed alone, except in a print statement. 995 996Void functions can only use the first two **return** statements listed above. 997They can also omit the return statement entirely. 998 999The word "void" is not treated as a keyword; it is still possible to have 1000variables, arrays, and functions named **void**. The word "void" is only 1001treated specially right after the **define** keyword. 1002 1003This is a **non-portable extension**. 1004 1005## Array References 1006 1007For any array in the parameter list, if the array is declared in the form 1008 1009``` 1010*I[] 1011``` 1012 1013it is a **reference**. Any changes to the array in the function are reflected, 1014when the function returns, to the array that was passed in. 1015 1016Other than this, all function arguments are passed by value. 1017 1018This is a **non-portable extension**. 1019 1020# LIBRARY 1021 1022All of the functions below, including the functions in the extended math 1023library (see the *Extended Library* subsection below), are available when the 1024**-l** or **-\-mathlib** command-line flags are given, except that the extended 1025math library is not available when the **-s** option, the **-w** option, or 1026equivalents are given. 1027 1028## Standard Library 1029 1030The [standard][1] defines the following functions for the math library: 1031 1032**s(x)** 1033 1034: Returns the sine of **x**, which is assumed to be in radians. 1035 1036 This is a transcendental function (see the *Transcendental Functions* 1037 subsection below). 1038 1039**c(x)** 1040 1041: Returns the cosine of **x**, which is assumed to be in radians. 1042 1043 This is a transcendental function (see the *Transcendental Functions* 1044 subsection below). 1045 1046**a(x)** 1047 1048: Returns the arctangent of **x**, in radians. 1049 1050 This is a transcendental function (see the *Transcendental Functions* 1051 subsection below). 1052 1053**l(x)** 1054 1055: Returns the natural logarithm of **x**. 1056 1057 This is a transcendental function (see the *Transcendental Functions* 1058 subsection below). 1059 1060**e(x)** 1061 1062: Returns the mathematical constant **e** raised to the power of **x**. 1063 1064 This is a transcendental function (see the *Transcendental Functions* 1065 subsection below). 1066 1067**j(x, n)** 1068 1069: Returns the bessel integer order **n** (truncated) of **x**. 1070 1071 This is a transcendental function (see the *Transcendental Functions* 1072 subsection below). 1073 1074## Extended Library 1075 1076The extended library is *not* loaded when the **-s**/**-\-standard** or 1077**-w**/**-\-warn** options are given since they are not part of the library 1078defined by the [standard][1]. 1079 1080The extended library is a **non-portable extension**. 1081 1082**p(x, y)** 1083 1084: Calculates **x** to the power of **y**, even if **y** is not an integer, and 1085 returns the result to the current **scale**. 1086 1087 It is an error if **y** is negative and **x** is **0**. 1088 1089 This is a transcendental function (see the *Transcendental Functions* 1090 subsection below). 1091 1092**r(x, p)** 1093 1094: Returns **x** rounded to **p** decimal places according to the rounding mode 1095 [round half away from **0**][3]. 1096 1097**ceil(x, p)** 1098 1099: Returns **x** rounded to **p** decimal places according to the rounding mode 1100 [round away from **0**][6]. 1101 1102**f(x)** 1103 1104: Returns the factorial of the truncated absolute value of **x**. 1105 1106**perm(n, k)** 1107 1108: Returns the permutation of the truncated absolute value of **n** of the 1109 truncated absolute value of **k**, if **k \<= n**. If not, it returns **0**. 1110 1111**comb(n, k)** 1112 1113: Returns the combination of the truncated absolute value of **n** of the 1114 truncated absolute value of **k**, if **k \<= n**. If not, it returns **0**. 1115 1116**l2(x)** 1117 1118: Returns the logarithm base **2** of **x**. 1119 1120 This is a transcendental function (see the *Transcendental Functions* 1121 subsection below). 1122 1123**l10(x)** 1124 1125: Returns the logarithm base **10** of **x**. 1126 1127 This is a transcendental function (see the *Transcendental Functions* 1128 subsection below). 1129 1130**log(x, b)** 1131 1132: Returns the logarithm base **b** of **x**. 1133 1134 This is a transcendental function (see the *Transcendental Functions* 1135 subsection below). 1136 1137**cbrt(x)** 1138 1139: Returns the cube root of **x**. 1140 1141**root(x, n)** 1142 1143: Calculates the truncated value of **n**, **r**, and returns the **r**th root 1144 of **x** to the current **scale**. 1145 1146 If **r** is **0** or negative, this raises an error and causes bc(1) to 1147 reset (see the **RESET** section). It also raises an error and causes bc(1) 1148 to reset if **r** is even and **x** is negative. 1149 1150**gcd(a, b)** 1151 1152: Returns the greatest common divisor (factor) of the truncated absolute value 1153 of **a** and the truncated absolute value of **b**. 1154 1155**lcm(a, b)** 1156 1157: Returns the least common multiple of the truncated absolute value of **a** 1158 and the truncated absolute value of **b**. 1159 1160**pi(p)** 1161 1162: Returns **pi** to **p** decimal places. 1163 1164 This is a transcendental function (see the *Transcendental Functions* 1165 subsection below). 1166 1167**t(x)** 1168 1169: Returns the tangent of **x**, which is assumed to be in radians. 1170 1171 This is a transcendental function (see the *Transcendental Functions* 1172 subsection below). 1173 1174**a2(y, x)** 1175 1176: Returns the arctangent of **y/x**, in radians. If both **y** and **x** are 1177 equal to **0**, it raises an error and causes bc(1) to reset (see the 1178 **RESET** section). Otherwise, if **x** is greater than **0**, it returns 1179 **a(y/x)**. If **x** is less than **0**, and **y** is greater than or equal 1180 to **0**, it returns **a(y/x)+pi**. If **x** is less than **0**, and **y** 1181 is less than **0**, it returns **a(y/x)-pi**. If **x** is equal to **0**, 1182 and **y** is greater than **0**, it returns **pi/2**. If **x** is equal to 1183 **0**, and **y** is less than **0**, it returns **-pi/2**. 1184 1185 This function is the same as the **atan2()** function in many programming 1186 languages. 1187 1188 This is a transcendental function (see the *Transcendental Functions* 1189 subsection below). 1190 1191**sin(x)** 1192 1193: Returns the sine of **x**, which is assumed to be in radians. 1194 1195 This is an alias of **s(x)**. 1196 1197 This is a transcendental function (see the *Transcendental Functions* 1198 subsection below). 1199 1200**cos(x)** 1201 1202: Returns the cosine of **x**, which is assumed to be in radians. 1203 1204 This is an alias of **c(x)**. 1205 1206 This is a transcendental function (see the *Transcendental Functions* 1207 subsection below). 1208 1209**tan(x)** 1210 1211: Returns the tangent of **x**, which is assumed to be in radians. 1212 1213 If **x** is equal to **1** or **-1**, this raises an error and causes bc(1) 1214 to reset (see the **RESET** section). 1215 1216 This is an alias of **t(x)**. 1217 1218 This is a transcendental function (see the *Transcendental Functions* 1219 subsection below). 1220 1221**atan(x)** 1222 1223: Returns the arctangent of **x**, in radians. 1224 1225 This is an alias of **a(x)**. 1226 1227 This is a transcendental function (see the *Transcendental Functions* 1228 subsection below). 1229 1230**atan2(y, x)** 1231 1232: Returns the arctangent of **y/x**, in radians. If both **y** and **x** are 1233 equal to **0**, it raises an error and causes bc(1) to reset (see the 1234 **RESET** section). Otherwise, if **x** is greater than **0**, it returns 1235 **a(y/x)**. If **x** is less than **0**, and **y** is greater than or equal 1236 to **0**, it returns **a(y/x)+pi**. If **x** is less than **0**, and **y** 1237 is less than **0**, it returns **a(y/x)-pi**. If **x** is equal to **0**, 1238 and **y** is greater than **0**, it returns **pi/2**. If **x** is equal to 1239 **0**, and **y** is less than **0**, it returns **-pi/2**. 1240 1241 This function is the same as the **atan2()** function in many programming 1242 languages. 1243 1244 This is an alias of **a2(y, x)**. 1245 1246 This is a transcendental function (see the *Transcendental Functions* 1247 subsection below). 1248 1249**r2d(x)** 1250 1251: Converts **x** from radians to degrees and returns the result. 1252 1253 This is a transcendental function (see the *Transcendental Functions* 1254 subsection below). 1255 1256**d2r(x)** 1257 1258: Converts **x** from degrees to radians and returns the result. 1259 1260 This is a transcendental function (see the *Transcendental Functions* 1261 subsection below). 1262 1263**frand(p)** 1264 1265: Generates a pseudo-random number between **0** (inclusive) and **1** 1266 (exclusive) with the number of decimal digits after the decimal point equal 1267 to the truncated absolute value of **p**. If **p** is not **0**, then 1268 calling this function will change the value of **seed**. If **p** is **0**, 1269 then **0** is returned, and **seed** is *not* changed. 1270 1271**ifrand(i, p)** 1272 1273: Generates a pseudo-random number that is between **0** (inclusive) and the 1274 truncated absolute value of **i** (exclusive) with the number of decimal 1275 digits after the decimal point equal to the truncated absolute value of 1276 **p**. If the absolute value of **i** is greater than or equal to **2**, and 1277 **p** is not **0**, then calling this function will change the value of 1278 **seed**; otherwise, **0** is returned and **seed** is not changed. 1279 1280**srand(x)** 1281 1282: Returns **x** with its sign flipped with probability **0.5**. In other 1283 words, it randomizes the sign of **x**. 1284 1285**brand()** 1286 1287: Returns a random boolean value (either **0** or **1**). 1288 1289**band(a, b)** 1290 1291: Takes the truncated absolute value of both **a** and **b** and calculates 1292 and returns the result of the bitwise **and** operation between them. 1293 1294 If you want to use signed two's complement arguments, use **s2u(x)** to 1295 convert. 1296 1297**bor(a, b)** 1298 1299: Takes the truncated absolute value of both **a** and **b** and calculates 1300 and returns the result of the bitwise **or** operation between them. 1301 1302 If you want to use signed two's complement arguments, use **s2u(x)** to 1303 convert. 1304 1305**bxor(a, b)** 1306 1307: Takes the truncated absolute value of both **a** and **b** and calculates 1308 and returns the result of the bitwise **xor** operation between them. 1309 1310 If you want to use signed two's complement arguments, use **s2u(x)** to 1311 convert. 1312 1313**bshl(a, b)** 1314 1315: Takes the truncated absolute value of both **a** and **b** and calculates 1316 and returns the result of **a** bit-shifted left by **b** places. 1317 1318 If you want to use signed two's complement arguments, use **s2u(x)** to 1319 convert. 1320 1321**bshr(a, b)** 1322 1323: Takes the truncated absolute value of both **a** and **b** and calculates 1324 and returns the truncated result of **a** bit-shifted right by **b** places. 1325 1326 If you want to use signed two's complement arguments, use **s2u(x)** to 1327 convert. 1328 1329**bnotn(x, n)** 1330 1331: Takes the truncated absolute value of **x** and does a bitwise not as though 1332 it has the same number of bytes as the truncated absolute value of **n**. 1333 1334 If you want to a use signed two's complement argument, use **s2u(x)** to 1335 convert. 1336 1337**bnot8(x)** 1338 1339: Does a bitwise not of the truncated absolute value of **x** as though it has 1340 **8** binary digits (1 unsigned byte). 1341 1342 If you want to a use signed two's complement argument, use **s2u(x)** to 1343 convert. 1344 1345**bnot16(x)** 1346 1347: Does a bitwise not of the truncated absolute value of **x** as though it has 1348 **16** binary digits (2 unsigned bytes). 1349 1350 If you want to a use signed two's complement argument, use **s2u(x)** to 1351 convert. 1352 1353**bnot32(x)** 1354 1355: Does a bitwise not of the truncated absolute value of **x** as though it has 1356 **32** binary digits (4 unsigned bytes). 1357 1358 If you want to a use signed two's complement argument, use **s2u(x)** to 1359 convert. 1360 1361**bnot64(x)** 1362 1363: Does a bitwise not of the truncated absolute value of **x** as though it has 1364 **64** binary digits (8 unsigned bytes). 1365 1366 If you want to a use signed two's complement argument, use **s2u(x)** to 1367 convert. 1368 1369**bnot(x)** 1370 1371: Does a bitwise not of the truncated absolute value of **x** as though it has 1372 the minimum number of power of two unsigned bytes. 1373 1374 If you want to a use signed two's complement argument, use **s2u(x)** to 1375 convert. 1376 1377**brevn(x, n)** 1378 1379: Runs a bit reversal on the truncated absolute value of **x** as though it 1380 has the same number of 8-bit bytes as the truncated absolute value of **n**. 1381 1382 If you want to a use signed two's complement argument, use **s2u(x)** to 1383 convert. 1384 1385**brev8(x)** 1386 1387: Runs a bit reversal on the truncated absolute value of **x** as though it 1388 has 8 binary digits (1 unsigned byte). 1389 1390 If you want to a use signed two's complement argument, use **s2u(x)** to 1391 convert. 1392 1393**brev16(x)** 1394 1395: Runs a bit reversal on the truncated absolute value of **x** as though it 1396 has 16 binary digits (2 unsigned bytes). 1397 1398 If you want to a use signed two's complement argument, use **s2u(x)** to 1399 convert. 1400 1401**brev32(x)** 1402 1403: Runs a bit reversal on the truncated absolute value of **x** as though it 1404 has 32 binary digits (4 unsigned bytes). 1405 1406 If you want to a use signed two's complement argument, use **s2u(x)** to 1407 convert. 1408 1409**brev64(x)** 1410 1411: Runs a bit reversal on the truncated absolute value of **x** as though it 1412 has 64 binary digits (8 unsigned bytes). 1413 1414 If you want to a use signed two's complement argument, use **s2u(x)** to 1415 convert. 1416 1417**brev(x)** 1418 1419: Runs a bit reversal on the truncated absolute value of **x** as though it 1420 has the minimum number of power of two unsigned bytes. 1421 1422 If you want to a use signed two's complement argument, use **s2u(x)** to 1423 convert. 1424 1425**broln(x, p, n)** 1426 1427: Does a left bitwise rotatation of the truncated absolute value of **x**, as 1428 though it has the same number of unsigned 8-bit bytes as the truncated 1429 absolute value of **n**, by the number of places equal to the truncated 1430 absolute value of **p** modded by the **2** to the power of the number of 1431 binary digits in **n** 8-bit bytes. 1432 1433 If you want to a use signed two's complement argument, use **s2u(x)** to 1434 convert. 1435 1436**brol8(x, p)** 1437 1438: Does a left bitwise rotatation of the truncated absolute value of **x**, as 1439 though it has **8** binary digits (**1** unsigned byte), by the number of 1440 places equal to the truncated absolute value of **p** modded by **2** to the 1441 power of **8**. 1442 1443 If you want to a use signed two's complement argument, use **s2u(x)** to 1444 convert. 1445 1446**brol16(x, p)** 1447 1448: Does a left bitwise rotatation of the truncated absolute value of **x**, as 1449 though it has **16** binary digits (**2** unsigned bytes), by the number of 1450 places equal to the truncated absolute value of **p** modded by **2** to the 1451 power of **16**. 1452 1453 If you want to a use signed two's complement argument, use **s2u(x)** to 1454 convert. 1455 1456**brol32(x, p)** 1457 1458: Does a left bitwise rotatation of the truncated absolute value of **x**, as 1459 though it has **32** binary digits (**2** unsigned bytes), by the number of 1460 places equal to the truncated absolute value of **p** modded by **2** to the 1461 power of **32**. 1462 1463 If you want to a use signed two's complement argument, use **s2u(x)** to 1464 convert. 1465 1466**brol64(x, p)** 1467 1468: Does a left bitwise rotatation of the truncated absolute value of **x**, as 1469 though it has **64** binary digits (**2** unsigned bytes), by the number of 1470 places equal to the truncated absolute value of **p** modded by **2** to the 1471 power of **64**. 1472 1473 If you want to a use signed two's complement argument, use **s2u(x)** to 1474 convert. 1475 1476**brol(x, p)** 1477 1478: Does a left bitwise rotatation of the truncated absolute value of **x**, as 1479 though it has the minimum number of power of two unsigned 8-bit bytes, by 1480 the number of places equal to the truncated absolute value of **p** modded 1481 by 2 to the power of the number of binary digits in the minimum number of 1482 8-bit bytes. 1483 1484 If you want to a use signed two's complement argument, use **s2u(x)** to 1485 convert. 1486 1487**brorn(x, p, n)** 1488 1489: Does a right bitwise rotatation of the truncated absolute value of **x**, as 1490 though it has the same number of unsigned 8-bit bytes as the truncated 1491 absolute value of **n**, by the number of places equal to the truncated 1492 absolute value of **p** modded by the **2** to the power of the number of 1493 binary digits in **n** 8-bit bytes. 1494 1495 If you want to a use signed two's complement argument, use **s2u(x)** to 1496 convert. 1497 1498**bror8(x, p)** 1499 1500: Does a right bitwise rotatation of the truncated absolute value of **x**, as 1501 though it has **8** binary digits (**1** unsigned byte), by the number of 1502 places equal to the truncated absolute value of **p** modded by **2** to the 1503 power of **8**. 1504 1505 If you want to a use signed two's complement argument, use **s2u(x)** to 1506 convert. 1507 1508**bror16(x, p)** 1509 1510: Does a right bitwise rotatation of the truncated absolute value of **x**, as 1511 though it has **16** binary digits (**2** unsigned bytes), by the number of 1512 places equal to the truncated absolute value of **p** modded by **2** to the 1513 power of **16**. 1514 1515 If you want to a use signed two's complement argument, use **s2u(x)** to 1516 convert. 1517 1518**bror32(x, p)** 1519 1520: Does a right bitwise rotatation of the truncated absolute value of **x**, as 1521 though it has **32** binary digits (**2** unsigned bytes), by the number of 1522 places equal to the truncated absolute value of **p** modded by **2** to the 1523 power of **32**. 1524 1525 If you want to a use signed two's complement argument, use **s2u(x)** to 1526 convert. 1527 1528**bror64(x, p)** 1529 1530: Does a right bitwise rotatation of the truncated absolute value of **x**, as 1531 though it has **64** binary digits (**2** unsigned bytes), by the number of 1532 places equal to the truncated absolute value of **p** modded by **2** to the 1533 power of **64**. 1534 1535 If you want to a use signed two's complement argument, use **s2u(x)** to 1536 convert. 1537 1538**bror(x, p)** 1539 1540: Does a right bitwise rotatation of the truncated absolute value of **x**, as 1541 though it has the minimum number of power of two unsigned 8-bit bytes, by 1542 the number of places equal to the truncated absolute value of **p** modded 1543 by 2 to the power of the number of binary digits in the minimum number of 1544 8-bit bytes. 1545 1546 If you want to a use signed two's complement argument, use **s2u(x)** to 1547 convert. 1548 1549**bmodn(x, n)** 1550 1551: Returns the modulus of the truncated absolute value of **x** by **2** to the 1552 power of the multiplication of the truncated absolute value of **n** and 1553 **8**. 1554 1555 If you want to a use signed two's complement argument, use **s2u(x)** to 1556 convert. 1557 1558**bmod8(x, n)** 1559 1560: Returns the modulus of the truncated absolute value of **x** by **2** to the 1561 power of **8**. 1562 1563 If you want to a use signed two's complement argument, use **s2u(x)** to 1564 convert. 1565 1566**bmod16(x, n)** 1567 1568: Returns the modulus of the truncated absolute value of **x** by **2** to the 1569 power of **16**. 1570 1571 If you want to a use signed two's complement argument, use **s2u(x)** to 1572 convert. 1573 1574**bmod32(x, n)** 1575 1576: Returns the modulus of the truncated absolute value of **x** by **2** to the 1577 power of **32**. 1578 1579 If you want to a use signed two's complement argument, use **s2u(x)** to 1580 convert. 1581 1582**bmod64(x, n)** 1583 1584: Returns the modulus of the truncated absolute value of **x** by **2** to the 1585 power of **64**. 1586 1587 If you want to a use signed two's complement argument, use **s2u(x)** to 1588 convert. 1589 1590**bunrev(t)** 1591 1592: Assumes **t** is a bitwise-reversed number with an extra set bit one place 1593 more significant than the real most significant bit (which was the least 1594 significant bit in the original number). This number is reversed and 1595 returned without the extra set bit. 1596 1597 This function is used to implement other bitwise functions; it is not meant 1598 to be used by users, but it can be. 1599 1600**ubytes(x)** 1601 1602: Returns the numbers of unsigned integer bytes required to hold the truncated 1603 absolute value of **x**. 1604 1605**sbytes(x)** 1606 1607: Returns the numbers of signed, two's-complement integer bytes required to 1608 hold the truncated value of **x**. 1609 1610**s2u(x)** 1611 1612: Returns **x** if it is non-negative. If it *is* negative, then it calculates 1613 what **x** would be as a 2's-complement signed integer and returns the 1614 non-negative integer that would have the same representation in binary. 1615 1616**s2un(x,n)** 1617 1618: Returns **x** if it is non-negative. If it *is* negative, then it calculates 1619 what **x** would be as a 2's-complement signed integer with **n** bytes and 1620 returns the non-negative integer that would have the same representation in 1621 binary. If **x** cannot fit into **n** 2's-complement signed bytes, it is 1622 truncated to fit. 1623 1624**hex(x)** 1625 1626: Outputs the hexadecimal (base **16**) representation of **x**. 1627 1628 This is a **void** function (see the *Void Functions* subsection of the 1629 **FUNCTIONS** section). 1630 1631**binary(x)** 1632 1633: Outputs the binary (base **2**) representation of **x**. 1634 1635 This is a **void** function (see the *Void Functions* subsection of the 1636 **FUNCTIONS** section). 1637 1638**output(x, b)** 1639 1640: Outputs the base **b** representation of **x**. 1641 1642 This is a **void** function (see the *Void Functions* subsection of the 1643 **FUNCTIONS** section). 1644 1645**uint(x)** 1646 1647: Outputs the representation, in binary and hexadecimal, of **x** as an 1648 unsigned integer in as few power of two bytes as possible. Both outputs are 1649 split into bytes separated by spaces. 1650 1651 If **x** is not an integer or is negative, an error message is printed 1652 instead, but bc(1) is not reset (see the **RESET** section). 1653 1654 This is a **void** function (see the *Void Functions* subsection of the 1655 **FUNCTIONS** section). 1656 1657**int(x)** 1658 1659: Outputs the representation, in binary and hexadecimal, of **x** as a signed, 1660 two's-complement integer in as few power of two bytes as possible. Both 1661 outputs are split into bytes separated by spaces. 1662 1663 If **x** is not an integer, an error message is printed instead, but bc(1) 1664 is not reset (see the **RESET** section). 1665 1666 This is a **void** function (see the *Void Functions* subsection of the 1667 **FUNCTIONS** section). 1668 1669**uintn(x, n)** 1670 1671: Outputs the representation, in binary and hexadecimal, of **x** as an 1672 unsigned integer in **n** bytes. Both outputs are split into bytes separated 1673 by spaces. 1674 1675 If **x** is not an integer, is negative, or cannot fit into **n** bytes, an 1676 error message is printed instead, but bc(1) is not reset (see the **RESET** 1677 section). 1678 1679 This is a **void** function (see the *Void Functions* subsection of the 1680 **FUNCTIONS** section). 1681 1682**intn(x, n)** 1683 1684: Outputs the representation, in binary and hexadecimal, of **x** as a signed, 1685 two's-complement integer in **n** bytes. Both outputs are split into bytes 1686 separated by spaces. 1687 1688 If **x** is not an integer or cannot fit into **n** bytes, an error message 1689 is printed instead, but bc(1) is not reset (see the **RESET** section). 1690 1691 This is a **void** function (see the *Void Functions* subsection of the 1692 **FUNCTIONS** section). 1693 1694**uint8(x)** 1695 1696: Outputs the representation, in binary and hexadecimal, of **x** as an 1697 unsigned integer in **1** byte. Both outputs are split into bytes separated 1698 by spaces. 1699 1700 If **x** is not an integer, is negative, or cannot fit into **1** byte, an 1701 error message is printed instead, but bc(1) is not reset (see the **RESET** 1702 section). 1703 1704 This is a **void** function (see the *Void Functions* subsection of the 1705 **FUNCTIONS** section). 1706 1707**int8(x)** 1708 1709: Outputs the representation, in binary and hexadecimal, of **x** as a signed, 1710 two's-complement integer in **1** byte. Both outputs are split into bytes 1711 separated by spaces. 1712 1713 If **x** is not an integer or cannot fit into **1** byte, an error message 1714 is printed instead, but bc(1) is not reset (see the **RESET** section). 1715 1716 This is a **void** function (see the *Void Functions* subsection of the 1717 **FUNCTIONS** section). 1718 1719**uint16(x)** 1720 1721: Outputs the representation, in binary and hexadecimal, of **x** as an 1722 unsigned integer in **2** bytes. Both outputs are split into bytes separated 1723 by spaces. 1724 1725 If **x** is not an integer, is negative, or cannot fit into **2** bytes, an 1726 error message is printed instead, but bc(1) is not reset (see the **RESET** 1727 section). 1728 1729 This is a **void** function (see the *Void Functions* subsection of the 1730 **FUNCTIONS** section). 1731 1732**int16(x)** 1733 1734: Outputs the representation, in binary and hexadecimal, of **x** as a signed, 1735 two's-complement integer in **2** bytes. Both outputs are split into bytes 1736 separated by spaces. 1737 1738 If **x** is not an integer or cannot fit into **2** bytes, an error message 1739 is printed instead, but bc(1) is not reset (see the **RESET** section). 1740 1741 This is a **void** function (see the *Void Functions* subsection of the 1742 **FUNCTIONS** section). 1743 1744**uint32(x)** 1745 1746: Outputs the representation, in binary and hexadecimal, of **x** as an 1747 unsigned integer in **4** bytes. Both outputs are split into bytes separated 1748 by spaces. 1749 1750 If **x** is not an integer, is negative, or cannot fit into **4** bytes, an 1751 error message is printed instead, but bc(1) is not reset (see the **RESET** 1752 section). 1753 1754 This is a **void** function (see the *Void Functions* subsection of the 1755 **FUNCTIONS** section). 1756 1757**int32(x)** 1758 1759: Outputs the representation, in binary and hexadecimal, of **x** as a signed, 1760 two's-complement integer in **4** bytes. Both outputs are split into bytes 1761 separated by spaces. 1762 1763 If **x** is not an integer or cannot fit into **4** bytes, an error message 1764 is printed instead, but bc(1) is not reset (see the **RESET** section). 1765 1766 This is a **void** function (see the *Void Functions* subsection of the 1767 **FUNCTIONS** section). 1768 1769**uint64(x)** 1770 1771: Outputs the representation, in binary and hexadecimal, of **x** as an 1772 unsigned integer in **8** bytes. Both outputs are split into bytes separated 1773 by spaces. 1774 1775 If **x** is not an integer, is negative, or cannot fit into **8** bytes, an 1776 error message is printed instead, but bc(1) is not reset (see the **RESET** 1777 section). 1778 1779 This is a **void** function (see the *Void Functions* subsection of the 1780 **FUNCTIONS** section). 1781 1782**int64(x)** 1783 1784: Outputs the representation, in binary and hexadecimal, of **x** as a signed, 1785 two's-complement integer in **8** bytes. Both outputs are split into bytes 1786 separated by spaces. 1787 1788 If **x** is not an integer or cannot fit into **8** bytes, an error message 1789 is printed instead, but bc(1) is not reset (see the **RESET** section). 1790 1791 This is a **void** function (see the *Void Functions* subsection of the 1792 **FUNCTIONS** section). 1793 1794**hex_uint(x, n)** 1795 1796: Outputs the representation of the truncated absolute value of **x** as an 1797 unsigned integer in hexadecimal using **n** bytes. Not all of the value will 1798 be output if **n** is too small. 1799 1800 This is a **void** function (see the *Void Functions* subsection of the 1801 **FUNCTIONS** section). 1802 1803**binary_uint(x, n)** 1804 1805: Outputs the representation of the truncated absolute value of **x** as an 1806 unsigned integer in binary using **n** bytes. Not all of the value will be 1807 output if **n** is too small. 1808 1809 This is a **void** function (see the *Void Functions* subsection of the 1810 **FUNCTIONS** section). 1811 1812**output_uint(x, n)** 1813 1814: Outputs the representation of the truncated absolute value of **x** as an 1815 unsigned integer in the current **obase** (see the **SYNTAX** section) using 1816 **n** bytes. Not all of the value will be output if **n** is too small. 1817 1818 This is a **void** function (see the *Void Functions* subsection of the 1819 **FUNCTIONS** section). 1820 1821**output_byte(x, i)** 1822 1823: Outputs byte **i** of the truncated absolute value of **x**, where **0** is 1824 the least significant byte and **number_of_bytes - 1** is the most 1825 significant byte. 1826 1827 This is a **void** function (see the *Void Functions* subsection of the 1828 **FUNCTIONS** section). 1829 1830## Transcendental Functions 1831 1832All transcendental functions can return slightly inaccurate results (up to 1 1833[ULP][4]). This is unavoidable, and [this article][5] explains why it is 1834impossible and unnecessary to calculate exact results for the transcendental 1835functions. 1836 1837Because of the possible inaccuracy, I recommend that users call those functions 1838with the precision (**scale**) set to at least 1 higher than is necessary. If 1839exact results are *absolutely* required, users can double the precision 1840(**scale**) and then truncate. 1841 1842The transcendental functions in the standard math library are: 1843 1844* **s(x)** 1845* **c(x)** 1846* **a(x)** 1847* **l(x)** 1848* **e(x)** 1849* **j(x, n)** 1850 1851The transcendental functions in the extended math library are: 1852 1853* **l2(x)** 1854* **l10(x)** 1855* **log(x, b)** 1856* **pi(p)** 1857* **t(x)** 1858* **a2(y, x)** 1859* **sin(x)** 1860* **cos(x)** 1861* **tan(x)** 1862* **atan(x)** 1863* **atan2(y, x)** 1864* **r2d(x)** 1865* **d2r(x)** 1866 1867# RESET 1868 1869When bc(1) encounters an error or a signal that it has a non-default handler 1870for, it resets. This means that several things happen. 1871 1872First, any functions that are executing are stopped and popped off the stack. 1873The behavior is not unlike that of exceptions in programming languages. Then 1874the execution point is set so that any code waiting to execute (after all 1875functions returned) is skipped. 1876 1877Thus, when bc(1) resets, it skips any remaining code waiting to be executed. 1878Then, if it is interactive mode, and the error was not a fatal error (see the 1879**EXIT STATUS** section), it asks for more input; otherwise, it exits with the 1880appropriate return code. 1881 1882Note that this reset behavior is different from the GNU bc(1), which attempts to 1883start executing the statement right after the one that caused an error. 1884 1885# PERFORMANCE 1886 1887Most bc(1) implementations use **char** types to calculate the value of **1** 1888decimal digit at a time, but that can be slow. This bc(1) does something 1889different. 1890 1891It uses large integers to calculate more than **1** decimal digit at a time. If 1892built in a environment where **BC_LONG_BIT** (see the **LIMITS** section) is 1893**64**, then each integer has **9** decimal digits. If built in an environment 1894where **BC_LONG_BIT** is **32** then each integer has **4** decimal digits. This 1895value (the number of decimal digits per large integer) is called 1896**BC_BASE_DIGS**. 1897 1898The actual values of **BC_LONG_BIT** and **BC_BASE_DIGS** can be queried with 1899the **limits** statement. 1900 1901In addition, this bc(1) uses an even larger integer for overflow checking. This 1902integer type depends on the value of **BC_LONG_BIT**, but is always at least 1903twice as large as the integer type used to store digits. 1904 1905# LIMITS 1906 1907The following are the limits on bc(1): 1908 1909**BC_LONG_BIT** 1910 1911: The number of bits in the **long** type in the environment where bc(1) was 1912 built. This determines how many decimal digits can be stored in a single 1913 large integer (see the **PERFORMANCE** section). 1914 1915**BC_BASE_DIGS** 1916 1917: The number of decimal digits per large integer (see the **PERFORMANCE** 1918 section). Depends on **BC_LONG_BIT**. 1919 1920**BC_BASE_POW** 1921 1922: The max decimal number that each large integer can store (see 1923 **BC_BASE_DIGS**) plus **1**. Depends on **BC_BASE_DIGS**. 1924 1925**BC_OVERFLOW_MAX** 1926 1927: The max number that the overflow type (see the **PERFORMANCE** section) can 1928 hold. Depends on **BC_LONG_BIT**. 1929 1930**BC_BASE_MAX** 1931 1932: The maximum output base. Set at **BC_BASE_POW**. 1933 1934**BC_DIM_MAX** 1935 1936: The maximum size of arrays. Set at **SIZE_MAX-1**. 1937 1938**BC_SCALE_MAX** 1939 1940: The maximum **scale**. Set at **BC_OVERFLOW_MAX-1**. 1941 1942**BC_STRING_MAX** 1943 1944: The maximum length of strings. Set at **BC_OVERFLOW_MAX-1**. 1945 1946**BC_NAME_MAX** 1947 1948: The maximum length of identifiers. Set at **BC_OVERFLOW_MAX-1**. 1949 1950**BC_NUM_MAX** 1951 1952: The maximum length of a number (in decimal digits), which includes digits 1953 after the decimal point. Set at **BC_OVERFLOW_MAX-1**. 1954 1955**BC_RAND_MAX** 1956 1957: The maximum integer (inclusive) returned by the **rand()** operand. Set at 1958 **2\^BC_LONG_BIT-1**. 1959 1960Exponent 1961 1962: The maximum allowable exponent (positive or negative). Set at 1963 **BC_OVERFLOW_MAX**. 1964 1965Number of vars 1966 1967: The maximum number of vars/arrays. Set at **SIZE_MAX-1**. 1968 1969The actual values can be queried with the **limits** statement. 1970 1971These limits are meant to be effectively non-existent; the limits are so large 1972(at least on 64-bit machines) that there should not be any point at which they 1973become a problem. In fact, memory should be exhausted before these limits should 1974be hit. 1975 1976# ENVIRONMENT VARIABLES 1977 1978bc(1) recognizes the following environment variables: 1979 1980**POSIXLY_CORRECT** 1981 1982: If this variable exists (no matter the contents), bc(1) behaves as if 1983 the **-s** option was given. 1984 1985**BC_ENV_ARGS** 1986 1987: This is another way to give command-line arguments to bc(1). They should be 1988 in the same format as all other command-line arguments. These are always 1989 processed first, so any files given in **BC_ENV_ARGS** will be processed 1990 before arguments and files given on the command-line. This gives the user 1991 the ability to set up "standard" options and files to be used at every 1992 invocation. The most useful thing for such files to contain would be useful 1993 functions that the user might want every time bc(1) runs. 1994 1995 The code that parses **BC_ENV_ARGS** will correctly handle quoted arguments, 1996 but it does not understand escape sequences. For example, the string 1997 **"/home/gavin/some bc file.bc"** will be correctly parsed, but the string 1998 **"/home/gavin/some \"bc\" file.bc"** will include the backslashes. 1999 2000 The quote parsing will handle either kind of quotes, **'** or **"**. Thus, 2001 if you have a file with any number of single quotes in the name, you can use 2002 double quotes as the outside quotes, as in **"some 'bc' file.bc"**, and vice 2003 versa if you have a file with double quotes. However, handling a file with 2004 both kinds of quotes in **BC_ENV_ARGS** is not supported due to the 2005 complexity of the parsing, though such files are still supported on the 2006 command-line where the parsing is done by the shell. 2007 2008**BC_LINE_LENGTH** 2009 2010: If this environment variable exists and contains an integer that is greater 2011 than **1** and is less than **UINT16_MAX** (**2\^16-1**), bc(1) will output 2012 lines to that length, including the backslash (**\\**). The default line 2013 length is **70**. 2014 2015**BC_BANNER** 2016 2017: If this environment variable exists and contains an integer, then a non-zero 2018 value activates the copyright banner when bc(1) is in interactive mode, 2019 while zero deactivates it. 2020 2021 If bc(1) is not in interactive mode (see the **INTERACTIVE MODE** section), 2022 then this environment variable has no effect because bc(1) does not print 2023 the banner when not in interactive mode. 2024 2025 This environment variable overrides the default, which can be queried with 2026 the **-h** or **-\-help** options. 2027 2028**BC_SIGINT_RESET** 2029 2030: If bc(1) is not in interactive mode (see the **INTERACTIVE MODE** section), 2031 then this environment variable has no effect because bc(1) exits on 2032 **SIGINT** when not in interactive mode. 2033 2034 However, when bc(1) is in interactive mode, then if this environment 2035 variable exists and contains an integer, a non-zero value makes bc(1) reset 2036 on **SIGINT**, rather than exit, and zero makes bc(1) exit. If this 2037 environment variable exists and is *not* an integer, then bc(1) will exit on 2038 **SIGINT**. 2039 2040 This environment variable overrides the default, which can be queried with 2041 the **-h** or **-\-help** options. 2042 2043**BC_TTY_MODE** 2044 2045: If TTY mode is *not* available (see the **TTY MODE** section), then this 2046 environment variable has no effect. 2047 2048 However, when TTY mode is available, then if this environment variable 2049 exists and contains an integer, then a non-zero value makes bc(1) use TTY 2050 mode, and zero makes bc(1) not use TTY mode. 2051 2052 This environment variable overrides the default, which can be queried with 2053 the **-h** or **-\-help** options. 2054 2055**BC_PROMPT** 2056 2057: If TTY mode is *not* available (see the **TTY MODE** section), then this 2058 environment variable has no effect. 2059 2060 However, when TTY mode is available, then if this environment variable 2061 exists and contains an integer, a non-zero value makes bc(1) use a prompt, 2062 and zero or a non-integer makes bc(1) not use a prompt. If this environment 2063 variable does not exist and **BC_TTY_MODE** does, then the value of the 2064 **BC_TTY_MODE** environment variable is used. 2065 2066 This environment variable and the **BC_TTY_MODE** environment variable 2067 override the default, which can be queried with the **-h** or **-\-help** 2068 options. 2069 2070# EXIT STATUS 2071 2072bc(1) returns the following exit statuses: 2073 2074**0** 2075 2076: No error. 2077 2078**1** 2079 2080: A math error occurred. This follows standard practice of using **1** for 2081 expected errors, since math errors will happen in the process of normal 2082 execution. 2083 2084 Math errors include divide by **0**, taking the square root of a negative 2085 number, using a negative number as a bound for the pseudo-random number 2086 generator, attempting to convert a negative number to a hardware integer, 2087 overflow when converting a number to a hardware integer, overflow when 2088 calculating the size of a number, and attempting to use a non-integer where 2089 an integer is required. 2090 2091 Converting to a hardware integer happens for the second operand of the power 2092 (**\^**), places (**\@**), left shift (**\<\<**), and right shift (**\>\>**) 2093 operators and their corresponding assignment operators. 2094 2095**2** 2096 2097: A parse error occurred. 2098 2099 Parse errors include unexpected **EOF**, using an invalid character, failing 2100 to find the end of a string or comment, using a token where it is invalid, 2101 giving an invalid expression, giving an invalid print statement, giving an 2102 invalid function definition, attempting to assign to an expression that is 2103 not a named expression (see the *Named Expressions* subsection of the 2104 **SYNTAX** section), giving an invalid **auto** list, having a duplicate 2105 **auto**/function parameter, failing to find the end of a code block, 2106 attempting to return a value from a **void** function, attempting to use a 2107 variable as a reference, and using any extensions when the option **-s** or 2108 any equivalents were given. 2109 2110**3** 2111 2112: A runtime error occurred. 2113 2114 Runtime errors include assigning an invalid number to any global (**ibase**, 2115 **obase**, or **scale**), giving a bad expression to a **read()** call, 2116 calling **read()** inside of a **read()** call, type errors, passing the 2117 wrong number of arguments to functions, attempting to call an undefined 2118 function, and attempting to use a **void** function call as a value in an 2119 expression. 2120 2121**4** 2122 2123: A fatal error occurred. 2124 2125 Fatal errors include memory allocation errors, I/O errors, failing to open 2126 files, attempting to use files that do not have only ASCII characters (bc(1) 2127 only accepts ASCII characters), attempting to open a directory as a file, 2128 and giving invalid command-line options. 2129 2130The exit status **4** is special; when a fatal error occurs, bc(1) always exits 2131and returns **4**, no matter what mode bc(1) is in. 2132 2133The other statuses will only be returned when bc(1) is not in interactive mode 2134(see the **INTERACTIVE MODE** section), since bc(1) resets its state (see the 2135**RESET** section) and accepts more input when one of those errors occurs in 2136interactive mode. This is also the case when interactive mode is forced by the 2137**-i** flag or **-\-interactive** option. 2138 2139These exit statuses allow bc(1) to be used in shell scripting with error 2140checking, and its normal behavior can be forced by using the **-i** flag or 2141**-\-interactive** option. 2142 2143# INTERACTIVE MODE 2144 2145Per the [standard][1], bc(1) has an interactive mode and a non-interactive mode. 2146Interactive mode is turned on automatically when both **stdin** and **stdout** 2147are hooked to a terminal, but the **-i** flag and **-\-interactive** option can 2148turn it on in other situations. 2149 2150In interactive mode, bc(1) attempts to recover from errors (see the **RESET** 2151section), and in normal execution, flushes **stdout** as soon as execution is 2152done for the current input. bc(1) may also reset on **SIGINT** instead of exit, 2153depending on the contents of, or default for, the **BC_SIGINT_RESET** 2154environment variable (see the **ENVIRONMENT VARIABLES** section). 2155 2156# TTY MODE 2157 2158If **stdin**, **stdout**, and **stderr** are all connected to a TTY, then "TTY 2159mode" is considered to be available, and thus, bc(1) can turn on TTY mode, 2160subject to some settings. 2161 2162If there is the environment variable **BC_TTY_MODE** in the environment (see the 2163**ENVIRONMENT VARIABLES** section), then if that environment variable contains a 2164non-zero integer, bc(1) will turn on TTY mode when **stdin**, **stdout**, and 2165**stderr** are all connected to a TTY. If the **BC_TTY_MODE** environment 2166variable exists but is *not* a non-zero integer, then bc(1) will not turn TTY 2167mode on. 2168 2169If the environment variable **BC_TTY_MODE** does *not* exist, the default 2170setting is used. The default setting can be queried with the **-h** or 2171**-\-help** options. 2172 2173TTY mode is different from interactive mode because interactive mode is required 2174in the [bc(1) specification][1], and interactive mode requires only **stdin** 2175and **stdout** to be connected to a terminal. 2176 2177## Prompt 2178 2179If TTY mode is available, then a prompt can be enabled. Like TTY mode itself, it 2180can be turned on or off with an environment variable: **BC_PROMPT** (see the 2181**ENVIRONMENT VARIABLES** section). 2182 2183If the environment variable **BC_PROMPT** exists and is a non-zero integer, then 2184the prompt is turned on when **stdin**, **stdout**, and **stderr** are connected 2185to a TTY and the **-P** and **-\-no-prompt** options were not used. The read 2186prompt will be turned on under the same conditions, except that the **-R** and 2187**-\-no-read-prompt** options must also not be used. 2188 2189However, if **BC_PROMPT** does not exist, the prompt can be enabled or disabled 2190with the **BC_TTY_MODE** environment variable, the **-P** and **-\-no-prompt** 2191options, and the **-R** and **-\-no-read-prompt** options. See the **ENVIRONMENT 2192VARIABLES** and **OPTIONS** sections for more details. 2193 2194# SIGNAL HANDLING 2195 2196Sending a **SIGINT** will cause bc(1) to do one of two things. 2197 2198If bc(1) is not in interactive mode (see the **INTERACTIVE MODE** section), or 2199the **BC_SIGINT_RESET** environment variable (see the **ENVIRONMENT VARIABLES** 2200section), or its default, is either not an integer or it is zero, bc(1) will 2201exit. 2202 2203However, if bc(1) is in interactive mode, and the **BC_SIGINT_RESET** or its 2204default is an integer and non-zero, then bc(1) will stop executing the current 2205input and reset (see the **RESET** section) upon receiving a **SIGINT**. 2206 2207Note that "current input" can mean one of two things. If bc(1) is processing 2208input from **stdin** in interactive mode, it will ask for more input. If bc(1) 2209is processing input from a file in interactive mode, it will stop processing the 2210file and start processing the next file, if one exists, or ask for input from 2211**stdin** if no other file exists. 2212 2213This means that if a **SIGINT** is sent to bc(1) as it is executing a file, it 2214can seem as though bc(1) did not respond to the signal since it will immediately 2215start executing the next file. This is by design; most files that users execute 2216when interacting with bc(1) have function definitions, which are quick to parse. 2217If a file takes a long time to execute, there may be a bug in that file. The 2218rest of the files could still be executed without problem, allowing the user to 2219continue. 2220 2221**SIGTERM** and **SIGQUIT** cause bc(1) to clean up and exit, and it uses the 2222default handler for all other signals. 2223 2224# LOCALES 2225 2226This bc(1) ships with support for adding error messages for different locales 2227and thus, supports **LC_MESSAGES**. 2228 2229# SEE ALSO 2230 2231dc(1) 2232 2233# STANDARDS 2234 2235bc(1) is compliant with the [IEEE Std 1003.1-2017 (“POSIX.1-2017”)][1] 2236specification. The flags **-efghiqsvVw**, all long options, and the extensions 2237noted above are extensions to that specification. 2238 2239Note that the specification explicitly says that bc(1) only accepts numbers that 2240use a period (**.**) as a radix point, regardless of the value of 2241**LC_NUMERIC**. 2242 2243This bc(1) supports error messages for different locales, and thus, it supports 2244**LC_MESSAGES**. 2245 2246# BUGS 2247 2248None are known. Report bugs at https://git.yzena.com/gavin/bc. 2249 2250# AUTHORS 2251 2252Gavin D. Howard <gavin@yzena.com> and contributors. 2253 2254[1]: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html 2255[2]: https://www.gnu.org/software/bc/ 2256[3]: https://en.wikipedia.org/wiki/Rounding#Round_half_away_from_zero 2257[4]: https://en.wikipedia.org/wiki/Unit_in_the_last_place 2258[5]: https://people.eecs.berkeley.edu/~wkahan/LOG10HAF.TXT 2259[6]: https://en.wikipedia.org/wiki/Rounding#Rounding_away_from_zero 2260