Debian Codegraph @

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