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