usr.bin/dc/dc.1

   1 .\"     $OpenBSD: dc.1,v 1.19 2004/10/18 07:49:00 otto Exp $
   2 .\"
   3 .\" Copyright (C) Caldera International Inc.  2001-2002.
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code and documentation must retain the above
  10 .\"    copyright notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"     This product includes software developed or owned by Caldera
  17 .\"     International, Inc.
  18 .\" 4. Neither the name of Caldera International, Inc. nor the names of other
  19 .\"    contributors may be used to endorse or promote products derived from
  20 .\"    this software without specific prior written permission.
  21 .\"
  22 .\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA
  23 .\" INTERNATIONAL, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR
  24 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  25 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  26 .\" IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE FOR ANY DIRECT,
  27 .\" INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  28 .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  29 .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  30 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  31 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
  32 .\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  33 .\" POSSIBILITY OF SUCH DAMAGE.
  34 .\"
  35 .\"     @(#)dc.1        8.1 (Berkeley) 6/6/93
  36 .\"
  37 .Dd October 10, 2004
  38 .Dt DC 1
  39 .Os
  40 .Sh NAME
  41 .Nm dc
  42 .Nd desk calculator
  43 .Sh SYNOPSIS
  44 .Nm
  45 .Op Fl x
  46 .Op Fl e Ar expression
  47 .Op Ar file
  48 .Sh DESCRIPTION
  49 .Nm
  50 is an arbitrary precision arithmetic package.
  51 The overall structure of
  52 .Nm
  53 is
  54 a stacking (reverse Polish) calculator i.e.\&
  55 numbers are stored on a stack.
  56 Adding a number pushes it onto the stack.
  57 Arithmetic operations pop arguments off the stack
  58 and push the results.
  59 See also the
  60 .Xr bc 1
  61 utility, which is a preprocessor for
  62 .Nm
  63 providing infix notation and a C-like syntax
  64 which implements functions and reasonable control
  65 structures for programs.
  66 The options are as follows:
  67 .Bl -tag -width Ds
  68 .It Fl e Ar expression
  69 Evaluate
  70 .Ar expression .
  71 If multiple
  72 .Fl e
  73 options are specified, they will be processed in the order given.
  74 If no
  75 .Ar file
  76 argument is given, execution will stop after processing the expressions
  77 given on the command line,
  78 otherwise processing will continue with the contents of
  79 .Ar file .
  80 .It Fl x
  81 Enable extended register mode.
  82 This mode is used by
  83 .Xr bc 1
  84 to allow more than 256 registers.
  85 See
  86 .Sx Registers
  87 for a more detailed description.
  88 .El
  89 .Pp
  90 Ordinarily,
  91 .Nm
  92 operates on decimal integers,
  93 but one may specify an input base, output base,
  94 and a number of fractional digits (scale) to be maintained.
  95 If an argument is given,
  96 input is taken from that file until its end,
  97 then from the standard input.
  98 Whitespace is ignored, expect where it signals the end of a number,
  99 end of a line or when a register name is expected.
 100 The following constructions are recognized:
 101 .Bl -tag -width "number"
 102 .It Va number
 103 The value of the number is pushed on the stack.
 104 A number is an unbroken string of the digits 0\-9 and letters A\-F.
 105 It may be preceded by an underscore
 106 .Pq Sq _
 107 to input a negative number.
 108 A number may contain a single decimal point.
 109 A number may also contain the characters A\-F, with the values 10\-15.
 110 .It Cm "+ - / * % ~ ^"
 111 The
 112 top two values on the stack are added
 113 (+),
 114 subtracted
 115 (\-),
 116 multiplied (*),
 117 divided (/),
 118 remaindered (%),
 119 divided and remaindered (~),
 120 or exponentiated (^).
 121 The two entries are popped off the stack;
 122 the result is pushed on the stack in their place.
 123 Any fractional part of an exponent is ignored.
 124 .Pp
 125 For addition and subtraction, the scale of the result is the maximum
 126 of scales of the operands.
 127 For division the scale of the result is defined
 128 by the scale set by the
 129 .Ic k
 130 operation.
 131 For multiplication, the scale is defined by the expression
 132 .Sy min(a+b,max(a,b,scale)) ,
 133 where
 134 .Sy a
 135 and
 136 .Sy b
 137 are the scales of the operands, and
 138 .Sy scale
 139 is the scale defined by the
 140 .Ic k
 141 operation.
 142 For exponentiation with a non-negative exponent, the scale of the result is
 143 .Sy min(a*b,max(scale,a)) ,
 144 where
 145 .Sy a
 146 is the scale of the base, and
 147 .Sy b
 148 is the
 149 .Em value
 150 of the exponent.
 151 If the exponent is negative, the scale of the result is the scale
 152 defined by the
 153 .Ic k
 154 operation.
 155 .Pp
 156 In the case of the division and modulus operator (~),
 157 the resultant quotient is pushed first followed by the remainder.
 158 This is a shorthand for the sequence:
 159 .Bd -literal -offset indent -compact
 160 x y / x y %
 161 .Ed
 162 The division and modulus operator is a non-portable extension.
 163 .It Ic a
 164 Pop the top value from the stack.
 165 If that value is a number, compute the integer part of the number modulo 256.
 166 If the result is zero, push an empty string.
 167 Otherwise push a one character string by interpreting the computed value
 168 as an
 169 .Tn ASCII
 170 character.
 171 .Pp
 172 If the top value is a string, push a string containing the first character
 173 of the original string.
 174 If the original string is empty, an empty string is pushed back.
 175 The
 176 .Ic a
 177 operator is a non-portable extension.
 178 .It Ic c
 179 All values on the stack are popped.
 180 .It Ic d
 181 The top value on the stack is duplicated.
 182 .It Ic f
 183 All values on the stack are printed, separated by newlines.
 184 .It Ic G
 185 The top two numbers are popped from the stack and compared.
 186 A one is pushed if the top of the stack is equal to the second number
 187 on the stack.
 188 A zero is pushed otherwise.
 189 This is a non-portable extension.
 190 .It Ic i
 191 The top value on the stack is popped and used as the
 192 base for further input.
 193 The initial input base is 10.
 194 .It Ic I
 195 Pushes the input base on the top of the stack.
 196 .It Ic J
 197 Pop the top value from the stack.
 198 The recursion level is popped by that value and, following that,
 199 the input is skipped until the first occurrence of the
 200 .Ic M
 201 operator.
 202 The
 203 .Ic J
 204 operator is a non-portable extension, used by the
 205 .Xr bc 1
 206 command.
 207 .It Ic K
 208 The current scale factor is pushed onto the stack.
 209 .It Ic k
 210 The top of the stack is popped, and that value is used as
 211 a non-negative scale factor:
 212 the appropriate number of places
 213 are printed on output,
 214 and maintained during multiplication, division, and exponentiation.
 215 The interaction of scale factor,
 216 input base, and output base will be reasonable if all are changed
 217 together.
 218 .It Ic L Ns Ar x
 219 Register
 220 .Ar x
 221 is treated as a stack and its top value is popped onto the main stack.
 222 .It Ic l Ns Ar x
 223 The
 224 value in register
 225 .Ar x
 226 is pushed on the stack.
 227 The register
 228 .Ar x
 229 is not altered.
 230 Initially, all registers contain the value zero.
 231 .It Ic M
 232 Mark used by the
 233 .Ic J
 234 operator.
 235 The
 236 .Ic M
 237 operator is a non-portable extensions, used by the
 238 .Xr bc 1
 239 command.
 240 .It Ic N
 241 The top of the stack is replaced by one if the top of the stack
 242 is equal to zero.
 243 If the top of the stack is unequal to zero, it is replaced by zero.
 244 This is a non-portable extension.
 245 .It Ic n
 246 The top value on the stack is popped and printed without a newline.
 247 This is a non-portable extension.
 248 .It Ic O
 249 Pushes the output base on the top of the stack.
 250 .It Ic o
 251 The top value on the stack is popped and used as the
 252 base for further output.
 253 The initial output base is 10.
 254 .It Ic P
 255 The top of the stack is popped.
 256 If the top of the stack is a string, it is printed without a trailing newline.
 257 If the top of the stack is a number, it is interpreted as a
 258 base 256 number, and each digit of this base 256 number is printed as
 259 an
 260 .Tn ASCII
 261 character, without a trailing newline.
 262 .It Ic p
 263 The top value on the stack is printed with a trailing newline.
 264 The top value remains unchanged.
 265 .It Ic Q
 266 The top value on the stack is popped and the string execution level is popped
 267 by that value.
 268 .It Ic q
 269 Exits the program.
 270 If executing a string, the recursion level is
 271 popped by two.
 272 .It Ic R
 273 The top of the stack is removed (popped).
 274 This is a non-portable extension.
 275 .It Ic r
 276 The top two values on the stack are reversed (swapped).
 277 This is a non-portable extension.
 278 .It Ic S Ns Ar x
 279 Register
 280 .Ar x
 281 is treated as a stack.
 282 The top value of the main stack is popped and pushed on it.
 283 .It Ic s Ns Ar x
 284 The
 285 top of the stack is popped and stored into
 286 a register named
 287 .Ar x .
 288 .It Ic v
 289 Replaces the top element on the stack by its square root.
 290 The scale of the result is the maximum of the scale of the argument
 291 and the current value of scale.
 292 .It Ic X
 293 Replaces the number on the top of the stack with its scale factor.
 294 If the top of the stack is a string, replace it with the integer 0.
 295 .It Ic x
 296 Treats the top element of the stack as a character string
 297 and executes it as a string of
 298 .Nm
 299 commands.
 300 .It Ic Z
 301 Replaces the number on the top of the stack with its length.
 302 The length of a string is its number of characters.
 303 The length of a number is its number of digits, not counting the minus sign
 304 and decimal point.
 305 .It Ic z
 306 The stack level is pushed onto the stack.
 307 .It Cm \&[ Ns ... Ns Cm \&]
 308 Puts the bracketed
 309 .Tn ASCII
 310 string onto the top of the stack.
 311 If the string includes brackets, these must be properly balanced.
 312 The backslash character
 313 .Pq Sq \e
 314 may be used as an escape character, making it
 315 possible to include unbalanced brackets in strings.
 316 To include a backslash in a string, use a double backslash.
 317 .It Xo
 318 .Cm < Ns Va x
 319 .Cm > Ns Va x
 320 .Cm = Ns Va x
 321 .Cm !< Ns Va x
 322 .Cm !> Ns Va x
 323 .Cm != Ns Va x
 324 .Xc
 325 The top two elements of the stack are popped and compared.
 326 Register
 327 .Ar x
 328 is executed if they obey the stated
 329 relation.
 330 .It Xo
 331 .Cm < Ns Va x Ns e Ns Va y
 332 .Cm > Ns Va x Ns e Ns Va y
 333 .Cm = Ns Va x Ns e Ns Va y
 334 .Cm !< Ns Va x Ns e Ns Va y
 335 .Cm !> Ns Va x Ns e Ns Va y
 336 .Cm != Ns Va x Ns e Ns Va y
 337 .Xc
 338 These operations are variants of the comparison operations above.
 339 The first register name is followed by the letter
 340 .Sq e
 341 and another register name.
 342 Register
 343 .Ar x
 344 will be executed if the relation is true, and register
 345 .Ar y
 346 will be executed if the relation is false.
 347 This is a non-portable extension.
 348 .It Ic \&(
 349 The top two numbers are popped from the stack and compared.
 350 A one is pushed if the top of the stack is less than the second number
 351 on the stack.
 352 A zero is pushed otherwise.
 353 This is a non-portable extension.
 354 .It Ic {
 355 The top two numbers are popped from the stack and compared.
 356 A one is pushed if the top of stack is less than or equal to the
 357 second number on the stack.
 358 A zero is pushed otherwise.
 359 This is a non-portable extension.
 360 .It Ic \&!
 361 Interprets the rest of the line as a
 362 .Ux
 363 command.
 364 .It Ic \&?
 365 A line of input is taken from the input source (usually the terminal)
 366 and executed.
 367 .It Ic \&: Ns Ar r
 368 Pop two values from the stack.
 369 The second value on the stack is stored into the array
 370 .Ar r
 371 indexed by the top of stack.
 372 .It Ic \&; Ns Ar r
 373 Pop a value from the stack.
 374 The value is used as an index into register
 375 .Ar r .
 376 The value in this register is pushed onto the stack.
 377 .Pp
 378 Array elements initially have the value zero.
 379 Each level of a stacked register has its own array associated with
 380 it.
 381 The command sequence
 382 .Bd -literal -offset indent
 383 [first] 0:a [dummy] Sa [second] 0:a 0;a p La 0;a p
 384 .Ed
 385 .Pp
 386 will print
 387 .Bd -literal -offset indent
 388 second
 389 first
 390 .Ed
 391 .Pp
 392 since the string
 393 .Ql second
 394 is written in an array that is later popped, to reveal the array that
 395 stored
 396 .Ql first .
 397 .It Ic #
 398 Skip the rest of the line.
 399 This is a non-portable extension.
 400 .El
 401 .Ss Registers
 402 Registers have a single character name
 403 .Ar x ,
 404 where
 405 .Ar x
 406 may be any character, including space, tab or any other special character.
 407 If extended register mode is enabled using the
 408 .Fl x
 409 option and the register identifier
 410 .Ar x
 411 has the value 255, the next two characters are interpreted as a
 412 two-byte register index.
 413 The set of standard single character registers and the set of extended
 414 registers do not overlap.
 415 Extended register mode is a non-portable extension.
 416 .Sh EXAMPLES
 417 An example which prints the first ten values of
 418 .Ic n! :
 419 .Bd -literal -offset indent
 420 [la1+dsa*pla10>y]sy
 421 0sa1
 422 lyx
 423 .Ed
 424 .Pp
 425 Independent of the current input base, the command
 426 .Bd -literal -offset indent
 427 Ai
 428 .Ed
 429 .Pp
 430 will reset the input base to decimal 10.
 431 .Sh DIAGNOSTICS
 432 .Bl -diag
 433 .It %c (0%o) is unimplemented
 434 an undefined operation was called.
 435 .It stack empty
 436 for not enough elements on the stack to do what was asked.
 437 .It stack register '%c' (0%o) is empty
 438 for an
 439 .Ar L
 440 operation from a stack register that is empty.
 441 .It Runtime warning: non-zero scale in exponent
 442 for a fractional part of an exponent that is being ignored.
 443 .It divide by zero
 444 for trying to divide by zero.
 445 .It remainder by zero
 446 for trying to take a remainder by zero.
 447 .It square root of negative number
 448 for trying to take the square root of a negative number.
 449 .It index too big
 450 for an array index that is larger than 2048.
 451 .It negative index
 452 for a negative array index.
 453 .It "input base must be a number between 2 and 16"
 454 for trying to set an illegal input base.
 455 .It output base must be a number greater than 1
 456 for trying to set an illegal output base.
 457 .It scale must be a nonnegative number
 458 for trying to set a negative or zero scale.
 459 .It scale too large
 460 for trying to set a scale that is too large.
 461 A scale must be representable as a 32-bit unsigned number.
 462 .It Q command argument exceeded string execution depth
 463 for trying to pop the recursion level more than the current
 464 recursion level.
 465 .It Q command requires a number >= 1
 466 for trying to pop an illegal number of recursion levels.
 467 .It recursion too deep
 468 for too many levels of nested execution.
 469 .Pp
 470 The recursion level is increased by one if the
 471 .Ar x
 472 or
 473 .Ar ?\&
 474 operation or one of the compare operations resulting in the execution
 475 of register is executed.
 476 As an exception, the recursion level is not increased if the operation
 477 is executed as the last command of a string.
 478 For example, the commands
 479 .Bd -literal -offset indent
 480 [lax]sa
 481 1 lax
 482 .Ed
 483 .Pp
 484 will execute an endless loop, while the commands
 485 .Bd -literal -offset indent
 486 [laxp]sa
 487 1 lax
 488 .Ed
 489 .Pp
 490 will terminate because of a too deep recursion level.
 491 .It J command argument exceeded string execution depth
 492 for trying to pop the recursion level more than the current
 493 recursion level.
 494 .It mark not found
 495 for a failed scan for an occurrence of the
 496 .Ic M
 497 operator.
 498 .El
 499 .Sh SEE ALSO
 500 .Xr bc 1
 501 .Rs
 502 .%B USD:05
 503 .%A L. L. Cherry
 504 .%A R. Morris
 505 .%T "DC \- An Interactive Desk Calculator"
 506 .Re
 507 .Sh STANDARDS
 508 The arithmetic operations of the
 509 .Nm
 510 utility are expected to conform to the definition listed in the
 511 .Xr bc 1
 512 section of the
 513 .St -p1003.2
 514 specification.
 515 .Sh HISTORY
 516 The
 517 .Nm
 518 command first appeared in
 519 .At v6 .
 520 A complete rewrite of the
 521 .Nm
 522 command using the
 523 .Xr bn 3
 524 big number routines first appeared in
 525 .Ox 3.5 .
 526 .Sh AUTHORS
 527 .An -nosplit
 528 The original version of the
 529 .Nm
 530 command was written by
 531 .An Robert Morris
 532 and
 533 .An Lorinda Cherry .
 534 The current version of the
 535 .Nm
 536 utility was written by
 537 .An Otto Moerbeek .