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