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
23 .\" $FreeBSD: src/contrib/bc/doc/dc.1,v 1.3.2.1 2001/03/04 09:34:56 kris Exp $
24 .\" $DragonFly: src/contrib/bc/doc/Attic/dc.1,v 1.2 2003/06/17 04:23:58 dillon Exp $
26 .TH DC 1 "1997-03-25" "GNU Project"
30 dc \- an arbitrary precision calculator
32 dc [-V] [--version] [-h] [--help]
33 [-e scriptexpression] [--expression=scriptexpression]
34 [-f scriptfile] [--file=scriptfile]
38 \*(Dc is a reverse-polish desk calculator which supports
39 unlimited precision arithmetic.
40 It also allows you to define and call macros.
41 Normally \*(dc reads from the standard input;
42 if any command arguments are given to it, they are filenames,
43 and \*(dc reads and executes the contents of the files before reading
45 All normal output is to standard output;
46 all error output is to standard error.
48 A reverse-polish calculator stores numbers on a stack.
49 Entering a number pushes it on the stack.
50 Arithmetic operations pop arguments off the stack and push the results.
54 type the digits with an optional decimal point.
55 Exponential notation is not supported.
56 To enter a negative number,
57 begin the number with ``_''.
58 ``-'' cannot be used for this,
59 as it is a binary operator for subtraction instead.
60 To enter two numbers in succession,
61 separate them with spaces or newlines.
62 These have no meaning as commands.
64 \*(Dc may be invoked with the following command-line options:
69 Print out the version of \*(dc that is being run and a copyright notice,
75 Print a usage message briefly summarizing these command-line options
76 and the bug-reporting address,
81 .BI --expression= script
84 to the set of commands to be run while processing the input.
86 .B -f \fIscript-file\fP
88 .BI --file= script-file
89 Add the commands contained in the file
91 to the set of commands to be run while processing the input.
93 If any command-line parameters remain after processing the above,
94 these parameters are interpreted as the names of input files to
98 refers to the standard input stream.
99 The standard input will processed if no file names are specified.
105 Prints the value on the top of the stack,
106 without altering the stack.
107 A newline is printed after the value.
110 Prints the value on the top of the stack, popping it off,
111 and does not print a newline after.
114 Pops off the value on top of the stack.
115 If it it a string, it is simply printed without a trailing newline.
116 Otherwise it is a number, and the integer portion of its absolute
117 value is printed out as a "base (UCHAR_MAX+1)" byte stream.
118 Assuming that (UCHAR_MAX+1) is 256
119 (as it is on most machines with 8-bit bytes),
120 the sequence \fBKSK 0k1/ [_1*]sx d0>x [256~aPd0<x]dsxx sxLKk\fP
121 could also accomplish this function,
122 except for the side-effect of clobbering the x register.
125 Prints the entire contents of the stack
127 and the contents of all of the registers,
129 without altering anything.
130 This is a good command to use if you are lost or want
131 to figure out what the effect of some command has been.
137 Pops two values off the stack, adds them,
138 and pushes the result.
139 The precision of the result is determined only
140 by the values of the arguments,
141 and is enough to be exact.
145 subtracts the first one popped from the second one popped,
146 and pushes the result.
149 Pops two values, multiplies them, and pushes the result.
150 The number of fraction digits in the result depends on
151 the current precision value and the number of fraction
152 digits in the two arguments.
156 divides the second one popped from the first one popped,
157 and pushes the result.
158 The number of fraction digits is specified by the precision value.
162 computes the remainder of the division that the
166 The value computed is the same as that computed by
167 the sequence \fBSd dld/ Ld*-\fP .
171 divides the second one popped from the first one popped.
172 The quotient is pushed first, and the remainder is pushed next.
173 The number of fraction digits used in the division
174 is specified by the precision value.
175 (The sequence \fBSdSn lnld/ LnLd%\fP could also accomplish
176 this function, with slightly different error checking.)
179 Pops two values and exponentiates,
180 using the first value popped as the exponent
181 and the second popped as the base.
182 The fraction part of the exponent is ignored.
183 The precision value specifies the number of fraction
184 digits in the result.
187 Pops three values and computes a modular exponentiation.
188 The first value popped is used as the reduction modulus;
189 this value must be a non-zero number,
190 and should be an integer.
191 The second popped is used as the exponent;
192 this value must be a non-negative number,
193 and any fractional part of this exponent will be ignored.
194 The third value popped is the base which gets exponentiated,
195 which should be an integer.
196 For small integers this is like the sequence \fBSm^Lm%\fP,
197 but, unlike \fB^\fP, this command will work with arbitrarily large exponents.
201 computes its square root,
203 The precision value specifies the number of fraction digits in the result.
205 Most arithmetic operations are affected by the ``precision value'',
206 which you can set with the
209 The default precision value is zero,
210 which means that all arithmetic except for
211 addition and subtraction produces integer results.
216 Clears the stack, rendering it empty.
219 Duplicates the value on the top of the stack,
220 pushing another copy of it.
221 Thus, ``4d*p'' computes 4 squared and prints it.
224 Reverses the order of (swaps) the top two values on the stack.
228 \*(Dc provides at least 256 memory registers,
229 each named by a single character.
230 You can store a number or a string in a register and retrieve it later.
233 Pop the value off the top of the stack and store
238 Copy the value in register
240 and push it onto the stack.
241 This does not alter the contents of
244 Each register also contains its own stack.
245 The current register value is the top of the register's stack.
248 Pop the value off the top of the (main) stack and
249 push it onto the stack of register
251 The previous value of the register becomes inaccessible.
254 Pop the value off the top of register
256 stack and push it onto the main stack.
261 is now accessible via the
268 command prints a list of all registers that have contents stored in them,
269 together with their contents.
270 Only the current contents of each register
271 (the top of its stack)
277 \*(Dc has three parameters that control its operation:
278 the precision, the input radix, and the output radix.
279 The precision specifies the number
280 of fraction digits to keep in the result of most arithmetic operations.
281 The input radix controls the interpretation of numbers typed in;
282 all numbers typed in use this radix.
283 The output radix is used for printing numbers.
285 The input and output radices are separate parameters;
286 you can make them unequal,
287 which can be useful or confusing.
288 The input radix must be between 2 and 16 inclusive.
289 The output radix must be at least 2.
290 The precision must be zero or greater.
291 The precision is always measured in decimal digits,
292 regardless of the current input or output radix.
295 Pops the value off the top of the stack
296 and uses it to set the input radix.
299 Pops the value off the top of the stack
300 and uses it to set the output radix.
303 Pops the value off the top of the stack
304 and uses it to set the precision.
307 Pushes the current input radix on the stack.
310 Pushes the current output radix on the stack.
313 Pushes the current precision on the stack.
317 \*(Dc can operate on strings as well as on numbers.
318 The only things you can do with strings are
319 print them and execute them as macros
320 (which means that the contents of the string are processed as
322 All registers and the stack can hold strings,
323 and \*(dc always knows whether any given object is a string or a number.
324 Some commands such as arithmetic operations demand numbers
325 as arguments and print errors if given strings.
326 Other commands can accept either a number or a string;
329 command can accept either and prints the object
330 according to its type.
333 Makes a string containing
335 (contained between balanced
340 and pushes it on the stack.
343 prints the characters
348 The top-of-stack is popped.
349 If it was a number, then the low-order byte of this number
350 is converted into a string and pushed onto the stack.
351 Otherwise the top-of-stack was a string,
352 and the first character of that string is pushed back.
355 Pops a value off the stack and executes it as a macro.
356 Normally it should be a string;
358 it is simply pushed back onto the stack.
365 on the stack and prints
369 Macros are most often stored in registers;
371 stores a macro to print
380 Pops two values off the stack and compares them
381 assuming they are numbers,
382 executing the contents of register
384 as a macro if the original top-of-stack
395 Similar but invokes the macro if the original top-of-stack is
396 not greater than (less than or equal to) what was the second-to-top.
399 Similar but invokes the macro if the original top-of-stack is less.
402 Similar but invokes the macro if the original top-of-stack is
403 not less than (greater than or equal to) what was the second-to-top.
406 Similar but invokes the macro if the two numbers popped are equal.
409 Similar but invokes the macro if the two numbers popped are not equal.
411 This can also be validly used to compare two strings for equality.
415 Reads a line from the terminal and executes it.
416 This command allows a macro to request input from the user.
419 exits from a macro and also from the macro which invoked it.
420 If called from the top level,
421 or from a macro which was called directly from the top level,
424 command will cause \*(dc to exit.
427 Pops a value off the stack and uses it as a count
428 of levels of macro execution to be exited.
434 command will never cause \*(dc to exit.
439 Pops a value off the stack,
440 calculates the number of digits it has
441 (or number of characters, if it is a string)
442 and pushes that number.
445 Pops a value off the stack,
446 calculates the number of fraction digits it has,
447 and pushes that number.
454 Pushes the current stack depth:
455 the number of objects on the stack before the execution of the
462 Will run the rest of the line as a system command.
463 Note that parsing of the !<, !=, and !> commands take precedence,
464 so if you want to run a command starting with <, =, or > you will
465 need to add a space after the !.
468 Will interpret the rest of the line as a comment.
471 Will pop the top two values off of the stack.
472 The old second-to-top value will be stored in the array
474 indexed by the old top-of-stack value.
477 Pops the top-of-stack and uses it as an index into
480 The selected value is then pushed onto the stack.
482 Note that each stacked instance of a register has its own
483 array associated with it.
484 Thus \fB1 0:a 0Sa 2 0:a La 0;ap\fP will print 1,
485 because the 2 was stored in an instance of 0:a that
projects / dragonfly.git / blob