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