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