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