usr.bin/dc/dc.1

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