Lines Matching +full:dc +full:- +full:valid
1 <!---
3 SPDX-License-Identifier: BSD-2-Clause
5 Copyright (c) 2018-2024 Gavin D. Howard and contributors.
29 -->
33 dc - arbitrary-precision decimal reverse-Polish notation calculator
37 …dc** [**-cChiPRvVx**] [**-\-version**] [**-\-help**] [**-\-digit-clamp**] [**-\-no-digit-clamp**] …
41 dc(1) is an arbitrary-precision calculator. It uses a stack (reverse Polish
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
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.
58 **-C**, **-\-no-digit-clamp**
67 If this and/or the **-c** or **-\-digit-clamp** options are given multiple
72 with the **-h** or **-\-help** options.
74 This is a **non-portable extension**.
76 **-c**, **-\-digit-clamp**
86 If this and/or the **-C** or **-\-no-digit-clamp** options are given
91 with the **-h** or **-\-help** options.
93 This is a **non-portable extension**.
95 **-E** *seed*, **-\-seed**=*seed*
98 is in base 10. It is a fatal error if *seed* is not a valid number.
102 This is a **non-portable extension**.
104 **-e** *expr*, **-\-expression**=*expr*
111 If this option is given on the command-line (i.e., not in **DC_ENV_ARGS**,
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.
119 This is a **non-portable extension**.
121 **-f** *file*, **-\-file**=*file*
127 If this option is given on the command-line (i.e., not in **DC_ENV_ARGS**,
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.
134 This is a **non-portable extension**.
136 **-h**, **-\-help**
140 **-I** *ibase*, **-\-ibase**=*ibase*
143 *ibase* is in base 10. It is a fatal error if *ibase* is not a valid number.
147 This is a **non-portable extension**.
149 **-i**, **-\-interactive**
153 This is a **non-portable extension**.
155 **-L**, **-\-no-line-length**
161 This is a **non-portable extension**.
163 **-O** *obase*, **-\-obase**=*obase*
166 *obase* is in base 10. It is a fatal error if *obase* is not a valid number.
170 This is a **non-portable extension**.
172 **-P**, **-\-no-prompt**
176 want a prompt or are not used to having them in dc(1). Most of those users
182 This is a **non-portable extension**.
184 **-R**, **-\-no-read-prompt**
188 do not want a read prompt or are not used to having them in dc(1). Most of
191 lines of dc(1) scripts that prompt for user input.
200 This is a **non-portable extension**.
202 **-S** *scale*, **-\-scale**=*scale*
205 *scale* is in base 10. It is a fatal error if *scale* is not a valid number.
209 This is a **non-portable extension**.
211 **-v**, **-V**, **-\-version**
215 **-x** **-\-extended-register**
220 This is a **non-portable extension**.
222 **-z**, **-\-leading-zeroes**
224 : Makes dc(1) print all numbers greater than **-1** and less than **1**, and
227 This is a **non-portable extension**.
229 All long options are **non-portable extensions**.
233 If no files are given on the command-line and no files or expressions are given
234 by the **-f**, **-\-file**, **-e**, or **-\-expression** options, then dc(1)
241 brackets, all brackets must be balanced before dc(1) parses and executes.
245 Any non-error output is written to **stdout**. In addition, if history (see the
249 **Note**: Unlike other dc(1) implementations, this dc(1) will issue a fatal
251 **stdout** is closed, as in **dc <file> >&-**, it will quit with an error. This
252 is done so that dc(1) can report problems when **stdout** is redirected to a
255 If there are scripts that depend on the behavior of other dc(1) implementations,
263 **Note**: Unlike other dc(1) implementations, this dc(1) will issue a fatal
265 **stderr** is closed, as in **dc <file> 2>&-**, it will quit with an error. This
266 is done so that dc(1) can exit with an error code when **stderr** is redirected
269 If there are scripts that depend on the behavior of other dc(1) implementations,
283 The max allowable value for **ibase** can be queried in dc(1) programs with the
294 Outputting in scientific and engineering notations are **non-portable
301 allowable value for **scale** can be queried in dc(1) programs with the **V**
304 **seed** is a register containing the current seed for the pseudo-random number
306 assigned to **seed** later, the pseudo-random number generator is guaranteed to
307 produce the same sequence of pseudo-random numbers that were generated after the
311 pseudo-random numbers. Likewise, when a value is assigned to **seed**, it is not
318 **Note**: The values returned by the pseudo-random number generator with the
320 This is a consequence of using a seeded pseudo-random number generator. However,
322 means that the pseudo-random values from dc(1) should only be used where a
323 reproducible stream of pseudo-random numbers is *ESSENTIAL*. In any other case,
324 use a non-seeded pseudo-random number generator.
326 The pseudo-random number generator, **seed**, and all associated operations are
327 **non-portable extensions**.
332 **non-portable extension**.
343 behavior depends on the existence of the **-c**/**-\-digit-clamp** or
344 **-C**/**-\-no-digit-clamp** options (see the **OPTIONS** section), the
347 the **-h**/**-\-help** option.
356 current value of **ibase** are set to the value of the highest valid digit in
362 There is one exception to clamping: single-character numbers (i.e., **A**
373 In addition, dc(1) accepts numbers in scientific notation. These have the form
381 if **ibase** is **16** and dc(1) is given the number string **FFeA**, the
382 resulting decimal number will be **2550000000000**, and if dc(1) is given the
385 Accepting input as scientific notation is a **non-portable extension**.
389 The valid commands are listed below.
402 **non-portable extension**.
422 interpreted as an 8-bit ASCII character, making it a byte stream.
426 This is a **non-portable extension**.
445 **-**
464 The first value popped off of the stack must be non-zero.
472 2) Using the result of step 1 to calculate **a-(a/b)\*b** to *scale*
475 The first value popped off of the stack must be non-zero.
484 The first value popped off of the stack must be non-zero.
486 This is a **non-portable extension**.
496 non-zero.
504 The value popped off of the stack must be non-negative.
513 **non-portable extension**.
520 This is a **non-portable extension**.
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
532 This is a **non-portable extension**.
539 This is a **non-portable extension**.
546 The first value popped off of the stack must be an integer and non-negative.
548 This is a **non-portable extension**.
555 The first value popped off of the stack must be an integer and non-negative.
557 This is a **non-portable extension**.
564 The first value popped off of the stack must be an integer and non-negative.
566 This is a **non-portable extension**.
573 This is a **non-portable extension**.
580 This is a **non-portable extension**.
587 This is a **non-portable extension**.
595 This is a **non-portable extension**.
602 This is a **non-portable extension**.
610 This is a **non-portable extension**.
614 : The top two values are popped off of the stack. If they are both non-zero, a
618 This is like the **&&** operator in bc(1), and it is *not* a short-circuit
621 This is a **non-portable extension**.
626 non-zero, a **1** is pushed onto the stack. If both of them are zero, then a
629 This is like the **||** operator in bc(1), and it is *not* a short-circuit
632 This is a **non-portable extension**.
634 ## Pseudo-Random Number Generator
636 dc(1) has a built-in pseudo-random number generator. These commands query the
637 pseudo-random number generator. (See Parameters for more information about the
638 **seed** value that controls the pseudo-random number generator.)
640 The pseudo-random number generator is guaranteed to **NOT** be
649 limitations of the pseudo-random number generator.
651 This is a **non-portable extension**.
657 non-integer, an error is raised, and dc(1) resets (see the **RESET**
660 pseudo-random integers, multiplying them by appropriate powers of
667 limitations of the pseudo-random number generator.
669 This is a **non-portable extension**.
739 which must be non-negative.
746 meaning of **seed** is dependent on the current pseudo-random number
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
758 sequence of pseudo-random numbers. This means that certain values assigned
759 to **seed** will not produce unique sequences of pseudo-random numbers.
764 This is a **non-portable extension**.
782 This is a **non-portable extension**.
788 This is a **non-portable extension**.
794 This is a **non-portable extension**.
800 This is a **non-portable extension**.
805 pseudo-random number generator command.
807 This is a **non-portable extension**.
813 dc(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
842 string; otherwise, push a one-character string where the character is the
847 the original string is used to create the new string as a one-character
850 This is a **non-portable extension**.
872 If either or both of the values are not numbers, dc(1) will raise an error
879 If either or both of the values are not numbers, dc(1) will raise an error
882 This is a **non-portable extension**.
890 If either or both of the values are not numbers, dc(1) will raise an error
897 If either or both of the values are not numbers, dc(1) will raise an error
900 This is a **non-portable extension**.
908 If either or both of the values are not numbers, dc(1) will raise an error
915 If either or both of the values are not numbers, dc(1) will raise an error
918 This is a **non-portable extension**.
926 If either or both of the values are not numbers, dc(1) will raise an error
933 If either or both of the values are not numbers, dc(1) will raise an error
936 This is a **non-portable extension**.
944 If either or both of the values are not numbers, dc(1) will raise an error
951 If either or both of the values are not numbers, dc(1) will raise an error
954 This is a **non-portable extension**.
962 If either or both of the values are not numbers, dc(1) will raise an error
969 If either or both of the values are not numbers, dc(1) will raise an error
972 This is a **non-portable extension**.
983 macro executing, dc(1) exits.
987 : Pops a value from the stack which must be non-negative and is used the
989 of levels to pop is greater than the number of executing macros, dc(1)
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.
999 This is a **non-portable extension**.
1028 This is a **non-portable extension**.
1035 This is a **non-portable extension**.
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
1052 This is a **non-portable extension**.
1072 This is a **non-portable extension**.
1095 with the **-z** or **-\-leading-zeroes** options (see the **OPTIONS**
1096 section), non-zero otherwise.
1108 In non-extended register mode, a register name is just the single character that
1115 Unlike most other dc(1) implentations, this dc(1) provides nearly unlimited
1118 If extended register mode is enabled (**-x** or **-\-extended-register**
1119 command-line arguments are given), then normal single character registers are
1125 **\[a-z\]\[a-z0-9\_\]\*** (like bc(1) identifiers), and it is a parse error if
1126 the next non-space characters do not match that regex.
1130 When dc(1) encounters an error or a signal that it has a non-default handler
1141 Thus, when dc(1) resets, it skips any remaining code waiting to be executed.
1148 Most dc(1) implementations use **char** types to calculate the value of **1**
1149 decimal digit at a time, but that can be slow. This dc(1) does something
1159 In addition, this dc(1) uses an even larger integer for overflow checking. This
1165 The following are the limits on dc(1):
1169 : The number of bits in the **long** type in the environment where dc(1) was
1194 : The maximum size of arrays. Set at **SIZE_MAX-1**.
1198 : The maximum **scale**. Set at **DC_OVERFLOW_MAX-1**.
1202 : The maximum length of strings. Set at **DC_OVERFLOW_MAX-1**.
1206 : The maximum length of identifiers. Set at **DC_OVERFLOW_MAX-1**.
1211 after the decimal point. Set at **DC_OVERFLOW_MAX-1**.
1215 : The maximum integer (inclusive) returned by the **'** command, if dc(1). Set
1216 at **2\^DC_LONG_BIT-1**.
1225 : The maximum number of vars/arrays. Set at **SIZE_MAX-1**.
1227 These 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
1234 As **non-portable extensions**, dc(1) recognizes the following environment
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
1242 before arguments and files given on the command-line. This gives the user
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**.
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.
1255 double quotes as the outside quotes, as in **"some 'dc' file.dc"**, and vice
1259 command-line where the parsing is done by the shell.
1264 than **1** and is less than **UINT16_MAX** (**2\^16-1**), dc(1) will output
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
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
1284 the **-h** or **-\-help** options.
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.
1296 the **-h** or **-\-help** options.
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
1310 override the default, which can be queried with the **-h** or **-\-help**
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
1319 dc(1) not exit.
1322 the **-h** or **-\-help** options.
1327 integer, a non-zero value makes dc(1) clamp digits that are greater than or
1333 This never applies to single-digit numbers, as per the bc(1) standard (see
1337 the **-h** or **-\-help** options.
1341 dc(1) returns the following exit statuses:
1354 number, using a negative number as a bound for the pseudo-random number
1357 calculating the size of a number, and attempting to use a non-integer where
1387 files, attempting to use files that do not have only ASCII characters (dc(1)
1389 and giving invalid command-line options.
1391 The exit status **4** is special; when a fatal error occurs, dc(1) always exits
1392 and returns **4**, no matter what mode dc(1) is in.
1394 The 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
1398 **-i** flag or **-\-interactive** option.
1400 These exit statuses allow dc(1) to be used in shell scripting with error
1401 checking, and its normal behavior can be forced by using the **-i** flag or
1402 **-\-interactive** option.
1406 Like bc(1), dc(1) has an interactive mode and a non-interactive mode.
1408 are hooked to a terminal, but the **-i** flag and **-\-interactive** option can
1411 In interactive mode, dc(1) attempts to recover from errors (see the **RESET**
1413 done for the current input. dc(1) may also reset on **SIGINT** instead of exit,
1420 mode" is considered to be available, and thus, dc(1) can turn on TTY mode,
1425 non-zero integer, dc(1) will turn on TTY mode when **stdin**, **stdout**, and
1427 variable exists but is *not* a non-zero integer, then dc(1) will not turn TTY
1431 setting is used. The default setting can be queried with the **-h** or
1432 **-\-help** options.
1438 ## Command-Line History
1440 Command-line history is only enabled if TTY mode is, i.e., that **stdin**,
1452 If the environment variable **DC_PROMPT** exists and is a non-zero integer, then
1454 to a TTY and the **-P** and **-\-no-prompt** options were not used. The read
1455 prompt will be turned on under the same conditions, except that the **-R** and
1456 **-\-no-read-prompt** options must also not be used.
1459 with the **DC_TTY_MODE** environment variable, the **-P** and **-\-no-prompt**
1460 options, and the **-R** and **-\-no-read-prompt** options. See the **ENVIRONMENT
1465 Sending a **SIGINT** will cause dc(1) to do one of two things.
1467 If dc(1) is not in interactive mode (see the **INTERACTIVE MODE** section), or
1469 section), or its default, is either not an integer or it is zero, dc(1) will
1472 However, if dc(1) is in interactive mode, and the **DC_SIGINT_RESET** or its
1473 default is an integer and non-zero, then dc(1) will stop executing the current
1476 Note that "current input" can mean one of two things. If dc(1) is processing
1477 input from **stdin** in interactive mode, it will ask for more input. If dc(1)
1482 This means that if a **SIGINT** is sent to dc(1) as it is executing a file, it
1483 can seem as though dc(1) did not respond to the signal since it will immediately
1485 when interacting with dc(1) have function definitions, which are quick to parse.
1490 **SIGTERM** and **SIGQUIT** cause dc(1) to clean up and exit, and it uses the
1492 case, 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.
1497 dc(1) supports interactive command-line editing.
1499 If dc(1) can be in TTY mode (see the **TTY MODE** section), history can be
1500 enabled. This means that command-line history can only be enabled when
1514 The dc(1) utility operators and some behavior are compliant with the operators
1515 in the IEEE Std 1003.1-2017 (“POSIX.1-2017”) bc(1) specification at