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