Annotation of src/usr.bin/dc/dc.1, Revision 1.29
1.29 ! schwarze 1: .\" $OpenBSD: dc.1,v 1.28 2015/10/03 17:15:26 deraadt 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.28 deraadt 37: .Dd $Mdocdate: October 3 2015 $
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.
188: .It Ic f
189: All values on the stack are printed, separated by newlines.
1.16 otto 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.
1.22 jmc 196: .It Ic I
197: Pushes the input base on the top of the stack.
1.10 otto 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
1.15 otto 203: Pop the top value from the stack.
1.10 otto 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.
1.1 otto 208: The
1.10 otto 209: .Ic J
1.15 otto 210: operator is a non-portable extension, used by the
1.10 otto 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
1.1 otto 226: .Ar x
1.10 otto 227: is treated as a stack and its top value is popped onto the main stack.
1.1 otto 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.
1.4 otto 236: Initially, all registers contain the value zero.
1.10 otto 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.
1.16 otto 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.
1.15 otto 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.
1.10 otto 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.
1.1 otto 260: .It Ic P
261: The top of the stack is popped.
1.2 jmc 262: If the top of the stack is a string, it is printed without a trailing newline.
1.1 otto 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.
1.10 otto 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.
1.1 otto 274: .It Ic q
275: Exits the program.
276: If executing a string, the recursion level is
277: popped by two.
1.17 otto 278: .It Ic R
279: The top of the stack is removed (popped).
280: This is a non-portable extension.
1.14 otto 281: .It Ic r
282: The top two values on the stack are reversed (swapped).
283: This is a non-portable extension.
1.10 otto 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
1.18 otto 293: .Ar x .
1.10 otto 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.
1.1 otto 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.
1.10 otto 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.
1.25 jmc 313: .It Cm \&[ Ns ... Ns Cm \&]
1.1 otto 314: Puts the bracketed
315: .Tn ASCII
316: string onto the top of the stack.
1.5 otto 317: If the string includes brackets, these must be properly balanced.
1.6 jmc 318: The backslash character
319: .Pq Sq \e
320: may be used as an escape character, making it
1.5 otto 321: possible to include unbalanced brackets in strings.
1.6 jmc 322: To include a backslash in a string, use a double backslash.
1.1 otto 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.
1.12 otto 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.
1.16 otto 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.
1.2 jmc 366: .It Ic \&?
1.1 otto 367: A line of input is taken from the input source (usually the terminal)
368: and executed.
1.25 jmc 369: .It Ic \&: Ns Ar r
1.2 jmc 370: Pop two values from the stack.
371: The second value on the stack is stored into the array
1.1 otto 372: .Ar r
373: indexed by the top of stack.
1.25 jmc 374: .It Ic \&; Ns Ar r
1.2 jmc 375: Pop a value from the stack.
376: The value is used as an index into register
1.1 otto 377: .Ar r .
378: The value in this register is pushed onto the stack.
379: .Pp
1.2 jmc 380: Array elements initially have the value zero.
1.1 otto 381: Each level of a stacked register has its own array associated with
382: it.
383: The command sequence
1.2 jmc 384: .Bd -literal -offset indent
1.1 otto 385: [first] 0:a [dummy] Sa [second] 0:a 0;a p La 0;a p
386: .Ed
387: .Pp
388: will print
1.2 jmc 389: .Bd -literal -offset indent
1.1 otto 390: second
391: first
392: .Ed
393: .Pp
394: since the string
395: .Ql second
396: is written in an array that is later popped, to reveal the array that
397: stored
398: .Ql first .
1.15 otto 399: .It Ic #
400: Skip the rest of the line.
401: This is a non-portable extension.
1.1 otto 402: .El
1.18 otto 403: .Ss Registers
404: Registers have a single character name
405: .Ar x ,
406: where
407: .Ar x
408: may be any character, including space, tab or any other special character.
409: If extended register mode is enabled using the
410: .Fl x
411: option and the register identifier
412: .Ar x
413: has the value 255, the next two characters are interpreted as a
414: two-byte register index.
415: The set of standard single character registers and the set of extended
416: registers do not overlap.
417: Extended register mode is a non-portable extension.
1.1 otto 418: .Sh EXAMPLES
419: An example which prints the first ten values of
1.2 jmc 420: .Ic n! :
421: .Bd -literal -offset indent
1.1 otto 422: [la1+dsa*pla10>y]sy
423: 0sa1
424: lyx
425: .Ed
426: .Pp
427: Independent of the current input base, the command
1.2 jmc 428: .Bd -literal -offset indent
1.1 otto 429: Ai
430: .Ed
431: .Pp
432: will reset the input base to decimal 10.
433: .Sh DIAGNOSTICS
1.2 jmc 434: .Bl -diag
435: .It %c (0%o) is unimplemented
1.1 otto 436: an undefined operation was called.
1.2 jmc 437: .It stack empty
1.1 otto 438: for not enough elements on the stack to do what was asked.
1.2 jmc 439: .It stack register '%c' (0%o) is empty
440: for an
1.1 otto 441: .Ar L
442: operation from a stack register that is empty.
1.2 jmc 443: .It Runtime warning: non-zero scale in exponent
1.1 otto 444: for a fractional part of an exponent that is being ignored.
1.2 jmc 445: .It divide by zero
1.1 otto 446: for trying to divide by zero.
1.2 jmc 447: .It remainder by zero
1.1 otto 448: for trying to take a remainder by zero.
1.2 jmc 449: .It square root of negative number
1.1 otto 450: for trying to take the square root of a negative number.
1.2 jmc 451: .It index too big
1.1 otto 452: for an array index that is larger than 2048.
1.2 jmc 453: .It negative index
1.1 otto 454: for a negative array index.
1.13 jmc 455: .It "input base must be a number between 2 and 16"
1.1 otto 456: for trying to set an illegal input base.
1.2 jmc 457: .It output base must be a number greater than 1
1.18 otto 458: for trying to set an illegal output base.
1.2 jmc 459: .It scale must be a nonnegative number
1.1 otto 460: for trying to set a negative or zero scale.
1.2 jmc 461: .It scale too large
1.1 otto 462: for trying to set a scale that is too large.
1.2 jmc 463: A scale must be representable as a 32-bit unsigned number.
464: .It Q command argument exceeded string execution depth
1.1 otto 465: for trying to pop the recursion level more than the current
466: recursion level.
1.2 jmc 467: .It Q command requires a number >= 1
1.1 otto 468: for trying to pop an illegal number of recursion levels.
1.2 jmc 469: .It recursion too deep
1.1 otto 470: for too many levels of nested execution.
471: .Pp
472: The recursion level is increased by one if the
473: .Ar x
474: or
1.2 jmc 475: .Ar ?\&
1.1 otto 476: operation or one of the compare operations resulting in the execution
477: of register is executed.
478: As an exception, the recursion level is not increased if the operation
479: is executed as the last command of a string.
1.2 jmc 480: For example, the commands
481: .Bd -literal -offset indent
1.1 otto 482: [lax]sa
483: 1 lax
484: .Ed
485: .Pp
486: will execute an endless loop, while the commands
1.2 jmc 487: .Bd -literal -offset indent
1.1 otto 488: [laxp]sa
489: 1 lax
490: .Ed
491: .Pp
492: will terminate because of a too deep recursion level.
1.8 otto 493: .It J command argument exceeded string execution depth
494: for trying to pop the recursion level more than the current
495: recursion level.
496: .It mark not found
1.9 jmc 497: for a failed scan for an occurrence of the
1.8 otto 498: .Ic M
499: operator.
1.1 otto 500: .El
501: .Sh SEE ALSO
1.2 jmc 502: .Xr bc 1
1.1 otto 503: .Sh STANDARDS
504: The arithmetic operations of the
505: .Nm
506: utility are expected to conform to the definition listed in the
507: .Xr bc 1
508: section of the
509: .St -p1003.2
510: specification.
511: .Sh HISTORY
512: The
513: .Nm
514: command first appeared in
515: .At v6 .
516: A complete rewrite of the
517: .Nm
518: command using the
1.29 ! schwarze 519: .Xr BN_new 3
1.1 otto 520: big number routines first appeared in
521: .Ox 3.5 .
522: .Sh AUTHORS
1.20 jaredy 523: .An -nosplit
1.1 otto 524: The original version of the
525: .Nm
526: command was written by
527: .An Robert Morris
528: and
529: .An Lorinda Cherry .
530: The current version of the
531: .Nm
532: utility was written by
533: .An Otto Moerbeek .