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

   1 <!---
   2
   3 SPDX-License-Identifier: BSD-2-Clause
   4
   5 Copyright (c) 2018-2021 Gavin D. Howard and contributors.
   6
   7 Redistribution and use in source and binary forms, with or without
   8 modification, are permitted provided that the following conditions are met:
   9
  10 * Redistributions of source code must retain the above copyright notice, this
  11   list of conditions and the following disclaimer.
  12
  13 * Redistributions in binary form must reproduce the above copyright notice,
  14   this list of conditions and the following disclaimer in the documentation
  15   and/or other materials provided with the distribution.
  16
  17 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  18 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
  21 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  22 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  23 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  24 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  25 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  26 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  27 POSSIBILITY OF SUCH DAMAGE.
  28
  29 -->
  30
  31 # Name
  32
  33 dc - arbitrary-precision decimal reverse-Polish notation calculator
  34
  35 # SYNOPSIS
  36
  37 **dc** [**-hiPvVx**] [**--version**] [**--help**] [**--interactive**] [**--no-prompt**] [**--extended-register**] [**-e** *expr*] [**--expression**=*expr*...] [**-f** *file*...] [**-file**=*file*...] [*file*...]
  38
  39 # DESCRIPTION
  40
  41 dc(1) is an arbitrary-precision calculator. It uses a stack (reverse Polish
  42 notation) to store numbers and results of computations. Arithmetic operations
  43 pop arguments off of the stack and push the results.
  44
  45 If no files are given on the command-line as extra arguments (i.e., not as
  46 **-f** or **--file** arguments), then dc(1) reads from **stdin**. Otherwise,
  47 those files are processed, and dc(1) will then exit.
  48
  49 This is different from the dc(1) on OpenBSD and possibly other dc(1)
  50 implementations, where **-e** (**--expression**) and **-f** (**--file**)
  51 arguments cause dc(1) to execute them and exit. The reason for this is that this
  52 dc(1) allows users to set arguments in the environment variable **DC_ENV_ARGS**
  53 (see the **ENVIRONMENT VARIABLES** section). Any expressions given on the
  54 command-line should be used to set up a standard environment. For example, if a
  55 user wants the **scale** always set to **10**, they can set **DC_ENV_ARGS** to
  56 **-e 10k**, and this dc(1) will always start with a **scale** of **10**.
  57
  58 If users want to have dc(1) exit after processing all input from **-e** and
  59 **-f** arguments (and their equivalents), then they can just simply add **-e q**
  60 as the last command-line argument or define the environment variable
  61 **DC_EXPR_EXIT**.
  62
  63 # OPTIONS
  64
  65 The following are the options that dc(1) accepts.
  66
  67 **-h**, **--help**
  68
  69 :   Prints a usage message and quits.
  70
  71 **-v**, **-V**, **--version**
  72
  73 :   Print the version information (copyright header) and exit.
  74
  75 **-i**, **--interactive**
  76
  77 :   Forces interactive mode. (See the **INTERACTIVE MODE** section.)
  78
  79     This is a **non-portable extension**.
  80
  81 **-P**, **--no-prompt**
  82
  83 :   This option is a no-op.
  84
  85     This is a **non-portable extension**.
  86
  87 **-x** **--extended-register**
  88
  89 :   Enables extended register mode. See the *Extended Register Mode* subsection
  90     of the **REGISTERS** section for more information.
  91
  92     This is a **non-portable extension**.
  93
  94 **-e** *expr*, **--expression**=*expr*
  95
  96 :   Evaluates *expr*. If multiple expressions are given, they are evaluated in
  97     order. If files are given as well (see below), the expressions and files are
  98     evaluated in the order given. This means that if a file is given before an
  99     expression, the file is read in and evaluated first.
 100
 101     If this option is given on the command-line (i.e., not in **DC_ENV_ARGS**,
 102     see the **ENVIRONMENT VARIABLES** section), then after processing all
 103     expressions and files, dc(1) will exit, unless **-** (**stdin**) was given
 104     as an argument at least once to **-f** or **--file**, whether on the
 105     command-line or in **DC_ENV_ARGS**. However, if any other **-e**,
 106     **--expression**, **-f**, or **--file** arguments are given after **-f-** or
 107     equivalent is given, dc(1) will give a fatal error and exit.
 108
 109     This is a **non-portable extension**.
 110
 111 **-f** *file*, **--file**=*file*
 112
 113 :   Reads in *file* and evaluates it, line by line, as though it were read
 114     through **stdin**. If expressions are also given (see above), the
 115     expressions are evaluated in the order given.
 116
 117     If this option is given on the command-line (i.e., not in **DC_ENV_ARGS**,
 118     see the **ENVIRONMENT VARIABLES** section), then after processing all
 119     expressions and files, dc(1) will exit, unless **-** (**stdin**) was given
 120     as an argument at least once to **-f** or **--file**. However, if any other
 121     **-e**, **--expression**, **-f**, or **--file** arguments are given after
 122     **-f-** or equivalent is given, dc(1) will give a fatal error and exit.
 123
 124     This is a **non-portable extension**.
 125
 126 All long options are **non-portable extensions**.
 127
 128 # STDOUT
 129
 130 Any non-error output is written to **stdout**. In addition, if history (see the
 131 **HISTORY** section) and the prompt (see the **TTY MODE** section) are enabled,
 132 both are output to **stdout**.
 133
 134 **Note**: Unlike other dc(1) implementations, this dc(1) will issue a fatal
 135 error (see the **EXIT STATUS** section) if it cannot write to **stdout**, so if
 136 **stdout** is closed, as in **dc <file> >&-**, it will quit with an error. This
 137 is done so that dc(1) can report problems when **stdout** is redirected to a
 138 file.
 139
 140 If there are scripts that depend on the behavior of other dc(1) implementations,
 141 it is recommended that those scripts be changed to redirect **stdout** to
 142 **/dev/null**.
 143
 144 # STDERR
 145
 146 Any error output is written to **stderr**.
 147
 148 **Note**: Unlike other dc(1) implementations, this dc(1) will issue a fatal
 149 error (see the **EXIT STATUS** section) if it cannot write to **stderr**, so if
 150 **stderr** is closed, as in **dc <file> 2>&-**, it will quit with an error. This
 151 is done so that dc(1) can exit with an error code when **stderr** is redirected
 152 to a file.
 153
 154 If there are scripts that depend on the behavior of other dc(1) implementations,
 155 it is recommended that those scripts be changed to redirect **stderr** to
 156 **/dev/null**.
 157
 158 # SYNTAX
 159
 160 Each item in the input source code, either a number (see the **NUMBERS**
 161 section) or a command (see the **COMMANDS** section), is processed and executed,
 162 in order. Input is processed immediately when entered.
 163
 164 **ibase** is a register (see the **REGISTERS** section) that determines how to
 165 interpret constant numbers. It is the "input" base, or the number base used for
 166 interpreting input numbers. **ibase** is initially **10**. The max allowable
 167 value for **ibase** is **16**. The min allowable value for **ibase** is **2**.
 168 The max allowable value for **ibase** can be queried in dc(1) programs with the
 169 **T** command.
 170
 171 **obase** is a register (see the **REGISTERS** section) that determines how to
 172 output results. It is the "output" base, or the number base used for outputting
 173 numbers. **obase** is initially **10**. The max allowable value for **obase** is
 174 **DC_BASE_MAX** and can be queried with the **U** command. The min allowable
 175 value for **obase** is **2**. Values are output in the specified base.
 176
 177 The *scale* of an expression is the number of digits in the result of the
 178 expression right of the decimal point, and **scale** is a register (see the
 179 **REGISTERS** section) that sets the precision of any operations (with
 180 exceptions). **scale** is initially **0**. **scale** cannot be negative. The max
 181 allowable value for **scale** can be queried in dc(1) programs with the **V**
 182 command.
 183
 184 ## Comments
 185
 186 Comments go from **#** until, and not including, the next newline. This is a
 187 **non-portable extension**.
 188
 189 # NUMBERS
 190
 191 Numbers are strings made up of digits, uppercase letters up to **F**, and at
 192 most **1** period for a radix. Numbers can have up to **DC_NUM_MAX** digits.
 193 Uppercase letters are equal to **9** + their position in the alphabet (i.e.,
 194 **A** equals **10**, or **9+1**). If a digit or letter makes no sense with the
 195 current value of **ibase**, they are set to the value of the highest valid digit
 196 in **ibase**.
 197
 198 Single-character numbers (i.e., **A** alone) take the value that they would have
 199 if they were valid digits, regardless of the value of **ibase**. This means that
 200 **A** alone always equals decimal **10** and **F** alone always equals decimal
 201 **15**.
 202
 203 # COMMANDS
 204
 205 The valid commands are listed below.
 206
 207 ## Printing
 208
 209 These commands are used for printing.
 210
 211 **p**
 212
 213 :   Prints the value on top of the stack, whether number or string, and prints a
 214     newline after.
 215
 216     This does not alter the stack.
 217
 218 **n**
 219
 220 :   Prints the value on top of the stack, whether number or string, and pops it
 221     off of the stack.
 222
 223 **P**
 224
 225 :   Pops a value off the stack.
 226
 227     If the value is a number, it is truncated and the absolute value of the
 228     result is printed as though **obase** is **UCHAR_MAX+1** and each digit is
 229     interpreted as an ASCII character, making it a byte stream.
 230
 231     If the value is a string, it is printed without a trailing newline.
 232
 233     This is a **non-portable extension**.
 234
 235 **f**
 236
 237 :   Prints the entire contents of the stack, in order from newest to oldest,
 238     without altering anything.
 239
 240     Users should use this command when they get lost.
 241
 242 ## Arithmetic
 243
 244 These are the commands used for arithmetic.
 245
 246 **+**
 247
 248 :   The top two values are popped off the stack, added, and the result is pushed
 249     onto the stack. The *scale* of the result is equal to the max *scale* of
 250     both operands.
 251
 252 **-**
 253
 254 :   The top two values are popped off the stack, subtracted, and the result is
 255     pushed onto the stack. The *scale* of the result is equal to the max
 256     *scale* of both operands.
 257
 258 **\***
 259
 260 :   The top two values are popped off the stack, multiplied, and the result is
 261     pushed onto the stack. If **a** is the *scale* of the first expression and
 262     **b** is the *scale* of the second expression, the *scale* of the result
 263     is equal to **min(a+b,max(scale,a,b))** where **min()** and **max()** return
 264     the obvious values.
 265
 266 **/**
 267
 268 :   The top two values are popped off the stack, divided, and the result is
 269     pushed onto the stack. The *scale* of the result is equal to **scale**.
 270
 271     The first value popped off of the stack must be non-zero.
 272
 273 **%**
 274
 275 :   The top two values are popped off the stack, remaindered, and the result is
 276     pushed onto the stack.
 277
 278     Remaindering is equivalent to 1) Computing **a/b** to current **scale**, and
 279     2) Using the result of step 1 to calculate **a-(a/b)\*b** to *scale*
 280     **max(scale+scale(b),scale(a))**.
 281
 282     The first value popped off of the stack must be non-zero.
 283
 284 **~**
 285
 286 :   The top two values are popped off the stack, divided and remaindered, and
 287     the results (divided first, remainder second) are pushed onto the stack.
 288     This is equivalent to **x y / x y %** except that **x** and **y** are only
 289     evaluated once.
 290
 291     The first value popped off of the stack must be non-zero.
 292
 293     This is a **non-portable extension**.
 294
 295 **\^**
 296
 297 :   The top two values are popped off the stack, the second is raised to the
 298     power of the first, and the result is pushed onto the stack. The *scale* of
 299     the result is equal to **scale**.
 300
 301     The first value popped off of the stack must be an integer, and if that
 302     value is negative, the second value popped off of the stack must be
 303     non-zero.
 304
 305 **v**
 306
 307 :   The top value is popped off the stack, its square root is computed, and the
 308     result is pushed onto the stack. The *scale* of the result is equal to
 309     **scale**.
 310
 311     The value popped off of the stack must be non-negative.
 312
 313 **\_**
 314
 315 :   If this command *immediately* precedes a number (i.e., no spaces or other
 316     commands), then that number is input as a negative number.
 317
 318     Otherwise, the top value on the stack is popped and copied, and the copy is
 319     negated and pushed onto the stack. This behavior without a number is a
 320     **non-portable extension**.
 321
 322 **b**
 323
 324 :   The top value is popped off the stack, and if it is zero, it is pushed back
 325     onto the stack. Otherwise, its absolute value is pushed onto the stack.
 326
 327     This is a **non-portable extension**.
 328
 329 **|**
 330
 331 :   The top three values are popped off the stack, a modular exponentiation is
 332     computed, and the result is pushed onto the stack.
 333
 334     The first value popped is used as the reduction modulus and must be an
 335     integer and non-zero. The second value popped is used as the exponent and
 336     must be an integer and non-negative. The third value popped is the base and
 337     must be an integer.
 338
 339     This is a **non-portable extension**.
 340
 341 **G**
 342
 343 :   The top two values are popped off of the stack, they are compared, and a
 344     **1** is pushed if they are equal, or **0** otherwise.
 345
 346     This is a **non-portable extension**.
 347
 348 **N**
 349
 350 :   The top value is popped off of the stack, and if it a **0**, a **1** is
 351     pushed; otherwise, a **0** is pushed.
 352
 353     This is a **non-portable extension**.
 354
 355 **(**
 356
 357 :   The top two values are popped off of the stack, they are compared, and a
 358     **1** is pushed if the first is less than the second, or **0** otherwise.
 359
 360     This is a **non-portable extension**.
 361
 362 **{**
 363
 364 :   The top two values are popped off of the stack, they are compared, and a
 365     **1** is pushed if the first is less than or equal to the second, or **0**
 366     otherwise.
 367
 368     This is a **non-portable extension**.
 369
 370 **)**
 371
 372 :   The top two values are popped off of the stack, they are compared, and a
 373     **1** is pushed if the first is greater than the second, or **0** otherwise.
 374
 375     This is a **non-portable extension**.
 376
 377 **}**
 378
 379 :   The top two values are popped off of the stack, they are compared, and a
 380     **1** is pushed if the first is greater than or equal to the second, or
 381     **0** otherwise.
 382
 383     This is a **non-portable extension**.
 384
 385 **M**
 386
 387 :   The top two values are popped off of the stack. If they are both non-zero, a
 388     **1** is pushed onto the stack. If either of them is zero, or both of them
 389     are, then a **0** is pushed onto the stack.
 390
 391     This is like the **&&** operator in bc(1), and it is *not* a short-circuit
 392     operator.
 393
 394     This is a **non-portable extension**.
 395
 396 **m**
 397
 398 :   The top two values are popped off of the stack. If at least one of them is
 399     non-zero, a **1** is pushed onto the stack. If both of them are zero, then a
 400     **0** is pushed onto the stack.
 401
 402     This is like the **||** operator in bc(1), and it is *not* a short-circuit
 403     operator.
 404
 405     This is a **non-portable extension**.
 406
 407 ## Stack Control
 408
 409 These commands control the stack.
 410
 411 **c**
 412
 413 :   Removes all items from ("clears") the stack.
 414
 415 **d**
 416
 417 :   Copies the item on top of the stack ("duplicates") and pushes the copy onto
 418     the stack.
 419
 420 **r**
 421
 422 :   Swaps ("reverses") the two top items on the stack.
 423
 424 **R**
 425
 426 :   Pops ("removes") the top value from the stack.
 427
 428 ## Register Control
 429
 430 These commands control registers (see the **REGISTERS** section).
 431
 432 **s***r*
 433
 434 :   Pops the value off the top of the stack and stores it into register *r*.
 435
 436 **l***r*
 437
 438 :   Copies the value in register *r* and pushes it onto the stack. This does not
 439     alter the contents of *r*.
 440
 441 **S***r*
 442
 443 :   Pops the value off the top of the (main) stack and pushes it onto the stack
 444     of register *r*. The previous value of the register becomes inaccessible.
 445
 446 **L***r*
 447
 448 :   Pops the value off the top of the stack for register *r* and push it onto
 449     the main stack. The previous value in the stack for register *r*, if any, is
 450     now accessible via the **l***r* command.
 451
 452 ## Parameters
 453
 454 These commands control the values of **ibase**, **obase**, and **scale**. Also
 455 see the **SYNTAX** section.
 456
 457 **i**
 458
 459 :   Pops the value off of the top of the stack and uses it to set **ibase**,
 460     which must be between **2** and **16**, inclusive.
 461
 462     If the value on top of the stack has any *scale*, the *scale* is ignored.
 463
 464 **o**
 465
 466 :   Pops the value off of the top of the stack and uses it to set **obase**,
 467     which must be between **2** and **DC_BASE_MAX**, inclusive (see the
 468     **LIMITS** section).
 469
 470     If the value on top of the stack has any *scale*, the *scale* is ignored.
 471
 472 **k**
 473
 474 :   Pops the value off of the top of the stack and uses it to set **scale**,
 475     which must be non-negative.
 476
 477     If the value on top of the stack has any *scale*, the *scale* is ignored.
 478
 479 **I**
 480
 481 :   Pushes the current value of **ibase** onto the main stack.
 482
 483 **O**
 484
 485 :   Pushes the current value of **obase** onto the main stack.
 486
 487 **K**
 488
 489 :   Pushes the current value of **scale** onto the main stack.
 490
 491 **T**
 492
 493 :   Pushes the maximum allowable value of **ibase** onto the main stack.
 494
 495     This is a **non-portable extension**.
 496
 497 **U**
 498
 499 :   Pushes the maximum allowable value of **obase** onto the main stack.
 500
 501     This is a **non-portable extension**.
 502
 503 **V**
 504
 505 :   Pushes the maximum allowable value of **scale** onto the main stack.
 506
 507     This is a **non-portable extension**.
 508
 509 ## Strings
 510
 511 The following commands control strings.
 512
 513 dc(1) can work with both numbers and strings, and registers (see the
 514 **REGISTERS** section) can hold both strings and numbers. dc(1) always knows
 515 whether the contents of a register are a string or a number.
 516
 517 While arithmetic operations have to have numbers, and will print an error if
 518 given a string, other commands accept strings.
 519
 520 Strings can also be executed as macros. For example, if the string **[1pR]** is
 521 executed as a macro, then the code **1pR** is executed, meaning that the **1**
 522 will be printed with a newline after and then popped from the stack.
 523
 524 **\[**_characters_**\]**
 525
 526 :   Makes a string containing *characters* and pushes it onto the stack.
 527
 528     If there are brackets (**\[** and **\]**) in the string, then they must be
 529     balanced. Unbalanced brackets can be escaped using a backslash (**\\**)
 530     character.
 531
 532     If there is a backslash character in the string, the character after it
 533     (even another backslash) is put into the string verbatim, but the (first)
 534     backslash is not.
 535
 536 **a**
 537
 538 :   The value on top of the stack is popped.
 539
 540     If it is a number, it is truncated and its absolute value is taken. The
 541     result mod **UCHAR_MAX+1** is calculated. If that result is **0**, push an
 542     empty string; otherwise, push a one-character string where the character is
 543     the result of the mod interpreted as an ASCII character.
 544
 545     If it is a string, then a new string is made. If the original string is
 546     empty, the new string is empty. If it is not, then the first character of
 547     the original string is used to create the new string as a one-character
 548     string. The new string is then pushed onto the stack.
 549
 550     This is a **non-portable extension**.
 551
 552 **x**
 553
 554 :   Pops a value off of the top of the stack.
 555
 556     If it is a number, it is pushed back onto the stack.
 557
 558     If it is a string, it is executed as a macro.
 559
 560     This behavior is the norm whenever a macro is executed, whether by this
 561     command or by the conditional execution commands below.
 562
 563 **\>***r*
 564
 565 :   Pops two values off of the stack that must be numbers and compares them. If
 566     the first value is greater than the second, then the contents of register
 567     *r* are executed.
 568
 569     For example, **0 1>a** will execute the contents of register **a**, and
 570     **1 0>a** will not.
 571
 572     If either or both of the values are not numbers, dc(1) will raise an error
 573     and reset (see the **RESET** section).
 574
 575 **>***r***e***s*
 576
 577 :   Like the above, but will execute register *s* if the comparison fails.
 578
 579     If either or both of the values are not numbers, dc(1) will raise an error
 580     and reset (see the **RESET** section).
 581
 582     This is a **non-portable extension**.
 583
 584 **!\>***r*
 585
 586 :   Pops two values off of the stack that must be numbers and compares them. If
 587     the first value is not greater than the second (less than or equal to), then
 588     the contents of register *r* are executed.
 589
 590     If either or both of the values are not numbers, dc(1) will raise an error
 591     and reset (see the **RESET** section).
 592
 593 **!\>***r***e***s*
 594
 595 :   Like the above, but will execute register *s* if the comparison fails.
 596
 597     If either or both of the values are not numbers, dc(1) will raise an error
 598     and reset (see the **RESET** section).
 599
 600     This is a **non-portable extension**.
 601
 602 **\<***r*
 603
 604 :   Pops two values off of the stack that must be numbers and compares them. If
 605     the first value is less than the second, then the contents of register *r*
 606     are executed.
 607
 608     If either or both of the values are not numbers, dc(1) will raise an error
 609     and reset (see the **RESET** section).
 610
 611 **\<***r***e***s*
 612
 613 :   Like the above, but will execute register *s* if the comparison fails.
 614
 615     If either or both of the values are not numbers, dc(1) will raise an error
 616     and reset (see the **RESET** section).
 617
 618     This is a **non-portable extension**.
 619
 620 **!\<***r*
 621
 622 :   Pops two values off of the stack that must be numbers and compares them. If
 623     the first value is not less than the second (greater than or equal to), then
 624     the contents of register *r* are executed.
 625
 626     If either or both of the values are not numbers, dc(1) will raise an error
 627     and reset (see the **RESET** section).
 628
 629 **!\<***r***e***s*
 630
 631 :   Like the above, but will execute register *s* if the comparison fails.
 632
 633     If either or both of the values are not numbers, dc(1) will raise an error
 634     and reset (see the **RESET** section).
 635
 636     This is a **non-portable extension**.
 637
 638 **=***r*
 639
 640 :   Pops two values off of the stack that must be numbers and compares them. If
 641     the first value is equal to the second, then the contents of register *r*
 642     are executed.
 643
 644     If either or both of the values are not numbers, dc(1) will raise an error
 645     and reset (see the **RESET** section).
 646
 647 **=***r***e***s*
 648
 649 :   Like the above, but will execute register *s* if the comparison fails.
 650
 651     If either or both of the values are not numbers, dc(1) will raise an error
 652     and reset (see the **RESET** section).
 653
 654     This is a **non-portable extension**.
 655
 656 **!=***r*
 657
 658 :   Pops two values off of the stack that must be numbers and compares them. If
 659     the first value is not equal to the second, then the contents of register
 660     *r* are executed.
 661
 662     If either or both of the values are not numbers, dc(1) will raise an error
 663     and reset (see the **RESET** section).
 664
 665 **!=***r***e***s*
 666
 667 :   Like the above, but will execute register *s* if the comparison fails.
 668
 669     If either or both of the values are not numbers, dc(1) will raise an error
 670     and reset (see the **RESET** section).
 671
 672     This is a **non-portable extension**.
 673
 674 **?**
 675
 676 :   Reads a line from the **stdin** and executes it. This is to allow macros to
 677     request input from users.
 678
 679 **q**
 680
 681 :   During execution of a macro, this exits the execution of that macro and the
 682     execution of the macro that executed it. If there are no macros, or only one
 683     macro executing, dc(1) exits.
 684
 685 **Q**
 686
 687 :   Pops a value from the stack which must be non-negative and is used the
 688     number of macro executions to pop off of the execution stack. If the number
 689     of levels to pop is greater than the number of executing macros, dc(1)
 690     exits.
 691
 692 ## Status
 693
 694 These commands query status of the stack or its top value.
 695
 696 **Z**
 697
 698 :   Pops a value off of the stack.
 699
 700     If it is a number, calculates the number of significant decimal digits it
 701     has and pushes the result.
 702
 703     If it is a string, pushes the number of characters the string has.
 704
 705 **X**
 706
 707 :   Pops a value off of the stack.
 708
 709     If it is a number, pushes the *scale* of the value onto the stack.
 710
 711     If it is a string, pushes **0**.
 712
 713 **z**
 714
 715 :   Pushes the current stack depth (before execution of this command).
 716
 717 ## Arrays
 718
 719 These commands manipulate arrays.
 720
 721 **:***r*
 722
 723 :   Pops the top two values off of the stack. The second value will be stored in
 724     the array *r* (see the **REGISTERS** section), indexed by the first value.
 725
 726 **;***r*
 727
 728 :   Pops the value on top of the stack and uses it as an index into the array
 729     *r*. The selected value is then pushed onto the stack.
 730
 731 # REGISTERS
 732
 733 Registers are names that can store strings, numbers, and arrays. (Number/string
 734 registers do not interfere with array registers.)
 735
 736 Each register is also its own stack, so the current register value is the top of
 737 the stack for the register. All registers, when first referenced, have one value
 738 (**0**) in their stack.
 739
 740 In non-extended register mode, a register name is just the single character that
 741 follows any command that needs a register name. The only exception is a newline
 742 (**'\\n'**); it is a parse error for a newline to be used as a register name.
 743
 744 ## Extended Register Mode
 745
 746 Unlike most other dc(1) implentations, this dc(1) provides nearly unlimited
 747 amounts of registers, if extended register mode is enabled.
 748
 749 If extended register mode is enabled (**-x** or **--extended-register**
 750 command-line arguments are given), then normal single character registers are
 751 used *unless* the character immediately following a command that needs a
 752 register name is a space (according to **isspace()**) and not a newline
 753 (**'\\n'**).
 754
 755 In that case, the register name is found according to the regex
 756 **\[a-z\]\[a-z0-9\_\]\*** (like bc(1) identifiers), and it is a parse error if
 757 the next non-space characters do not match that regex.
 758
 759 # RESET
 760
 761 When dc(1) encounters an error or a signal that it has a non-default handler
 762 for, it resets. This means that several things happen.
 763
 764 First, any macros that are executing are stopped and popped off the stack.
 765 The behavior is not unlike that of exceptions in programming languages. Then
 766 the execution point is set so that any code waiting to execute (after all
 767 macros returned) is skipped.
 768
 769 Thus, when dc(1) resets, it skips any remaining code waiting to be executed.
 770 Then, if it is interactive mode, and the error was not a fatal error (see the
 771 **EXIT STATUS** section), it asks for more input; otherwise, it exits with the
 772 appropriate return code.
 773
 774 # PERFORMANCE
 775
 776 Most dc(1) implementations use **char** types to calculate the value of **1**
 777 decimal digit at a time, but that can be slow. This dc(1) does something
 778 different.
 779
 780 It uses large integers to calculate more than **1** decimal digit at a time. If
 781 built in a environment where **DC_LONG_BIT** (see the **LIMITS** section) is
 782 **64**, then each integer has **9** decimal digits. If built in an environment
 783 where **DC_LONG_BIT** is **32** then each integer has **4** decimal digits. This
 784 value (the number of decimal digits per large integer) is called
 785 **DC_BASE_DIGS**.
 786
 787 In addition, this dc(1) uses an even larger integer for overflow checking. This
 788 integer type depends on the value of **DC_LONG_BIT**, but is always at least
 789 twice as large as the integer type used to store digits.
 790
 791 # LIMITS
 792
 793 The following are the limits on dc(1):
 794
 795 **DC_LONG_BIT**
 796
 797 :   The number of bits in the **long** type in the environment where dc(1) was
 798     built. This determines how many decimal digits can be stored in a single
 799     large integer (see the **PERFORMANCE** section).
 800
 801 **DC_BASE_DIGS**
 802
 803 :   The number of decimal digits per large integer (see the **PERFORMANCE**
 804     section). Depends on **DC_LONG_BIT**.
 805
 806 **DC_BASE_POW**
 807
 808 :   The max decimal number that each large integer can store (see
 809     **DC_BASE_DIGS**) plus **1**. Depends on **DC_BASE_DIGS**.
 810
 811 **DC_OVERFLOW_MAX**
 812
 813 :   The max number that the overflow type (see the **PERFORMANCE** section) can
 814     hold. Depends on **DC_LONG_BIT**.
 815
 816 **DC_BASE_MAX**
 817
 818 :   The maximum output base. Set at **DC_BASE_POW**.
 819
 820 **DC_DIM_MAX**
 821
 822 :   The maximum size of arrays. Set at **SIZE_MAX-1**.
 823
 824 **DC_SCALE_MAX**
 825
 826 :   The maximum **scale**. Set at **DC_OVERFLOW_MAX-1**.
 827
 828 **DC_STRING_MAX**
 829
 830 :   The maximum length of strings. Set at **DC_OVERFLOW_MAX-1**.
 831
 832 **DC_NAME_MAX**
 833
 834 :   The maximum length of identifiers. Set at **DC_OVERFLOW_MAX-1**.
 835
 836 **DC_NUM_MAX**
 837
 838 :   The maximum length of a number (in decimal digits), which includes digits
 839     after the decimal point. Set at **DC_OVERFLOW_MAX-1**.
 840
 841 Exponent
 842
 843 :   The maximum allowable exponent (positive or negative). Set at
 844     **DC_OVERFLOW_MAX**.
 845
 846 Number of vars
 847
 848 :   The maximum number of vars/arrays. Set at **SIZE_MAX-1**.
 849
 850 These limits are meant to be effectively non-existent; the limits are so large
 851 (at least on 64-bit machines) that there should not be any point at which they
 852 become a problem. In fact, memory should be exhausted before these limits should
 853 be hit.
 854
 855 # ENVIRONMENT VARIABLES
 856
 857 dc(1) recognizes the following environment variables:
 858
 859 **DC_ENV_ARGS**
 860
 861 :   This is another way to give command-line arguments to dc(1). They should be
 862     in the same format as all other command-line arguments. These are always
 863     processed first, so any files given in **DC_ENV_ARGS** will be processed
 864     before arguments and files given on the command-line. This gives the user
 865     the ability to set up "standard" options and files to be used at every
 866     invocation. The most useful thing for such files to contain would be useful
 867     functions that the user might want every time dc(1) runs. Another use would
 868     be to use the **-e** option to set **scale** to a value other than **0**.
 869
 870     The code that parses **DC_ENV_ARGS** will correctly handle quoted arguments,
 871     but it does not understand escape sequences. For example, the string
 872     **"/home/gavin/some dc file.dc"** will be correctly parsed, but the string
 873     **"/home/gavin/some \"dc\" file.dc"** will include the backslashes.
 874
 875     The quote parsing will handle either kind of quotes, **'** or **"**. Thus,
 876     if you have a file with any number of single quotes in the name, you can use
 877     double quotes as the outside quotes, as in **"some 'dc' file.dc"**, and vice
 878     versa if you have a file with double quotes. However, handling a file with
 879     both kinds of quotes in **DC_ENV_ARGS** is not supported due to the
 880     complexity of the parsing, though such files are still supported on the
 881     command-line where the parsing is done by the shell.
 882
 883 **DC_LINE_LENGTH**
 884
 885 :   If this environment variable exists and contains an integer that is greater
 886     than **1** and is less than **UINT16_MAX** (**2\^16-1**), dc(1) will output
 887     lines to that length, including the backslash newline combo. The default
 888     line length is **70**.
 889
 890 **DC_EXPR_EXIT**
 891
 892 :   If this variable exists (no matter the contents), dc(1) will exit
 893     immediately after executing expressions and files given by the **-e** and/or
 894     **-f** command-line options (and any equivalents).
 895
 896 # EXIT STATUS
 897
 898 dc(1) returns the following exit statuses:
 899
 900 **0**
 901
 902 :   No error.
 903
 904 **1**
 905
 906 :   A math error occurred. This follows standard practice of using **1** for
 907     expected errors, since math errors will happen in the process of normal
 908     execution.
 909
 910     Math errors include divide by **0**, taking the square root of a negative
 911     number, attempting to convert a negative number to a hardware integer,
 912     overflow when converting a number to a hardware integer, and attempting to
 913     use a non-integer where an integer is required.
 914
 915     Converting to a hardware integer happens for the second operand of the power
 916     (**\^**) operator.
 917
 918 **2**
 919
 920 :   A parse error occurred.
 921
 922     Parse errors include unexpected **EOF**, using an invalid character, failing
 923     to find the end of a string or comment, and using a token where it is
 924     invalid.
 925
 926 **3**
 927
 928 :   A runtime error occurred.
 929
 930     Runtime errors include assigning an invalid number to **ibase**, **obase**,
 931     or **scale**; give a bad expression to a **read()** call, calling **read()**
 932     inside of a **read()** call, type errors, and attempting an operation when
 933     the stack has too few elements.
 934
 935 **4**
 936
 937 :   A fatal error occurred.
 938
 939     Fatal errors include memory allocation errors, I/O errors, failing to open
 940     files, attempting to use files that do not have only ASCII characters (dc(1)
 941     only accepts ASCII characters), attempting to open a directory as a file,
 942     and giving invalid command-line options.
 943
 944 The exit status **4** is special; when a fatal error occurs, dc(1) always exits
 945 and returns **4**, no matter what mode dc(1) is in.
 946
 947 The other statuses will only be returned when dc(1) is not in interactive mode
 948 (see the **INTERACTIVE MODE** section), since dc(1) resets its state (see the
 949 **RESET** section) and accepts more input when one of those errors occurs in
 950 interactive mode. This is also the case when interactive mode is forced by the
 951 **-i** flag or **--interactive** option.
 952
 953 These exit statuses allow dc(1) to be used in shell scripting with error
 954 checking, and its normal behavior can be forced by using the **-i** flag or
 955 **--interactive** option.
 956
 957 # INTERACTIVE MODE
 958
 959 Like bc(1), dc(1) has an interactive mode and a non-interactive mode.
 960 Interactive mode is turned on automatically when both **stdin** and **stdout**
 961 are hooked to a terminal, but the **-i** flag and **--interactive** option can
 962 turn it on in other cases.
 963
 964 In interactive mode, dc(1) attempts to recover from errors (see the **RESET**
 965 section), and in normal execution, flushes **stdout** as soon as execution is
 966 done for the current input.
 967
 968 # TTY MODE
 969
 970 If **stdin**, **stdout**, and **stderr** are all connected to a TTY, dc(1) turns
 971 on "TTY mode."
 972
 973 TTY mode is required for history to be enabled (see the **COMMAND LINE HISTORY**
 974 section). It is also required to enable special handling for **SIGINT** signals.
 975
 976 TTY mode is different from interactive mode because interactive mode is required
 977 in the [bc(1) specification][1], and interactive mode requires only **stdin**
 978 and **stdout** to be connected to a terminal.
 979
 980 # SIGNAL HANDLING
 981
 982 Sending a **SIGINT** will cause dc(1) to stop execution of the current input. If
 983 dc(1) is in TTY mode (see the **TTY MODE** section), it will reset (see the
 984 **RESET** section). Otherwise, it will clean up and exit.
 985
 986 Note that "current input" can mean one of two things. If dc(1) is processing
 987 input from **stdin** in TTY mode, it will ask for more input. If dc(1) is
 988 processing input from a file in TTY mode, it will stop processing the file and
 989 start processing the next file, if one exists, or ask for input from **stdin**
 990 if no other file exists.
 991
 992 This means that if a **SIGINT** is sent to dc(1) as it is executing a file, it
 993 can seem as though dc(1) did not respond to the signal since it will immediately
 994 start executing the next file. This is by design; most files that users execute
 995 when interacting with dc(1) have function definitions, which are quick to parse.
 996 If a file takes a long time to execute, there may be a bug in that file. The
 997 rest of the files could still be executed without problem, allowing the user to
 998 continue.
 999
1000 **SIGTERM** and **SIGQUIT** cause dc(1) to clean up and exit, and it uses the
1001 default handler for all other signals. The one exception is **SIGHUP**; in that
1002 case, when dc(1) is in TTY mode, a **SIGHUP** will cause dc(1) to clean up and
1003 exit.
1004
1005 # COMMAND LINE HISTORY
1006
1007 dc(1) supports interactive command-line editing. If dc(1) is in TTY mode (see
1008 the **TTY MODE** section), history is enabled. Previous lines can be recalled
1009 and edited with the arrow keys.
1010
1011 **Note**: tabs are converted to 8 spaces.
1012
1013 # LOCALES
1014
1015 This dc(1) ships with support for adding error messages for different locales
1016 and thus, supports **LC_MESSAGS**.
1017
1018 # SEE ALSO
1019
1020 bc(1)
1021
1022 # STANDARDS
1023
1024 The dc(1) utility operators are compliant with the operators in the bc(1)
1025 [IEEE Std 1003.1-2017 (“POSIX.1-2017”)][1] specification.
1026
1027 # BUGS
1028
1029 None are known. Report bugs at https://git.yzena.com/gavin/bc.
1030
1031 # AUTHOR
1032
1033 Gavin D. Howard <gavin@yzena.com> and contributors.
1034
1035 [1]: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html