1 .\" $OpenBSD: dc.1,v 1.27 2012/08/19 12:07:21 jmc Exp $
3 .\" Copyright (C) Caldera International Inc. 2001-2002.
4 .\" All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
9 .\" 1. Redistributions of source code and documentation must retain the above
10 .\" copyright notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. All advertising materials mentioning features or use of this software
15 .\" must display the following acknowledgement:
16 .\" This product includes software developed or owned by Caldera
17 .\" International, Inc.
18 .\" 4. Neither the name of Caldera International, Inc. nor the names of other
19 .\" contributors may be used to endorse or promote products derived from
20 .\" this software without specific prior written permission.
22 .\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA
23 .\" INTERNATIONAL, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR
24 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
25 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
26 .\" IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE FOR ANY DIRECT,
27 .\" INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
28 .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
29 .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
31 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
32 .\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
33 .\" POSSIBILITY OF SUCH DAMAGE.
44 .Op Fl e Ar expression
49 is an arbitrary precision arithmetic package.
50 The overall structure of
53 a stacking (reverse Polish) calculator i.e.\&
54 numbers are stored on a stack.
55 Adding a number pushes it onto the stack.
56 Arithmetic operations pop arguments off the stack
60 utility, which is a preprocessor for
62 providing infix notation and a C-like syntax
63 which implements functions and reasonable control
64 structures for programs.
65 The options are as follows:
67 .It Fl e Ar expr , Fl Fl expression Ar expr
72 options are specified, they will be processed in the order given.
73 .It Fl f Ar filename , Fl Fl file Ar filename
74 Process the content of the given file before further calculations are done.
77 options are specified, they will be processed in the order given.
79 Print short usage info.
80 .It Fl V , Fl Fl version
83 Enable extended register mode.
86 to allow more than 256 registers.
89 for a more detailed description.
96 are specified on the command line,
98 reads from the standard input.
109 operates on decimal integers,
110 but one may specify an input base, output base,
111 and a number of fractional digits (scale) to be maintained.
112 Whitespace is ignored, except where it signals the end of a number,
113 end of a line or when a register name is expected.
114 The following constructions are recognized:
115 .Bl -tag -width "number"
117 The value of the number is pushed on the stack.
118 A number is an unbroken string of the digits 0\-9 and letters A\-F.
119 It may be preceded by an underscore
121 to input a negative number.
122 A number may contain a single decimal point.
123 A number may also contain the characters A\-F, with the values 10\-15.
124 .It Cm "+ - / * % ~ ^"
126 top two values on the stack are added
133 divided and remaindered (~),
134 or exponentiated (^).
135 The two entries are popped off the stack;
136 the result is pushed on the stack in their place.
137 Any fractional part of an exponent is ignored.
139 For addition, subtraction, and remainder, the scale of the result is the
140 maximum of scales of the operands.
141 For division the scale of the result is defined
142 by the scale set by the
145 For multiplication, the scale is defined by the expression
146 .Sy min(a+b,max(a,b,scale)) ,
151 are the scales of the operands, and
153 is the scale defined by the
156 For exponentiation with a non-negative exponent, the scale of the result is
157 .Sy min(a*b,max(scale,a)) ,
160 is the scale of the base, and
165 If the exponent is negative, the scale of the result is the scale
170 In the case of the division and modulus operator (~),
171 the resultant quotient is pushed first followed by the remainder.
172 This is a shorthand for the sequence:
173 .Bd -literal -offset indent -compact
176 The division and modulus operator is a non-portable extension.
178 Pop the top value from the stack.
179 If that value is a number, compute the integer part of the number modulo 256.
180 If the result is zero, push an empty string.
181 Otherwise push a one character string by interpreting the computed value
186 If the top value is a string, push a string containing the first character
187 of the original string.
188 If the original string is empty, an empty string is pushed back.
191 operator is a non-portable extension.
193 All values on the stack are popped.
195 The top value on the stack is duplicated.
199 except that the output is written to the standard error stream.
201 All values on the stack are printed, separated by newlines.
203 The top two numbers are popped from the stack and compared.
204 A one is pushed if the top of the stack is equal to the second number
206 A zero is pushed otherwise.
207 This is a non-portable extension.
209 Pushes the input base on the top of the stack.
211 The top value on the stack is popped and used as the
212 base for further input.
213 The initial input base is 10.
215 Pop the top value from the stack.
216 The recursion level is popped by that value and, following that,
217 the input is skipped until the first occurrence of the
222 operator is a non-portable extension, used by the
226 The current scale factor is pushed onto the stack.
228 The top of the stack is popped, and that value is used as
229 a non-negative scale factor:
230 the appropriate number of places
231 are printed on output,
232 and maintained during multiplication, division, and exponentiation.
233 The interaction of scale factor,
234 input base, and output base will be reasonable if all are changed
239 is treated as a stack and its top value is popped onto the main stack.
244 is pushed on the stack.
248 Initially, all registers contain the value zero.
255 operator is a non-portable extensions, used by the
259 The top of the stack is replaced by one if the top of the stack
261 If the top of the stack is unequal to zero, it is replaced by zero.
262 This is a non-portable extension.
264 The top value on the stack is popped and printed without a newline.
265 This is a non-portable extension.
267 Pushes the output base on the top of the stack.
269 The top value on the stack is popped and used as the
270 base for further output.
271 The initial output base is 10.
273 The top of the stack is popped.
274 If the top of the stack is a string, it is printed without a trailing newline.
275 If the top of the stack is a number, it is interpreted as a
276 base 256 number, and each digit of this base 256 number is printed as
279 character, without a trailing newline.
281 The top value on the stack is printed with a trailing newline.
282 The top value remains unchanged.
284 The top value on the stack is popped and the string execution level is popped
288 If executing a string, the recursion level is
291 The top of the stack is removed (popped).
292 This is a non-portable extension.
294 The top two values on the stack are reversed (swapped).
295 This is a non-portable extension.
299 is treated as a stack.
300 The top value of the main stack is popped and pushed on it.
303 top of the stack is popped and stored into
307 Replaces the top element on the stack by its square root.
308 The scale of the result is the maximum of the scale of the argument
309 and the current value of scale.
311 Replaces the number on the top of the stack with its scale factor.
312 If the top of the stack is a string, replace it with the integer 0.
314 Treats the top element of the stack as a character string
315 and executes it as a string of
319 Replaces the number on the top of the stack with its length.
320 The length of a string is its number of characters.
321 The length of a number is its number of digits, not counting the minus sign
324 The stack level is pushed onto the stack.
325 .It Cm \&[ Ns ... Ns Cm \&]
328 string onto the top of the stack.
329 If the string includes brackets, these must be properly balanced.
330 The backslash character
332 may be used as an escape character, making it
333 possible to include unbalanced brackets in strings.
334 To include a backslash in a string, use a double backslash.
343 The top two elements of the stack are popped and compared.
346 is executed if they obey the stated
349 .Cm < Ns Va x Ns e Ns Va y
350 .Cm > Ns Va x Ns e Ns Va y
351 .Cm = Ns Va x Ns e Ns Va y
352 .Cm !< Ns Va x Ns e Ns Va y
353 .Cm !> Ns Va x Ns e Ns Va y
354 .Cm != Ns Va x Ns e Ns Va y
356 These operations are variants of the comparison operations above.
357 The first register name is followed by the letter
359 and another register name.
362 will be executed if the relation is true, and register
364 will be executed if the relation is false.
365 This is a non-portable extension.
367 The top two numbers are popped from the stack and compared.
368 A one is pushed if the top of the stack is less than the second number
370 A zero is pushed otherwise.
371 This is a non-portable extension.
373 The top two numbers are popped from the stack and compared.
374 A one is pushed if the top of stack is less than or equal to the
375 second number on the stack.
376 A zero is pushed otherwise.
377 This is a non-portable extension.
379 Interprets the rest of the line as a
383 A line of input is taken from the input source (usually the terminal)
386 Pop two values from the stack.
387 The second value on the stack is stored into the array
389 indexed by the top of stack.
391 Pop a value from the stack.
392 The value is used as an index into register
394 The value in this register is pushed onto the stack.
396 Array elements initially have the value zero.
397 Each level of a stacked register has its own array associated with
400 .Bd -literal -offset indent
401 [first] 0:a [dummy] Sa [second] 0:a 0;a p La 0;a p
405 .Bd -literal -offset indent
412 is written in an array that is later popped, to reveal the array that
416 Skip the rest of the line.
417 This is a non-portable extension.
420 Registers have a single character name
424 may be any character, including space, tab or any other special character.
425 If extended register mode is enabled using the
427 option and the register identifier
429 has the value 255, the next two characters are interpreted as a
430 two-byte register index.
431 The set of standard single character registers and the set of extended
432 registers do not overlap.
433 Extended register mode is a non-portable extension.
435 An example which prints the first ten values of
437 .Bd -literal -offset indent
443 Independent of the current input base, the command
444 .Bd -literal -offset indent
448 will reset the input base to decimal 10.
451 .It %c (0%o) is unimplemented
452 an undefined operation was called.
454 for not enough elements on the stack to do what was asked.
455 .It stack register '%c' (0%o) is empty
458 operation from a stack register that is empty.
459 .It Runtime warning: non-zero scale in exponent
460 for a fractional part of an exponent that is being ignored.
462 for trying to divide by zero.
463 .It remainder by zero
464 for trying to take a remainder by zero.
465 .It square root of negative number
466 for trying to take the square root of a negative number.
468 for an array index that is larger than 2048.
470 for a negative array index.
471 .It "input base must be a number between 2 and 16"
472 for trying to set an illegal input base.
473 .It output base must be a number greater than 1
474 for trying to set an illegal output base.
475 .It scale must be a nonnegative number
476 for trying to set a negative or zero scale.
478 for trying to set a scale that is too large.
479 A scale must be representable as a 32-bit unsigned number.
480 .It Q command argument exceeded string execution depth
481 for trying to pop the recursion level more than the current
483 .It Q command requires a number >= 1
484 for trying to pop an illegal number of recursion levels.
485 .It recursion too deep
486 for too many levels of nested execution.
488 The recursion level is increased by one if the
492 operation or one of the compare operations resulting in the execution
493 of register is executed.
494 As an exception, the recursion level is not increased if the operation
495 is executed as the last command of a string.
496 For example, the commands
497 .Bd -literal -offset indent
502 will execute an endless loop, while the commands
503 .Bd -literal -offset indent
508 will terminate because of a too deep recursion level.
509 .It J command argument exceeded string execution depth
510 for trying to pop the recursion level more than the current
513 for a failed scan for an occurrence of the
523 "DC \- An Interactive Desk Calculator"
524 .Pa /usr/share/doc/usd/05.dc/ .
526 The arithmetic operations of the
528 utility are expected to conform to the definition listed in the
536 command first appeared in
538 A complete rewrite of the
542 big number routines first appeared in
546 The original version of the
548 command was written by
552 The current version of the
554 utility was written by