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