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