Annotation of src/usr.bin/dc/dc.1, Revision 1.35
1.35 ! jsg 1: .\" $OpenBSD: dc.1,v 1.34 2019/09/06 19:25:08 schwarze Exp $
1.1 otto 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: .\"
1.35 ! jsg 37: .Dd $Mdocdate: September 6 2019 $
1.1 otto 38: .Dt DC 1
1.24 schwarze 39: .Os
1.1 otto 40: .Sh NAME
41: .Nm dc
42: .Nd desk calculator
43: .Sh SYNOPSIS
44: .Nm
1.18 otto 45: .Op Fl x
1.19 otto 46: .Op Fl e Ar expression
1.2 jmc 47: .Op Ar file
1.1 otto 48: .Sh DESCRIPTION
49: .Nm
50: is an arbitrary precision arithmetic package.
51: The overall structure of
52: .Nm
53: is
1.2 jmc 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.
1.18 otto 66: The options are as follows:
67: .Bl -tag -width Ds
1.19 otto 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.
1.18 otto 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
1.2 jmc 83: .Pp
1.27 jmc 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
1.2 jmc 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.
1.21 kjell 104: Whitespace is ignored, except where it signals the end of a number,
1.1 otto 105: end of a line or when a register name is expected.
106: The following constructions are recognized:
1.2 jmc 107: .Bl -tag -width "number"
1.1 otto 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.
1.2 jmc 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.
1.1 otto 115: A number may also contain the characters A\-F, with the values 10\-15.
1.7 otto 116: .It Cm "+ - / * % ~ ^"
1.1 otto 117: The
118: top two values on the stack are added
119: (+),
120: subtracted
121: (\-),
122: multiplied (*),
123: divided (/),
124: remaindered (%),
1.7 otto 125: divided and remaindered (~),
1.1 otto 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
1.8 otto 135: .Ic k
1.1 otto 136: operation.
1.2 jmc 137: For multiplication, the scale is defined by the expression
138: .Sy min(a+b,max(a,b,scale)) ,
1.1 otto 139: where
140: .Sy a
141: and
142: .Sy b
143: are the scales of the operands, and
144: .Sy scale
1.2 jmc 145: is the scale defined by the
1.8 otto 146: .Ic k
1.1 otto 147: operation.
1.11 jmc 148: For exponentiation with a non-negative exponent, the scale of the result is
1.2 jmc 149: .Sy min(a*b,max(scale,a)) ,
1.1 otto 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
1.8 otto 159: .Ic k
1.1 otto 160: operation.
1.7 otto 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.
1.15 otto 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.
1.10 otto 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.
1.30 otto 188: .It Ic e
189: Equivalent to
190: .Ic p ,
191: except that the output is written to the standard error stream.
1.31 otto 192: This is a non-portable extension.
1.10 otto 193: .It Ic f
194: All values on the stack are printed, separated by newlines.
1.16 otto 195: .It Ic G
196: The top two numbers are popped from the stack and compared.
197: A one is pushed if the top of the stack is equal to the second number
198: on the stack.
199: A zero is pushed otherwise.
200: This is a non-portable extension.
1.22 jmc 201: .It Ic I
202: Pushes the input base on the top of the stack.
1.10 otto 203: .It Ic i
204: The top value on the stack is popped and used as the
205: base for further input.
206: The initial input base is 10.
207: .It Ic J
1.15 otto 208: Pop the top value from the stack.
1.10 otto 209: The recursion level is popped by that value and, following that,
210: the input is skipped until the first occurrence of the
211: .Ic M
212: operator.
1.1 otto 213: The
1.10 otto 214: .Ic J
1.15 otto 215: operator is a non-portable extension, used by the
1.10 otto 216: .Xr bc 1
217: command.
218: .It Ic K
219: The current scale factor is pushed onto the stack.
220: .It Ic k
221: The top of the stack is popped, and that value is used as
222: a non-negative scale factor:
223: the appropriate number of places
224: are printed on output,
225: and maintained during multiplication, division, and exponentiation.
226: The interaction of scale factor,
227: input base, and output base will be reasonable if all are changed
228: together.
229: .It Ic L Ns Ar x
230: Register
1.1 otto 231: .Ar x
1.10 otto 232: is treated as a stack and its top value is popped onto the main stack.
1.1 otto 233: .It Ic l Ns Ar x
234: The
235: value in register
236: .Ar x
237: is pushed on the stack.
238: The register
239: .Ar x
240: is not altered.
1.4 otto 241: Initially, all registers contain the value zero.
1.10 otto 242: .It Ic M
243: Mark used by the
244: .Ic J
245: operator.
246: The
247: .Ic M
1.32 otto 248: operator is a non-portable extension, used by the
1.10 otto 249: .Xr bc 1
250: command.
1.16 otto 251: .It Ic N
252: The top of the stack is replaced by one if the top of the stack
253: is equal to zero.
254: If the top of the stack is unequal to zero, it is replaced by zero.
255: This is a non-portable extension.
1.15 otto 256: .It Ic n
257: The top value on the stack is popped and printed without a newline.
258: This is a non-portable extension.
1.10 otto 259: .It Ic O
260: Pushes the output base on the top of the stack.
261: .It Ic o
262: The top value on the stack is popped and used as the
263: base for further output.
264: The initial output base is 10.
1.1 otto 265: .It Ic P
266: The top of the stack is popped.
1.2 jmc 267: If the top of the stack is a string, it is printed without a trailing newline.
1.1 otto 268: If the top of the stack is a number, it is interpreted as a
269: base 256 number, and each digit of this base 256 number is printed as
270: an
271: .Tn ASCII
272: character, without a trailing newline.
1.10 otto 273: .It Ic p
274: The top value on the stack is printed with a trailing newline.
275: The top value remains unchanged.
276: .It Ic Q
277: The top value on the stack is popped and the string execution level is popped
278: by that value.
1.1 otto 279: .It Ic q
280: Exits the program.
281: If executing a string, the recursion level is
282: popped by two.
1.17 otto 283: .It Ic R
284: The top of the stack is removed (popped).
285: This is a non-portable extension.
1.14 otto 286: .It Ic r
287: The top two values on the stack are reversed (swapped).
288: This is a non-portable extension.
1.10 otto 289: .It Ic S Ns Ar x
290: Register
291: .Ar x
292: is treated as a stack.
293: The top value of the main stack is popped and pushed on it.
294: .It Ic s Ns Ar x
295: The
296: top of the stack is popped and stored into
297: a register named
1.18 otto 298: .Ar x .
1.10 otto 299: .It Ic v
300: Replaces the top element on the stack by its square root.
301: The scale of the result is the maximum of the scale of the argument
302: and the current value of scale.
303: .It Ic X
304: Replaces the number on the top of the stack with its scale factor.
305: If the top of the stack is a string, replace it with the integer 0.
1.1 otto 306: .It Ic x
307: Treats the top element of the stack as a character string
308: and executes it as a string of
309: .Nm
310: commands.
1.10 otto 311: .It Ic Z
312: Replaces the number on the top of the stack with its length.
313: The length of a string is its number of characters.
314: The length of a number is its number of digits, not counting the minus sign
315: and decimal point.
1.33 otto 316: The length of a zero value is its scale.
1.10 otto 317: .It Ic z
318: The stack level is pushed onto the stack.
1.25 jmc 319: .It Cm \&[ Ns ... Ns Cm \&]
1.1 otto 320: Puts the bracketed
321: .Tn ASCII
322: string onto the top of the stack.
1.5 otto 323: If the string includes brackets, these must be properly balanced.
1.6 jmc 324: The backslash character
325: .Pq Sq \e
326: may be used as an escape character, making it
1.5 otto 327: possible to include unbalanced brackets in strings.
1.6 jmc 328: To include a backslash in a string, use a double backslash.
1.1 otto 329: .It Xo
330: .Cm < Ns Va x
331: .Cm > Ns Va x
332: .Cm = Ns Va x
333: .Cm !< Ns Va x
334: .Cm !> Ns Va x
335: .Cm != Ns Va x
336: .Xc
337: The top two elements of the stack are popped and compared.
338: Register
339: .Ar x
340: is executed if they obey the stated
341: relation.
1.12 otto 342: .It Xo
343: .Cm < Ns Va x Ns e Ns Va y
344: .Cm > Ns Va x Ns e Ns Va y
345: .Cm = Ns Va x Ns e Ns Va y
346: .Cm !< Ns Va x Ns e Ns Va y
347: .Cm !> Ns Va x Ns e Ns Va y
348: .Cm != Ns Va x Ns e Ns Va y
349: .Xc
350: These operations are variants of the comparison operations above.
351: The first register name is followed by the letter
352: .Sq e
353: and another register name.
354: Register
355: .Ar x
356: will be executed if the relation is true, and register
357: .Ar y
358: will be executed if the relation is false.
359: This is a non-portable extension.
1.16 otto 360: .It Ic \&(
361: The top two numbers are popped from the stack and compared.
362: A one is pushed if the top of the stack is less than the second number
363: on the stack.
364: A zero is pushed otherwise.
365: This is a non-portable extension.
366: .It Ic {
367: The top two numbers are popped from the stack and compared.
368: A one is pushed if the top of stack is less than or equal to the
369: second number on the stack.
370: A zero is pushed otherwise.
371: This is a non-portable extension.
1.2 jmc 372: .It Ic \&?
1.1 otto 373: A line of input is taken from the input source (usually the terminal)
374: and executed.
1.25 jmc 375: .It Ic \&: Ns Ar r
1.2 jmc 376: Pop two values from the stack.
377: The second value on the stack is stored into the array
1.1 otto 378: .Ar r
379: indexed by the top of stack.
1.25 jmc 380: .It Ic \&; Ns Ar r
1.2 jmc 381: Pop a value from the stack.
382: The value is used as an index into register
1.1 otto 383: .Ar r .
384: The value in this register is pushed onto the stack.
385: .Pp
1.2 jmc 386: Array elements initially have the value zero.
1.1 otto 387: Each level of a stacked register has its own array associated with
388: it.
389: The command sequence
1.2 jmc 390: .Bd -literal -offset indent
1.1 otto 391: [first] 0:a [dummy] Sa [second] 0:a 0;a p La 0;a p
392: .Ed
393: .Pp
394: will print
1.2 jmc 395: .Bd -literal -offset indent
1.1 otto 396: second
397: first
398: .Ed
399: .Pp
400: since the string
401: .Ql second
402: is written in an array that is later popped, to reveal the array that
403: stored
404: .Ql first .
1.15 otto 405: .It Ic #
406: Skip the rest of the line.
407: This is a non-portable extension.
1.1 otto 408: .El
1.18 otto 409: .Ss Registers
410: Registers have a single character name
411: .Ar x ,
412: where
413: .Ar x
414: may be any character, including space, tab or any other special character.
415: If extended register mode is enabled using the
416: .Fl x
417: option and the register identifier
418: .Ar x
419: has the value 255, the next two characters are interpreted as a
420: two-byte register index.
421: The set of standard single character registers and the set of extended
422: registers do not overlap.
423: Extended register mode is a non-portable extension.
1.1 otto 424: .Sh EXAMPLES
425: An example which prints the first ten values of
1.2 jmc 426: .Ic n! :
427: .Bd -literal -offset indent
1.1 otto 428: [la1+dsa*pla10>y]sy
429: 0sa1
430: lyx
431: .Ed
432: .Pp
433: Independent of the current input base, the command
1.2 jmc 434: .Bd -literal -offset indent
1.1 otto 435: Ai
436: .Ed
437: .Pp
438: will reset the input base to decimal 10.
439: .Sh DIAGNOSTICS
1.2 jmc 440: .Bl -diag
441: .It %c (0%o) is unimplemented
1.1 otto 442: an undefined operation was called.
1.2 jmc 443: .It stack empty
1.1 otto 444: for not enough elements on the stack to do what was asked.
1.2 jmc 445: .It stack register '%c' (0%o) is empty
446: for an
1.1 otto 447: .Ar L
448: operation from a stack register that is empty.
1.2 jmc 449: .It Runtime warning: non-zero scale in exponent
1.1 otto 450: for a fractional part of an exponent that is being ignored.
1.2 jmc 451: .It divide by zero
1.1 otto 452: for trying to divide by zero.
1.2 jmc 453: .It remainder by zero
1.1 otto 454: for trying to take a remainder by zero.
1.2 jmc 455: .It square root of negative number
1.1 otto 456: for trying to take the square root of a negative number.
1.2 jmc 457: .It index too big
1.1 otto 458: for an array index that is larger than 2048.
1.2 jmc 459: .It negative index
1.1 otto 460: for a negative array index.
1.13 jmc 461: .It "input base must be a number between 2 and 16"
1.1 otto 462: for trying to set an illegal input base.
1.2 jmc 463: .It output base must be a number greater than 1
1.18 otto 464: for trying to set an illegal output base.
1.2 jmc 465: .It scale must be a nonnegative number
1.1 otto 466: for trying to set a negative or zero scale.
1.2 jmc 467: .It scale too large
1.1 otto 468: for trying to set a scale that is too large.
1.2 jmc 469: A scale must be representable as a 32-bit unsigned number.
470: .It Q command argument exceeded string execution depth
1.1 otto 471: for trying to pop the recursion level more than the current
472: recursion level.
1.2 jmc 473: .It Q command requires a number >= 1
1.1 otto 474: for trying to pop an illegal number of recursion levels.
1.2 jmc 475: .It recursion too deep
1.1 otto 476: for too many levels of nested execution.
477: .Pp
478: The recursion level is increased by one if the
479: .Ar x
480: or
1.2 jmc 481: .Ar ?\&
1.1 otto 482: operation or one of the compare operations resulting in the execution
483: of register is executed.
484: As an exception, the recursion level is not increased if the operation
485: is executed as the last command of a string.
1.2 jmc 486: For example, the commands
487: .Bd -literal -offset indent
1.1 otto 488: [lax]sa
489: 1 lax
490: .Ed
491: .Pp
492: will execute an endless loop, while the commands
1.2 jmc 493: .Bd -literal -offset indent
1.1 otto 494: [laxp]sa
495: 1 lax
496: .Ed
497: .Pp
498: will terminate because of a too deep recursion level.
1.8 otto 499: .It J command argument exceeded string execution depth
500: for trying to pop the recursion level more than the current
501: recursion level.
502: .It mark not found
1.9 jmc 503: for a failed scan for an occurrence of the
1.8 otto 504: .Ic M
505: operator.
1.1 otto 506: .El
507: .Sh SEE ALSO
1.2 jmc 508: .Xr bc 1
1.35 ! jsg 509: .Rs
! 510: .\" 4.4BSD USD:5
! 511: .%A R. H. Morris
! 512: .%A L. L. Cherry
! 513: .%T DC \(em An Interactive Desk Calculator
! 514: .Re
1.1 otto 515: .Sh STANDARDS
516: The arithmetic operations of the
517: .Nm
518: utility are expected to conform to the definition listed in the
519: .Xr bc 1
520: section of the
521: .St -p1003.2
522: specification.
523: .Sh HISTORY
524: The
525: .Nm
1.34 schwarze 526: command appeared in
527: .At v1 .
1.1 otto 528: A complete rewrite of the
529: .Nm
530: command using the
1.29 schwarze 531: .Xr BN_new 3
1.1 otto 532: big number routines first appeared in
533: .Ox 3.5 .
534: .Sh AUTHORS
1.20 jaredy 535: .An -nosplit
1.1 otto 536: The original version of the
537: .Nm
538: command was written by
539: .An Robert Morris
540: and
541: .An Lorinda Cherry .
542: The current version of the
543: .Nm
544: utility was written by
545: .An Otto Moerbeek .
1.32 otto 546: .Sh CAVEATS
547: While fractional input in base 10 is always exact,
548: other bases may suffer from unintuitive rounding.
549: To avoid surprising results, plain integer division can be used
550: instead of the corresponding floating point notation.
![[BACK]](/icons/back.gif){kind=icon}
Return to dc.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / dc