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