usr.bin/dc/dc.1

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