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