1dc(1) General Commands Manual dc(1)
2
6 dc - an arbitrary precision calculator
7
9 dc [-V] [--version] [-h] [--help]
10 [-e scriptexpression] [--expression=scriptexpression]
11 [-f scriptfile] [--file=scriptfile]
12 [file ...]
13
15 dc is a reverse-polish desk calculator which supports unlimited preci‐
16 sion arithmetic. It also allows you to define and call macros. Nor‐
17 mally dc reads from the standard input; if any command arguments are
18 given to it, they are filenames, and dc reads and executes the contents
19 of the files before reading from standard input. All normal output is
20 to standard output; all error output is to standard error.
21 A reverse-polish calculator stores numbers on a stack. Entering a num‐
23 ber pushes it on the stack. Arithmetic operations pop arguments off
24 the stack and push the results.
25 To enter a number in dc, type the digits (using upper case letters A
27 through F as "digits" when working with input bases greater than ten),
28 with an optional decimal point. Exponential notation is not supported.
29 To enter a negative number, begin the number with ``_''. ``-'' cannot
30 be used for this, as it is a binary operator for subtraction instead.
31 To enter two numbers in succession, separate them with spaces or new‐
32 lines. These have no meaning as commands.
33
35 dc may be invoked with the following command-line options:
36 -V
38 --version
40 Print out the version of dc that is being run and a copyright
41 notice, then exit.
42 -h
44 --help Print a usage message briefly summarizing these command-line
46 options and the bug-reporting address, then exit.
47 -e script
49 --expression=script
51 Add the commands in script to the set of commands to be run
52 while processing the input.
53 -f script-file
55 --file=script-file
57 Add the commands contained in the file script-file to the set of
58 commands to be run while processing the input.
59 If any command-line parameters remain after processing the above, these
61 parameters are interpreted as the names of input files to be processed.
62 A file name of - refers to the standard input stream. The standard
63 input will processed if no script files or expressions are specified.
64
66 p Prints the value on the top of the stack, without altering the
67 stack. A newline is printed after the value.
68 n Prints the value on the top of the stack, popping it off, and
70 does not print a newline after.
71 P Pops off the value on top of the stack. If it it a string, it
73 is simply printed without a trailing newline. Otherwise it is a
74 number, and the integer portion of its absolute value is printed
75 out as a "base (UCHAR_MAX+1)" byte stream. Assuming that
76 (UCHAR_MAX+1) is 256 (as it is on most machines with 8-bit
77 bytes), the sequence KSK0k1/_1Ss [ls*]Sxd0>x
78 [256~Ssd0<x]dsxxsx[q]Sq[Lsd0>qaPlxx] dsxxsx0sqLqsxLxLK+k could
79 also accomplish this function. (Much of the complexity of the
80 above native-dc code is due to the ~ computing the characters
81 backwards, and the desire to ensure that all registers wind up
82 back in their original states.)
83 f Prints the entire contents of the stack without altering any‐
85 thing. This is a good command to use if you are lost or want to
86 figure out what the effect of some command has been.
87
89 + Pops two values off the stack, adds them, and pushes the result.
90 The precision of the result is determined only by the values of
91 the arguments, and is enough to be exact.
92 - Pops two values, subtracts the first one popped from the second
94 one popped, and pushes the result.
95 * Pops two values, multiplies them, and pushes the result. The
97 number of fraction digits in the result depends on the current
98 precision value and the number of fraction digits in the two
99 arguments.
100 / Pops two values, divides the second one popped from the first
102 one popped, and pushes the result. The number of fraction dig‐
103 its is specified by the precision value.
104 % Pops two values, computes the remainder of the division that the
106 / command would do, and pushes that. The value computed is the
107 same as that computed by the sequence Sd dld/ Ld*- .
108 ~ Pops two values, divides the second one popped from the first
110 one popped. The quotient is pushed first, and the remainder is
111 pushed next. The number of fraction digits used in the division
112 is specified by the precision value. (The sequence SdSn lnld/
113 LnLd% could also accomplish this function, with slightly differ‐
114 ent error checking.)
115 ^ Pops two values and exponentiates, using the first value popped
117 as the exponent and the second popped as the base. The fraction
118 part of the exponent is ignored. The precision value specifies
119 the number of fraction digits in the result.
120 | Pops three values and computes a modular exponentiation. The
122 first value popped is used as the reduction modulus; this value
123 must be a non-zero number, and should be an integer. The second
124 popped is used as the exponent; this value must be a non-nega‐
125 tive number, and any fractional part of this exponent will be
126 ignored. The third value popped is the base which gets exponen‐
127 tiated, which should be an integer. For small integers this is
128 like the sequence Sm^Lm%, but, unlike ^, this command will work
129 with arbitrarily large exponents.
130 v Pops one value, computes its square root, and pushes that. The
132 precision value specifies the number of fraction digits in the
133 result.
134 Most arithmetic operations are affected by the ``precision value'',
136 which you can set with the k command. The default precision value is
137 zero, which means that all arithmetic except for addition and subtrac‐
138 tion produces integer results.
139
141 c Clears the stack, rendering it empty.
142 d Duplicates the value on the top of the stack, pushing another
144 copy of it. Thus, ``4d*p'' computes 4 squared and prints it.
145 r Reverses the order of (swaps) the top two values on the stack.
147 (This can also be accomplished with the sequence SaSbLaLb.)
148
150 dc provides at least 256 memory registers, each named by a single char‐
151 acter. You can store a number or a string in a register and retrieve
152 it later.
153 sr Pop the value off the top of the stack and store it into regis‐
155 ter r.
156 lr Copy the value in register r and push it onto the stack. This
158 does not alter the contents of r.
159 Each register also contains its own stack. The current register value
161 is the top of the register's stack.
162 Sr Pop the value off the top of the (main) stack and push it onto
164 the stack of register r. The previous value of the register
165 becomes inaccessible.
166 Lr Pop the value off the top of register r's stack and push it onto
168 the main stack. The previous value in register r's stack, if
169 any, is now accessible via the lr command.
170
172 dc has three parameters that control its operation: the precision, the
173 input radix, and the output radix. The precision specifies the number
174 of fraction digits to keep in the result of most arithmetic operations.
175 The input radix controls the interpretation of numbers typed in; all
176 numbers typed in use this radix. The output radix is used for printing
177 numbers.
178 The input and output radices are separate parameters; you can make them
180 unequal, which can be useful or confusing. The input radix must be
181 between 2 and 16 inclusive. The output radix must be at least 2. The
182 precision must be zero or greater. The precision is always measured in
183 decimal digits, regardless of the current input or output radix.
184 i Pops the value off the top of the stack and uses it to set the
186 input radix.
187 o Pops the value off the top of the stack and uses it to set the
189 output radix.
190 k Pops the value off the top of the stack and uses it to set the
192 precision.
193 I Pushes the current input radix on the stack.
195 O Pushes the current output radix on the stack.
197 K Pushes the current precision on the stack.
199
201 dc has a limited ability to operate on strings as well as on numbers;
202 the only things you can do with strings are print them and execute them
203 as macros (which means that the contents of the string are processed as
204 dc commands). All registers and the stack can hold strings, and dc
205 always knows whether any given object is a string or a number. Some
206 commands such as arithmetic operations demand numbers as arguments and
207 print errors if given strings. Other commands can accept either a num‐
208 ber or a string; for example, the p command can accept either and
209 prints the object according to its type.
210 [characters]
212 Makes a string containing characters (contained between balanced
213 [ and ] characters), and pushes it on the stack. For example,
214 [foo]P prints the characters foo (with no newline).
215 a The top-of-stack is popped. If it was a number, then the low-
217 order byte of this number is converted into a string and pushed
218 onto the stack. Otherwise the top-of-stack was a string, and
219 the first character of that string is pushed back.
220 x Pops a value off the stack and executes it as a macro. Normally
222 it should be a string; if it is a number, it is simply pushed
223 back onto the stack. For example, [1p]x executes the macro 1p
224 which pushes 1 on the stack and prints 1 on a separate line.
225 Macros are most often stored in registers; [1p]sa stores a macro to
227 print 1 into register a, and lax invokes this macro.
228 >r Pops two values off the stack and compares them assuming they
230 are numbers, executing the contents of register r as a macro if
231 the original top-of-stack is greater. Thus, 1 2>a will invoke
232 register a's contents and 2 1>a will not.
233 !>r Similar but invokes the macro if the original top-of-stack is
235 not greater than (less than or equal to) what was the second-to-
236 top.
237 <r Similar but invokes the macro if the original top-of-stack is
239 less.
240 !<r Similar but invokes the macro if the original top-of-stack is
242 not less than (greater than or equal to) what was the second-to-
243 top.
244 =r Similar but invokes the macro if the two numbers popped are
246 equal.
247 !=r Similar but invokes the macro if the two numbers popped are not
249 equal.
250 ? Reads a line from the terminal and executes it. This command
252 allows a macro to request input from the user.
253 q exits from a macro and also from the macro which invoked it. If
255 called from the top level, or from a macro which was called
256 directly from the top level, the q command will cause dc to
257 exit.
258 Q Pops a value off the stack and uses it as a count of levels of
260 macro execution to be exited. Thus, 3Q exits three levels. The
261 Q command will never cause dc to exit.
262
264 Z Pops a value off the stack, calculates the number of digits it
265 has (or number of characters, if it is a string) and pushes that
266 number. The digit count for a number does not include any lead‐
267 ing zeros, even if those appear to the right of the radix point.
268 X Pops a value off the stack, calculates the number of fraction
270 digits it has, and pushes that number. For a string, the value
271 pushed is 0.
272 z Pushes the current stack depth: the number of objects on the
274 stack before the execution of the z command.
275
277 ! Will run the rest of the line as a system command. Note that
278 parsing of the !<, !=, and !> commands take precedence, so if
279 you want to run a command starting with <, =, or > you will need
280 to add a space after the !.
281 # Will interpret the rest of the line as a comment.
283 :r Will pop the top two values off of the stack. The old second-
285 to-top value will be stored in the array r, indexed by the old
286 top-of-stack value.
287 ;r Pops the top-of-stack and uses it as an index into the array r.
289 The selected value is then pushed onto the stack.
290 Note that each stacked instance of a register has its own array associ‐
292 ated with it. Thus 1 0:a 0Sa 2 0:a La 0;ap will print 1, because the 2
293 was stored in an instance of 0:a that was later popped.
294
296 Email bug reports to bug-dc@gnu.org.
297GNU Project 2006-06-11 dc(1)