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