contrib/bc/manuals/bc/HNP.1.md

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