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