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