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