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