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