usr.bin/dc/dc.1

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