2 .\" $OpenBSD: dc.1,v 1.27 2012/08/19 12:07:21 jmc Exp $
4 .\" Copyright (C) Caldera International Inc. 2001-2002.
5 .\" All rights reserved.
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
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.
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.
36 .\" @(#)dc.1 8.1 (Berkeley) 6/6/93
47 .Op Fl e Ar expression
52 is an arbitrary precision arithmetic package.
53 The overall structure of
56 a stacking (reverse Polish) calculator i.e.\&
57 numbers are stored on a stack.
58 Adding a number pushes it onto the stack.
59 Arithmetic operations pop arguments off the stack
63 utility, which is a preprocessor for
65 providing infix notation and a C-like syntax
66 which implements functions and reasonable control
67 structures for programs.
68 The options are as follows:
70 .It Fl e Ar expr , Fl Fl expression Ar expr
75 options are specified, they will be processed in the order given.
76 .It Fl f Ar filename , Fl Fl file Ar filename
77 Process the content of the given file before further calculations are done.
80 options are specified, they will be processed in the order given.
82 Print short usage info.
83 .It Fl V , Fl Fl version
86 Enable extended register mode.
89 to allow more than 256 registers.
92 for a more detailed description.
99 are specified on the command line,
101 reads from the standard input.
112 operates on decimal integers,
113 but one may specify an input base, output base,
114 and a number of fractional digits (scale) to be maintained.
115 Whitespace is ignored, except where it signals the end of a number,
116 end of a line or when a register name is expected.
117 The following constructions are recognized:
118 .Bl -tag -width "number"
120 The value of the number is pushed on the stack.
121 A number is an unbroken string of the digits 0\-9 and letters A\-F.
122 It may be preceded by an underscore
124 to input a negative number.
125 A number may contain a single decimal point.
126 A number may also contain the characters A\-F, with the values 10\-15.
127 .It Cm "+ - / * % ~ ^"
129 top two values on the stack are added
136 divided and remaindered (~),
137 or exponentiated (^).
138 The two entries are popped off the stack;
139 the result is pushed on the stack in their place.
140 Any fractional part of an exponent is ignored.
142 For addition, subtraction, and remainder, the scale of the result is the
143 maximum of scales of the operands.
144 For division the scale of the result is defined
145 by the scale set by the
148 For multiplication, the scale is defined by the expression
149 .Sy min(a+b,max(a,b,scale)) ,
154 are the scales of the operands, and
156 is the scale defined by the
159 For exponentiation with a non-negative exponent, the scale of the result is
160 .Sy min(a*b,max(scale,a)) ,
163 is the scale of the base, and
168 If the exponent is negative, the scale of the result is the scale
173 In the case of the division and modulus operator (~),
174 the resultant quotient is pushed first followed by the remainder.
175 This is a shorthand for the sequence:
176 .Bd -literal -offset indent -compact
179 The division and modulus operator is a non-portable extension.
181 Pop the top value from the stack.
182 If that value is a number, compute the integer part of the number modulo 256.
183 If the result is zero, push an empty string.
184 Otherwise push a one character string by interpreting the computed value
189 If the top value is a string, push a string containing the first character
190 of the original string.
191 If the original string is empty, an empty string is pushed back.
194 operator is a non-portable extension.
196 All values on the stack are popped.
198 The top value on the stack is duplicated.
202 except that the output is written to the standard error stream.
204 All values on the stack are printed, separated by newlines.
206 The top two numbers are popped from the stack and compared.
207 A one is pushed if the top of the stack is equal to the second number
209 A zero is pushed otherwise.
210 This is a non-portable extension.
212 Pushes the input base on the top of the stack.
214 The top value on the stack is popped and used as the
215 base for further input.
216 The initial input base is 10.
218 Pop the top value from the stack.
219 The recursion level is popped by that value and, following that,
220 the input is skipped until the first occurrence of the
225 operator is a non-portable extension, used by the
229 The current scale factor is pushed onto the stack.
231 The top of the stack is popped, and that value is used as
232 a non-negative scale factor:
233 the appropriate number of places
234 are printed on output,
235 and maintained during multiplication, division, and exponentiation.
236 The interaction of scale factor,
237 input base, and output base will be reasonable if all are changed
242 is treated as a stack and its top value is popped onto the main stack.
247 is pushed on the stack.
251 Initially, all registers contain the value zero.
258 operator is a non-portable extensions, used by the
262 The top of the stack is replaced by one if the top of the stack
264 If the top of the stack is unequal to zero, it is replaced by zero.
265 This is a non-portable extension.
267 The top value on the stack is popped and printed without a newline.
268 This is a non-portable extension.
270 Pushes the output base on the top of the stack.
272 The top value on the stack is popped and used as the
273 base for further output.
274 The initial output base is 10.
276 The top of the stack is popped.
277 If the top of the stack is a string, it is printed without a trailing newline.
278 If the top of the stack is a number, it is interpreted as a
279 base 256 number, and each digit of this base 256 number is printed as
282 character, without a trailing newline.
284 The top value on the stack is printed with a trailing newline.
285 The top value remains unchanged.
287 The top value on the stack is popped and the string execution level is popped
291 If executing a string, the recursion level is
294 The top of the stack is removed (popped).
295 This is a non-portable extension.
297 The top two values on the stack are reversed (swapped).
298 This is a non-portable extension.
302 is treated as a stack.
303 The top value of the main stack is popped and pushed on it.
306 top of the stack is popped and stored into
310 Replaces the top element on the stack by its square root.
311 The scale of the result is the maximum of the scale of the argument
312 and the current value of scale.
314 Replaces the number on the top of the stack with its scale factor.
315 If the top of the stack is a string, replace it with the integer 0.
317 Treats the top element of the stack as a character string
318 and executes it as a string of
322 Replaces the number on the top of the stack with its length.
323 The length of a string is its number of characters.
324 The length of a number is its number of digits, not counting the minus sign
327 The stack level is pushed onto the stack.
328 .It Cm \&[ Ns ... Ns Cm \&]
331 string onto the top of the stack.
332 If the string includes brackets, these must be properly balanced.
333 The backslash character
335 may be used as an escape character, making it
336 possible to include unbalanced brackets in strings.
337 To include a backslash in a string, use a double backslash.
346 The top two elements of the stack are popped and compared.
349 is executed if they obey the stated
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
355 .Cm !< Ns Va x Ns e Ns Va y
356 .Cm !> Ns Va x Ns e Ns Va y
357 .Cm != Ns Va x Ns e Ns Va y
359 These operations are variants of the comparison operations above.
360 The first register name is followed by the letter
362 and another register name.
365 will be executed if the relation is true, and register
367 will be executed if the relation is false.
368 This is a non-portable extension.
370 The top two numbers are popped from the stack and compared.
371 A one is pushed if the top of the stack is less than the second number
373 A zero is pushed otherwise.
374 This is a non-portable extension.
376 The top two numbers are popped from the stack and compared.
377 A one is pushed if the top of stack is less than or equal to the
378 second number on the stack.
379 A zero is pushed otherwise.
380 This is a non-portable extension.
382 Interprets the rest of the line as a
386 A line of input is taken from the input source (usually the terminal)
389 Pop two values from the stack.
390 The second value on the stack is stored into the array
392 indexed by the top of stack.
394 Pop a value from the stack.
395 The value is used as an index into register
397 The value in this register is pushed onto the stack.
399 Array elements initially have the value zero.
400 Each level of a stacked register has its own array associated with
403 .Bd -literal -offset indent
404 [first] 0:a [dummy] Sa [second] 0:a 0;a p La 0;a p
408 .Bd -literal -offset indent
415 is written in an array that is later popped, to reveal the array that
419 Skip the rest of the line.
420 This is a non-portable extension.
423 Registers have a single character name
427 may be any character, including space, tab or any other special character.
428 If extended register mode is enabled using the
430 option and the register identifier
432 has the value 255, the next two characters are interpreted as a
433 two-byte register index.
434 The set of standard single character registers and the set of extended
435 registers do not overlap.
436 Extended register mode is a non-portable extension.
438 An example which prints the first ten values of
440 .Bd -literal -offset indent
446 Independent of the current input base, the command
447 .Bd -literal -offset indent
451 will reset the input base to decimal 10.
454 .It %c (0%o) is unimplemented
455 an undefined operation was called.
457 for not enough elements on the stack to do what was asked.
458 .It stack register '%c' (0%o) is empty
461 operation from a stack register that is empty.
462 .It Runtime warning: non-zero scale in exponent
463 for a fractional part of an exponent that is being ignored.
465 for trying to divide by zero.
466 .It remainder by zero
467 for trying to take a remainder by zero.
468 .It square root of negative number
469 for trying to take the square root of a negative number.
471 for an array index that is larger than 2048.
473 for a negative array index.
474 .It "input base must be a number between 2 and 16"
475 for trying to set an illegal input base.
476 .It output base must be a number greater than 1
477 for trying to set an illegal output base.
478 .It scale must be a nonnegative number
479 for trying to set a negative or zero scale.
481 for trying to set a scale that is too large.
482 A scale must be representable as a 32-bit unsigned number.
483 .It Q command argument exceeded string execution depth
484 for trying to pop the recursion level more than the current
486 .It Q command requires a number >= 1
487 for trying to pop an illegal number of recursion levels.
488 .It recursion too deep
489 for too many levels of nested execution.
491 The recursion level is increased by one if the
495 operation or one of the compare operations resulting in the execution
496 of register is executed.
497 As an exception, the recursion level is not increased if the operation
498 is executed as the last command of a string.
499 For example, the commands
500 .Bd -literal -offset indent
505 will execute an endless loop, while the commands
506 .Bd -literal -offset indent
511 will terminate because of a too deep recursion level.
512 .It J command argument exceeded string execution depth
513 for trying to pop the recursion level more than the current
516 for a failed scan for an occurrence of the
526 "DC \- An Interactive Desk Calculator"
527 .Pa /usr/share/doc/usd/05.dc/ .
529 The arithmetic operations of the
531 utility are expected to conform to the definition listed in the
539 command first appeared in
541 A complete rewrite of the
545 big number routines first appeared in
549 The original version of the
551 command was written by
555 The current version of the
557 utility was written by