Lines Matching +full:dc +full:- +full:to +full:- +full:dc
2 .\" SPDX-License-Identifier: BSD-2-Clause
4 .\" Copyright (c) 2018-2024 Gavin D. Howard and contributors.
17 .\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
28 .TH "DC" "1" "August 2024" "Gavin D. Howard" "General Commands Manual"
32 dc \- arbitrary\-precision decimal reverse\-Polish notation calculator
34 \f[B]dc\f[R] [\f[B]\-cChiPRvVx\f[R]] [\f[B]\-\-version\f[R]]
35 [\f[B]\-\-help\f[R]] [\f[B]\-\-digit\-clamp\f[R]]
36 [\f[B]\-\-no\-digit\-clamp\f[R]] [\f[B]\-\-interactive\f[R]]
37 [\f[B]\-\-no\-prompt\f[R]] [\f[B]\-\-no\-read\-prompt\f[R]]
38 [\f[B]\-\-extended\-register\f[R]] [\f[B]\-e\f[R] \f[I]expr\f[R]]
39 [\f[B]\-\-expression\f[R]=\f[I]expr\f[R]\&...]
40 [\f[B]\-f\f[R] \f[I]file\f[R]\&...]
41 [\f[B]\-\-file\f[R]=\f[I]file\f[R]\&...]
44 dc(1) is an arbitrary\-precision calculator.
45 It uses a stack (reverse Polish notation) to store numbers and results
50 If no files are given on the command\-line, then dc(1) reads from
52 Otherwise, those files are processed, and dc(1) will then exit.
54 If a user wants to set up a standard environment, they can use
56 For example, if a user wants the \f[B]scale\f[R] always set to
57 \f[B]10\f[R], they can set \f[B]DC_ENV_ARGS\f[R] to \f[B]\-e 10k\f[R],
58 and this dc(1) will always start with a \f[B]scale\f[R] of \f[B]10\f[R].
60 The following are the options that dc(1) accepts.
62 \f[B]\-C\f[R], \f[B]\-\-no\-digit\-clamp\f[R]
63 Disables clamping of digits greater than or equal to the current
67 This means that the value added to a number from a digit is always that
68 digit\[cq]s value multiplied by the value of ibase raised to the power
72 If this and/or the \f[B]\-c\f[R] or \f[B]\-\-digit\-clamp\f[R] options
77 can be queried with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options.
79 This is a \f[B]non\-portable extension\f[R].
82 \f[B]\-c\f[R], \f[B]\-\-digit\-clamp\f[R]
83 Enables clamping of digits greater than or equal to the current
87 This means that digits that the value added to a number from a digit
88 that is greater than or equal to the ibase is the value of ibase minus 1
89 all multiplied by the value of ibase raised to the power of the
93 If this and/or the \f[B]\-C\f[R] or \f[B]\-\-no\-digit\-clamp\f[R]
98 can be queried with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options.
100 This is a \f[B]non\-portable extension\f[R].
103 \f[B]\-e\f[R] \f[I]expr\f[R], \f[B]\-\-expression\f[R]=\f[I]expr\f[R]
112 If this option is given on the command\-line (i.e., not in
114 then after processing all expressions and files, dc(1) will exit, unless
115 \f[B]\-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to
116 \f[B]\-f\f[R] or \f[B]\-\-file\f[R], whether on the command\-line or in
118 However, if any other \f[B]\-e\f[R], \f[B]\-\-expression\f[R],
119 \f[B]\-f\f[R], or \f[B]\-\-file\f[R] arguments are given after
120 \f[B]\-f\-\f[R] or equivalent is given, dc(1) will give a fatal error
123 This is a \f[B]non\-portable extension\f[R].
126 \f[B]\-f\f[R] \f[I]file\f[R], \f[B]\-\-file\f[R]=\f[I]file\f[R]
133 If this option is given on the command\-line (i.e., not in
135 then after processing all expressions and files, dc(1) will exit, unless
136 \f[B]\-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to
137 \f[B]\-f\f[R] or \f[B]\-\-file\f[R].
138 However, if any other \f[B]\-e\f[R], \f[B]\-\-expression\f[R],
139 \f[B]\-f\f[R], or \f[B]\-\-file\f[R] arguments are given after
140 \f[B]\-f\-\f[R] or equivalent is given, dc(1) will give a fatal error
143 This is a \f[B]non\-portable extension\f[R].
146 \f[B]\-h\f[R], \f[B]\-\-help\f[R]
149 \f[B]\-I\f[R] \f[I]ibase\f[R], \f[B]\-\-ibase\f[R]=\f[I]ibase\f[R]
150 Sets the builtin variable \f[B]ibase\f[R] to the value \f[I]ibase\f[R]
157 This is a \f[B]non\-portable extension\f[R].
160 \f[B]\-i\f[R], \f[B]\-\-interactive\f[R]
165 This is a \f[B]non\-portable extension\f[R].
168 \f[B]\-L\f[R], \f[B]\-\-no\-line\-length\f[R]
171 In other words, this option sets \f[B]BC_LINE_LENGTH\f[R] to \f[B]0\f[R]
175 This is a \f[B]non\-portable extension\f[R].
178 \f[B]\-O\f[R] \f[I]obase\f[R], \f[B]\-\-obase\f[R]=\f[I]obase\f[R]
179 Sets the builtin variable \f[B]obase\f[R] to the value \f[I]obase\f[R]
186 This is a \f[B]non\-portable extension\f[R].
189 \f[B]\-P\f[R], \f[B]\-\-no\-prompt\f[R]
194 to having them in dc(1).
195 Most of those users would want to put this option in
202 This is a \f[B]non\-portable extension\f[R].
205 \f[B]\-R\f[R], \f[B]\-\-no\-read\-prompt\f[R]
210 used to having them in dc(1).
211 Most of those users would want to put this option in
213 This option is also useful in hash bang lines of dc(1) scripts that
224 This is a \f[B]non\-portable extension\f[R].
227 \f[B]\-S\f[R] \f[I]scale\f[R], \f[B]\-\-scale\f[R]=\f[I]scale\f[R]
228 Sets the builtin variable \f[B]scale\f[R] to the value \f[I]scale\f[R]
235 This is a \f[B]non\-portable extension\f[R].
238 \f[B]\-v\f[R], \f[B]\-V\f[R], \f[B]\-\-version\f[R]
241 \f[B]\-x\f[R] \f[B]\-\-extended\-register\f[R]
247 This is a \f[B]non\-portable extension\f[R].
250 \f[B]\-z\f[R], \f[B]\-\-leading\-zeroes\f[R]
251 Makes dc(1) print all numbers greater than \f[B]\-1\f[R] and less than
252 \f[B]1\f[R], and not equal to \f[B]0\f[R], with a leading zero.
255 This is a \f[B]non\-portable extension\f[R].
258 All long options are \f[B]non\-portable extensions\f[R].
260 If no files are given on the command\-line and no files or expressions
261 are given by the \f[B]\-f\f[R], \f[B]\-\-file\f[R], \f[B]\-e\f[R], or
262 \f[B]\-\-expression\f[R] options, then dc(1) reads from \f[B]stdin\f[R].
264 However, there is a caveat to this.
267 The only exception to this is if a string has been finished, but not
270 balanced before dc(1) parses and executes.
272 Any non\-error output is written to \f[B]stdout\f[R].
277 \f[B]Note\f[R]: Unlike other dc(1) implementations, this dc(1) will
279 write to \f[B]stdout\f[R], so if \f[B]stdout\f[R] is closed, as in
280 \f[B]dc >&\-\f[R], it will quit with an error.
281 This is done so that dc(1) can report problems when \f[B]stdout\f[R] is
282 redirected to a file.
284 If there are scripts that depend on the behavior of other dc(1)
285 implementations, it is recommended that those scripts be changed to
286 redirect \f[B]stdout\f[R] to \f[B]/dev/null\f[R].
288 Any error output is written to \f[B]stderr\f[R].
290 \f[B]Note\f[R]: Unlike other dc(1) implementations, this dc(1) will
292 write to \f[B]stderr\f[R], so if \f[B]stderr\f[R] is closed, as in
293 \f[B]dc 2>&\-\f[R], it will quit with an error.
294 This is done so that dc(1) can exit with an error code when
295 \f[B]stderr\f[R] is redirected to a file.
297 If there are scripts that depend on the behavior of other dc(1)
298 implementations, it is recommended that those scripts be changed to
299 redirect \f[B]stderr\f[R] to \f[B]/dev/null\f[R].
307 determines how to interpret constant numbers.
313 The max allowable value for \f[B]ibase\f[R] can be queried in dc(1)
317 determines how to output results.
332 The max allowable value for \f[B]scale\f[R] can be queried in dc(1)
336 This is a \f[B]non\-portable extension\f[R].
338 Numbers are strings made up of digits, uppercase letters up to
340 Numbers can have up to \f[B]DC_NUM_MAX\f[R] digits.
341 Uppercase letters are equal to \f[B]9\f[R] plus their position in the
345 \f[B]ibase\f[R] (i.e., they are greater than or equal to the current
347 the \f[B]\-c\f[R]/\f[B]\-\-digit\-clamp\f[R] or
348 \f[B]\-C\f[R]/\f[B]\-\-no\-digit\-clamp\f[R] options (see the
352 \f[B]\-h\f[R]/\f[B]\-\-help\f[R] option.
355 equal to the current value of \f[B]ibase\f[R] are not changed.
359 \f[B]AB\f[R] is equal to \f[B]3\[ha]1*A+3\[ha]0*B\f[R], which is
363 to the current value of \f[B]ibase\f[R] are set to the value of the
367 \f[B]AB\f[R] is equal to \f[B]3\[ha]1*2+3\[ha]0*2\f[R], which is
370 There is one exception to clamping: single\-character numbers (i.e.,
377 section) and is meant to provide an easy way to set the current
406 digit is interpreted as an 8\-bit ASCII character, making it a byte
411 This is a \f[B]non\-portable extension\f[R].
415 Prints the entire contents of the stack, in order from newest to oldest,
427 The \f[I]scale\f[R] of the result is equal to the max \f[I]scale\f[R] of
430 \f[B]\-\f[R]
433 The \f[I]scale\f[R] of the result is equal to the max \f[I]scale\f[R] of
441 \f[I]scale\f[R] of the result is equal to
448 The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R].
451 The first value popped off of the stack must be non\-zero.
459 Remaindering is equivalent to 1) Computing \f[B]a/b\f[R] to current
460 \f[B]scale\f[R], and 2) Using the result of step 1 to calculate
461 \f[B]a\-(a/b)*b\f[R] to \f[I]scale\f[R]
464 The first value popped off of the stack must be non\-zero.
471 This is equivalent to \f[B]x y / x y %\f[R] except that \f[B]x\f[R] and
475 The first value popped off of the stack must be non\-zero.
477 This is a \f[B]non\-portable extension\f[R].
481 The top two values are popped off the stack, the second is raised to the
483 The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R].
488 non\-zero.
494 The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R].
497 The value popped off of the stack must be non\-negative.
507 This behavior without a number is a \f[B]non\-portable extension\f[R].
516 This is a \f[B]non\-portable extension\f[R].
525 integer and non\-zero.
527 and non\-negative.
530 This is a \f[B]non\-portable extension\f[R].
538 This is a \f[B]non\-portable extension\f[R].
546 This is a \f[B]non\-portable extension\f[R].
555 This is a \f[B]non\-portable extension\f[R].
560 \f[B]1\f[R] is pushed if the first is less than or equal to the second,
564 This is a \f[B]non\-portable extension\f[R].
573 This is a \f[B]non\-portable extension\f[R].
578 \f[B]1\f[R] is pushed if the first is greater than or equal to the
582 This is a \f[B]non\-portable extension\f[R].
587 If they are both non\-zero, a \f[B]1\f[R] is pushed onto the stack.
593 a short\-circuit operator.
595 This is a \f[B]non\-portable extension\f[R].
600 If at least one of them is non\-zero, a \f[B]1\f[R] is pushed onto the
606 a short\-circuit operator.
608 This is a \f[B]non\-portable extension\f[R].
652 Pops the value off of the top of the stack and uses it to set
662 Pops the value off of the top of the stack and uses it to set
672 Pops the value off of the top of the stack and uses it to set
673 \f[B]scale\f[R], which must be non\-negative.
694 This is a \f[B]non\-portable extension\f[R].
702 This is a \f[B]non\-portable extension\f[R].
710 This is a \f[B]non\-portable extension\f[R].
720 While arithmetic operations have to have numbers, and will print an
750 one\-character string where the character is the result of the mod
755 If it is not, then the first character of the original string is used to
756 create the new string as a one\-character string.
759 This is a \f[B]non\-portable extension\f[R].
783 If either or both of the values are not numbers, dc(1) will raise an
792 If either or both of the values are not numbers, dc(1) will raise an
795 This is a \f[B]non\-portable extension\f[R].
804 If either or both of the values are not numbers, dc(1) will raise an
813 If either or both of the values are not numbers, dc(1) will raise an
816 This is a \f[B]non\-portable extension\f[R].
825 If either or both of the values are not numbers, dc(1) will raise an
834 If either or both of the values are not numbers, dc(1) will raise an
837 This is a \f[B]non\-portable extension\f[R].
846 If either or both of the values are not numbers, dc(1) will raise an
855 If either or both of the values are not numbers, dc(1) will raise an
858 This is a \f[B]non\-portable extension\f[R].
863 If the first value is equal to the second, then the contents of register
867 If either or both of the values are not numbers, dc(1) will raise an
876 If either or both of the values are not numbers, dc(1) will raise an
879 This is a \f[B]non\-portable extension\f[R].
884 If the first value is not equal to the second, then the contents of
888 If either or both of the values are not numbers, dc(1) will raise an
897 If either or both of the values are not numbers, dc(1) will raise an
900 This is a \f[B]non\-portable extension\f[R].
905 This is to allow macros to request input from users.
910 If there are no macros, or only one macro executing, dc(1) exits.
913 Pops a value from the stack which must be non\-negative and is used the
914 number of macro executions to pop off of the execution stack.
915 If the number of levels to pop is greater than the number of executing
916 macros, dc(1) exits.
922 to make dc(1) exit with the \f[B]Q\f[R] command, so the sequence
923 \f[B],Q\f[R] will make dc(1) exit.
926 This is a \f[B]non\-portable extension\f[R].
959 This is a \f[B]non\-portable extension\f[R].
968 This is a \f[B]non\-portable extension\f[R].
981 \f[B]0\f[R] in the top item) when dc(1) starts, dc(1) requires that each
982 register\[cq]s stack must always have at least one item; dc(1) will give
986 This is a \f[B]non\-portable extension\f[R].
1005 This is a \f[B]non\-portable extension\f[R].
1027 been enabled with the \f[B]\-z\f[R] or \f[B]\-\-leading\-zeroes\f[R]
1028 options (see the \f[B]OPTIONS\f[R] section), non\-zero otherwise.
1036 their stack, and it is a runtime error to attempt to pop that item off
1039 In non\-extended register mode, a register name is just the single
1043 bracket to be used as a register name.
1045 Unlike most other dc(1) implentations, this dc(1) provides nearly
1048 If extended register mode is enabled (\f[B]\-x\f[R] or
1049 \f[B]\-\-extended\-register\f[R] command\-line arguments are given),
1052 a space (according to \f[B]isspace()\f[R]) and not a newline
1055 In that case, the register name is found according to the regex
1056 \f[B][a\-z][a\-z0\-9_]*\f[R] (like bc(1) identifiers), and it is a parse
1057 error if the next non\-space characters do not match that regex.
1059 When dc(1) encounters an error or a signal that it has a non\-default
1066 Then the execution point is set so that any code waiting to execute
1072 Thus, when dc(1) resets, it skips any remaining code waiting to be
1078 Most dc(1) implementations use \f[B]char\f[R] types to calculate the
1080 This dc(1) does something different.
1082 It uses large integers to calculate more than \f[B]1\f[R] decimal digit
1092 In addition, this dc(1) uses an even larger integer for overflow
1095 always at least twice as large as the integer type used to store digits.
1097 The following are the limits on dc(1):
1126 Set at \f[B]SIZE_MAX\-1\f[R].
1130 Set at \f[B]DC_OVERFLOW_MAX\-1\f[R].
1134 Set at \f[B]DC_OVERFLOW_MAX\-1\f[R].
1138 Set at \f[B]DC_OVERFLOW_MAX\-1\f[R].
1143 Set at \f[B]DC_OVERFLOW_MAX\-1\f[R].
1151 Set at \f[B]SIZE_MAX\-1\f[R].
1153 These limits are meant to be effectively non\-existent; the limits are
1154 so large (at least on 64\-bit machines) that there should not be any
1158 As \f[B]non\-portable extensions\f[R], dc(1) recognizes the following
1162 This is another way to give command\-line arguments to dc(1).
1163 They should be in the same format as all other command\-line arguments.
1166 on the command\-line.
1167 This gives the user the ability to set up \[lq]standard\[rq] options and
1168 files to be used at every invocation.
1169 The most useful thing for such files to contain would be useful
1170 functions that the user might want every time dc(1) runs.
1171 Another use would be to use the \f[B]\-e\f[R] option to set
1172 \f[B]scale\f[R] to a value other than \f[B]0\f[R].
1177 For example, the string \f[B]\[lq]/home/gavin/some dc file.dc\[rq]\f[R]
1179 \[dq]dc\[dq] file.dc\[rq]\f[R] will include the backslashes.
1185 `dc' file.dc\[rq]\f[R], and vice versa if you have a file with double
1188 \f[B]DC_ENV_ARGS\f[R] is not supported due to the complexity of the
1189 parsing, though such files are still supported on the command\-line
1196 (\f[B]2\[ha]16\-1\f[R]), dc(1) will output lines to that length,
1202 print numbers without regard to line length and without backslashes and
1207 If dc(1) is not in interactive mode (see the \f[B]INTERACTIVE MODE\f[R]
1208 section), then this environment variable has no effect because dc(1)
1212 However, when dc(1) is in interactive mode, then if this environment
1213 variable exists and contains an integer, a non\-zero value makes dc(1)
1214 reset on \f[B]SIGINT\f[R], rather than exit, and zero makes dc(1) exit.
1216 then dc(1) will exit on \f[B]SIGINT\f[R].
1219 with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options.
1228 exists and contains an integer, then a non\-zero value makes dc(1) use
1229 TTY mode, and zero makes dc(1) not use TTY mode.
1232 with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options.
1241 exists and contains an integer, a non\-zero value makes dc(1) use a
1242 prompt, and zero or a non\-integer makes dc(1) not use a prompt.
1249 \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options.
1253 If any expressions or expression files are given on the command\-line
1254 with \f[B]\-e\f[R], \f[B]\-\-expression\f[R], \f[B]\-f\f[R], or
1255 \f[B]\-\-file\f[R], then if this environment variable exists and
1256 contains an integer, a non\-zero value makes dc(1) exit after executing
1257 the expressions and expression files, and a zero value makes dc(1) not
1262 with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options.
1267 contains an integer, a non\-zero value makes dc(1) clamp digits that are
1268 greater than or equal to the current \f[B]ibase\f[R] so that all such
1269 digits are considered equal to the \f[B]ibase\f[R] minus 1, and a zero
1270 value disables such clamping so that those digits are always equal to
1274 This never applies to single\-digit numbers, as per the bc(1) standard
1278 with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options.
1293 negative number, attempting to convert a negative number to a hardware
1294 integer, overflow when converting a number to a hardware integer,
1295 overflow when calculating the size of a number, and attempting to use a
1296 non\-integer where an integer is required.
1298 Converting to a hardware integer happens for the second operand of the
1307 character, failing to find the end of a string or comment, and using a
1315 Runtime errors include assigning an invalid number to any global
1317 expression to a \f[B]read()\f[R] call, calling \f[B]read()\f[R] inside
1318 of a \f[B]read()\f[R] call, type errors (including attempting to execute
1327 Fatal errors include memory allocation errors, I/O errors, failing to
1328 open files, attempting to use files that do not have only ASCII
1329 characters (dc(1) only accepts ASCII characters), attempting to open a
1330 directory as a file, and giving invalid command\-line options.
1333 The exit status \f[B]4\f[R] is special; when a fatal error occurs, dc(1)
1334 always exits and returns \f[B]4\f[R], no matter what mode dc(1) is in.
1336 The other statuses will only be returned when dc(1) is not in
1341 \f[B]\-i\f[R] flag or \f[B]\-\-interactive\f[R] option.
1343 These exit statuses allow dc(1) to be used in shell scripting with error
1345 \f[B]\-i\f[R] flag or \f[B]\-\-interactive\f[R] option.
1347 Like bc(1), dc(1) has an interactive mode and a non\-interactive mode.
1349 and \f[B]stdout\f[R] are hooked to a terminal, but the \f[B]\-i\f[R]
1350 flag and \f[B]\-\-interactive\f[R] option can turn it on in other
1353 In interactive mode, dc(1) attempts to recover from errors (see the
1361 connected to a TTY, then \[lq]TTY mode\[rq] is considered to be
1362 available, and thus, dc(1) can turn on TTY mode, subject to some
1367 that environment variable contains a non\-zero integer, dc(1) will turn
1369 are all connected to a TTY.
1371 \f[I]not\f[R] a non\-zero integer, then dc(1) will not turn TTY mode on.
1375 The default setting can be queried with the \f[B]\-h\f[R] or
1376 \f[B]\-\-help\f[R] options.
1381 \f[B]stdout\f[R] to be connected to a terminal.
1389 non\-zero integer, then the prompt is turned on when \f[B]stdin\f[R],
1390 \f[B]stdout\f[R], and \f[B]stderr\f[R] are connected to a TTY and the
1391 \f[B]\-P\f[R] and \f[B]\-\-no\-prompt\f[R] options were not used.
1393 the \f[B]\-R\f[R] and \f[B]\-\-no\-read\-prompt\f[R] options must also
1398 the \f[B]\-P\f[R] and \f[B]\-\-no\-prompt\f[R] options, and the
1399 \f[B]\-R\f[R] and \f[B]\-\-no\-read\-prompt\f[R] options.
1403 Sending a \f[B]SIGINT\f[R] will cause dc(1) to do one of two things.
1405 If dc(1) is not in interactive mode (see the \f[B]INTERACTIVE MODE\f[R]
1408 an integer or it is zero, dc(1) will exit.
1410 However, if dc(1) is in interactive mode, and the
1411 \f[B]DC_SIGINT_RESET\f[R] or its default is an integer and non\-zero,
1412 then dc(1) will stop executing the current input and reset (see the
1416 If dc(1) is processing input from \f[B]stdin\f[R] in interactive mode,
1418 If dc(1) is processing input from a file in interactive mode, it will
1422 This means that if a \f[B]SIGINT\f[R] is sent to dc(1) as it is
1423 executing a file, it can seem as though dc(1) did not respond to the
1426 dc(1) have function definitions, which are quick to parse.
1427 If a file takes a long time to execute, there may be a bug in that file.
1429 the user to continue.
1431 \f[B]SIGTERM\f[R] and \f[B]SIGQUIT\f[R] cause dc(1) to clean up and
1434 This dc(1) ships with support for adding error messages for different
1439 The dc(1) utility operators and some behavior are compliant with the
1440 operators in the IEEE Std 1003.1\-2017 (\[lq]POSIX.1\-2017\[rq]) bc(1)