contrib/bc/manuals/dc/EH.1.md

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