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