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