1.\" $FreeBSD$ 2.\" $OpenBSD: dc.1,v 1.24 2010/01/02 19:48:56 schwarze 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 January 22, 2010 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. 76If no 77.Ar filename 78argument is given, execution will stop after processing the expressions 79given on the command line, 80otherwise processing will continue with the contents of 81.Ar filename . 82.It Fl f Ar filename , Fl Fl file Ar filename 83Process the content of the given file before further calculations are done. 84If multiple 85.Fl f 86options are specified, they will be processed in the order given. 87.It Fl h , Fl Fl help 88Print short usage info. 89.It Fl V , Fl Fl version 90Print version info. 91.It Fl x 92Enable extended register mode. 93This mode is used by 94.Xr bc 1 95to allow more than 256 registers. 96See 97.Sx Registers 98for a more detailed description. 99.El 100.Pp 101Ordinarily, 102.Nm 103operates on decimal integers, 104but one may specify an input base, output base, 105and a number of fractional digits (scale) to be maintained. 106If an argument is given, 107input is taken from that file until its end, 108then from the standard input. 109Whitespace is ignored, except where it signals the end of a number, 110end of a line or when a register name is expected. 111The following constructions are recognized: 112.Bl -tag -width "number" 113.It Va number 114The value of the number is pushed on the stack. 115A number is an unbroken string of the digits 0\-9 and letters A\-F. 116It may be preceded by an underscore 117.Pq Sq _ 118to input a negative number. 119A number may contain a single decimal point. 120A number may also contain the characters A\-F, with the values 10\-15. 121.It Cm "+ - / * % ~ ^" 122The 123top two values on the stack are added 124(+), 125subtracted 126(\-), 127multiplied (*), 128divided (/), 129remaindered (%), 130divided and remaindered (~), 131or exponentiated (^). 132The two entries are popped off the stack; 133the result is pushed on the stack in their place. 134Any fractional part of an exponent is ignored. 135.Pp 136For addition and subtraction, the scale of the result is the maximum 137of scales of the operands. 138For division the scale of the result is defined 139by the scale set by the 140.Ic k 141operation. 142For multiplication, the scale is defined by the expression 143.Sy min(a+b,max(a,b,scale)) , 144where 145.Sy a 146and 147.Sy b 148are the scales of the operands, and 149.Sy scale 150is the scale defined by the 151.Ic k 152operation. 153For exponentiation with a non-negative exponent, the scale of the result is 154.Sy min(a*b,max(scale,a)) , 155where 156.Sy a 157is the scale of the base, and 158.Sy b 159is the 160.Em value 161of the exponent. 162If the exponent is negative, the scale of the result is the scale 163defined by the 164.Ic k 165operation. 166.Pp 167In the case of the division and modulus operator (~), 168the resultant quotient is pushed first followed by the remainder. 169This is a shorthand for the sequence: 170.Bd -literal -offset indent -compact 171x y / x y % 172.Ed 173The division and modulus operator is a non-portable extension. 174.It Ic a 175Pop the top value from the stack. 176If that value is a number, compute the integer part of the number modulo 256. 177If the result is zero, push an empty string. 178Otherwise push a one character string by interpreting the computed value 179as an 180.Tn ASCII 181character. 182.Pp 183If the top value is a string, push a string containing the first character 184of the original string. 185If the original string is empty, an empty string is pushed back. 186The 187.Ic a 188operator is a non-portable extension. 189.It Ic c 190All values on the stack are popped. 191.It Ic d 192The top value on the stack is duplicated. 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 extensions, 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. 316.It Ic z 317The stack level is pushed onto the stack. 318.It Cm \&[ Ns ... Ns Cm \&] 319Puts the bracketed 320.Tn ASCII 321string onto the top of the stack. 322If the string includes brackets, these must be properly balanced. 323The backslash character 324.Pq Sq \e 325may be used as an escape character, making it 326possible to include unbalanced brackets in strings. 327To include a backslash in a string, use a double backslash. 328.It Xo 329.Cm < Ns Va x 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.Xc 336The top two elements of the stack are popped and compared. 337Register 338.Ar x 339is executed if they obey the stated 340relation. 341.It Xo 342.Cm < Ns Va x Ns e Ns Va y 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.Xc 349These operations are variants of the comparison operations above. 350The first register name is followed by the letter 351.Sq e 352and another register name. 353Register 354.Ar x 355will be executed if the relation is true, and register 356.Ar y 357will be executed if the relation is false. 358This is a non-portable extension. 359.It Ic \&( 360The top two numbers are popped from the stack and compared. 361A one is pushed if the top of the stack is less than the second number 362on the stack. 363A zero is pushed otherwise. 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 stack is less than or equal to the 368second number on the stack. 369A zero is pushed otherwise. 370This is a non-portable extension. 371.It Ic \&! 372Interprets the rest of the line as a 373.Ux 374command. 375.It Ic \&? 376A line of input is taken from the input source (usually the terminal) 377and executed. 378.It Ic \&: Ns Ar r 379Pop two values from the stack. 380The second value on the stack is stored into the array 381.Ar r 382indexed by the top of stack. 383.It Ic \&; Ns Ar r 384Pop a value from the stack. 385The value is used as an index into register 386.Ar r . 387The value in this register is pushed onto the stack. 388.Pp 389Array elements initially have the value zero. 390Each level of a stacked register has its own array associated with 391it. 392The command sequence 393.Bd -literal -offset indent 394[first] 0:a [dummy] Sa [second] 0:a 0;a p La 0;a p 395.Ed 396.Pp 397will print 398.Bd -literal -offset indent 399second 400first 401.Ed 402.Pp 403since the string 404.Ql second 405is written in an array that is later popped, to reveal the array that 406stored 407.Ql first . 408.It Ic # 409Skip the rest of the line. 410This is a non-portable extension. 411.El 412.Ss Registers 413Registers have a single character name 414.Ar x , 415where 416.Ar x 417may be any character, including space, tab or any other special character. 418If extended register mode is enabled using the 419.Fl x 420option and the register identifier 421.Ar x 422has the value 255, the next two characters are interpreted as a 423two-byte register index. 424The set of standard single character registers and the set of extended 425registers do not overlap. 426Extended register mode is a non-portable extension. 427.Sh EXAMPLES 428An example which prints the first ten values of 429.Ic n! : 430.Bd -literal -offset indent 431[la1+dsa*pla10>y]sy 4320sa1 433lyx 434.Ed 435.Pp 436Independent of the current input base, the command 437.Bd -literal -offset indent 438Ai 439.Ed 440.Pp 441will reset the input base to decimal 10. 442.Sh DIAGNOSTICS 443.Bl -diag 444.It %c (0%o) is unimplemented 445an undefined operation was called. 446.It stack empty 447for not enough elements on the stack to do what was asked. 448.It stack register '%c' (0%o) is empty 449for an 450.Ar L 451operation from a stack register that is empty. 452.It Runtime warning: non-zero scale in exponent 453for a fractional part of an exponent that is being ignored. 454.It divide by zero 455for trying to divide by zero. 456.It remainder by zero 457for trying to take a remainder by zero. 458.It square root of negative number 459for trying to take the square root of a negative number. 460.It index too big 461for an array index that is larger than 2048. 462.It negative index 463for a negative array index. 464.It "input base must be a number between 2 and 16" 465for trying to set an illegal input base. 466.It output base must be a number greater than 1 467for trying to set an illegal output base. 468.It scale must be a nonnegative number 469for trying to set a negative or zero scale. 470.It scale too large 471for trying to set a scale that is too large. 472A scale must be representable as a 32-bit unsigned number. 473.It Q command argument exceeded string execution depth 474for trying to pop the recursion level more than the current 475recursion level. 476.It Q command requires a number >= 1 477for trying to pop an illegal number of recursion levels. 478.It recursion too deep 479for too many levels of nested execution. 480.Pp 481The recursion level is increased by one if the 482.Ar x 483or 484.Ar ?\& 485operation or one of the compare operations resulting in the execution 486of register is executed. 487As an exception, the recursion level is not increased if the operation 488is executed as the last command of a string. 489For example, the commands 490.Bd -literal -offset indent 491[lax]sa 4921 lax 493.Ed 494.Pp 495will execute an endless loop, while the commands 496.Bd -literal -offset indent 497[laxp]sa 4981 lax 499.Ed 500.Pp 501will terminate because of a too deep recursion level. 502.It J command argument exceeded string execution depth 503for trying to pop the recursion level more than the current 504recursion level. 505.It mark not found 506for a failed scan for an occurrence of the 507.Ic M 508operator. 509.El 510.Sh SEE ALSO 511.Xr bc 1 512.Pp 513.An -nosplit 514.An L. L. Cherry , 515.An R. Morris 516"DC \- An Interactive Desk Calculator" 517.Pa /usr/share/doc/usd/05.dc/ . 518.Sh STANDARDS 519The arithmetic operations of the 520.Nm 521utility are expected to conform to the definition listed in the 522.Xr bc 1 523section of the 524.St -p1003.2 525specification. 526.Sh HISTORY 527The 528.Nm 529command first appeared in 530.At v6 . 531A complete rewrite of the 532.Nm 533command using the 534.Xr bn 3 535big number routines first appeared in 536.Ox 3.5 . 537.Sh AUTHORS 538.An -nosplit 539The original version of the 540.Nm 541command was written by 542.An Robert Morris 543and 544.An Lorinda Cherry . 545The current version of the 546.Nm 547utility was written by 548.An Otto Moerbeek . 549