1<!--- 2 3SPDX-License-Identifier: BSD-2-Clause 4 5Copyright (c) 2018-2021 Gavin D. Howard and contributors. 6 7Redistribution and use in source and binary forms, with or without 8modification, 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 17THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 18AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 19IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 21LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 22CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 23SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 24INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 25CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 26ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 27POSSIBILITY OF SUCH DAMAGE. 28 29--> 30 31# Name 32 33dc - 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 41dc(1) is an arbitrary-precision calculator. It uses a stack (reverse Polish 42notation) to store numbers and results of computations. Arithmetic operations 43pop arguments off of the stack and push the results. 44 45If 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, 47those files are processed, and dc(1) will then exit. 48 49This is different from the dc(1) on OpenBSD and possibly other dc(1) 50implementations, where **-e** (**-\-expression**) and **-f** (**-\-file**) 51arguments cause dc(1) to execute them and exit. The reason for this is that this 52dc(1) allows users to set arguments in the environment variable **DC_ENV_ARGS** 53(see the **ENVIRONMENT VARIABLES** section). Any expressions given on the 54command-line should be used to set up a standard environment. For example, if a 55user 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 58If 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** 60as the last command-line argument or define the environment variable 61**DC_EXPR_EXIT**. 62 63# OPTIONS 64 65The 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 132All long options are **non-portable extensions**. 133 134# STDOUT 135 136Any 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, 138both are output to **stdout**. 139 140**Note**: Unlike other dc(1) implementations, this dc(1) will issue a fatal 141error (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 143is done so that dc(1) can report problems when **stdout** is redirected to a 144file. 145 146If there are scripts that depend on the behavior of other dc(1) implementations, 147it is recommended that those scripts be changed to redirect **stdout** to 148**/dev/null**. 149 150# STDERR 151 152Any error output is written to **stderr**. 153 154**Note**: Unlike other dc(1) implementations, this dc(1) will issue a fatal 155error (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 157is done so that dc(1) can exit with an error code when **stderr** is redirected 158to a file. 159 160If there are scripts that depend on the behavior of other dc(1) implementations, 161it is recommended that those scripts be changed to redirect **stderr** to 162**/dev/null**. 163 164# SYNTAX 165 166Each item in the input source code, either a number (see the **NUMBERS** 167section) or a command (see the **COMMANDS** section), is processed and executed, 168in order. Input is processed immediately when entered. 169 170**ibase** is a register (see the **REGISTERS** section) that determines how to 171interpret constant numbers. It is the "input" base, or the number base used for 172interpreting input numbers. **ibase** is initially **10**. The max allowable 173value for **ibase** is **16**. The min allowable value for **ibase** is **2**. 174The 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 178output results. It is the "output" base, or the number base used for outputting 179numbers. **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 181value for **obase** is **2**. Values are output in the specified base. 182 183The *scale* of an expression is the number of digits in the result of the 184expression right of the decimal point, and **scale** is a register (see the 185**REGISTERS** section) that sets the precision of any operations (with 186exceptions). **scale** is initially **0**. **scale** cannot be negative. The max 187allowable value for **scale** can be queried in dc(1) programs with the **V** 188command. 189 190## Comments 191 192Comments go from **#** until, and not including, the next newline. This is a 193**non-portable extension**. 194 195# NUMBERS 196 197Numbers are strings made up of digits, uppercase letters up to **F**, and at 198most **1** period for a radix. Numbers can have up to **DC_NUM_MAX** digits. 199Uppercase 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 201current value of **ibase**, they are set to the value of the highest valid digit 202in **ibase**. 203 204Single-character numbers (i.e., **A** alone) take the value that they would have 205if 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 211The valid commands are listed below. 212 213## Printing 214 215These 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 250These 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 415These 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 436These 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 460These commands control the values of **ibase**, **obase**, and **scale**. Also 461see 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 517The following commands control strings. 518 519dc(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 521whether the contents of a register are a string or a number. 522 523While arithmetic operations have to have numbers, and will print an error if 524given a string, other commands accept strings. 525 526Strings can also be executed as macros. For example, if the string **[1pR]** is 527executed as a macro, then the code **1pR** is executed, meaning that the **1** 528will 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 700These 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 725These 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 739Registers are names that can store strings, numbers, and arrays. (Number/string 740registers do not interfere with array registers.) 741 742Each register is also its own stack, so the current register value is the top of 743the stack for the register. All registers, when first referenced, have one value 744(**0**) in their stack. 745 746In non-extended register mode, a register name is just the single character that 747follows 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 752Unlike most other dc(1) implentations, this dc(1) provides nearly unlimited 753amounts of registers, if extended register mode is enabled. 754 755If extended register mode is enabled (**-x** or **-\-extended-register** 756command-line arguments are given), then normal single character registers are 757used *unless* the character immediately following a command that needs a 758register name is a space (according to **isspace()**) and not a newline 759(**'\\n'**). 760 761In 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 763the next non-space characters do not match that regex. 764 765# RESET 766 767When dc(1) encounters an error or a signal that it has a non-default handler 768for, it resets. This means that several things happen. 769 770First, any macros that are executing are stopped and popped off the stack. 771The behavior is not unlike that of exceptions in programming languages. Then 772the execution point is set so that any code waiting to execute (after all 773macros returned) is skipped. 774 775Thus, when dc(1) resets, it skips any remaining code waiting to be executed. 776Then, 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 778appropriate return code. 779 780# PERFORMANCE 781 782Most dc(1) implementations use **char** types to calculate the value of **1** 783decimal digit at a time, but that can be slow. This dc(1) does something 784different. 785 786It uses large integers to calculate more than **1** decimal digit at a time. If 787built 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 789where **DC_LONG_BIT** is **32** then each integer has **4** decimal digits. This 790value (the number of decimal digits per large integer) is called 791**DC_BASE_DIGS**. 792 793In addition, this dc(1) uses an even larger integer for overflow checking. This 794integer type depends on the value of **DC_LONG_BIT**, but is always at least 795twice as large as the integer type used to store digits. 796 797# LIMITS 798 799The 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 847Exponent 848 849: The maximum allowable exponent (positive or negative). Set at 850 **DC_OVERFLOW_MAX**. 851 852Number of vars 853 854: The maximum number of vars/arrays. Set at **SIZE_MAX-1**. 855 856These 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 858become a problem. In fact, memory should be exhausted before these limits should 859be hit. 860 861# ENVIRONMENT VARIABLES 862 863dc(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 904dc(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 950The exit status **4** is special; when a fatal error occurs, dc(1) always exits 951and returns **4**, no matter what mode dc(1) is in. 952 953The 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 956interactive mode. This is also the case when interactive mode is forced by the 957**-i** flag or **-\-interactive** option. 958 959These exit statuses allow dc(1) to be used in shell scripting with error 960checking, and its normal behavior can be forced by using the **-i** flag or 961**-\-interactive** option. 962 963# INTERACTIVE MODE 964 965Like bc(1), dc(1) has an interactive mode and a non-interactive mode. 966Interactive mode is turned on automatically when both **stdin** and **stdout** 967are hooked to a terminal, but the **-i** flag and **-\-interactive** option can 968turn it on in other cases. 969 970In interactive mode, dc(1) attempts to recover from errors (see the **RESET** 971section), and in normal execution, flushes **stdout** as soon as execution is 972done for the current input. 973 974# TTY MODE 975 976If **stdin**, **stdout**, and **stderr** are all connected to a TTY, dc(1) turns 977on "TTY mode." 978 979TTY mode is different from interactive mode because interactive mode is required 980in the [bc(1) specification][1], and interactive mode requires only **stdin** 981and **stdout** to be connected to a terminal. 982 983# SIGNAL HANDLING 984 985Sending a **SIGINT** will cause dc(1) to stop execution of the current input. If 986dc(1) is in TTY mode (see the **TTY MODE** section), it will reset (see the 987**RESET** section). Otherwise, it will clean up and exit. 988 989Note that "current input" can mean one of two things. If dc(1) is processing 990input from **stdin** in TTY mode, it will ask for more input. If dc(1) is 991processing input from a file in TTY mode, it will stop processing the file and 992start processing the next file, if one exists, or ask for input from **stdin** 993if no other file exists. 994 995This means that if a **SIGINT** is sent to dc(1) as it is executing a file, it 996can seem as though dc(1) did not respond to the signal since it will immediately 997start executing the next file. This is by design; most files that users execute 998when interacting with dc(1) have function definitions, which are quick to parse. 999If a file takes a long time to execute, there may be a bug in that file. The 1000rest of the files could still be executed without problem, allowing the user to 1001continue. 1002 1003**SIGTERM** and **SIGQUIT** cause dc(1) to clean up and exit, and it uses the 1004default handler for all other signals. 1005 1006# LOCALES 1007 1008This dc(1) ships with support for adding error messages for different locales 1009and thus, supports **LC_MESSAGS**. 1010 1011# SEE ALSO 1012 1013bc(1) 1014 1015# STANDARDS 1016 1017The dc(1) utility operators are compliant with the operators in the bc(1) 1018[IEEE Std 1003.1-2017 (���POSIX.1-2017���)][1] specification. 1019 1020# BUGS 1021 1022None are known. Report bugs at https://git.yzena.com/gavin/bc. 1023 1024# AUTHOR 1025 1026Gavin D. Howard <gavin@yzena.com> and contributors. 1027 1028[1]: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html 1029