NAME
dc —
desk calculator
SYNOPSIS
dc |
[-x]
[-e
expression]
[file] |
DESCRIPTION
dc is an arbitrary precision arithmetic package. The overall
structure of
dc is a stacking (reverse Polish) calculator
i.e. numbers are stored on a stack. Adding a number pushes it onto the stack.
Arithmetic operations pop arguments off the stack and push the results. See
also the
bc(1) utility, which is a
preprocessor for
dc providing infix notation and a C-like
syntax which implements functions and reasonable control structures for
programs. The options are as follows:
-
-
- -e
expression
- Evaluate expression. If multiple
-e options are specified, they will be processed in the
order given.
-
-
- -x
- Enable extended register mode. This mode is used by
bc(1) to allow more than 256
registers. See Registers for a more
detailed description.
If neither
expression nor
file are
specified on the command line,
dc reads from the standard
input. Otherwise
expression and
file are processed and
dc exits.
Ordinarily,
dc operates on decimal integers, but one may
specify an input base, output base, and a number of fractional digits (scale)
to be maintained. Whitespace is ignored, except where it signals the end of a
number, end of a line or when a register name is expected. The following
constructions are recognized:
-
-
- number
- The value of the number is pushed on the stack. A number is
an unbroken string of the digits 0-9 and letters A-F. It may be preceded
by an underscore (‘_’) to input a negative number. A number
may contain a single decimal point. A number may also contain the
characters A-F, with the values 10-15.
-
-
- + - / * % ~
^
- The top two values on the stack are added (+), subtracted
(-), multiplied (*), divided (/), remaindered (%), divided and remaindered
(~), or exponentiated (^). The two entries are popped off the stack; the
result is pushed on the stack in their place. Any fractional part of an
exponent is ignored.
For addition and subtraction, the scale of the result is the maximum of
scales of the operands. For division the scale of the result is defined by
the scale set by the k operation. For multiplication,
the scale is defined by the expression
min(a+b,max(a,b,scale)), where a and
b are the scales of the operands, and
scale is the scale defined by the k
operation. For exponentiation with a non-negative exponent, the scale of
the result is min(a*b,max(scale,a)), where
a is the scale of the base, and b is
the value of the exponent. If the exponent is negative,
the scale of the result is the scale defined by the k
operation.
In the case of the division and modulus operator (~), the resultant quotient
is pushed first followed by the remainder. This is a shorthand for the
sequence:
The division and modulus operator is a non-portable extension.
-
-
- a
- Pop the top value from the stack. If that value is a
number, compute the integer part of the number modulo 256. If the result
is zero, push an empty string. Otherwise push a one character string by
interpreting the computed value as an ASCII character.
If the top value is a string, push a string containing the first character
of the original string. If the original string is empty, an empty string
is pushed back. The a operator is a non-portable
extension.
-
-
- c
- All values on the stack are popped.
-
-
- d
- The top value on the stack is duplicated.
-
-
- e
- Equivalent to p, except that the output
is written to the standard error stream.
-
-
- f
- All values on the stack are printed, separated by
newlines.
-
-
- G
- The top two numbers are popped from the stack and compared.
A one is pushed if the top of the stack is equal to the second number on
the stack. A zero is pushed otherwise. This is a non-portable
extension.
-
-
- I
- Pushes the input base on the top of the stack.
-
-
- i
- The top value on the stack is popped and used as the base
for further input. The initial input base is 10.
-
-
- J
- Pop the top value from the stack. The recursion level is
popped by that value and, following that, the input is skipped until the
first occurrence of the M operator. The
J operator is a non-portable extension, used by the
bc(1) command.
-
-
- K
- The current scale factor is pushed onto the stack.
-
-
- k
- The top of the stack is popped, and that value is used as a
non-negative scale factor: the appropriate number of places are printed on
output, and maintained during multiplication, division, and
exponentiation. The interaction of scale factor, input base, and output
base will be reasonable if all are changed together.
-
-
- Lx
- Register x is treated as a stack and
its top value is popped onto the main stack.
-
-
- lx
- The value in register x is pushed on
the stack. The register x is not altered. Initially,
all registers contain the value zero.
-
-
- M
- Mark used by the J operator. The
M operator is a non-portable extensions, used by the
bc(1) command.
-
-
- N
- The top of the stack is replaced by one if the top of the
stack is equal to zero. If the top of the stack is unequal to zero, it is
replaced by zero. This is a non-portable extension.
-
-
- n
- The top value on the stack is popped and printed without a
newline. This is a non-portable extension.
-
-
- O
- Pushes the output base on the top of the stack.
-
-
- o
- The top value on the stack is popped and used as the base
for further output. The initial output base is 10.
-
-
- P
- The top of the stack is popped. If the top of the stack is
a string, it is printed without a trailing newline. If the top of the
stack is a number, it is interpreted as a base 256 number, and each digit
of this base 256 number is printed as an ASCII character, without a
trailing newline.
-
-
- p
- The top value on the stack is printed with a trailing
newline. The top value remains unchanged.
-
-
- Q
- The top value on the stack is popped and the string
execution level is popped by that value.
-
-
- q
- Exits the program. If executing a string, the recursion
level is popped by two.
-
-
- R
- The top of the stack is removed (popped). This is a
non-portable extension.
-
-
- r
- The top two values on the stack are reversed (swapped).
This is a non-portable extension.
-
-
- Sx
- Register x is treated as a stack. The
top value of the main stack is popped and pushed on it.
-
-
- sx
- The top of the stack is popped and stored into a register
named x.
-
-
- v
- Replaces the top element on the stack by its square root.
The scale of the result is the maximum of the scale of the argument and
the current value of scale.
-
-
- X
- Replaces the number on the top of the stack with its scale
factor. If the top of the stack is a string, replace it with the integer
0.
-
-
- x
- Treats the top element of the stack as a character string
and executes it as a string of dc commands.
-
-
- Z
- Replaces the number on the top of the stack with its
length. The length of a string is its number of characters. The length of
a number is its number of digits, not counting the minus sign and decimal
point.
-
-
- z
- The stack level is pushed onto the stack.
-
-
- [...]
- Puts the bracketed ASCII string onto the top of the stack.
If the string includes brackets, these must be properly balanced. The
backslash character (‘\’) may be used as an escape character,
making it possible to include unbalanced brackets in strings. To include a
backslash in a string, use a double backslash.
-
-
- <x
>x
=x
!<x
!>x
!=x
- The top two elements of the stack are popped and compared.
Register x is executed if they obey the stated
relation.
-
-
- <xey
>xey
=xey
!<xey
!>xey
!=xey
- These operations are variants of the comparison operations
above. The first register name is followed by the letter ‘e’
and another register name. Register x will be
executed if the relation is true, and register y
will be executed if the relation is false. This is a non-portable
extension.
-
-
- (
- The top two numbers are popped from the stack and compared.
A one is pushed if the top of the stack is less than the second number on
the stack. A zero is pushed otherwise. This is a non-portable
extension.
-
-
- {
- The top two numbers are popped from the stack and compared.
A one is pushed if the top of stack is less than or equal to the second
number on the stack. A zero is pushed otherwise. This is a non-portable
extension.
-
-
- ?
- A line of input is taken from the input source (usually the
terminal) and executed.
-
-
- :r
- Pop two values from the stack. The second value on the
stack is stored into the array r indexed by the top
of stack.
-
-
- ;r
- Pop a value from the stack. The value is used as an index
into register r. The value in this register is
pushed onto the stack.
Array elements initially have the value zero. Each level of a stacked
register has its own array associated with it. The command sequence
[first] 0:a [dummy] Sa [second] 0:a 0;a p La 0;a p
will print
since the string ‘second
’ is written in
an array that is later popped, to reveal the array that stored
‘first
’.
-
-
- #
- Skip the rest of the line. This is a non-portable
extension.
Registers
Registers have a single character name
x, where
x may be any character, including space, tab or any
other special character. If extended register mode is enabled using the
-x option and the register identifier
x has the value 255, the next two characters are
interpreted as a two-byte register index. The set of standard single character
registers and the set of extended registers do not overlap. Extended register
mode is a non-portable extension.
EXAMPLES
An example which prints the first ten values of
n!:
[la1+dsa*pla10>y]sy
0sa1
lyx
Independent of the current input base, the command
will reset the input base to decimal 10.
DIAGNOSTICS
- %c (0%o) is unimplemented
- an undefined operation was called.
- stack empty
- for not enough elements on the stack to do what was
asked.
- stack register '%c' (0%o) is
empty
- for an L operation from a stack
register that is empty.
- Runtime warning: non-zero scale in
exponent
- for a fractional part of an exponent that is being
ignored.
- divide by zero
- for trying to divide by zero.
- remainder by zero
- for trying to take a remainder by zero.
- square root of negative number
- for trying to take the square root of a negative
number.
- index too big
- for an array index that is larger than 2048.
- negative index
- for a negative array index.
- input base must be a number between 2
and 16
- for trying to set an illegal input base.
- output base must be a number greater
than 1
- for trying to set an illegal output base.
- scale must be a nonnegative
number
- for trying to set a negative or zero scale.
- scale too large
- for trying to set a scale that is too large. A scale must
be representable as a 32-bit unsigned number.
- Q command argument exceeded string
execution depth
- for trying to pop the recursion level more than the
current recursion level.
- Q command requires a number >=
1
- for trying to pop an illegal number of recursion
levels.
- recursion too deep
- for too many levels of nested execution.
The recursion level is increased by one if the x or
? operation or one of the compare operations
resulting in the execution of register is executed. As an exception, the
recursion level is not increased if the operation is executed as the last
command of a string. For example, the commands
will execute an endless loop, while the commands
will terminate because of a too deep recursion level.
- J command argument exceeded string
execution depth
- for trying to pop the recursion level more than the
current recursion level.
- mark not found
- for a failed scan for an occurrence of the
M operator.
SEE ALSO
bc(1)
STANDARDS
The arithmetic operations of the
dc utility are expected to
conform to the definition listed in the
bc(1) section of the
IEEE Std 1003.2 (“POSIX.2”) specification.
HISTORY
The
dc command first appeared in
Version 6 AT&T UNIX. A complete rewrite of
the
dc command using the
BN_new(3) big number routines
first appeared in
OpenBSD 3.5.
AUTHORS
The original version of the
dc command was written by
Robert Morris and
Lorinda
Cherry. The current version of the
dc utility was
written by
Otto Moerbeek.