1.\" $OpenBSD: dc.1,v 1.35 2021/03/08 02:47:27 jsg 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: March 8 2021 $ 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 e 189Equivalent to 190.Ic p , 191except that the output is written to the standard error stream. 192This is a non-portable extension. 193.It Ic f 194All values on the stack are printed, separated by newlines. 195.It Ic G 196The top two numbers are popped from the stack and compared. 197A one is pushed if the top of the stack is equal to the second number 198on the stack. 199A zero is pushed otherwise. 200This is a non-portable extension. 201.It Ic I 202Pushes the input base on the top of the stack. 203.It Ic i 204The top value on the stack is popped and used as the 205base for further input. 206The initial input base is 10. 207.It Ic J 208Pop the top value from the stack. 209The recursion level is popped by that value and, following that, 210the input is skipped until the first occurrence of the 211.Ic M 212operator. 213The 214.Ic J 215operator is a non-portable extension, used by the 216.Xr bc 1 217command. 218.It Ic K 219The current scale factor is pushed onto the stack. 220.It Ic k 221The top of the stack is popped, and that value is used as 222a non-negative scale factor: 223the appropriate number of places 224are printed on output, 225and maintained during multiplication, division, and exponentiation. 226The interaction of scale factor, 227input base, and output base will be reasonable if all are changed 228together. 229.It Ic L Ns Ar x 230Register 231.Ar x 232is treated as a stack and its top value is popped onto the main stack. 233.It Ic l Ns Ar x 234The 235value in register 236.Ar x 237is pushed on the stack. 238The register 239.Ar x 240is not altered. 241Initially, all registers contain the value zero. 242.It Ic M 243Mark used by the 244.Ic J 245operator. 246The 247.Ic M 248operator is a non-portable extension, used by the 249.Xr bc 1 250command. 251.It Ic N 252The top of the stack is replaced by one if the top of the stack 253is equal to zero. 254If the top of the stack is unequal to zero, it is replaced by zero. 255This is a non-portable extension. 256.It Ic n 257The top value on the stack is popped and printed without a newline. 258This is a non-portable extension. 259.It Ic O 260Pushes the output base on the top of the stack. 261.It Ic o 262The top value on the stack is popped and used as the 263base for further output. 264The initial output base is 10. 265.It Ic P 266The top of the stack is popped. 267If the top of the stack is a string, it is printed without a trailing newline. 268If the top of the stack is a number, it is interpreted as a 269base 256 number, and each digit of this base 256 number is printed as 270an 271.Tn ASCII 272character, without a trailing newline. 273.It Ic p 274The top value on the stack is printed with a trailing newline. 275The top value remains unchanged. 276.It Ic Q 277The top value on the stack is popped and the string execution level is popped 278by that value. 279.It Ic q 280Exits the program. 281If executing a string, the recursion level is 282popped by two. 283.It Ic R 284The top of the stack is removed (popped). 285This is a non-portable extension. 286.It Ic r 287The top two values on the stack are reversed (swapped). 288This is a non-portable extension. 289.It Ic S Ns Ar x 290Register 291.Ar x 292is treated as a stack. 293The top value of the main stack is popped and pushed on it. 294.It Ic s Ns Ar x 295The 296top of the stack is popped and stored into 297a register named 298.Ar x . 299.It Ic v 300Replaces the top element on the stack by its square root. 301The scale of the result is the maximum of the scale of the argument 302and the current value of scale. 303.It Ic X 304Replaces the number on the top of the stack with its scale factor. 305If the top of the stack is a string, replace it with the integer 0. 306.It Ic x 307Treats the top element of the stack as a character string 308and executes it as a string of 309.Nm 310commands. 311.It Ic Z 312Replaces the number on the top of the stack with its length. 313The length of a string is its number of characters. 314The length of a number is its number of digits, not counting the minus sign 315and decimal point. 316The length of a zero value is its scale. 317.It Ic z 318The stack level is pushed onto the stack. 319.It Cm \&[ Ns ... Ns Cm \&] 320Puts the bracketed 321.Tn ASCII 322string onto the top of the stack. 323If the string includes brackets, these must be properly balanced. 324The backslash character 325.Pq Sq \e 326may be used as an escape character, making it 327possible to include unbalanced brackets in strings. 328To include a backslash in a string, use a double backslash. 329.It Xo 330.Cm < Ns Va x 331.Cm > Ns Va x 332.Cm = Ns Va x 333.Cm !< Ns Va x 334.Cm !> Ns Va x 335.Cm != Ns Va x 336.Xc 337The top two elements of the stack are popped and compared. 338Register 339.Ar x 340is executed if they obey the stated 341relation. 342.It Xo 343.Cm < Ns Va x Ns e Ns Va y 344.Cm > Ns Va x Ns e Ns Va y 345.Cm = Ns Va x Ns e Ns Va y 346.Cm !< Ns Va x Ns e Ns Va y 347.Cm !> Ns Va x Ns e Ns Va y 348.Cm != Ns Va x Ns e Ns Va y 349.Xc 350These operations are variants of the comparison operations above. 351The first register name is followed by the letter 352.Sq e 353and another register name. 354Register 355.Ar x 356will be executed if the relation is true, and register 357.Ar y 358will be executed if the relation is false. 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 the stack is less than the second number 363on the stack. 364A zero is pushed otherwise. 365This is a non-portable extension. 366.It Ic { 367The top two numbers are popped from the stack and compared. 368A one is pushed if the top of stack is less than or equal to the 369second number on the stack. 370A zero is pushed otherwise. 371This is a non-portable extension. 372.It Ic \&? 373A line of input is taken from the input source (usually the terminal) 374and executed. 375.It Ic \&: Ns Ar r 376Pop two values from the stack. 377The second value on the stack is stored into the array 378.Ar r 379indexed by the top of stack. 380.It Ic \&; Ns Ar r 381Pop a value from the stack. 382The value is used as an index into register 383.Ar r . 384The value in this register is pushed onto the stack. 385.Pp 386Array elements initially have the value zero. 387Each level of a stacked register has its own array associated with 388it. 389The command sequence 390.Bd -literal -offset indent 391[first] 0:a [dummy] Sa [second] 0:a 0;a p La 0;a p 392.Ed 393.Pp 394will print 395.Bd -literal -offset indent 396second 397first 398.Ed 399.Pp 400since the string 401.Ql second 402is written in an array that is later popped, to reveal the array that 403stored 404.Ql first . 405.It Ic # 406Skip the rest of the line. 407This is a non-portable extension. 408.El 409.Ss Registers 410Registers have a single character name 411.Ar x , 412where 413.Ar x 414may be any character, including space, tab or any other special character. 415If extended register mode is enabled using the 416.Fl x 417option and the register identifier 418.Ar x 419has the value 255, the next two characters are interpreted as a 420two-byte register index. 421The set of standard single character registers and the set of extended 422registers do not overlap. 423Extended register mode is a non-portable extension. 424.Sh EXAMPLES 425An example which prints the first ten values of 426.Ic n! : 427.Bd -literal -offset indent 428[la1+dsa*pla10>y]sy 4290sa1 430lyx 431.Ed 432.Pp 433Independent of the current input base, the command 434.Bd -literal -offset indent 435Ai 436.Ed 437.Pp 438will reset the input base to decimal 10. 439.Sh DIAGNOSTICS 440.Bl -diag 441.It %c (0%o) is unimplemented 442an undefined operation was called. 443.It stack empty 444for not enough elements on the stack to do what was asked. 445.It stack register '%c' (0%o) is empty 446for an 447.Ar L 448operation from a stack register that is empty. 449.It Runtime warning: non-zero scale in exponent 450for a fractional part of an exponent that is being ignored. 451.It divide by zero 452for trying to divide by zero. 453.It remainder by zero 454for trying to take a remainder by zero. 455.It square root of negative number 456for trying to take the square root of a negative number. 457.It index too big 458for an array index that is larger than 2048. 459.It negative index 460for a negative array index. 461.It "input base must be a number between 2 and 16" 462for trying to set an illegal input base. 463.It output base must be a number greater than 1 464for trying to set an illegal output base. 465.It scale must be a nonnegative number 466for trying to set a negative or zero scale. 467.It scale too large 468for trying to set a scale that is too large. 469A scale must be representable as a 32-bit unsigned number. 470.It Q command argument exceeded string execution depth 471for trying to pop the recursion level more than the current 472recursion level. 473.It Q command requires a number >= 1 474for trying to pop an illegal number of recursion levels. 475.It recursion too deep 476for too many levels of nested execution. 477.Pp 478The recursion level is increased by one if the 479.Ar x 480or 481.Ar ?\& 482operation or one of the compare operations resulting in the execution 483of register is executed. 484As an exception, the recursion level is not increased if the operation 485is executed as the last command of a string. 486For example, the commands 487.Bd -literal -offset indent 488[lax]sa 4891 lax 490.Ed 491.Pp 492will execute an endless loop, while the commands 493.Bd -literal -offset indent 494[laxp]sa 4951 lax 496.Ed 497.Pp 498will terminate because of a too deep recursion level. 499.It J command argument exceeded string execution depth 500for trying to pop the recursion level more than the current 501recursion level. 502.It mark not found 503for a failed scan for an occurrence of the 504.Ic M 505operator. 506.El 507.Sh SEE ALSO 508.Xr bc 1 509.Rs 510.\" 4.4BSD USD:5 511.%A R. H. Morris 512.%A L. L. Cherry 513.%T DC \(em An Interactive Desk Calculator 514.Re 515.Sh STANDARDS 516The arithmetic operations of the 517.Nm 518utility are expected to conform to the definition listed in the 519.Xr bc 1 520section of the 521.St -p1003.2 522specification. 523.Sh HISTORY 524The 525.Nm 526command appeared in 527.At v1 . 528A complete rewrite of the 529.Nm 530command using the 531.Xr BN_new 3 532big number routines first appeared in 533.Ox 3.5 . 534.Sh AUTHORS 535.An -nosplit 536The original version of the 537.Nm 538command was written by 539.An Robert Morris 540and 541.An Lorinda Cherry . 542The current version of the 543.Nm 544utility was written by 545.An Otto Moerbeek . 546.Sh CAVEATS 547While fractional input in base 10 is always exact, 548other bases may suffer from unintuitive rounding. 549To avoid surprising results, plain integer division can be used 550instead of the corresponding floating point notation. 551