1 |
.\" $OpenBSD: dc.1,v 1.23 2007/05/31 19:20:09 jmc Exp $ |
2 |
.\" $MidnightBSD$ |
3 |
.\" |
4 |
.\" Copyright (C) Caldera International Inc. 2001-2002. |
5 |
.\" All rights reserved. |
6 |
.\" |
7 |
.\" Redistribution and use in source and binary forms, with or without |
8 |
.\" modification, are permitted provided that the following conditions |
9 |
.\" are met: |
10 |
.\" 1. Redistributions of source code and documentation must retain the above |
11 |
.\" copyright notice, this list of conditions and the following disclaimer. |
12 |
.\" 2. Redistributions in binary form must reproduce the above copyright |
13 |
.\" notice, this list of conditions and the following disclaimer in the |
14 |
.\" documentation and/or other materials provided with the distribution. |
15 |
.\" 3. All advertising materials mentioning features or use of this software |
16 |
.\" must display the following acknowledgement: |
17 |
.\" This product includes software developed or owned by Caldera |
18 |
.\" International, Inc. |
19 |
.\" 4. Neither the name of Caldera International, Inc. nor the names of other |
20 |
.\" contributors may be used to endorse or promote products derived from |
21 |
.\" this software without specific prior written permission. |
22 |
.\" |
23 |
.\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA |
24 |
.\" INTERNATIONAL, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR |
25 |
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES |
26 |
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. |
27 |
.\" IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE FOR ANY DIRECT, |
28 |
.\" INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES |
29 |
.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR |
30 |
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
31 |
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, |
32 |
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING |
33 |
.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE |
34 |
.\" POSSIBILITY OF SUCH DAMAGE. |
35 |
.\" |
36 |
.\" @(#)dc.1 8.1 (Berkeley) 6/6/93 |
37 |
.\" |
38 |
.Dd $Mdocdate: May 31 2007 $ |
39 |
.Dt DC 1 |
40 |
.Sh NAME |
41 |
.Nm dc |
42 |
.Nd desk calculator |
43 |
.Sh SYNOPSIS |
44 |
.Nm |
45 |
.Op Fl x |
46 |
.Op Fl e Ar expression |
47 |
.Op Ar file |
48 |
.Sh DESCRIPTION |
49 |
.Nm |
50 |
is an arbitrary precision arithmetic package. |
51 |
The overall structure of |
52 |
.Nm |
53 |
is |
54 |
a stacking (reverse Polish) calculator i.e.\& |
55 |
numbers are stored on a stack. |
56 |
Adding a number pushes it onto the stack. |
57 |
Arithmetic operations pop arguments off the stack |
58 |
and push the results. |
59 |
See also the |
60 |
.Xr bc 1 |
61 |
utility, which is a preprocessor for |
62 |
.Nm |
63 |
providing infix notation and a C-like syntax |
64 |
which implements functions and reasonable control |
65 |
structures for programs. |
66 |
The options are as follows: |
67 |
.Bl -tag -width Ds |
68 |
.It Fl e Ar expression |
69 |
Evaluate |
70 |
.Ar expression . |
71 |
If multiple |
72 |
.Fl e |
73 |
options are specified, they will be processed in the order given. |
74 |
If no |
75 |
.Ar file |
76 |
argument is given, execution will stop after processing the expressions |
77 |
given on the command line, |
78 |
otherwise processing will continue with the contents of |
79 |
.Ar file . |
80 |
.It Fl x |
81 |
Enable extended register mode. |
82 |
This mode is used by |
83 |
.Xr bc 1 |
84 |
to allow more than 256 registers. |
85 |
See |
86 |
.Sx Registers |
87 |
for a more detailed description. |
88 |
.El |
89 |
.Pp |
90 |
Ordinarily, |
91 |
.Nm |
92 |
operates on decimal integers, |
93 |
but one may specify an input base, output base, |
94 |
and a number of fractional digits (scale) to be maintained. |
95 |
If an argument is given, |
96 |
input is taken from that file until its end, |
97 |
then from the standard input. |
98 |
Whitespace is ignored, except where it signals the end of a number, |
99 |
end of a line or when a register name is expected. |
100 |
The following constructions are recognized: |
101 |
.Bl -tag -width "number" |
102 |
.It Va number |
103 |
The value of the number is pushed on the stack. |
104 |
A number is an unbroken string of the digits 0\-9 and letters A\-F. |
105 |
It may be preceded by an underscore |
106 |
.Pq Sq _ |
107 |
to input a negative number. |
108 |
A number may contain a single decimal point. |
109 |
A number may also contain the characters A\-F, with the values 10\-15. |
110 |
.It Cm "+ - / * % ~ ^" |
111 |
The |
112 |
top two values on the stack are added |
113 |
(+), |
114 |
subtracted |
115 |
(\-), |
116 |
multiplied (*), |
117 |
divided (/), |
118 |
remaindered (%), |
119 |
divided and remaindered (~), |
120 |
or exponentiated (^). |
121 |
The two entries are popped off the stack; |
122 |
the result is pushed on the stack in their place. |
123 |
Any fractional part of an exponent is ignored. |
124 |
.Pp |
125 |
For addition and subtraction, the scale of the result is the maximum |
126 |
of scales of the operands. |
127 |
For division the scale of the result is defined |
128 |
by the scale set by the |
129 |
.Ic k |
130 |
operation. |
131 |
For multiplication, the scale is defined by the expression |
132 |
.Sy min(a+b,max(a,b,scale)) , |
133 |
where |
134 |
.Sy a |
135 |
and |
136 |
.Sy b |
137 |
are the scales of the operands, and |
138 |
.Sy scale |
139 |
is the scale defined by the |
140 |
.Ic k |
141 |
operation. |
142 |
For exponentiation with a non-negative exponent, the scale of the result is |
143 |
.Sy min(a*b,max(scale,a)) , |
144 |
where |
145 |
.Sy a |
146 |
is the scale of the base, and |
147 |
.Sy b |
148 |
is the |
149 |
.Em value |
150 |
of the exponent. |
151 |
If the exponent is negative, the scale of the result is the scale |
152 |
defined by the |
153 |
.Ic k |
154 |
operation. |
155 |
.Pp |
156 |
In the case of the division and modulus operator (~), |
157 |
the resultant quotient is pushed first followed by the remainder. |
158 |
This is a shorthand for the sequence: |
159 |
.Bd -literal -offset indent -compact |
160 |
x y / x y % |
161 |
.Ed |
162 |
The division and modulus operator is a non-portable extension. |
163 |
.It Ic a |
164 |
Pop the top value from the stack. |
165 |
If that value is a number, compute the integer part of the number modulo 256. |
166 |
If the result is zero, push an empty string. |
167 |
Otherwise push a one character string by interpreting the computed value |
168 |
as an |
169 |
.Tn ASCII |
170 |
character. |
171 |
.Pp |
172 |
If the top value is a string, push a string containing the first character |
173 |
of the original string. |
174 |
If the original string is empty, an empty string is pushed back. |
175 |
The |
176 |
.Ic a |
177 |
operator is a non-portable extension. |
178 |
.It Ic c |
179 |
All values on the stack are popped. |
180 |
.It Ic d |
181 |
The top value on the stack is duplicated. |
182 |
.It Ic f |
183 |
All values on the stack are printed, separated by newlines. |
184 |
.It Ic G |
185 |
The top two numbers are popped from the stack and compared. |
186 |
A one is pushed if the top of the stack is equal to the second number |
187 |
on the stack. |
188 |
A zero is pushed otherwise. |
189 |
This is a non-portable extension. |
190 |
.It Ic I |
191 |
Pushes the input base on the top of the stack. |
192 |
.It Ic i |
193 |
The top value on the stack is popped and used as the |
194 |
base for further input. |
195 |
The initial input base is 10. |
196 |
.It Ic J |
197 |
Pop the top value from the stack. |
198 |
The recursion level is popped by that value and, following that, |
199 |
the input is skipped until the first occurrence of the |
200 |
.Ic M |
201 |
operator. |
202 |
The |
203 |
.Ic J |
204 |
operator is a non-portable extension, used by the |
205 |
.Xr bc 1 |
206 |
command. |
207 |
.It Ic K |
208 |
The current scale factor is pushed onto the stack. |
209 |
.It Ic k |
210 |
The top of the stack is popped, and that value is used as |
211 |
a non-negative scale factor: |
212 |
the appropriate number of places |
213 |
are printed on output, |
214 |
and maintained during multiplication, division, and exponentiation. |
215 |
The interaction of scale factor, |
216 |
input base, and output base will be reasonable if all are changed |
217 |
together. |
218 |
.It Ic L Ns Ar x |
219 |
Register |
220 |
.Ar x |
221 |
is treated as a stack and its top value is popped onto the main stack. |
222 |
.It Ic l Ns Ar x |
223 |
The |
224 |
value in register |
225 |
.Ar x |
226 |
is pushed on the stack. |
227 |
The register |
228 |
.Ar x |
229 |
is not altered. |
230 |
Initially, all registers contain the value zero. |
231 |
.It Ic M |
232 |
Mark used by the |
233 |
.Ic J |
234 |
operator. |
235 |
The |
236 |
.Ic M |
237 |
operator is a non-portable extensions, used by the |
238 |
.Xr bc 1 |
239 |
command. |
240 |
.It Ic N |
241 |
The top of the stack is replaced by one if the top of the stack |
242 |
is equal to zero. |
243 |
If the top of the stack is unequal to zero, it is replaced by zero. |
244 |
This is a non-portable extension. |
245 |
.It Ic n |
246 |
The top value on the stack is popped and printed without a newline. |
247 |
This is a non-portable extension. |
248 |
.It Ic O |
249 |
Pushes the output base on the top of the stack. |
250 |
.It Ic o |
251 |
The top value on the stack is popped and used as the |
252 |
base for further output. |
253 |
The initial output base is 10. |
254 |
.It Ic P |
255 |
The top of the stack is popped. |
256 |
If the top of the stack is a string, it is printed without a trailing newline. |
257 |
If the top of the stack is a number, it is interpreted as a |
258 |
base 256 number, and each digit of this base 256 number is printed as |
259 |
an |
260 |
.Tn ASCII |
261 |
character, without a trailing newline. |
262 |
.It Ic p |
263 |
The top value on the stack is printed with a trailing newline. |
264 |
The top value remains unchanged. |
265 |
.It Ic Q |
266 |
The top value on the stack is popped and the string execution level is popped |
267 |
by that value. |
268 |
.It Ic q |
269 |
Exits the program. |
270 |
If executing a string, the recursion level is |
271 |
popped by two. |
272 |
.It Ic R |
273 |
The top of the stack is removed (popped). |
274 |
This is a non-portable extension. |
275 |
.It Ic r |
276 |
The top two values on the stack are reversed (swapped). |
277 |
This is a non-portable extension. |
278 |
.It Ic S Ns Ar x |
279 |
Register |
280 |
.Ar x |
281 |
is treated as a stack. |
282 |
The top value of the main stack is popped and pushed on it. |
283 |
.It Ic s Ns Ar x |
284 |
The |
285 |
top of the stack is popped and stored into |
286 |
a register named |
287 |
.Ar x . |
288 |
.It Ic v |
289 |
Replaces the top element on the stack by its square root. |
290 |
The scale of the result is the maximum of the scale of the argument |
291 |
and the current value of scale. |
292 |
.It Ic X |
293 |
Replaces the number on the top of the stack with its scale factor. |
294 |
If the top of the stack is a string, replace it with the integer 0. |
295 |
.It Ic x |
296 |
Treats the top element of the stack as a character string |
297 |
and executes it as a string of |
298 |
.Nm |
299 |
commands. |
300 |
.It Ic Z |
301 |
Replaces the number on the top of the stack with its length. |
302 |
The length of a string is its number of characters. |
303 |
The length of a number is its number of digits, not counting the minus sign |
304 |
and decimal point. |
305 |
.It Ic z |
306 |
The stack level is pushed onto the stack. |
307 |
.It Cm [ Ns ... Ns Cm ] |
308 |
Puts the bracketed |
309 |
.Tn ASCII |
310 |
string onto the top of the stack. |
311 |
If the string includes brackets, these must be properly balanced. |
312 |
The backslash character |
313 |
.Pq Sq \e |
314 |
may be used as an escape character, making it |
315 |
possible to include unbalanced brackets in strings. |
316 |
To include a backslash in a string, use a double backslash. |
317 |
.It Xo |
318 |
.Cm < Ns Va x |
319 |
.Cm > Ns Va x |
320 |
.Cm = Ns Va x |
321 |
.Cm !< Ns Va x |
322 |
.Cm !> Ns Va x |
323 |
.Cm != Ns Va x |
324 |
.Xc |
325 |
The top two elements of the stack are popped and compared. |
326 |
Register |
327 |
.Ar x |
328 |
is executed if they obey the stated |
329 |
relation. |
330 |
.It Xo |
331 |
.Cm < Ns Va x Ns e Ns Va y |
332 |
.Cm > Ns Va x Ns e Ns Va y |
333 |
.Cm = Ns Va x Ns e Ns Va y |
334 |
.Cm !< Ns Va x Ns e Ns Va y |
335 |
.Cm !> Ns Va x Ns e Ns Va y |
336 |
.Cm != Ns Va x Ns e Ns Va y |
337 |
.Xc |
338 |
These operations are variants of the comparison operations above. |
339 |
The first register name is followed by the letter |
340 |
.Sq e |
341 |
and another register name. |
342 |
Register |
343 |
.Ar x |
344 |
will be executed if the relation is true, and register |
345 |
.Ar y |
346 |
will be executed if the relation is false. |
347 |
This is a non-portable extension. |
348 |
.It Ic \&( |
349 |
The top two numbers are popped from the stack and compared. |
350 |
A one is pushed if the top of the stack is less than the second number |
351 |
on the stack. |
352 |
A zero is pushed otherwise. |
353 |
This is a non-portable extension. |
354 |
.It Ic { |
355 |
The top two numbers are popped from the stack and compared. |
356 |
A one is pushed if the top of stack is less than or equal to the |
357 |
second number on the stack. |
358 |
A zero is pushed otherwise. |
359 |
This is a non-portable extension. |
360 |
.It Ic \&! |
361 |
Interprets the rest of the line as a |
362 |
.Ux |
363 |
command. |
364 |
.It Ic \&? |
365 |
A line of input is taken from the input source (usually the terminal) |
366 |
and executed. |
367 |
.It Ic : Ns Ar r |
368 |
Pop two values from the stack. |
369 |
The second value on the stack is stored into the array |
370 |
.Ar r |
371 |
indexed by the top of stack. |
372 |
.It Ic ; Ns Ar r |
373 |
Pop a value from the stack. |
374 |
The value is used as an index into register |
375 |
.Ar r . |
376 |
The value in this register is pushed onto the stack. |
377 |
.Pp |
378 |
Array elements initially have the value zero. |
379 |
Each level of a stacked register has its own array associated with |
380 |
it. |
381 |
The command sequence |
382 |
.Bd -literal -offset indent |
383 |
[first] 0:a [dummy] Sa [second] 0:a 0;a p La 0;a p |
384 |
.Ed |
385 |
.Pp |
386 |
will print |
387 |
.Bd -literal -offset indent |
388 |
second |
389 |
first |
390 |
.Ed |
391 |
.Pp |
392 |
since the string |
393 |
.Ql second |
394 |
is written in an array that is later popped, to reveal the array that |
395 |
stored |
396 |
.Ql first . |
397 |
.It Ic # |
398 |
Skip the rest of the line. |
399 |
This is a non-portable extension. |
400 |
.El |
401 |
.Ss Registers |
402 |
Registers have a single character name |
403 |
.Ar x , |
404 |
where |
405 |
.Ar x |
406 |
may be any character, including space, tab or any other special character. |
407 |
If extended register mode is enabled using the |
408 |
.Fl x |
409 |
option and the register identifier |
410 |
.Ar x |
411 |
has the value 255, the next two characters are interpreted as a |
412 |
two-byte register index. |
413 |
The set of standard single character registers and the set of extended |
414 |
registers do not overlap. |
415 |
Extended register mode is a non-portable extension. |
416 |
.Sh EXAMPLES |
417 |
An example which prints the first ten values of |
418 |
.Ic n! : |
419 |
.Bd -literal -offset indent |
420 |
[la1+dsa*pla10>y]sy |
421 |
0sa1 |
422 |
lyx |
423 |
.Ed |
424 |
.Pp |
425 |
Independent of the current input base, the command |
426 |
.Bd -literal -offset indent |
427 |
Ai |
428 |
.Ed |
429 |
.Pp |
430 |
will reset the input base to decimal 10. |
431 |
.Sh DIAGNOSTICS |
432 |
.Bl -diag |
433 |
.It %c (0%o) is unimplemented |
434 |
an undefined operation was called. |
435 |
.It stack empty |
436 |
for not enough elements on the stack to do what was asked. |
437 |
.It stack register '%c' (0%o) is empty |
438 |
for an |
439 |
.Ar L |
440 |
operation from a stack register that is empty. |
441 |
.It Runtime warning: non-zero scale in exponent |
442 |
for a fractional part of an exponent that is being ignored. |
443 |
.It divide by zero |
444 |
for trying to divide by zero. |
445 |
.It remainder by zero |
446 |
for trying to take a remainder by zero. |
447 |
.It square root of negative number |
448 |
for trying to take the square root of a negative number. |
449 |
.It index too big |
450 |
for an array index that is larger than 2048. |
451 |
.It negative index |
452 |
for a negative array index. |
453 |
.It "input base must be a number between 2 and 16" |
454 |
for trying to set an illegal input base. |
455 |
.It output base must be a number greater than 1 |
456 |
for trying to set an illegal output base. |
457 |
.It scale must be a nonnegative number |
458 |
for trying to set a negative or zero scale. |
459 |
.It scale too large |
460 |
for trying to set a scale that is too large. |
461 |
A scale must be representable as a 32-bit unsigned number. |
462 |
.It Q command argument exceeded string execution depth |
463 |
for trying to pop the recursion level more than the current |
464 |
recursion level. |
465 |
.It Q command requires a number >= 1 |
466 |
for trying to pop an illegal number of recursion levels. |
467 |
.It recursion too deep |
468 |
for too many levels of nested execution. |
469 |
.Pp |
470 |
The recursion level is increased by one if the |
471 |
.Ar x |
472 |
or |
473 |
.Ar ?\& |
474 |
operation or one of the compare operations resulting in the execution |
475 |
of register is executed. |
476 |
As an exception, the recursion level is not increased if the operation |
477 |
is executed as the last command of a string. |
478 |
For example, the commands |
479 |
.Bd -literal -offset indent |
480 |
[lax]sa |
481 |
1 lax |
482 |
.Ed |
483 |
.Pp |
484 |
will execute an endless loop, while the commands |
485 |
.Bd -literal -offset indent |
486 |
[laxp]sa |
487 |
1 lax |
488 |
.Ed |
489 |
.Pp |
490 |
will terminate because of a too deep recursion level. |
491 |
.It J command argument exceeded string execution depth |
492 |
for trying to pop the recursion level more than the current |
493 |
recursion level. |
494 |
.It mark not found |
495 |
for a failed scan for an occurrence of the |
496 |
.Ic M |
497 |
operator. |
498 |
.El |
499 |
.Sh SEE ALSO |
500 |
.Xr bc 1 |
501 |
.Rs |
502 |
.%B USD:05 |
503 |
.%A L. L. Cherry |
504 |
.%A R. Morris |
505 |
.%T "DC \- An Interactive Desk Calculator" |
506 |
.Re |
507 |
.Sh STANDARDS |
508 |
The arithmetic operations of the |
509 |
.Nm |
510 |
utility are expected to conform to the definition listed in the |
511 |
.Xr bc 1 |
512 |
section of the |
513 |
.St -p1003.2 |
514 |
specification. |
515 |
.Sh HISTORY |
516 |
The |
517 |
.Nm |
518 |
command first appeared in |
519 |
.At v6 . |
520 |
A complete rewrite of the |
521 |
.Nm |
522 |
command using the |
523 |
.Xr bn 3 |
524 |
big number routines first appeared in |
525 |
.Ox 3.5 . |
526 |
.Sh AUTHORS |
527 |
.An -nosplit |
528 |
The original version of the |
529 |
.Nm |
530 |
command was written by |
531 |
.An Robert Morris |
532 |
and |
533 |
.An Lorinda Cherry . |
534 |
The current version of the |
535 |
.Nm |
536 |
utility was written by |
537 |
.An Otto Moerbeek . |