manuals/dc.1.md.in

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