| blob | 7a136a7d0574bb8aee42a91577751323b06b756d |
1 .\"
2 .\" dc.1 - the *roff document processor source for the dc manual
3 .\"
4 .\" This file is part of GNU dc.
5 .\" Copyright (C) 1994, 1997, 1998, 2000 Free Software Foundation, Inc.
6 .\"
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.
11 .\"
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.
16 .\"
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
22 .\"
23 .TH DC 1 "1997-03-25" "GNU Project"
24 .ds dc \fIdc\fP
25 .ds Dc \fIDc\fP
26 .SH NAME
27 dc \- an arbitrary precision calculator
28 .SH SYNOPSIS
29 dc [-V] [--version] [-h] [--help]
30 [-e scriptexpression] [--expression=scriptexpression]
31 [-f scriptfile] [--file=scriptfile]
32 [file ...]
33 .SH DESCRIPTION
34 .PP
35 \*(Dc is a reverse-polish desk calculator which supports
36 unlimited precision arithmetic.
37 It also allows you to define and call macros.
38 Normally \*(dc reads from the standard input;
39 if any command arguments are given to it, they are filenames,
40 and \*(dc reads and executes the contents of the files before reading
41 from standard input.
42 All normal output is to standard output;
43 all error output is to standard error.
44 .PP
45 A reverse-polish calculator stores numbers on a stack.
46 Entering a number pushes it on the stack.
47 Arithmetic operations pop arguments off the stack and push the results.
48 .PP
49 To enter a number in
50 .IR dc ,
51 type the digits with an optional decimal point.
52 Exponential notation is not supported.
53 To enter a negative number,
54 begin the number with ``_''.
55 ``-'' cannot be used for this,
56 as it is a binary operator for subtraction instead.
57 To enter two numbers in succession,
58 separate them with spaces or newlines.
59 These have no meaning as commands.
60 .SH OPTIONS
61 \*(Dc may be invoked with the following command-line options:
62 .TP
63 .B -V
64 .TP
65 .B --version
66 Print out the version of \*(dc that is being run and a copyright notice,
67 then exit.
68 .TP
69 .B -h
70 .TP
71 .B --help
72 Print a usage message briefly summarizing these command-line options
73 and the bug-reporting address,
74 then exit.
75 .TP
76 .B -e \fIscript\fP
77 .TP
78 .BI --expression= script
79 Add the commands in
80 .I script
81 to the set of commands to be run while processing the input.
82 .TP
83 .B -f \fIscript-file\fP
84 .TP
85 .BI --file= script-file
86 Add the commands contained in the file
87 .I script-file
88 to the set of commands to be run while processing the input.
89 .PP
90 If any command-line parameters remain after processing the above,
91 these parameters are interpreted as the names of input files to
92 be processed.
93 A file name of
94 .B -
95 refers to the standard input stream.
96 The standard input will processed if no file names are specified.
97 .PD
98 .SH
99 Printing Commands
100 .TP
101 .B p
102 Prints the value on the top of the stack,
103 without altering the stack.
104 A newline is printed after the value.
105 .TP
106 .B n
107 Prints the value on the top of the stack, popping it off,
108 and does not print a newline after.
109 .TP
110 .B P
111 Pops off the value on top of the stack.
112 If it it a string, it is simply printed without a trailing newline.
113 Otherwise it is a number, and the integer portion of its absolute
114 value is printed out as a "base (UCHAR_MAX+1)" byte stream.
115 Assuming that (UCHAR_MAX+1) is 256
116 (as it is on most machines with 8-bit bytes),
117 the sequence \fBKSK 0k1/ [_1*]sx d0>x [256~aPd0<x]dsxx sxLKk\fP
118 could also accomplish this function,
119 except for the side-effect of clobbering the x register.
120 .TP
121 .B f
122 Prints the entire contents of the stack
123 .ig
124 and the contents of all of the registers,
125 ..
126 without altering anything.
127 This is a good command to use if you are lost or want
128 to figure out what the effect of some command has been.
129 .PD
130 .SH
131 Arithmetic
132 .TP
133 .B +
134 Pops two values off the stack, adds them,
135 and pushes the result.
136 The precision of the result is determined only
137 by the values of the arguments,
138 and is enough to be exact.
139 .TP
140 .B -
141 Pops two values,
142 subtracts the first one popped from the second one popped,
143 and pushes the result.
144 .TP
145 .B *
146 Pops two values, multiplies them, and pushes the result.
147 The number of fraction digits in the result depends on
148 the current precision value and the number of fraction
149 digits in the two arguments.
150 .TP
151 .B /
152 Pops two values,
153 divides the second one popped from the first one popped,
154 and pushes the result.
155 The number of fraction digits is specified by the precision value.
156 .TP
157 .B %
158 Pops two values,
159 computes the remainder of the division that the
160 .B /
161 command would do,
162 and pushes that.
163 The value computed is the same as that computed by
164 the sequence \fBSd dld/ Ld*-\fP .
165 .TP
166 .B ~
167 Pops two values,
168 divides the second one popped from the first one popped.
169 The quotient is pushed first, and the remainder is pushed next.
170 The number of fraction digits used in the division
171 is specified by the precision value.
172 (The sequence \fBSdSn lnld/ LnLd%\fP could also accomplish
173 this function, with slightly different error checking.)
174 .TP
175 .B ^
176 Pops two values and exponentiates,
177 using the first value popped as the exponent
178 and the second popped as the base.
179 The fraction part of the exponent is ignored.
180 The precision value specifies the number of fraction
181 digits in the result.
182 .TP
183 .B |
184 Pops three values and computes a modular exponentiation.
185 The first value popped is used as the reduction modulus;
186 this value must be a non-zero number,
187 and should be an integer.
188 The second popped is used as the exponent;
189 this value must be a non-negative number,
190 and any fractional part of this exponent will be ignored.
191 The third value popped is the base which gets exponentiated,
192 which should be an integer.
193 For small integers this is like the sequence \fBSm^Lm%\fP,
194 but, unlike \fB^\fP, this command will work with arbitrarily large exponents.
195 .TP
196 .B v
197 Pops one value,
198 computes its square root,
199 and pushes that.
200 The precision value specifies the number of fraction digits in the result.
201 .PP
202 Most arithmetic operations are affected by the ``precision value'',
203 which you can set with the
204 .B k
205 command.
206 The default precision value is zero,
207 which means that all arithmetic except for
208 addition and subtraction produces integer results.
209 .SH
210 Stack Control
211 .TP
212 .B c
213 Clears the stack, rendering it empty.
214 .TP
215 .B d
216 Duplicates the value on the top of the stack,
217 pushing another copy of it.
218 Thus, ``4d*p'' computes 4 squared and prints it.
219 .TP
220 .B r
221 Reverses the order of (swaps) the top two values on the stack.
222 .SH
223 Registers
224 .PP
225 \*(Dc provides at least 256 memory registers,
226 each named by a single character.
227 You can store a number or a string in a register and retrieve it later.
228 .TP
229 .BI s r
230 Pop the value off the top of the stack and store
231 it into register
232 .IR r .
233 .TP
234 .BI l r
235 Copy the value in register
236 .I r
237 and push it onto the stack.
238 This does not alter the contents of
239 .IR r .
240 .PP
241 Each register also contains its own stack.
242 The current register value is the top of the register's stack.
243 .TP
244 .BI S r
245 Pop the value off the top of the (main) stack and
246 push it onto the stack of register
247 .IR r .
248 The previous value of the register becomes inaccessible.
249 .TP
250 .BI L r
251 Pop the value off the top of register
252 .IR r 's
253 stack and push it onto the main stack.
254 The previous value
255 in register
256 .IR r 's
257 stack, if any,
258 is now accessible via the
259 .BI l r
260 command.
261 .ig
262 .PP
263 The
264 .B f
265 command prints a list of all registers that have contents stored in them,
266 together with their contents.
267 Only the current contents of each register
268 (the top of its stack)
269 is printed.
270 ..
271 .SH
272 Parameters
273 .PP
274 \*(Dc has three parameters that control its operation:
275 the precision, the input radix, and the output radix.
276 The precision specifies the number
277 of fraction digits to keep in the result of most arithmetic operations.
278 The input radix controls the interpretation of numbers typed in;
279 all numbers typed in use this radix.
280 The output radix is used for printing numbers.
281 .PP
282 The input and output radices are separate parameters;
283 you can make them unequal,
284 which can be useful or confusing.
285 The input radix must be between 2 and 16 inclusive.
286 The output radix must be at least 2.
287 The precision must be zero or greater.
288 The precision is always measured in decimal digits,
289 regardless of the current input or output radix.
290 .TP
291 .B i
292 Pops the value off the top of the stack
293 and uses it to set the input radix.
294 .TP
295 .B o
296 Pops the value off the top of the stack
297 and uses it to set the output radix.
298 .TP
299 .B k
300 Pops the value off the top of the stack
301 and uses it to set the precision.
302 .TP
303 .B I
304 Pushes the current input radix on the stack.
305 .TP
306 .B O
307 Pushes the current output radix on the stack.
308 .TP
309 .B K
310 Pushes the current precision on the stack.
311 .SH
312 Strings
313 .PP
314 \*(Dc can operate on strings as well as on numbers.
315 The only things you can do with strings are
316 print them and execute them as macros
317 (which means that the contents of the string are processed as
318 \*(dc commands).
319 All registers and the stack can hold strings,
320 and \*(dc always knows whether any given object is a string or a number.
321 Some commands such as arithmetic operations demand numbers
322 as arguments and print errors if given strings.
323 Other commands can accept either a number or a string;
324 for example, the
325 .B p
326 command can accept either and prints the object
327 according to its type.
328 .TP
329 .BI [ characters ]
330 Makes a string containing
331 .I characters
332 (contained between balanced
333 .B [
334 and
335 .B ]
336 characters),
337 and pushes it on the stack.
338 For example,
339 .B [foo]P
340 prints the characters
341 .B foo
342 (with no newline).
343 .TP
344 .B a
345 The top-of-stack is popped.
346 If it was a number, then the low-order byte of this number
347 is converted into a string and pushed onto the stack.
348 Otherwise the top-of-stack was a string,
349 and the first character of that string is pushed back.
350 .TP
351 .B x
352 Pops a value off the stack and executes it as a macro.
353 Normally it should be a string;
354 if it is a number,
355 it is simply pushed back onto the stack.
356 For example,
357 .B [1p]x
358 executes the macro
359 .B 1p
360 which pushes
361 .B 1
362 on the stack and prints
363 .B 1
364 on a separate line.
365 .PP
366 Macros are most often stored in registers;
367 .B [1p]sa
368 stores a macro to print
369 .B 1
370 into register
371 .BR a ,
372 and
373 .B lax
374 invokes this macro.
375 .TP
376 .BI > r
377 Pops two values off the stack and compares them
378 assuming they are numbers,
379 executing the contents of register
380 .I r
381 as a macro if the original top-of-stack
382 is greater.
383 Thus,
384 .B 1 2>a
385 will invoke register
386 .BR a 's
387 contents and
388 .B 2 1>a
389 will not.
390 .TP
391 .BI !> r
392 Similar but invokes the macro if the original top-of-stack is
393 not greater than (less than or equal to) what was the second-to-top.
394 .TP
395 .BI < r
396 Similar but invokes the macro if the original top-of-stack is less.
397 .TP
398 .BI !< r
399 Similar but invokes the macro if the original top-of-stack is
400 not less than (greater than or equal to) what was the second-to-top.
401 .TP
402 .BI = r
403 Similar but invokes the macro if the two numbers popped are equal.
404 .TP
405 .BI != r
406 Similar but invokes the macro if the two numbers popped are not equal.
407 .ig
408 This can also be validly used to compare two strings for equality.
409 ..
410 .TP
411 .B ?
412 Reads a line from the terminal and executes it.
413 This command allows a macro to request input from the user.
414 .TP
415 .B q
416 exits from a macro and also from the macro which invoked it.
417 If called from the top level,
418 or from a macro which was called directly from the top level,
419 the
420 .B q
421 command will cause \*(dc to exit.
422 .TP
423 .B Q
424 Pops a value off the stack and uses it as a count
425 of levels of macro execution to be exited.
426 Thus,
427 .B 3Q
428 exits three levels.
429 The
430 .B Q
431 command will never cause \*(dc to exit.
432 .SH
433 Status Inquiry
434 .TP
435 .B Z
436 Pops a value off the stack,
437 calculates the number of digits it has
438 (or number of characters, if it is a string)
439 and pushes that number.
440 .TP
441 .B X
442 Pops a value off the stack,
443 calculates the number of fraction digits it has,
444 and pushes that number.
445 For a string,
446 the value pushed is
447 .\" -1.
448 0.
449 .TP
450 .B z
451 Pushes the current stack depth:
452 the number of objects on the stack before the execution of the
453 .B z
454 command.
455 .SH
456 Miscellaneous
457 .TP
458 .B !
459 Will run the rest of the line as a system command.
460 Note that parsing of the !<, !=, and !> commands take precedence,
461 so if you want to run a command starting with <, =, or > you will
462 need to add a space after the !.
463 .TP
464 .B #
465 Will interpret the rest of the line as a comment.
466 .TP
467 .BI : r
468 Will pop the top two values off of the stack.
469 The old second-to-top value will be stored in the array
470 .IR r ,
471 indexed by the old top-of-stack value.
472 .TP
473 .BI ; r
474 Pops the top-of-stack and uses it as an index into
475 the array
476 .IR r .
477 The selected value is then pushed onto the stack.
478 .P
479 Note that each stacked instance of a register has its own
480 array associated with it.
481 Thus \fB1 0:a 0Sa 2 0:a La 0;ap\fP will print 1,
482 because the 2 was stored in an instance of 0:a that
483 was later popped.
484 .SH
485 BUGS
486 .PP
487 Email bug reports to
488 .BR bug-dc@gnu.org .