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