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