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