3 SPDX-License-Identifier: BSD-2-Clause
5 Copyright (c) 2018-2021 Gavin D. Howard and contributors.
7 Redistribution and use in source and binary forms, with or without
8 modification, are permitted provided that the following conditions are met:
10 * Redistributions of source code must retain the above copyright notice, this
11 list of conditions and the following disclaimer.
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.
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.
33 dc - arbitrary-precision decimal reverse-Polish notation calculator
37 **dc** [**-hiPRvVx**] [**-\-version**] [**-\-help**] [**-\-interactive**] [**-\-no-prompt**] [**-\-no-read-prompt**] [**-\-extended-register**] [**-e** *expr*] [**-\-expression**=*expr*...] [**-f** *file*...] [**-\-file**=*file*...] [*file*...]
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.
45 If no files are given on the command-line, then dc(1) reads from **stdin** (see
46 the **STDIN** section). Otherwise, those files are processed, and dc(1) will
49 If a user wants to set up a standard environment, they can use **DC_ENV_ARGS**
50 (see the **ENVIRONMENT VARIABLES** section). For example, if a user wants the
51 **scale** always set to **10**, they can set **DC_ENV_ARGS** to **-e 10k**, and
52 this dc(1) will always start with a **scale** of **10**.
56 The following are the options that dc(1) accepts.
60 : Prints a usage message and quits.
62 **-v**, **-V**, **-\-version**
64 : Print the version information (copyright header) and exit.
66 **-i**, **-\-interactive**
68 : Forces interactive mode. (See the **INTERACTIVE MODE** section.)
70 This is a **non-portable extension**.
72 **-L**, **-\-no-line-length**
74 : Disables line length checking and prints numbers without backslashes and
75 newlines. In other words, this option sets **BC_LINE_LENGTH** to **0** (see
76 the **ENVIRONMENT VARIABLES** section).
78 This is a **non-portable extension**.
80 **-P**, **-\-no-prompt**
82 : Disables the prompt in TTY mode. (The prompt is only enabled in TTY mode.
83 See the **TTY MODE** section.) This is mostly for those users that do not
84 want a prompt or are not used to having them in dc(1). Most of those users
85 would want to put this option in **DC_ENV_ARGS**.
87 These options override the **DC_PROMPT** and **DC_TTY_MODE** environment
88 variables (see the **ENVIRONMENT VARIABLES** section).
90 This is a **non-portable extension**.
92 **-R**, **-\-no-read-prompt**
94 : Disables the read prompt in TTY mode. (The read prompt is only enabled in
95 TTY mode. See the **TTY MODE** section.) This is mostly for those users that
96 do not want a read prompt or are not used to having them in dc(1). Most of
97 those users would want to put this option in **BC_ENV_ARGS** (see the
98 **ENVIRONMENT VARIABLES** section). This option is also useful in hash bang
99 lines of dc(1) scripts that prompt for user input.
101 This option does not disable the regular prompt because the read prompt is
102 only used when the **?** command is used.
104 These options *do* override the **DC_PROMPT** and **DC_TTY_MODE**
105 environment variables (see the **ENVIRONMENT VARIABLES** section), but only
108 This is a **non-portable extension**.
110 **-x** **-\-extended-register**
112 : Enables extended register mode. See the *Extended Register Mode* subsection
113 of the **REGISTERS** section for more information.
115 This is a **non-portable extension**.
117 **-z**, **-\-leading-zeroes**
119 : Makes bc(1) print all numbers greater than **-1** and less than **1**, and
120 not equal to **0**, with a leading zero.
122 This can be set for individual numbers with the **plz(x)**, plznl(x)**,
123 **pnlz(x)**, and **pnlznl(x)** functions in the extended math library (see
124 the **LIBRARY** section).
126 This is a **non-portable extension**.
128 **-e** *expr*, **-\-expression**=*expr*
130 : Evaluates *expr*. If multiple expressions are given, they are evaluated in
131 order. If files are given as well (see below), the expressions and files are
132 evaluated in the order given. This means that if a file is given before an
133 expression, the file is read in and evaluated first.
135 If this option is given on the command-line (i.e., not in **DC_ENV_ARGS**,
136 see the **ENVIRONMENT VARIABLES** section), then after processing all
137 expressions and files, dc(1) will exit, unless **-** (**stdin**) was given
138 as an argument at least once to **-f** or **-\-file**, whether on the
139 command-line or in **DC_ENV_ARGS**. However, if any other **-e**,
140 **-\-expression**, **-f**, or **-\-file** arguments are given after **-f-**
141 or equivalent is given, dc(1) will give a fatal error and exit.
143 This is a **non-portable extension**.
145 **-f** *file*, **-\-file**=*file*
147 : Reads in *file* and evaluates it, line by line, as though it were read
148 through **stdin**. If expressions are also given (see above), the
149 expressions are evaluated in the order given.
151 If this option is given on the command-line (i.e., not in **DC_ENV_ARGS**,
152 see the **ENVIRONMENT VARIABLES** section), then after processing all
153 expressions and files, dc(1) will exit, unless **-** (**stdin**) was given
154 as an argument at least once to **-f** or **-\-file**. However, if any other
155 **-e**, **-\-expression**, **-f**, or **-\-file** arguments are given after
156 **-f-** or equivalent is given, dc(1) will give a fatal error and exit.
158 This is a **non-portable extension**.
160 All long options are **non-portable extensions**.
164 If no files are given on the command-line and no files or expressions are given
165 by the **-f**, **-\-file**, **-e**, or **-\-expression** options, then dc(1)
168 However, there is a caveat to this.
170 First, **stdin** is evaluated a line at a time. The only exception to this is if
171 a string has been finished, but not ended. This means that, except for escaped
172 brackets, all brackets must be balanced before dc(1) parses and executes.
176 Any non-error output is written to **stdout**. In addition, if history (see the
177 **HISTORY** section) and the prompt (see the **TTY MODE** section) are enabled,
178 both are output to **stdout**.
180 **Note**: Unlike other dc(1) implementations, this dc(1) will issue a fatal
181 error (see the **EXIT STATUS** section) if it cannot write to **stdout**, so if
182 **stdout** is closed, as in **dc <file> >&-**, it will quit with an error. This
183 is done so that dc(1) can report problems when **stdout** is redirected to a
186 If there are scripts that depend on the behavior of other dc(1) implementations,
187 it is recommended that those scripts be changed to redirect **stdout** to
192 Any error output is written to **stderr**.
194 **Note**: Unlike other dc(1) implementations, this dc(1) will issue a fatal
195 error (see the **EXIT STATUS** section) if it cannot write to **stderr**, so if
196 **stderr** is closed, as in **dc <file> 2>&-**, it will quit with an error. This
197 is done so that dc(1) can exit with an error code when **stderr** is redirected
200 If there are scripts that depend on the behavior of other dc(1) implementations,
201 it is recommended that those scripts be changed to redirect **stderr** to
206 Each item in the input source code, either a number (see the **NUMBERS**
207 section) or a command (see the **COMMANDS** section), is processed and executed,
208 in order. Input is processed immediately when entered.
210 **ibase** is a register (see the **REGISTERS** section) that determines how to
211 interpret constant numbers. It is the "input" base, or the number base used for
212 interpreting input numbers. **ibase** is initially **10**. The max allowable
213 value for **ibase** is **16**. The min allowable value for **ibase** is **2**.
214 The max allowable value for **ibase** can be queried in dc(1) programs with the
217 **obase** is a register (see the **REGISTERS** section) that determines how to
218 output results. It is the "output" base, or the number base used for outputting
219 numbers. **obase** is initially **10**. The max allowable value for **obase** is
220 **DC_BASE_MAX** and can be queried with the **U** command. The min allowable
221 value for **obase** is **2**. Values are output in the specified base.
223 The *scale* of an expression is the number of digits in the result of the
224 expression right of the decimal point, and **scale** is a register (see the
225 **REGISTERS** section) that sets the precision of any operations (with
226 exceptions). **scale** is initially **0**. **scale** cannot be negative. The max
227 allowable value for **scale** can be queried in dc(1) programs with the **V**
232 Comments go from **#** until, and not including, the next newline. This is a
233 **non-portable extension**.
237 Numbers are strings made up of digits, uppercase letters up to **F**, and at
238 most **1** period for a radix. Numbers can have up to **DC_NUM_MAX** digits.
239 Uppercase letters are equal to **9** + their position in the alphabet (i.e.,
240 **A** equals **10**, or **9+1**). If a digit or letter makes no sense with the
241 current value of **ibase**, they are set to the value of the highest valid digit
244 Single-character numbers (i.e., **A** alone) take the value that they would have
245 if they were valid digits, regardless of the value of **ibase**. This means that
246 **A** alone always equals decimal **10** and **F** alone always equals decimal
251 The valid commands are listed below.
255 These commands are used for printing.
259 : Prints the value on top of the stack, whether number or string, and prints a
262 This does not alter the stack.
266 : Prints the value on top of the stack, whether number or string, and pops it
271 : Pops a value off the stack.
273 If the value is a number, it is truncated and the absolute value of the
274 result is printed as though **obase** is **256** and each digit is
275 interpreted as an 8-bit ASCII character, making it a byte stream.
277 If the value is a string, it is printed without a trailing newline.
279 This is a **non-portable extension**.
283 : Prints the entire contents of the stack, in order from newest to oldest,
284 without altering anything.
286 Users should use this command when they get lost.
290 These are the commands used for arithmetic.
294 : The top two values are popped off the stack, added, and the result is pushed
295 onto the stack. The *scale* of the result is equal to the max *scale* of
300 : The top two values are popped off the stack, subtracted, and the result is
301 pushed onto the stack. The *scale* of the result is equal to the max
302 *scale* of both operands.
306 : The top two values are popped off the stack, multiplied, and the result is
307 pushed onto the stack. If **a** is the *scale* of the first expression and
308 **b** is the *scale* of the second expression, the *scale* of the result
309 is equal to **min(a+b,max(scale,a,b))** where **min()** and **max()** return
314 : The top two values are popped off the stack, divided, and the result is
315 pushed onto the stack. The *scale* of the result is equal to **scale**.
317 The first value popped off of the stack must be non-zero.
321 : The top two values are popped off the stack, remaindered, and the result is
322 pushed onto the stack.
324 Remaindering is equivalent to 1) Computing **a/b** to current **scale**, and
325 2) Using the result of step 1 to calculate **a-(a/b)\*b** to *scale*
326 **max(scale+scale(b),scale(a))**.
328 The first value popped off of the stack must be non-zero.
332 : The top two values are popped off the stack, divided and remaindered, and
333 the results (divided first, remainder second) are pushed onto the stack.
334 This is equivalent to **x y / x y %** except that **x** and **y** are only
337 The first value popped off of the stack must be non-zero.
339 This is a **non-portable extension**.
343 : The top two values are popped off the stack, the second is raised to the
344 power of the first, and the result is pushed onto the stack. The *scale* of
345 the result is equal to **scale**.
347 The first value popped off of the stack must be an integer, and if that
348 value is negative, the second value popped off of the stack must be
353 : The top value is popped off the stack, its square root is computed, and the
354 result is pushed onto the stack. The *scale* of the result is equal to
357 The value popped off of the stack must be non-negative.
361 : If this command *immediately* precedes a number (i.e., no spaces or other
362 commands), then that number is input as a negative number.
364 Otherwise, the top value on the stack is popped and copied, and the copy is
365 negated and pushed onto the stack. This behavior without a number is a
366 **non-portable extension**.
370 : The top value is popped off the stack, and if it is zero, it is pushed back
371 onto the stack. Otherwise, its absolute value is pushed onto the stack.
373 This is a **non-portable extension**.
377 : The top three values are popped off the stack, a modular exponentiation is
378 computed, and the result is pushed onto the stack.
380 The first value popped is used as the reduction modulus and must be an
381 integer and non-zero. The second value popped is used as the exponent and
382 must be an integer and non-negative. The third value popped is the base and
385 This is a **non-portable extension**.
389 : The top two values are popped off of the stack, they are compared, and a
390 **1** is pushed if they are equal, or **0** otherwise.
392 This is a **non-portable extension**.
396 : The top value is popped off of the stack, and if it a **0**, a **1** is
397 pushed; otherwise, a **0** is pushed.
399 This is a **non-portable extension**.
403 : The top two values are popped off of the stack, they are compared, and a
404 **1** is pushed if the first is less than the second, or **0** otherwise.
406 This is a **non-portable extension**.
410 : The top two values are popped off of the stack, they are compared, and a
411 **1** is pushed if the first is less than or equal to the second, or **0**
414 This is a **non-portable extension**.
418 : The top two values are popped off of the stack, they are compared, and a
419 **1** is pushed if the first is greater than the second, or **0** otherwise.
421 This is a **non-portable extension**.
425 : The top two values are popped off of the stack, they are compared, and a
426 **1** is pushed if the first is greater than or equal to the second, or
429 This is a **non-portable extension**.
433 : The top two values are popped off of the stack. If they are both non-zero, a
434 **1** is pushed onto the stack. If either of them is zero, or both of them
435 are, then a **0** is pushed onto the stack.
437 This is like the **&&** operator in bc(1), and it is *not* a short-circuit
440 This is a **non-portable extension**.
444 : The top two values are popped off of the stack. If at least one of them is
445 non-zero, a **1** is pushed onto the stack. If both of them are zero, then a
446 **0** is pushed onto the stack.
448 This is like the **||** operator in bc(1), and it is *not* a short-circuit
451 This is a **non-portable extension**.
455 These commands control the stack.
459 : Removes all items from ("clears") the stack.
463 : Copies the item on top of the stack ("duplicates") and pushes the copy onto
468 : Swaps ("reverses") the two top items on the stack.
472 : Pops ("removes") the top value from the stack.
476 These commands control registers (see the **REGISTERS** section).
480 : Pops the value off the top of the stack and stores it into register *r*.
484 : Copies the value in register *r* and pushes it onto the stack. This does not
485 alter the contents of *r*.
489 : Pops the value off the top of the (main) stack and pushes it onto the stack
490 of register *r*. The previous value of the register becomes inaccessible.
494 : Pops the value off the top of the stack for register *r* and push it onto
495 the main stack. The previous value in the stack for register *r*, if any, is
496 now accessible via the **l**_r_ command.
500 These commands control the values of **ibase**, **obase**, and **scale**. Also
501 see the **SYNTAX** section.
505 : Pops the value off of the top of the stack and uses it to set **ibase**,
506 which must be between **2** and **16**, inclusive.
508 If the value on top of the stack has any *scale*, the *scale* is ignored.
512 : Pops the value off of the top of the stack and uses it to set **obase**,
513 which must be between **2** and **DC_BASE_MAX**, inclusive (see the
516 If the value on top of the stack has any *scale*, the *scale* is ignored.
520 : Pops the value off of the top of the stack and uses it to set **scale**,
521 which must be non-negative.
523 If the value on top of the stack has any *scale*, the *scale* is ignored.
527 : Pushes the current value of **ibase** onto the main stack.
531 : Pushes the current value of **obase** onto the main stack.
535 : Pushes the current value of **scale** onto the main stack.
539 : Pushes the maximum allowable value of **ibase** onto the main stack.
541 This is a **non-portable extension**.
545 : Pushes the maximum allowable value of **obase** onto the main stack.
547 This is a **non-portable extension**.
551 : Pushes the maximum allowable value of **scale** onto the main stack.
553 This is a **non-portable extension**.
557 The following commands control strings.
559 dc(1) can work with both numbers and strings, and registers (see the
560 **REGISTERS** section) can hold both strings and numbers. dc(1) always knows
561 whether the contents of a register are a string or a number.
563 While arithmetic operations have to have numbers, and will print an error if
564 given a string, other commands accept strings.
566 Strings can also be executed as macros. For example, if the string **[1pR]** is
567 executed as a macro, then the code **1pR** is executed, meaning that the **1**
568 will be printed with a newline after and then popped from the stack.
570 **\[**_characters_**\]**
572 : Makes a string containing *characters* and pushes it onto the stack.
574 If there are brackets (**\[** and **\]**) in the string, then they must be
575 balanced. Unbalanced brackets can be escaped using a backslash (**\\**)
578 If there is a backslash character in the string, the character after it
579 (even another backslash) is put into the string verbatim, but the (first)
584 : The value on top of the stack is popped.
586 If it is a number, it is truncated and its absolute value is taken. The
587 result mod **256** is calculated. If that result is **0**, push an empty
588 string; otherwise, push a one-character string where the character is the
589 result of the mod interpreted as an ASCII character.
591 If it is a string, then a new string is made. If the original string is
592 empty, the new string is empty. If it is not, then the first character of
593 the original string is used to create the new string as a one-character
594 string. The new string is then pushed onto the stack.
596 This is a **non-portable extension**.
600 : Pops a value off of the top of the stack.
602 If it is a number, it is pushed back onto the stack.
604 If it is a string, it is executed as a macro.
606 This behavior is the norm whenever a macro is executed, whether by this
607 command or by the conditional execution commands below.
611 : Pops two values off of the stack that must be numbers and compares them. If
612 the first value is greater than the second, then the contents of register
615 For example, **0 1>a** will execute the contents of register **a**, and
618 If either or both of the values are not numbers, dc(1) will raise an error
619 and reset (see the **RESET** section).
623 : Like the above, but will execute register *s* if the comparison fails.
625 If either or both of the values are not numbers, dc(1) will raise an error
626 and reset (see the **RESET** section).
628 This is a **non-portable extension**.
632 : Pops two values off of the stack that must be numbers and compares them. If
633 the first value is not greater than the second (less than or equal to), then
634 the contents of register *r* are executed.
636 If either or both of the values are not numbers, dc(1) will raise an error
637 and reset (see the **RESET** section).
641 : Like the above, but will execute register *s* if the comparison fails.
643 If either or both of the values are not numbers, dc(1) will raise an error
644 and reset (see the **RESET** section).
646 This is a **non-portable extension**.
650 : Pops two values off of the stack that must be numbers and compares them. If
651 the first value is less than the second, then the contents of register *r*
654 If either or both of the values are not numbers, dc(1) will raise an error
655 and reset (see the **RESET** section).
659 : Like the above, but will execute register *s* if the comparison fails.
661 If either or both of the values are not numbers, dc(1) will raise an error
662 and reset (see the **RESET** section).
664 This is a **non-portable extension**.
668 : Pops two values off of the stack that must be numbers and compares them. If
669 the first value is not less than the second (greater than or equal to), then
670 the contents of register *r* are executed.
672 If either or both of the values are not numbers, dc(1) will raise an error
673 and reset (see the **RESET** section).
677 : Like the above, but will execute register *s* if the comparison fails.
679 If either or both of the values are not numbers, dc(1) will raise an error
680 and reset (see the **RESET** section).
682 This is a **non-portable extension**.
686 : Pops two values off of the stack that must be numbers and compares them. If
687 the first value is equal to the second, then the contents of register *r*
690 If either or both of the values are not numbers, dc(1) will raise an error
691 and reset (see the **RESET** section).
695 : Like the above, but will execute register *s* if the comparison fails.
697 If either or both of the values are not numbers, dc(1) will raise an error
698 and reset (see the **RESET** section).
700 This is a **non-portable extension**.
704 : Pops two values off of the stack that must be numbers and compares them. If
705 the first value is not equal to the second, then the contents of register
708 If either or both of the values are not numbers, dc(1) will raise an error
709 and reset (see the **RESET** section).
713 : Like the above, but will execute register *s* if the comparison fails.
715 If either or both of the values are not numbers, dc(1) will raise an error
716 and reset (see the **RESET** section).
718 This is a **non-portable extension**.
722 : Reads a line from the **stdin** and executes it. This is to allow macros to
723 request input from users.
727 : During execution of a macro, this exits the execution of that macro and the
728 execution of the macro that executed it. If there are no macros, or only one
729 macro executing, dc(1) exits.
733 : Pops a value from the stack which must be non-negative and is used the
734 number of macro executions to pop off of the execution stack. If the number
735 of levels to pop is greater than the number of executing macros, dc(1)
740 : Pushes the depth of the execution stack onto the stack. The execution stack
741 is the stack of string executions. The number that is pushed onto the stack
742 is exactly as many as is needed to make dc(1) exit with the **Q** command,
743 so the sequence **,Q** will make dc(1) exit.
747 These commands query status of the stack or its top value.
751 : Pops a value off of the stack.
753 If it is a number, calculates the number of significant decimal digits it
754 has and pushes the result. It will push **1** if the argument is **0** with
757 If it is a string, pushes the number of characters the string has.
761 : Pops a value off of the stack.
763 If it is a number, pushes the *scale* of the value onto the stack.
765 If it is a string, pushes **0**.
769 : Pushes the current depth of the stack (before execution of this command)
774 : Pushes the current stack depth of the register *r* onto the main stack.
776 Because each register has a depth of **1** (with the value **0** in the top
777 item) when dc(1) starts, dc(1) requires that each register's stack must
778 always have at least one item; dc(1) will give an error and reset otherwise
779 (see the **RESET** section). This means that this command will never push
782 This is a **non-portable extension**.
786 These commands manipulate arrays.
790 : Pops the top two values off of the stack. The second value will be stored in
791 the array *r* (see the **REGISTERS** section), indexed by the first value.
795 : Pops the value on top of the stack and uses it as an index into the array
796 *r*. The selected value is then pushed onto the stack.
800 : Pushes the length of the array *r* onto the stack.
802 This is a **non-portable extension**.
806 These commands retrieve global settings. These are the only commands that
807 require multiple specific characters, and all of them begin with the letter
808 **g**. Only the characters below are allowed after the character **g**; any
809 other character produces a parse error (see the **ERRORS** section).
813 : Pushes the line length set by **DC_LINE_LENGTH** (see the **ENVIRONMENT
814 VARIABLES** section) onto the stack.
818 : Pushes **0** onto the stack if the leading zero setting has not been enabled
819 with the **-z** or **-\-leading-zeroes** options (see the **OPTIONS**
820 section), non-zero otherwise.
824 Registers are names that can store strings, numbers, and arrays. (Number/string
825 registers do not interfere with array registers.)
827 Each register is also its own stack, so the current register value is the top of
828 the stack for the register. All registers, when first referenced, have one value
829 (**0**) in their stack, and it is a runtime error to attempt to pop that item
830 off of the register stack.
832 In non-extended register mode, a register name is just the single character that
833 follows any command that needs a register name. The only exceptions are: a
834 newline (**'\\n'**) and a left bracket (**'['**); it is a parse error for a
835 newline or a left bracket to be used as a register name.
837 ## Extended Register Mode
839 Unlike most other dc(1) implentations, this dc(1) provides nearly unlimited
840 amounts of registers, if extended register mode is enabled.
842 If extended register mode is enabled (**-x** or **-\-extended-register**
843 command-line arguments are given), then normal single character registers are
844 used *unless* the character immediately following a command that needs a
845 register name is a space (according to **isspace()**) and not a newline
848 In that case, the register name is found according to the regex
849 **\[a-z\]\[a-z0-9\_\]\*** (like bc(1) identifiers), and it is a parse error if
850 the next non-space characters do not match that regex.
854 When dc(1) encounters an error or a signal that it has a non-default handler
855 for, it resets. This means that several things happen.
857 First, any macros that are executing are stopped and popped off the stack.
858 The behavior is not unlike that of exceptions in programming languages. Then
859 the execution point is set so that any code waiting to execute (after all
860 macros returned) is skipped.
862 Thus, when dc(1) resets, it skips any remaining code waiting to be executed.
863 Then, if it is interactive mode, and the error was not a fatal error (see the
864 **EXIT STATUS** section), it asks for more input; otherwise, it exits with the
865 appropriate return code.
869 Most dc(1) implementations use **char** types to calculate the value of **1**
870 decimal digit at a time, but that can be slow. This dc(1) does something
873 It uses large integers to calculate more than **1** decimal digit at a time. If
874 built in a environment where **DC_LONG_BIT** (see the **LIMITS** section) is
875 **64**, then each integer has **9** decimal digits. If built in an environment
876 where **DC_LONG_BIT** is **32** then each integer has **4** decimal digits. This
877 value (the number of decimal digits per large integer) is called
880 In addition, this dc(1) uses an even larger integer for overflow checking. This
881 integer type depends on the value of **DC_LONG_BIT**, but is always at least
882 twice as large as the integer type used to store digits.
886 The following are the limits on dc(1):
890 : The number of bits in the **long** type in the environment where dc(1) was
891 built. This determines how many decimal digits can be stored in a single
892 large integer (see the **PERFORMANCE** section).
896 : The number of decimal digits per large integer (see the **PERFORMANCE**
897 section). Depends on **DC_LONG_BIT**.
901 : The max decimal number that each large integer can store (see
902 **DC_BASE_DIGS**) plus **1**. Depends on **DC_BASE_DIGS**.
906 : The max number that the overflow type (see the **PERFORMANCE** section) can
907 hold. Depends on **DC_LONG_BIT**.
911 : The maximum output base. Set at **DC_BASE_POW**.
915 : The maximum size of arrays. Set at **SIZE_MAX-1**.
919 : The maximum **scale**. Set at **DC_OVERFLOW_MAX-1**.
923 : The maximum length of strings. Set at **DC_OVERFLOW_MAX-1**.
927 : The maximum length of identifiers. Set at **DC_OVERFLOW_MAX-1**.
931 : The maximum length of a number (in decimal digits), which includes digits
932 after the decimal point. Set at **DC_OVERFLOW_MAX-1**.
936 : The maximum allowable exponent (positive or negative). Set at
941 : The maximum number of vars/arrays. Set at **SIZE_MAX-1**.
943 These limits are meant to be effectively non-existent; the limits are so large
944 (at least on 64-bit machines) that there should not be any point at which they
945 become a problem. In fact, memory should be exhausted before these limits should
948 # ENVIRONMENT VARIABLES
950 dc(1) recognizes the following environment variables:
954 : This is another way to give command-line arguments to dc(1). They should be
955 in the same format as all other command-line arguments. These are always
956 processed first, so any files given in **DC_ENV_ARGS** will be processed
957 before arguments and files given on the command-line. This gives the user
958 the ability to set up "standard" options and files to be used at every
959 invocation. The most useful thing for such files to contain would be useful
960 functions that the user might want every time dc(1) runs. Another use would
961 be to use the **-e** option to set **scale** to a value other than **0**.
963 The code that parses **DC_ENV_ARGS** will correctly handle quoted arguments,
964 but it does not understand escape sequences. For example, the string
965 **"/home/gavin/some dc file.dc"** will be correctly parsed, but the string
966 **"/home/gavin/some \"dc\" file.dc"** will include the backslashes.
968 The quote parsing will handle either kind of quotes, **'** or **"**. Thus,
969 if you have a file with any number of single quotes in the name, you can use
970 double quotes as the outside quotes, as in **"some 'dc' file.dc"**, and vice
971 versa if you have a file with double quotes. However, handling a file with
972 both kinds of quotes in **DC_ENV_ARGS** is not supported due to the
973 complexity of the parsing, though such files are still supported on the
974 command-line where the parsing is done by the shell.
978 : If this environment variable exists and contains an integer that is greater
979 than **1** and is less than **UINT16_MAX** (**2\^16-1**), dc(1) will output
980 lines to that length, including the backslash newline combo. The default
981 line length is **70**.
983 The special value of **0** will disable line length checking and print
984 numbers without regard to line length and without backslashes and newlines.
988 : If dc(1) is not in interactive mode (see the **INTERACTIVE MODE** section),
989 then this environment variable has no effect because dc(1) exits on
990 **SIGINT** when not in interactive mode.
992 However, when dc(1) is in interactive mode, then if this environment
993 variable exists and contains an integer, a non-zero value makes dc(1) reset
994 on **SIGINT**, rather than exit, and zero makes dc(1) exit. If this
995 environment variable exists and is *not* an integer, then dc(1) will exit on
998 This environment variable overrides the default, which can be queried with
999 the **-h** or **-\-help** options.
1003 : If TTY mode is *not* available (see the **TTY MODE** section), then this
1004 environment variable has no effect.
1006 However, when TTY mode is available, then if this environment variable
1007 exists and contains an integer, then a non-zero value makes dc(1) use TTY
1008 mode, and zero makes dc(1) not use TTY mode.
1010 This environment variable overrides the default, which can be queried with
1011 the **-h** or **-\-help** options.
1015 : If TTY mode is *not* available (see the **TTY MODE** section), then this
1016 environment variable has no effect.
1018 However, when TTY mode is available, then if this environment variable
1019 exists and contains an integer, a non-zero value makes dc(1) use a prompt,
1020 and zero or a non-integer makes dc(1) not use a prompt. If this environment
1021 variable does not exist and **DC_TTY_MODE** does, then the value of the
1022 **DC_TTY_MODE** environment variable is used.
1024 This environment variable and the **DC_TTY_MODE** environment variable
1025 override the default, which can be queried with the **-h** or **-\-help**
1030 dc(1) returns the following exit statuses:
1038 : A math error occurred. This follows standard practice of using **1** for
1039 expected errors, since math errors will happen in the process of normal
1042 Math errors include divide by **0**, taking the square root of a negative
1043 number, attempting to convert a negative number to a hardware integer,
1044 overflow when converting a number to a hardware integer, overflow when
1045 calculating the size of a number, and attempting to use a non-integer where
1046 an integer is required.
1048 Converting to a hardware integer happens for the second operand of the power
1053 : A parse error occurred.
1055 Parse errors include unexpected **EOF**, using an invalid character, failing
1056 to find the end of a string or comment, and using a token where it is
1061 : A runtime error occurred.
1063 Runtime errors include assigning an invalid number to any global (**ibase**,
1064 **obase**, or **scale**), giving a bad expression to a **read()** call,
1065 calling **read()** inside of a **read()** call, type errors (including
1066 attempting to execute a number), and attempting an operation when the stack
1067 has too few elements.
1071 : A fatal error occurred.
1073 Fatal errors include memory allocation errors, I/O errors, failing to open
1074 files, attempting to use files that do not have only ASCII characters (dc(1)
1075 only accepts ASCII characters), attempting to open a directory as a file,
1076 and giving invalid command-line options.
1078 The exit status **4** is special; when a fatal error occurs, dc(1) always exits
1079 and returns **4**, no matter what mode dc(1) is in.
1081 The other statuses will only be returned when dc(1) is not in interactive mode
1082 (see the **INTERACTIVE MODE** section), since dc(1) resets its state (see the
1083 **RESET** section) and accepts more input when one of those errors occurs in
1084 interactive mode. This is also the case when interactive mode is forced by the
1085 **-i** flag or **-\-interactive** option.
1087 These exit statuses allow dc(1) to be used in shell scripting with error
1088 checking, and its normal behavior can be forced by using the **-i** flag or
1089 **-\-interactive** option.
1093 Like bc(1), dc(1) has an interactive mode and a non-interactive mode.
1094 Interactive mode is turned on automatically when both **stdin** and **stdout**
1095 are hooked to a terminal, but the **-i** flag and **-\-interactive** option can
1096 turn it on in other situations.
1098 In interactive mode, dc(1) attempts to recover from errors (see the **RESET**
1099 section), and in normal execution, flushes **stdout** as soon as execution is
1100 done for the current input. dc(1) may also reset on **SIGINT** instead of exit,
1101 depending on the contents of, or default for, the **DC_SIGINT_RESET**
1102 environment variable (see the **ENVIRONMENT VARIABLES** section).
1106 If **stdin**, **stdout**, and **stderr** are all connected to a TTY, then "TTY
1107 mode" is considered to be available, and thus, dc(1) can turn on TTY mode,
1108 subject to some settings.
1110 If there is the environment variable **DC_TTY_MODE** in the environment (see the
1111 **ENVIRONMENT VARIABLES** section), then if that environment variable contains a
1112 non-zero integer, dc(1) will turn on TTY mode when **stdin**, **stdout**, and
1113 **stderr** are all connected to a TTY. If the **DC_TTY_MODE** environment
1114 variable exists but is *not* a non-zero integer, then dc(1) will not turn TTY
1117 If the environment variable **DC_TTY_MODE** does *not* exist, the default
1118 setting is used. The default setting can be queried with the **-h** or
1119 **-\-help** options.
1121 TTY mode is different from interactive mode because interactive mode is required
1122 in the [bc(1) specification][1], and interactive mode requires only **stdin**
1123 and **stdout** to be connected to a terminal.
1125 ## Command-Line History
1127 Command-line history is only enabled if TTY mode is, i.e., that **stdin**,
1128 **stdout**, and **stderr** are connected to a TTY and the **DC_TTY_MODE**
1129 environment variable (see the **ENVIRONMENT VARIABLES** section) and its default
1130 do not disable TTY mode. See the **COMMAND LINE HISTORY** section for more
1135 If TTY mode is available, then a prompt can be enabled. Like TTY mode itself, it
1136 can be turned on or off with an environment variable: **DC_PROMPT** (see the
1137 **ENVIRONMENT VARIABLES** section).
1139 If the environment variable **DC_PROMPT** exists and is a non-zero integer, then
1140 the prompt is turned on when **stdin**, **stdout**, and **stderr** are connected
1141 to a TTY and the **-P** and **-\-no-prompt** options were not used. The read
1142 prompt will be turned on under the same conditions, except that the **-R** and
1143 **-\-no-read-prompt** options must also not be used.
1145 However, if **DC_PROMPT** does not exist, the prompt can be enabled or disabled
1146 with the **DC_TTY_MODE** environment variable, the **-P** and **-\-no-prompt**
1147 options, and the **-R** and **-\-no-read-prompt** options. See the **ENVIRONMENT
1148 VARIABLES** and **OPTIONS** sections for more details.
1152 Sending a **SIGINT** will cause dc(1) to do one of two things.
1154 If dc(1) is not in interactive mode (see the **INTERACTIVE MODE** section), or
1155 the **DC_SIGINT_RESET** environment variable (see the **ENVIRONMENT VARIABLES**
1156 section), or its default, is either not an integer or it is zero, dc(1) will
1159 However, if dc(1) is in interactive mode, and the **DC_SIGINT_RESET** or its
1160 default is an integer and non-zero, then dc(1) will stop executing the current
1161 input and reset (see the **RESET** section) upon receiving a **SIGINT**.
1163 Note that "current input" can mean one of two things. If dc(1) is processing
1164 input from **stdin** in interactive mode, it will ask for more input. If dc(1)
1165 is processing input from a file in interactive mode, it will stop processing the
1166 file and start processing the next file, if one exists, or ask for input from
1167 **stdin** if no other file exists.
1169 This means that if a **SIGINT** is sent to dc(1) as it is executing a file, it
1170 can seem as though dc(1) did not respond to the signal since it will immediately
1171 start executing the next file. This is by design; most files that users execute
1172 when interacting with dc(1) have function definitions, which are quick to parse.
1173 If a file takes a long time to execute, there may be a bug in that file. The
1174 rest of the files could still be executed without problem, allowing the user to
1177 **SIGTERM** and **SIGQUIT** cause dc(1) to clean up and exit, and it uses the
1178 default handler for all other signals. The one exception is **SIGHUP**; in that
1179 case, and only when dc(1) is in TTY mode (see the **TTY MODE** section), a
1180 **SIGHUP** will cause dc(1) to clean up and exit.
1182 # COMMAND LINE HISTORY
1184 dc(1) supports interactive command-line editing.
1186 If dc(1) can be in TTY mode (see the **TTY MODE** section), history can be
1187 enabled. This means that command-line history can only be enabled when
1188 **stdin**, **stdout**, and **stderr** are all connected to a TTY.
1190 Like TTY mode itself, it can be turned on or off with the environment variable
1191 **DC_TTY_MODE** (see the **ENVIRONMENT VARIABLES** section).
1193 **Note**: tabs are converted to 8 spaces.
1197 This dc(1) ships with support for adding error messages for different locales
1198 and thus, supports **LC_MESSAGES**.
1206 The dc(1) utility operators are compliant with the operators in the bc(1)
1207 [IEEE Std 1003.1-2017 (“POSIX.1-2017”)][1] specification.
1211 None are known. Report bugs at https://git.yzena.com/gavin/bc.
1215 Gavin D. Howard <gavin@yzena.com> and contributors.
1217 [1]: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html