| 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] . |