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