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