Debian Codegraph @

upstream/debian-unstable/man1/dc.1

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