1.\" $NetBSD: dc.1,v 1.2 2017/04/10 16:37:48 christos Exp $ 2.\" $OpenBSD: dc.1,v 1.30 2017/02/23 06:40:17 otto 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 February 23, 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 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 e 190Equivalent to 191.Ic p , 192except that the output is written to the standard error stream. 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 \&? 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.Sh STANDARDS 509The arithmetic operations of the 510.Nm 511utility are expected to conform to the definition listed in the 512.Xr bc 1 513section of the 514.St -p1003.2 515specification. 516.Sh HISTORY 517The 518.Nm 519command first appeared in 520.At v6 . 521A complete rewrite of the 522.Nm 523command using the 524.Xr BN_new 3 525big number routines first appeared in 526.Ox 3.5 . 527.Sh AUTHORS 528.An -nosplit 529The original version of the 530.Nm 531command was written by 532.An Robert Morris 533and 534.An Lorinda Cherry . 535The current version of the 536.Nm 537utility was written by 538.An Otto Moerbeek . 539