DC(1)                      OpenBSD Reference Manual                      DC(1)

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 opera-
     tions 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.  If no file argument is
             given, execution will stop after processing the expressions given
             on the command line, otherwise processing will continue with the
             contents of file.

     -x      Enable extended register mode.  This mode is used by bc(1) to al-
             low more than 256 registers.  See Registers for a more detailed
             description.

     Ordinarily, dc operates on decimal integers, but one may specify an input
     base, output base, and a number of fractional digits (scale) to be main-
     tained.  If an argument is given, input is taken from that file until its
     end, then from the standard input.  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 remain-
             dered (~), 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 max-
             imum of scales of the operands.  For division the scale of the
             result is defined by the scale set by the k operation.  For mul-
             tiplication, 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 re-
             sult 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 resul-
             tant quotient is pushed first followed by the remainder.  This is
             a shorthand for the sequence:
                   x y / x y %
             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 emp-
             ty, 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.

     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 num-
             ber 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, divi-
             sion, and exponentiation.  The interaction of scale factor, input
             base, and output base will be reasonable if all are changed to-
             gether.

     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 new-
             line.  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 fac-
             tor.  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 ex-
             ecutes 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.  Reg-
             ister 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.

     !       Interprets the rest of the line as a UNIX command.

     ?       A line of input is taken from the input source (usually the ter-
             minal) 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 com-
             mand sequence

                   [first] 0:a [dummy] Sa [second] 0:a 0;a p La 0;a p

             will print

                   second
                   first

             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 regis-
     ter 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 reg-
     ister 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

           Ai

     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 reg-
     ister 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 ille-
     gal 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 execut-
     ed.  As an exception, the recursion level is not increased if the opera-
     tion is executed as the last command of a string.  For example, the com-
     mands

           [lax]sa
           1 lax

     will execute an endless loop, while the commands

           [laxp]sa
           1 lax

     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)

     L. L. Cherry and R. Morris, "DC - An Interactive Desk Calculator",
     USD:05.

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

OpenBSD 4.7                     January 2, 2010                              5
