Annotation of src/usr.bin/dc/dc.1, Revision 1.5
1.5 ! otto 1: .\" $OpenBSD: dc.1,v 1.4 2003/09/22 14:50:32 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.2 jmc 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 (%),
93: or exponentiated (^).
94: The two entries are popped off the stack;
95: the result is pushed on the stack in their place.
96: Any fractional part of an exponent is ignored.
97: .Pp
98: For addition and subtraction, the scale of the result is the maximum
99: of scales of the operands.
100: For division the scale of the result is defined
101: by the scale set by the
102: .Ar k
103: operation.
1.2 jmc 104: For multiplication, the scale is defined by the expression
105: .Sy min(a+b,max(a,b,scale)) ,
1.1 otto 106: where
107: .Sy a
108: and
109: .Sy b
110: are the scales of the operands, and
111: .Sy scale
1.2 jmc 112: is the scale defined by the
1.1 otto 113: .Ar k
114: operation.
115: For exponentation with a non-negative exponent, the scale of the result is
1.2 jmc 116: .Sy min(a*b,max(scale,a)) ,
1.1 otto 117: where
118: .Sy a
119: is the scale of the base, and
120: .Sy b
121: is the
122: .Em value
123: of the exponent.
124: If the exponent is negative, the scale of the result is the scale
125: defined by the
126: .Ar k
127: operation.
128: .It Ic s Ns Ar x
129: The
130: top of the stack is popped and stored into
131: a register named
132: .Ar x ,
133: where
134: .Ar x
135: may be any character, including space, tab or any other special character.
136: If the
137: .Ar s
138: is capitalized,
139: .Ar x
140: is treated as a stack and the value is pushed on it.
141: .It Ic l Ns Ar x
142: The
143: value in register
144: .Ar x
145: is pushed on the stack.
146: The register
147: .Ar x
148: is not altered.
1.4 otto 149: Initially, all registers contain the value zero.
1.1 otto 150: If the
151: .Ar l
152: is capitalized,
153: register
154: .Ar x
155: is treated as a stack and its top value is popped onto the main stack.
156: .It Ic d
157: The top value on the stack is duplicated.
158: .It Ic p
159: The top value on the stack is printed with a trailing newline.
160: The top value remains unchanged.
161: .It Ic P
162: The top of the stack is popped.
1.2 jmc 163: If the top of the stack is a string, it is printed without a trailing newline.
1.1 otto 164: If the top of the stack is a number, it is interpreted as a
165: base 256 number, and each digit of this base 256 number is printed as
166: an
167: .Tn ASCII
168: character, without a trailing newline.
169: .It Ic f
170: All values on the stack are printed, separated by newlines.
171: .It Ic q
172: Exits the program.
173: If executing a string, the recursion level is
174: popped by two.
175: If
176: .Ar q
177: is capitalized,
178: the top value on the stack is popped and the string execution level is popped
179: by that value.
180: .It Ic x
181: Treats the top element of the stack as a character string
182: and executes it as a string of
183: .Nm
184: commands.
185: .It Ic X
1.2 jmc 186: Replaces the number on the top of the stack with its scale factor.
187: If the top of the stack is a string, replace it with the integer 0.
1.1 otto 188: .It Cm [ Ns ... Ns Cm ]
189: Puts the bracketed
190: .Tn ASCII
191: string onto the top of the stack.
1.5 ! otto 192: If the string includes brackets, these must be properly balanced.
! 193: The backslash character \e\ may be used as an escape character, making it
! 194: possible to include unbalanced brackets in strings.
! 195: To include a backslash into a string, use a double backslash.
1.1 otto 196: .It Xo
197: .Cm < Ns Va x
198: .Cm > Ns Va x
199: .Cm = Ns Va x
200: .Cm !< Ns Va x
201: .Cm !> Ns Va x
202: .Cm != Ns Va x
203: .Xc
204: The top two elements of the stack are popped and compared.
205: Register
206: .Ar x
207: is executed if they obey the stated
208: relation.
209: .It Ic v
210: Replaces the top element on the stack by its square root.
211: The scale of the result is the maximum of the scale of the argument
212: and the current value of scale.
1.2 jmc 213: .It Ic \&!
1.1 otto 214: Interprets the rest of the line as a
215: .Ux
216: command.
217: .It Ic c
218: All values on the stack are popped.
219: .It Ic i
220: The top value on the stack is popped and used as the
1.2 jmc 221: base for further input.
222: The initial input base is 10.
1.1 otto 223: .Ic I
224: Pushes the input base on the top of the stack.
225: .It Ic o
226: The top value on the stack is popped and used as the
1.2 jmc 227: base for further output.
228: The initial output base is 10.
1.1 otto 229: .It Ic O
230: Pushes the output base on the top of the stack.
231: .It Ic k
232: The top of the stack is popped, and that value is used as
233: a non-negative scale factor:
234: the appropriate number of places
235: are printed on output,
236: and maintained during multiplication, division, and exponentiation.
237: The interaction of scale factor,
238: input base, and output base will be reasonable if all are changed
239: together.
240: .It Ic K
241: The current scale factor is pushed onto the stack.
242: .It Ic z
243: The stack level is pushed onto the stack.
244: .It Ic Z
245: Replaces the number on the top of the stack with its length.
246: The length of a string is its number of characters.
247: The length of a number is its number of digits, not counting the minus sign
248: and decimal point.
1.2 jmc 249: .It Ic \&?
1.1 otto 250: A line of input is taken from the input source (usually the terminal)
251: and executed.
252: .It Ic : Ns Ar r
1.2 jmc 253: Pop two values from the stack.
254: The second value on the stack is stored into the array
1.1 otto 255: .Ar r
256: indexed by the top of stack.
257: .It Ic ; Ns Ar r
1.2 jmc 258: Pop a value from the stack.
259: The value is used as an index into register
1.1 otto 260: .Ar r .
261: The value in this register is pushed onto the stack.
262: .Pp
1.2 jmc 263: Array elements initially have the value zero.
1.1 otto 264: Each level of a stacked register has its own array associated with
265: it.
266: The command sequence
1.2 jmc 267: .Bd -literal -offset indent
1.1 otto 268: [first] 0:a [dummy] Sa [second] 0:a 0;a p La 0;a p
269: .Ed
270: .Pp
271: will print
1.2 jmc 272: .Bd -literal -offset indent
1.1 otto 273: second
274: first
275: .Ed
276: .Pp
277: since the string
278: .Ql second
279: is written in an array that is later popped, to reveal the array that
280: stored
281: .Ql first .
282: .El
283: .Sh EXAMPLES
284: An example which prints the first ten values of
1.2 jmc 285: .Ic n! :
286: .Bd -literal -offset indent
1.1 otto 287: [la1+dsa*pla10>y]sy
288: 0sa1
289: lyx
290: .Ed
291: .Pp
292: Independent of the current input base, the command
1.2 jmc 293: .Bd -literal -offset indent
1.1 otto 294: Ai
295: .Ed
296: .Pp
297: will reset the input base to decimal 10.
298: .Sh DIAGNOSTICS
1.2 jmc 299: .Bl -diag
300: .It %c (0%o) is unimplemented
1.1 otto 301: an undefined operation was called.
1.2 jmc 302: .It stack empty
1.1 otto 303: for not enough elements on the stack to do what was asked.
1.2 jmc 304: .It stack register '%c' (0%o) is empty
305: for an
1.1 otto 306: .Ar L
307: operation from a stack register that is empty.
1.2 jmc 308: .It Runtime warning: non-zero scale in exponent
1.1 otto 309: for a fractional part of an exponent that is being ignored.
1.2 jmc 310: .It divide by zero
1.1 otto 311: for trying to divide by zero.
1.2 jmc 312: .It remainder by zero
1.1 otto 313: for trying to take a remainder by zero.
1.2 jmc 314: .It square root of negative number
1.1 otto 315: for trying to take the square root of a negative number.
1.2 jmc 316: .It index too big
1.1 otto 317: for an array index that is larger than 2048.
1.2 jmc 318: .It negative index
1.1 otto 319: for a negative array index.
1.2 jmc 320: .It input base must be a number between 2 and 16
1.1 otto 321: for trying to set an illegal input base.
1.2 jmc 322: .It output base must be a number greater than 1
1.1 otto 323: for trying to set an illegal input base.
1.2 jmc 324: .It scale must be a nonnegative number
1.1 otto 325: for trying to set a negative or zero scale.
1.2 jmc 326: .It scale too large
1.1 otto 327: for trying to set a scale that is too large.
1.2 jmc 328: A scale must be representable as a 32-bit unsigned number.
329: .It Q command argument exceeded string execution depth
1.1 otto 330: for trying to pop the recursion level more than the current
331: recursion level.
1.2 jmc 332: .It Q command requires a number >= 1
1.1 otto 333: for trying to pop an illegal number of recursion levels.
1.2 jmc 334: .It recursion too deep
1.1 otto 335: for too many levels of nested execution.
336: .Pp
337: The recursion level is increased by one if the
338: .Ar x
339: or
1.2 jmc 340: .Ar ?\&
1.1 otto 341: operation or one of the compare operations resulting in the execution
342: of register is executed.
343: As an exception, the recursion level is not increased if the operation
344: is executed as the last command of a string.
1.2 jmc 345: For example, the commands
346: .Bd -literal -offset indent
1.1 otto 347: [lax]sa
348: 1 lax
349: .Ed
350: .Pp
351: will execute an endless loop, while the commands
1.2 jmc 352: .Bd -literal -offset indent
1.1 otto 353: [laxp]sa
354: 1 lax
355: .Ed
356: .Pp
357: will terminate because of a too deep recursion level.
358: .El
359: .Sh SEE ALSO
1.2 jmc 360: .Xr bc 1
1.1 otto 361: .Pp
362: USD:05
363: .Em "DC \- An Interactive Desk Calculator"
364: .Sh STANDARDS
365: The arithmetic operations of the
366: .Nm
367: utility are expected to conform to the definition listed in the
368: .Xr bc 1
369: section of the
370: .St -p1003.2
371: specification.
372: .Sh HISTORY
373: The
374: .Nm
375: command first appeared in
376: .At v6 .
377: A complete rewrite of the
378: .Nm
379: command using the
380: .Xr bn 3
381: big number routines first appeared in
382: .Ox 3.5 .
383: .Sh AUTHORS
384: The original version of the
385: .Nm
386: command was written by
387: .An Robert Morris
388: and
389: .An Lorinda Cherry .
390: The current version of the
391: .Nm
392: utility was written by
393: .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