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

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