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