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