usr.bin/dc/dc.1

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