manuals/bc/EP.1.md

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