2 .\" dc.1 - the *roff document processor source for the dc manual
4 .\" This file is part of GNU dc.
5 .\" Copyright (C) 1994, 1997, 1998, 2000 Free Software Foundation, Inc.
7 .\" This program is free software; you can redistribute it and/or modify
8 .\" it under the terms of the GNU General Public License as published by
9 .\" the Free Software Foundation; either version 2 of the License , or
10 .\" (at your option) any later version.
12 .\" This program is distributed in the hope that it will be useful,
13 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
14 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 .\" GNU General Public License for more details.
17 .\" You should have received a copy of the GNU General Public License
18 .\" along with this program; see the file COPYING. If not, write to:
19 .\" The Free Software Foundation, Inc.
20 .\" 59 Temple Place, Suite 330
21 .\" Boston, MA 02111 USA
25 .TH DC 1 "1997-03-25" "GNU Project"
29 dc \- an arbitrary precision calculator
31 dc [-V] [--version] [-h] [--help]
32 [-e scriptexpression] [--expression=scriptexpression]
33 [-f scriptfile] [--file=scriptfile]
37 \*(Dc is a reverse-polish desk calculator which supports
38 unlimited precision arithmetic.
39 It also allows you to define and call macros.
40 Normally \*(dc reads from the standard input;
41 if any command arguments are given to it, they are filenames,
42 and \*(dc reads and executes the contents of the files before reading
44 All normal output is to standard output;
45 all error output is to standard error.
47 A reverse-polish calculator stores numbers on a stack.
48 Entering a number pushes it on the stack.
49 Arithmetic operations pop arguments off the stack and push the results.
53 type the digits with an optional decimal point.
54 Exponential notation is not supported.
55 To enter a negative number,
56 begin the number with ``_''.
57 ``-'' cannot be used for this,
58 as it is a binary operator for subtraction instead.
59 To enter two numbers in succession,
60 separate them with spaces or newlines.
61 These have no meaning as commands.
63 \*(Dc may be invoked with the following command-line options:
68 Print out the version of \*(dc that is being run and a copyright notice,
74 Print a usage message briefly summarizing these command-line options
75 and the bug-reporting address,
80 .BI --expression= script
83 to the set of commands to be run while processing the input.
85 .B -f \fIscript-file\fP
87 .BI --file= script-file
88 Add the commands contained in the file
90 to the set of commands to be run while processing the input.
92 If any command-line parameters remain after processing the above,
93 these parameters are interpreted as the names of input files to
97 refers to the standard input stream.
98 The standard input will processed if no file names are specified.
104 Prints the value on the top of the stack,
105 without altering the stack.
106 A newline is printed after the value.
109 Prints the value on the top of the stack, popping it off,
110 and does not print a newline after.
113 Pops off the value on top of the stack.
114 If it it a string, it is simply printed without a trailing newline.
115 Otherwise it is a number, and the integer portion of its absolute
116 value is printed out as a "base (UCHAR_MAX+1)" byte stream.
117 Assuming that (UCHAR_MAX+1) is 256
118 (as it is on most machines with 8-bit bytes),
119 the sequence \fBKSK 0k1/ [_1*]sx d0>x [256~aPd0<x]dsxx sxLKk\fP
120 could also accomplish this function,
121 except for the side-effect of clobbering the x register.
124 Prints the entire contents of the stack
126 and the contents of all of the registers,
128 without altering anything.
129 This is a good command to use if you are lost or want
130 to figure out what the effect of some command has been.
136 Pops two values off the stack, adds them,
137 and pushes the result.
138 The precision of the result is determined only
139 by the values of the arguments,
140 and is enough to be exact.
144 subtracts the first one popped from the second one popped,
145 and pushes the result.
148 Pops two values, multiplies them, and pushes the result.
149 The number of fraction digits in the result depends on
150 the current precision value and the number of fraction
151 digits in the two arguments.
155 divides the second one popped from the first one popped,
156 and pushes the result.
157 The number of fraction digits is specified by the precision value.
161 computes the remainder of the division that the
165 The value computed is the same as that computed by
166 the sequence \fBSd dld/ Ld*-\fP .
170 divides the second one popped from the first one popped.
171 The quotient is pushed first, and the remainder is pushed next.
172 The number of fraction digits used in the division
173 is specified by the precision value.
174 (The sequence \fBSdSn lnld/ LnLd%\fP could also accomplish
175 this function, with slightly different error checking.)
178 Pops two values and exponentiates,
179 using the first value popped as the exponent
180 and the second popped as the base.
181 The fraction part of the exponent is ignored.
182 The precision value specifies the number of fraction
183 digits in the result.
186 Pops three values and computes a modular exponentiation.
187 The first value popped is used as the reduction modulus;
188 this value must be a non-zero number,
189 and should be an integer.
190 The second popped is used as the exponent;
191 this value must be a non-negative number,
192 and any fractional part of this exponent will be ignored.
193 The third value popped is the base which gets exponentiated,
194 which should be an integer.
195 For small integers this is like the sequence \fBSm^Lm%\fP,
196 but, unlike \fB^\fP, this command will work with arbitrarily large exponents.
200 computes its square root,
202 The precision value specifies the number of fraction digits in the result.
204 Most arithmetic operations are affected by the ``precision value'',
205 which you can set with the
208 The default precision value is zero,
209 which means that all arithmetic except for
210 addition and subtraction produces integer results.
215 Clears the stack, rendering it empty.
218 Duplicates the value on the top of the stack,
219 pushing another copy of it.
220 Thus, ``4d*p'' computes 4 squared and prints it.
223 Reverses the order of (swaps) the top two values on the stack.
227 \*(Dc provides at least 256 memory registers,
228 each named by a single character.
229 You can store a number or a string in a register and retrieve it later.
232 Pop the value off the top of the stack and store
237 Copy the value in register
239 and push it onto the stack.
240 This does not alter the contents of
243 Each register also contains its own stack.
244 The current register value is the top of the register's stack.
247 Pop the value off the top of the (main) stack and
248 push it onto the stack of register
250 The previous value of the register becomes inaccessible.
253 Pop the value off the top of register
255 stack and push it onto the main stack.
260 is now accessible via the
267 command prints a list of all registers that have contents stored in them,
268 together with their contents.
269 Only the current contents of each register
270 (the top of its stack)
276 \*(Dc has three parameters that control its operation:
277 the precision, the input radix, and the output radix.
278 The precision specifies the number
279 of fraction digits to keep in the result of most arithmetic operations.
280 The input radix controls the interpretation of numbers typed in;
281 all numbers typed in use this radix.
282 The output radix is used for printing numbers.
284 The input and output radices are separate parameters;
285 you can make them unequal,
286 which can be useful or confusing.
287 The input radix must be between 2 and 16 inclusive.
288 The output radix must be at least 2.
289 The precision must be zero or greater.
290 The precision is always measured in decimal digits,
291 regardless of the current input or output radix.
294 Pops the value off the top of the stack
295 and uses it to set the input radix.
298 Pops the value off the top of the stack
299 and uses it to set the output radix.
302 Pops the value off the top of the stack
303 and uses it to set the precision.
306 Pushes the current input radix on the stack.
309 Pushes the current output radix on the stack.
312 Pushes the current precision on the stack.
316 \*(Dc can operate on strings as well as on numbers.
317 The only things you can do with strings are
318 print them and execute them as macros
319 (which means that the contents of the string are processed as
321 All registers and the stack can hold strings,
322 and \*(dc always knows whether any given object is a string or a number.
323 Some commands such as arithmetic operations demand numbers
324 as arguments and print errors if given strings.
325 Other commands can accept either a number or a string;
328 command can accept either and prints the object
329 according to its type.
332 Makes a string containing
334 (contained between balanced
339 and pushes it on the stack.
342 prints the characters
347 The top-of-stack is popped.
348 If it was a number, then the low-order byte of this number
349 is converted into a string and pushed onto the stack.
350 Otherwise the top-of-stack was a string,
351 and the first character of that string is pushed back.
354 Pops a value off the stack and executes it as a macro.
355 Normally it should be a string;
357 it is simply pushed back onto the stack.
364 on the stack and prints
368 Macros are most often stored in registers;
370 stores a macro to print
379 Pops two values off the stack and compares them
380 assuming they are numbers,
381 executing the contents of register
383 as a macro if the original top-of-stack
394 Similar but invokes the macro if the original top-of-stack is
395 not greater than (less than or equal to) what was the second-to-top.
398 Similar but invokes the macro if the original top-of-stack is less.
401 Similar but invokes the macro if the original top-of-stack is
402 not less than (greater than or equal to) what was the second-to-top.
405 Similar but invokes the macro if the two numbers popped are equal.
408 Similar but invokes the macro if the two numbers popped are not equal.
410 This can also be validly used to compare two strings for equality.
414 Reads a line from the terminal and executes it.
415 This command allows a macro to request input from the user.
418 exits from a macro and also from the macro which invoked it.
419 If called from the top level,
420 or from a macro which was called directly from the top level,
423 command will cause \*(dc to exit.
426 Pops a value off the stack and uses it as a count
427 of levels of macro execution to be exited.
433 command will never cause \*(dc to exit.
438 Pops a value off the stack,
439 calculates the number of digits it has
440 (or number of characters, if it is a string)
441 and pushes that number.
444 Pops a value off the stack,
445 calculates the number of fraction digits it has,
446 and pushes that number.
453 Pushes the current stack depth:
454 the number of objects on the stack before the execution of the
461 Will run the rest of the line as a system command.
462 Note that parsing of the !<, !=, and !> commands take precedence,
463 so if you want to run a command starting with <, =, or > you will
464 need to add a space after the !.
467 Will interpret the rest of the line as a comment.
470 Will pop the top two values off of the stack.
471 The old second-to-top value will be stored in the array
473 indexed by the old top-of-stack value.
476 Pops the top-of-stack and uses it as an index into
479 The selected value is then pushed onto the stack.
481 Note that each stacked instance of a register has its own
482 array associated with it.
483 Thus \fB1 0:a 0Sa 2 0:a La 0;ap\fP will print 1,
484 because the 2 was stored in an instance of 0:a that