1dc(1) -- arbitrary-precision reverse-Polish notation calculator 2=============================================================== 3 4SYNOPSIS 5-------- 6 7`dc` [`-hiPvVx`] [`--version`] [`--help`] [`--interactive`] [`--no-prompt`] 8[`--extended-register`] [`-e` *expr*] [`--expression=`*expr*...] 9[`-f` *file*...] [`-file=`*file*...] [*file*...] 10 11DESCRIPTION 12----------- 13 14dc(1) is an arbitrary-precision calculator. It uses a stack (reverse Polish 15notation) to store numbers and results of computations. Arithmetic operations 16pop arguments off of the stack and push the results. 17 18If no files are given on the command-line as extra arguments (i.e., not as `-f` 19or `--file` arguments), then dc(1) reads from `stdin`. Otherwise, those files 20are processed, and dc(1) will then exit. 21 22This is different from the dc(1) on OpenBSD and possibly other dc(1) 23implementations, where `-e` (`--expression`) and `-f` (`--file`) arguments cause 24dc(1) to execute them and exit. The reason for this is that this dc(1) allows 25users to set arguments in the environment variable `DC_ENV_ARGS` (see the 26ENVIRONMENT VARIABLES section). Any expressions given on the command-line should 27be used to set up a standard environment. For example, if a user wants the 28`scale` always set to `10`, they can set `DC_ENV_ARGS` to "-e 10k", and this 29dc(1) will always start with a `scale` of `10`. 30 31If users want to have dc(1) exit after processing all input from `-e` and `-f` 32arguments (and their equivalents), then they can just simply add "-e q" as the 33last command-line argument. 34 35OPTIONS 36------- 37 38The following are the options that dc(1) accepts. 39 40 * `-h`, `--help`: 41 Prints a usage message and quits. 42 43 * `-v`, `-V`, `--version`: 44 Print the version information (copyright header) and exit. 45 46 * `-i`, `--interactive`: 47 Forces interactive mode. 48 49 dc(1) has an interactive mode and a non-interactive mode. The interactive 50 mode is turned on automatically when both `stdin` and `stdout` are hooked to 51 a terminal, but this flag can turn it on in other cases. In interactive 52 mode, dc(1) attempts to recover from errors (see the RESET section), and in 53 normal execution, flushes `stdout` as soon as execution is done for the 54 current input. 55 56 This is a **non-portable extension**. 57 58 * `-P`, `--no-prompt`: 59 Disables the prompt in interactive mode. This is mostly for those users that 60 do not want a prompt or are not used to having them in `dc`. Most of those 61 users would want to put this option in `DC_ENV_ARGS`. 62 63 If the prompt has been disabled while building dc(1), this option is a 64 no-op. 65 66 This is a **non-portable extension**. 67 68 * `-x` `--extended-register`: 69 Enables extended register mode. See the REGISTERS section for more 70 information. 71 72 This is a **non-portable extension**. 73 74 * `-e` *expr*, `--expression`=*expr*: 75 Evaluates `expr`. If multiple expressions are given, they are evaluated in 76 order. If files are given as well (see below), the expressions and files are 77 evaluated in the order given. This means that if a file is given before an 78 expression, the file is read in and evaluated first. 79 80 In other dc(1) implementations, this option causes the program to execute 81 the expressions and then exit. This dc(1) does not, unless the 82 `DC_EXPR_EXIT` is defined (see the ENVIRONMENT VARIABLES section). 83 84 This is a **non-portable extension**. 85 86 * `-f` *file*, `--file`=*file*: 87 Reads in `file` and evaluates it. If expressions are also given (see above), 88 the expressions are evaluated in the order given. 89 90 In other dc(1) implementations, this option causes the program to execute 91 the files and then exit. This dc(1) does not, unless the 92 `DC_EXPR_EXIT` is defined (see the ENVIRONMENT VARIABLES section). 93 94 This is a **non-portable extension**. 95 96STDOUT 97------ 98 99Any non-error output is written to `stdout`. 100 101**Note**: Unlike other dc(1) implementations, this dc(1) will issue a fatal 102error (see the EXIT STATUS section) if it cannot write to `stdout`, so if 103`stdout` is closed, as in `dc <file> >&-`, it will quit with an error. This is 104done so that dc(1) can report problems when `stdout` is redirected to a file. 105 106If there are scripts that depend on the behavior of other dc(1) implementations, 107it is recommended that those scripts be changed to redirect `stdout` to 108`/dev/null`. 109 110STDERR 111------ 112 113Any error output is written to `stderr`. 114 115**Note**: Unlike other dc(1) implementations, this dc(1) will issue a fatal 116error (see the EXIT STATUS section) if it cannot write to `stderr`, so if 117`stderr` is closed, as in `dc <file> 2>&-`, it will quit with an error. This is 118done so that dc(1) can report problems when `stderr` is redirected to a file. 119 120If there are scripts that depend on the behavior of other dc(1) implementations, 121it is recommended that those scripts be changed to redirect `stderr` to 122`/dev/null`. 123 124SYNTAX 125------ 126 127`ibase` is a register (see the REGISTERS section) determining how to interpret 128constant numbers. It is the "input" base, or the number base used for 129interpreting input numbers. `ibase` is initially `10`. The max allowable value 130for `ibase` is `16`. The min allowable value for `ibase` is `2`. The max 131allowable value for `ibase` can be queried in dc(1) programs with the `T` 132command. 133 134`obase` is a register (see the REGISTERS section) determining how to output 135results. It is the "output" base, or the number base used for outputting 136numbers. `obase` is initially `10`. The max allowable value for `obase` is 137`DC_BASE_MAX`. The min allowable value for `obase` is `2` unless dc(1) was built 138with the extra math option. If it was, then the min allowable value is `0`. In 139this case, if `obase` is `0`, values are output in scientific notation, and if 140`obase` is `1`, values are output in engineering notation. (Outputting in 141scientific or engineering notation are **non-portable extensions**.) The max 142allowable value for `obase` can be queried in dc(1) programs with the `U` 143command. 144 145The **scale** of an expression is the number of digits in the result of the 146expression right of the decimal point, and `scale` is a register (see the 147REGISTERS section) that sets the precision of any operations (with exceptions). 148`scale` is initially `0`. `scale` cannot be negative. The max allowable value 149for `scale` can be queried in dc(1) programs with the `V` command. 150 151Each item in the input source code, either a number (see the NUMBERS section) or 152a command (see the COMMANDS section), is processed and executed, in order. Input 153is processed immediately when entered. 154 155### Comments 156 157Comments go from `#` until, and not including, the next newline. This is a 158**non-portable extension**. 159 160NUMBERS 161------- 162 163Numbers are strings made up of digits, uppercase letters up to `F`, and at most 164`1` period for a radix. Numbers can have up to `DC_NUM_MAX` digits. Uppercase 165letters equal `9` + their position in the alphabet (i.e., `A` equals `10`, or 166`9 + 1`). If a digit or letter makes no sense with the current value of `ibase`, 167they are set to the value of the highest valid digit in `ibase`. 168 169Single-character numbers (i.e., `A`) take the value that they would have if they 170were valid digits, regardless of the value of `ibase`. This means that `A` 171always equals decimal `10` and `F` always equals decimal `15`. 172 173In addition, if dc(1) was built with the extra math option, it accepts numbers 174in scientific notation. For dc(1), an example is `1.89237e9`, which is equal to 175`1892370000`. Negative exponents are also allowed, so `4.2890e_3` is equal to 176`0.0042890`. 177 178**WARNING**: Both the number and the exponent in scientific notation are 179interpreted according to the current `ibase`, but the number is still multiplied 180by `10^exponent` regardless of the current `ibase`. For example, if `ibase` is 181`16` and dc(1) is given the number string `"FFeA"`, the resulting decimal number 182will be `2550000000000`, and if dc(1) is given the number string `"10e_4"`, the 183resulting decimal number will be `0.0016`. 184 185Accepting input as scientific notation is a **non-portable extension**. 186 187COMMANDS 188-------- 189 190The valid commands are listed below. 191 192### Printing 193 194These commands are used for printing. 195 196Note that if dc(1) has been built with the extra math option enabled, both 197scientific notation and engineering notation are available for printing numbers. 198Scientific notation is activated by assigning `0` to `obase` using `0o` (in any 199other context, an `obase` of `0` is invalid), and engineering notation is 200activated by assigning `1` to `obase` using `1o` (which is also invalid in any 201other context). To deactivate them, just assign a different value to `obase`. 202 203Printing numbers in scientific notation and/or engineering notation is a 204**non-portable extension**. 205 206 * `p`: 207 Prints the value on top of the stack, whether number or string, and prints a 208 newline after. 209 210 This does not alter the stack. 211 212 * `n`: 213 Prints the value on top of the stack, whether number or string, and pops it 214 off of the stack. 215 216 * `P`: 217 Pops a value off the stack. 218 219 If the value is a number, it is truncated and the absolute value of the 220 result is printed as though `obase` is `UCHAR_MAX + 1` and each digit is 221 interpreted as an ASCII character, making it a byte stream. 222 223 If the value is a string, it is printed without a trailing newline. 224 225 This is a **non-portable extension**. 226 227 * `f`: 228 Prints the entire contents of the stack, in order from newest to oldest, 229 without altering anything. 230 231 Users should use this command when they get lost. 232 233### Arithmetic 234 235These are the commands used for arithmetic. 236 237 * `+`: 238 The top two values are popped off the stack, added, and the result is pushed 239 onto the stack. The **scale** of the result is equal to the max **scale** of 240 both operands. 241 242 * `-`: 243 The top two values are popped off the stack, subtracted, and the result is 244 pushed onto the stack. The **scale** of the result is equal to the max 245 **scale** of both operands. 246 247 * `*`: 248 The top two values are popped off the stack, multiplied, and the result is 249 pushed onto the stack. If `a` is the **scale** of the first expression and 250 `b` is the **scale** of the second expression, the **scale** of the result 251 is equal to `min(a+b,max(scale,a,b))` where `min` and `max` return the 252 obvious values. 253 254 * `/`: 255 The top two values are popped off the stack, divided, and the result is 256 pushed onto the stack. The **scale** of the result is equal to `scale`. 257 258 The first value popped off of the stack must be non-zero. 259 260 * `%`: 261 The top two values are popped off the stack, remaindered, and the result is 262 pushed onto the stack. 263 264 Remaindering is equivalent to 1) Computing `a/b` to current `scale`, and 2) 265 Using the result of step 1 to calculate `a-(a/b)*b` to **scale** 266 `max(scale + scale(b), scale(a))`. 267 268 The first value popped off of the stack must be non-zero. 269 270 * `~`: 271 The top two values are popped off the stack, divided and remaindered, and 272 the results (divided first, remainder second) are pushed onto the stack. 273 This is equivalent to `x y / x y %` except that `x` and `y` are only 274 evaluated once. 275 276 The first value popped off of the stack must be non-zero. 277 278 This is a **non-portable extension**. 279 280 * `^`: 281 The top two values are popped off the stack, the second is raised to the 282 power of the first, and the result is pushed onto the stack. 283 284 The first value popped off of the stack must be an integer, and if that 285 value is negative, the second value popped off of the stack must be 286 non-zero. 287 288 * `v`: 289 The top value is popped off the stack, its square root is computed, and the 290 result is pushed onto the stack. The **scale** of the result is equal to 291 `scale`. 292 293 The value popped off of the stack must be non-negative. 294 295 * `_`: 296 If this command *immediately* precedes a number (i.e., no spaces or other 297 commands), then that number is input as a negative number. 298 299 Otherwise, the top value on the stack is popped and copied, and the copy is 300 negated and pushed onto the stack. This behavior without a number is a 301 **non-portable extension**. 302 303 * `b`: 304 The top value is popped off the stack, and if it is zero, it is pushed back 305 onto the stack. Otherwise, its absolute value is pushed onto the stack. 306 307 This is a **non-portable extension**. 308 309 * `|`: 310 The top three values are popped off the stack, a modular exponentiation is 311 computed, and the result is pushed onto the stack. 312 313 The first value popped is used as the reduction modulus and must be an 314 integer and non-zero. The second value popped is used as the exponent and 315 must be an integer and non-negative. The third value popped is the base and 316 must be an integer. 317 318 This is a **non-portable extension**. 319 320 * `$`: 321 The top value is popped off the stack and copied, and the copy is truncated 322 and pushed onto the stack. 323 324 This is a **non-portable extension**. 325 326 * `@`: 327 The top two values are popped off the stack, and the precision of the second 328 is set to the value of the first, whether by truncation or extension. 329 330 The first value popped off of the stack must be an integer and non-negative. 331 332 This is a **non-portable extension**. 333 334 * `H`: 335 The top two values are popped off the stack, and the second is shifted left 336 (radix shifted right) to the value of the first. 337 338 The first value popped off of the stack must be an integer and non-negative. 339 340 This is a **non-portable extension**. 341 342 * `h`: 343 The top two values are popped off the stack, and the second is shifted right 344 (radix shifted left) to the value of the first. 345 346 The first value popped off of the stack must be an integer and non-negative. 347 348 This is a **non-portable extension**. 349 350 * `G`: 351 The top two values are popped off of the stack, they are compared, and a `1` 352 is pushed if they are equal, or `0` otherwise. 353 354 This is a **non-portable extension**. 355 356 * `N`: 357 The top value is popped off of the stack, and if it a `0`, a `1` is pushed; 358 otherwise, a `0` is pushed. 359 360 This is a **non-portable extension**. 361 362 * `(`: 363 The top two values are popped off of the stack, they are compared, and a `1` 364 is pushed if the first is less than the second, or `0` otherwise. 365 366 This is a **non-portable extension**. 367 368 * `{`: 369 The top two values are popped off of the stack, they are compared, and a `1` 370 is pushed if the first is less than or equal to the second, or `0` 371 otherwise. 372 373 This is a **non-portable extension**. 374 375 * `)`: 376 The top two values are popped off of the stack, they are compared, and a `1` 377 is pushed if the first is greater than the second, or `0` otherwise. 378 379 This is a **non-portable extension**. 380 381 * `}`: 382 The top two values are popped off of the stack, they are compared, and a `1` 383 is pushed if the first is greater than or equal to the second, or `0` 384 otherwise. 385 386 This is a **non-portable extension**. 387 388 * `M`: 389 The top two values are popped off of the stack. If they are both non-zero, a 390 `1` is pushed onto the stack. If either of them is zero, or both of them 391 are, then a `0` is pushed onto the stack. 392 393 This is like the `&&` operator in bc(1), and it is not a short-circuit 394 operator. 395 396 This is a **non-portable extension**. 397 398 * `m`: 399 The top two values are popped off of the stack. If at least one of them is 400 non-zero, a `1` is pushed onto the stack. If both of them are zero, then a 401 `0` is pushed onto the stack. 402 403 This is like the `||` operator in bc(1), and it is not a short-circuit 404 operator. 405 406 This is a **non-portable extension**. 407 408### Stack Control 409 410These commands control the stack. 411 412 * `c`: 413 Removes all items from ("clears") the stack. 414 415 * `d`: 416 Copies the item on top of the stack ("duplicates") and pushes the copy onto 417 the stack. 418 419 * `r`: 420 Swaps ("reverses") the two top items on the stack. 421 422 * `R`: 423 Pops ("removes") the top value from the stack. 424 425### Register Control 426 427These commands control registers (see the REGISTERS section). 428 429 * `s`*r*: 430 Pops the value off the top of the stack and stores it into register `r`. 431 432 * `l`*r*: 433 Copies the value in register `r` and pushes it onto the stack. This does not 434 alter the contents of `r`. 435 436 * `S`*r*: 437 Pops the value off the top of the (main) stack and pushes it onto the stack 438 of register `r`. The previous value of the register becomes inaccessible. 439 440 * `L`*r*: 441 Pops the value off the top of the stack for register `r` and push it onto 442 the main stack. The previous value in the stack for register `r`, if any, is 443 now accessible via the `l`*r* command. 444 445### Parameters 446 447These commands control the values of `ibase`, `obase`, and `scale` (see the 448SYNTAX section). 449 450 * `i`: 451 Pops the value off of the top of the stack and uses it to set `ibase`, which 452 must be between `2` and `16`, inclusive. 453 454 If the value on top of the stack has any **scale**, the **scale** is 455 ignored. 456 457 * `o`: 458 Pops the value off of the top of the stack and uses it to set `obase`, which 459 must be between `2` and `DC_BASE_MAX`, inclusive (see bc(1)). The value can 460 be either `0` or `1` if dc(1) was built with the extra math option. 461 462 If the value on top of the stack has any **scale**, the **scale** is 463 ignored. 464 465 * `k`: 466 Pops the value off of the top of the stack and uses it to set `scale`, which 467 must be non-negative. 468 469 If the value on top of the stack has any **scale**, the **scale** is 470 ignored. 471 472 * `I`: 473 Pushes the current value of `ibase` onto the main stack. 474 475 * `O`: 476 Pushes the current value of `obase` onto the main stack. 477 478 * `K`: 479 Pushes the current value of `scale` onto the main stack. 480 481 * `T`: 482 Pushes the maximum allowable value of `ibase` onto the main stack. 483 484 This is a **non-portable extension**. 485 486 * `U`: 487 Pushes the maximum allowable value of `obase` onto the main stack. 488 489 This is a **non-portable extension**. 490 491 * `V`: 492 Pushes the maximum allowable value of `scale` onto the main stack. 493 494 This is a **non-portable extension**. 495 496### Strings 497 498The following commands control strings. 499 500dc(1) can work with both numbers and strings, and registers (see the REGISTERS 501section) can hold both strings and numbers. dc(1) always knows whether the 502contents of a register are a string or a number. 503 504While arithmetic operations have to have numbers, and will print an error if 505given a string, other commands accept strings. 506 507Strings can also be executed as macros. For example, if the string `[1pR]` is 508executed as a macro, then the code `1pR` is executed, meaning that the `1` will 509be printed with a newline after and then popped from the stack. 510 511 * `[`*characters*`]`: 512 Makes a string containing *characters* and pushes it onto the stack. 513 514 If there are brackets (`[` and `]`) in the string, then they must be 515 balanced. Unbalanced brackets can be escaped using a backslash (`\`) 516 character. 517 518 If there is a backslash character in the string, the character after it 519 (even another backslash) is put into the string verbatim, but the (first) 520 backslash is not. 521 522 * `a`: 523 The value on top of the stack is popped. 524 525 If it is a number, it is truncated and its absolute value is taken. The 526 result mod `UCHAR_MAX + 1` is calculated. If that result is `0`, push an 527 empty string; otherwise, push a one-character string where the character is 528 the result of the mod interpreted as an ASCII character. 529 530 If it is a string, then a new string is made. If the original string is 531 empty, the new string is empty. If it is not, then the first character of 532 the original string is used to create the new string as a one-character 533 string. The new string is then pushed onto the stack. 534 535 This is a **non-portable extension**. 536 537 * `x`: 538 Pops a value off of the top of the stack. 539 540 If it is a number, it is pushed onto the stack. 541 542 If it is a string, it is executed as a macro. 543 544 This behavior is the norm whenever a macro is executed, whether by this 545 command or by the conditional execution commands below. 546 547 * `>`*r*: 548 Pops two values off of the stack that must be numbers and compares them. If 549 the first value is greater than the second, then the contents of register 550 `r` are executed. 551 552 For example, `0 1>a` will execute the contents of register `a`, and `1 0>a` 553 will not. 554 555 * `>`*r*`e`*s*: 556 Like the above, but will execute register `s` if the comparison fails. 557 558 This is a **non-portable extension**. 559 560 * `!>`*r*: 561 Pops two values off of the stack that must be numbers and compares them. If 562 the first value is not greater than the second (less than or equal to), then 563 the contents of register `r` are executed. 564 565 * `!>`*r*`e`*s*: 566 Like the above, but will execute register `s` if the comparison fails. 567 568 This is a **non-portable extension**. 569 570 * `<`*r*: 571 Pops two values off of the stack that must be numbers and compares them. If 572 the first value is less than the second, then the contents of register `r` 573 are executed. 574 575 * `<`*r*`e`*s*: 576 Like the above, but will execute register `s` if the comparison fails. 577 578 This is a **non-portable extension**. 579 580 * `!<`*r*: 581 Pops two values off of the stack that must be numbers and compares them. If 582 the first value is not less than the second (greater than or equal to), then 583 the contents of register `r` are executed. 584 585 * `!<`*r*`e`*s*: 586 Like the above, but will execute register `s` if the comparison fails. 587 588 This is a **non-portable extension**. 589 590 * `=`*r*: 591 Pops two values off of the stack that must be numbers and compares them. If 592 the first value is equal to the second, then the contents of register `r` 593 are executed. 594 595 * `=`*r*`e`*s*: 596 Like the above, but will execute register `s` if the comparison fails. 597 598 This is a **non-portable extension**. 599 600 * `!=`*r*: 601 Pops two values off of the stack that must be numbers and compares them. If 602 the first value is not equal to the second, then the contents of register 603 `r` are executed. 604 605 * `!=`*r*`e`*s*: 606 Like the above, but will execute register `s` if the comparison fails. 607 608 This is a **non-portable extension**. 609 610 * `?`: 611 Reads a line from the `stdin` and executes it. This is to allow macros to 612 request input from users. 613 614 * `q`: 615 During execution of a macro, this exits the execution of that macro and the 616 execution of the macro that executed it. If there are no macros, or only one 617 macro executing, dc(1) exits. 618 619 * `Q`: 620 Pops a value from the stack which must be non-negative and is used the 621 number of macro executions to pop off of the execution stack. If the number 622 of levels to pop is greater than the number of executing macros, dc(1) 623 exits. 624 625### Status 626 627These commands query status of the stack or its top value. 628 629 * `Z`: 630 Pops a value off of the stack. 631 632 If it is a number, calculates the number of significant decimal digits it 633 has and pushes the result. 634 635 If it is a string, pushes the number of characters the string has. 636 637 * `X`: 638 Pops a value off of the stack. 639 640 If it is a number, pushes the **scale** of the value onto the stack. 641 642 If it is a string, pushes `0`. 643 644 * `z`: 645 Pushes the current stack depth (before execution of this command). 646 647### Arrays 648 649These commands manipulate arrays. 650 651 * `:`*r*: 652 Pops the top two values off of the stack. The second value will be stored in 653 the array `r` (see the REGISTERS section), indexed by the first value. 654 655 * `;`*r*: 656 Pops the value on top of the stack and uses it as an index into the array 657 `r`. The selected value is then pushed onto the stack. 658 659REGISTERS 660--------- 661 662Registers are names that can store strings, numbers, and arrays. (Number/string 663registers do not interfere with array registers.) 664 665Each register is also its own stack, so the current register value is the top of 666the stack for the register. All registers, when first referenced, have one value 667(`0`) in their stack. 668 669In non-extended register mode, a register name is just the single character that 670follows any command that needs a register name. The only exception is a newline 671(`'\n'`); it is a parse error for a newline to be used as a register name. 672 673### Extended Register Mode 674 675Unlike most other dc(1) implentations, this dc(1) provides nearly unlimited 676amounts of registers, if extended register mode is enabled. 677 678If extended register mode is enabled (`-x` or `--extended-register` command-line 679arguments are given), then normal single character registers are used 680***unless*** the character immediately following a command that needs a register 681name is a space (according to `isspace()`) and not a newline (`'\n'`). 682 683In that case, the register name is found according to the regex 684`[a-z][a-z0-9_]*` (like bc(1)), and it is a parse error if the next 685non-space characters do not match that regex. 686 687RESET 688----- 689 690When dc(1) encounters an error or a signal that it has a non-default handler 691for, it resets. This means that several things happen. 692 693First, any macros that are executing are stopped and popped off the stack. 694The behavior is not unlike that of exceptions in programming languages. Then 695the execution point is set so that any code waiting to execute (after all 696functions returned) is skipped. 697 698Thus, when dc(1) resets, it skips any remaining code waiting to be executed. 699Then, if it is interactive mode, and the error was not a fatal error (see the 700EXIT STATUS section), it asks for more input; otherwise, it exits with the 701appropriate return code. 702 703PERFORMANCE 704----------- 705 706Most dc(1) implementations use `char` types to calculate the value of `1` 707decimal digit at a time, but that can be slow. This dc(1) does something 708different. 709 710It uses large integers to calculate more than `1` decimal digit at a time. If 711built in a environment where `DC_LONG_BIT` (see the LIMITS section) is `64`, 712then each integer has `9` decimal digits. If built in an environment where 713`DC_LONG_BIT` is `32` then each integer has `4` decimal digits. This value (the 714number of decimal digits per large integer) is called `DC_BASE_DIGS`. 715 716In addition, this dc(1) uses an even larger integer for overflow checking. This 717integer type depends on the value of `DC_LONG_BIT`, but is always at least twice 718as large as the integer type used to store digits. 719 720LIMITS 721------ 722 723The following are the limits on dc(1): 724 725 * `DC_LONG_BIT`: 726 The number of bits in the `long` type in the environment where dc(1) was 727 built. This determines how many decimal digits can be stored in a single 728 large integer (see the PERFORMANCE section). 729 730 * `DC_BASE_DIGS`: 731 The number of decimal digits per large integer (see the PERFORMANCE 732 section). Depends on `DC_LONG_BIT`. 733 734 * `DC_BASE_POW`: 735 The max decimal number that each large integer can store (see 736 `DC_BASE_DIGS`) plus `1`. Depends on `DC_BASE_DIGS`. 737 738 * `DC_OVERFLOW_MAX`: 739 The max number that the overflow type (see the PERFORMANCE section) can 740 hold. Depends on `DC_LONG_BIT`. 741 742 * `DC_BASE_DIGS`: 743 The number of decimal digits per large integer (see the PERFORMANCE 744 section). 745 746 * `DC_BASE_MAX`: 747 The maximum output base. Set at `DC_BASE_POW`. 748 749 * `DC_DIM_MAX`: 750 The maximum size of arrays. Set at `SIZE_MAX-1`. 751 752 * `DC_SCALE_MAX`: 753 The maximum `scale`. Set at `DC_OVERFLOW_MAX-1`. 754 755 * `DC_STRING_MAX`: 756 The maximum length of strings. Set at `DC_OVERFLOW_MAX-1`. 757 758 * `DC_NAME_MAX`: 759 The maximum length of identifiers. Set at `DC_OVERFLOW_MAX-1`. 760 761 * `DC_NUM_MAX`: 762 The maximum length of a number (in decimal digits), which includes digits 763 after the decimal point. Set at `DC_OVERFLOW_MAX-1`. 764 765 * Exponent: 766 The maximum allowable exponent (positive or negative). Set at 767 `DC_OVERFLOW_MAX`. 768 769 * Number of vars: 770 The maximum number of vars/arrays. Set at `SIZE_MAX-1`. 771 772These limits are meant to be effectively non-existent; the limits are so large 773(at least on 64-bit machines) that there should not be any point at which they 774become a problem. In fact, memory should be exhausted before these limits should 775be hit. 776 777ENVIRONMENT VARIABLES 778--------------------- 779 780dc(1) recognizes the following environment variables: 781 782 * `DC_ENV_ARGS`: 783 This is another way to give command-line arguments to dc(1). They should be 784 in the same format as all other command-line arguments. These are always 785 processed first, so any files given in `DC_ENV_ARGS` will be processed 786 before files given on the command-line. This gives the user the ability to 787 set up "standard" options and files to be used at every invocation. The most 788 useful thing for such files to contain would be useful functions that the 789 user might want every time dc(1) runs. Another use would be to use the `-e` 790 option to set `scale` to a value other than `0`. 791 792 * `DC_LINE_LENGTH`: 793 If this environment variable exists and contains an integer that is greater 794 than `1` and is less than `UINT16_MAX` (`2^16-1`), dc(1) will output lines 795 to that length, including the backslash newline combo. The default line 796 length is `70`. 797 798 * `DC_EXPR_EXIT`: 799 If this variable exists (no matter the contents), dc(1) will exit 800 immediately after executing expressions and files given by the `-e` and/or 801 `-f` command-line options (and any equivalents). 802 803EXIT STATUS 804----------- 805 806dc(1) returns the following exit statuses: 807 808 * `0`: 809 No error. 810 811 * `1`: 812 A math error occurred. This follows standard practice of using `1` for 813 expected errors, since math errors will happen in the process of normal 814 execution. 815 816 Math errors include divide by `0`, taking the square root of a negative 817 number, attempting to convert a negative number to a hardware integer, 818 overflow when converting a number to a hardware integer, and attempting to 819 use a non-integer where an integer is required. 820 821 Converting to a hardware integer happens for the second operand of the power 822 (`^`), places (`@`), left shift (`H`), and right shift (`h`) operators. 823 824 * `2`: 825 A parse error occurred. 826 827 Parse errors include unexpected `EOF`, using an invalid character, failing 828 to find the end of a string or comment, and using a token where it is 829 invalid. 830 831 * `3`: 832 A runtime error occurred. 833 834 Runtime errors include assigning an invalid number to `ibase`, `obase`, or 835 `scale`; give a bad expression to a `read()` call, calling `read()` inside 836 of a `read()` call, type errors, and attempting an operation when the stack 837 has too few elements. 838 839 * `4`: 840 A fatal error occurred. 841 842 Fatal errors include memory allocation errors, I/O errors, failing to open 843 files, attempting to use files that do not have only ASCII characters (dc(1) 844 only accepts ASCII characters), attempting to open a directory as a file, 845 and giving invalid command-line options. 846 847The exit status `4` is special; when a fatal error occurs, dc(1) always exits 848and returns `4`, no matter what mode dc(1) is in. 849 850The other statuses will only be returned when dc(1) is not in interactive mode, 851since dc(1) resets its state (see the RESET section) and accepts more input when 852one of those errors occurs in interactive mode. This is also the case when 853interactive mode is forced by the `-i` option. 854 855These exit statuses allow dc(1) to be used in shell scripting with error 856checking, and its normal behavior can be forced by using `-i`. 857 858SIGNAL HANDLING 859--------------- 860 861If dc(1) has been compiled with the signal handling, sending a `SIGINT` will 862cause dc(1) to stop execution of the current input and reset (see the RESET 863section), asking for more input. 864 865Otherwise, `SIGTERM` and `SIGQUIT` cause dc(1) to clean up and exit, and it uses 866the default handler for all other signals. 867 868If dc(1) has not been compiled with signal handling, it uses the default signal 869handlers for all signals. 870 871COMMAND LINE HISTORY 872-------------------- 873 874dc(1) supports interactive command-line editing, if compiled with the history 875option enabled. If `stdin` is hooked to a terminal, it is enabled. Previous 876lines can be recalled and edited with the arrow keys. 877 878**Note**: when dc(1) is built with history support, tabs are converted to 8 879spaces. 880 881LOCALES 882------- 883 884This dc(1) ships with support for adding error messages for different locales. 885 886SEE ALSO 887-------- 888 889bc(1) 890 891STANDARDS 892--------- 893 894The dc(1) utility operators are compliant with the operators in the bc(1) 895[IEEE Std 1003.1-2017 (“POSIX.1-2017”)][1] specification. 896 897AUTHOR 898------ 899 900This dc(1) was made from scratch by Gavin D. Howard. 901 902BUGS 903---- 904 905None are known. Report bugs at https://github.com/gavinhoward/bc. 906 907[1]: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html 908