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