fatbase

portable OpenBSD tools
git clone git@git.2f30.org/fatbase.git
Log | Files | Refs

dc.1 (15074B)


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