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