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