contrib/bc/manuals/bc/EP.1.md

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