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 with an optional decimal
27 point. Exponential notation is not supported. To enter a negative
28 number, begin the number with ``_''. ``-'' cannot be used for this, as
29 it is a binary operator for subtraction instead. To enter two numbers
30 in succession, separate them with spaces or newlines. These have no
31 meaning as commands.
32
34 Dc may be invoked with the following command-line options:
35 -V
37 --version
39 Print out the version of dc that is being run and a copyright
40 notice, then exit.
41 -h
43 --help Print a usage message briefly summarizing these command-line
45 options and the bug-reporting address, then exit.
46 -e script
48 --expression=script
50 Add the commands in script to the set of commands to be run
51 while processing the input.
52 -f script-file
54 --file=script-file
56 Add the commands contained in the file script-file to the set of
57 commands to be run while processing the input.
58 If any command-line parameters remain after processing the above, these
60 parameters are interpreted as the names of input files to be processed.
61 A file name of - refers to the standard input stream. The standard
62 input will processed if no file names are specified.
63
65 p Prints the value on the top of the stack, without altering the
66 stack. A newline is printed after the value.
67 n Prints the value on the top of the stack, popping it off, and
69 does not print a newline after.
70 P Pops off the value on top of the stack. If it it a string, it
72 is simply printed without a trailing newline. Otherwise it is a
73 number, and the integer portion of its absolute value is printed
74 out as a "base (UCHAR_MAX+1)" byte stream. Assuming that
75 (UCHAR_MAX+1) is 256 (as it is on most machines with 8-bit
76 bytes), the sequence KSK 0k1/ [_1*]sx d0>x [256~aPd0<x]dsxx
77 sxLKk could also accomplish this function, except for the side-
78 effect of clobbering the x register.
79 f Prints the entire contents of the stack without altering any‐
81 thing. This is a good command to use if you are lost or want to
82 figure out what the effect of some command has been.
83
85 + Pops two values off the stack, adds them, and pushes the result.
86 The precision of the result is determined only by the values of
87 the arguments, and is enough to be exact.
88 - Pops two values, subtracts the first one popped from the second
90 one popped, and pushes the result.
91 * Pops two values, multiplies them, and pushes the result. The
93 number of fraction digits in the result depends on the current
94 precision value and the number of fraction digits in the two
95 arguments.
96 / Pops two values, divides the second one popped from the first
98 one popped, and pushes the result. The number of fraction dig‐
99 its is specified by the precision value.
100 % Pops two values, computes the remainder of the division that the
102 / command would do, and pushes that. The value computed is the
103 same as that computed by the sequence Sd dld/ Ld*- .
104 ~ Pops two values, divides the second one popped from the first
106 one popped. The quotient is pushed first, and the remainder is
107 pushed next. The number of fraction digits used in the division
108 is specified by the precision value. (The sequence SdSn lnld/
109 LnLd% could also accomplish this function, with slightly differ‐
110 ent error checking.)
111 ^ Pops two values and exponentiates, using the first value popped
113 as the exponent and the second popped as the base. The fraction
114 part of the exponent is ignored. The precision value specifies
115 the number of fraction digits in the result.
116 | Pops three values and computes a modular exponentiation. The
118 first value popped is used as the reduction modulus; this value
119 must be a non-zero number, and should be an integer. The second
120 popped is used as the exponent; this value must be a non-nega‐
121 tive number, and any fractional part of this exponent will be
122 ignored. The third value popped is the base which gets exponen‐
123 tiated, which should be an integer. For small integers this is
124 like the sequence Sm^Lm%, but, unlike ^, this command will work
125 with arbitrarily large exponents.
126 v Pops one value, computes its square root, and pushes that. The
128 precision value specifies the number of fraction digits in the
129 result.
130 Most arithmetic operations are affected by the ``precision value'',
132 which you can set with the k command. The default precision value is
133 zero, which means that all arithmetic except for addition and subtrac‐
134 tion produces integer results.
135
137 c Clears the stack, rendering it empty.
138 d Duplicates the value on the top of the stack, pushing another
140 copy of it. Thus, ``4d*p'' computes 4 squared and prints it.
141 r Reverses the order of (swaps) the top two values on the stack.
143
145 Dc provides at least 256 memory registers, each named by a single char‐
146 acter. You can store a number or a string in a register and retrieve
147 it later.
148 sr Pop the value off the top of the stack and store it into regis‐
150 ter r.
151 lr Copy the value in register r and push it onto the stack. This
153 does not alter the contents of r.
154 Each register also contains its own stack. The current register value
156 is the top of the register's stack.
157 Sr Pop the value off the top of the (main) stack and push it onto
159 the stack of register r. The previous value of the register
160 becomes inaccessible.
161 Lr Pop the value off the top of register r's stack and push it onto
163 the main stack. The previous value in register r's stack, if
164 any, is now accessible via the lr command.
165
167 Dc has three parameters that control its operation: the precision, the
168 input radix, and the output radix. The precision specifies the number
169 of fraction digits to keep in the result of most arithmetic operations.
170 The input radix controls the interpretation of numbers typed in; all
171 numbers typed in use this radix. The output radix is used for printing
172 numbers.
173 The input and output radices are separate parameters; you can make them
175 unequal, which can be useful or confusing. The input radix must be
176 between 2 and 16 inclusive. The output radix must be at least 2. The
177 precision must be zero or greater. The precision is always measured in
178 decimal digits, regardless of the current input or output radix.
179 i Pops the value off the top of the stack and uses it to set the
181 input radix.
182 o Pops the value off the top of the stack and uses it to set the
184 output radix.
185 k Pops the value off the top of the stack and uses it to set the
187 precision.
188 I Pushes the current input radix on the stack.
190 O Pushes the current output radix on the stack.
192 K Pushes the current precision on the stack.
194
196 Dc can operate on strings as well as on numbers. The only things you
197 can do with strings are print them and execute them as macros (which
198 means that the contents of the string are processed as dc commands).
199 All registers and the stack can hold strings, and dc always knows
200 whether any given object is a string or a number. Some commands such
201 as arithmetic operations demand numbers as arguments and print errors
202 if given strings. Other commands can accept either a number or a
203 string; for example, the p command can accept either and prints the
204 object according to its type.
205 [characters]
207 Makes a string containing characters (contained between balanced
208 [ and ] characters), and pushes it on the stack. For example,
209 [foo]P prints the characters foo (with no newline).
210 a The top-of-stack is popped. If it was a number, then the low-
212 order byte of this number is converted into a string and pushed
213 onto the stack. Otherwise the top-of-stack was a string, and
214 the first character of that string is pushed back.
215 x Pops a value off the stack and executes it as a macro. Normally
217 it should be a string; if it is a number, it is simply pushed
218 back onto the stack. For example, [1p]x executes the macro 1p
219 which pushes 1 on the stack and prints 1 on a separate line.
220 Macros are most often stored in registers; [1p]sa stores a macro to
222 print 1 into register a, and lax invokes this macro.
223 >r Pops two values off the stack and compares them assuming they
225 are numbers, executing the contents of register r as a macro if
226 the original top-of-stack is greater. Thus, 1 2>a will invoke
227 register a's contents and 2 1>a will not.
228 !>r Similar but invokes the macro if the original top-of-stack is
230 not greater than (less than or equal to) what was the second-to-
231 top.
232 <r Similar but invokes the macro if the original top-of-stack is
234 less.
235 !<r Similar but invokes the macro if the original top-of-stack is
237 not less than (greater than or equal to) what was the second-to-
238 top.
239 =r Similar but invokes the macro if the two numbers popped are
241 equal.
242 !=r Similar but invokes the macro if the two numbers popped are not
244 equal.
245 ? Reads a line from the terminal and executes it. This command
247 allows a macro to request input from the user.
248 q exits from a macro and also from the macro which invoked it. If
250 called from the top level, or from a macro which was called
251 directly from the top level, the q command will cause dc to
252 exit.
253 Q Pops a value off the stack and uses it as a count of levels of
255 macro execution to be exited. Thus, 3Q exits three levels. The
256 Q command will never cause dc to exit.
257
259 Z Pops a value off the stack, calculates the number of digits it
260 has (or number of characters, if it is a string) and pushes that
261 number.
262 X Pops a value off the stack, calculates the number of fraction
264 digits it has, and pushes that number. For a string, the value
265 pushed is 0.
266 z Pushes the current stack depth: the number of objects on the
268 stack before the execution of the z command.
269
271 ! Will run the rest of the line as a system command. Note that
272 parsing of the !<, !=, and !> commands take precedence, so if
273 you want to run a command starting with <, =, or > you will need
274 to add a space after the !.
275 # Will interpret the rest of the line as a comment.
277 :r Will pop the top two values off of the stack. The old second-
279 to-top value will be stored in the array r, indexed by the old
280 top-of-stack value.
281 ;r Pops the top-of-stack and uses it as an index into the array r.
283 The selected value is then pushed onto the stack.
284 Note that each stacked instance of a register has its own array associ‐
286 ated with it. Thus 1 0:a 0Sa 2 0:a La 0;ap will print 1, because the 2
287 was stored in an instance of 0:a that was later popped.
288
290 Email bug reports to bug-dc@gnu.org.
291GNU Project 1997-03-25 DC(1)