Annotation of src/usr.bin/dc/dc.1, Revision 1.27
1.27 ! jmc 1: .\" $OpenBSD: dc.1,v 1.26 2010/10/18 14:48:49 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.27 ! jmc 37: .Dd $Mdocdate: October 18 2010 $
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: Interprets the rest of the line as a
368: .Ux
369: command.
1.2 jmc 370: .It Ic \&?
1.1 otto 371: A line of input is taken from the input source (usually the terminal)
372: and executed.
1.25 jmc 373: .It Ic \&: Ns Ar r
1.2 jmc 374: Pop two values from the stack.
375: The second value on the stack is stored into the array
1.1 otto 376: .Ar r
377: indexed by the top of stack.
1.25 jmc 378: .It Ic \&; Ns Ar r
1.2 jmc 379: Pop a value from the stack.
380: The value is used as an index into register
1.1 otto 381: .Ar r .
382: The value in this register is pushed onto the stack.
383: .Pp
1.2 jmc 384: Array elements initially have the value zero.
1.1 otto 385: Each level of a stacked register has its own array associated with
386: it.
387: The command sequence
1.2 jmc 388: .Bd -literal -offset indent
1.1 otto 389: [first] 0:a [dummy] Sa [second] 0:a 0;a p La 0;a p
390: .Ed
391: .Pp
392: will print
1.2 jmc 393: .Bd -literal -offset indent
1.1 otto 394: second
395: first
396: .Ed
397: .Pp
398: since the string
399: .Ql second
400: is written in an array that is later popped, to reveal the array that
401: stored
402: .Ql first .
1.15 otto 403: .It Ic #
404: Skip the rest of the line.
405: This is a non-portable extension.
1.1 otto 406: .El
1.18 otto 407: .Ss Registers
408: Registers have a single character name
409: .Ar x ,
410: where
411: .Ar x
412: may be any character, including space, tab or any other special character.
413: If extended register mode is enabled using the
414: .Fl x
415: option and the register identifier
416: .Ar x
417: has the value 255, the next two characters are interpreted as a
418: two-byte register index.
419: The set of standard single character registers and the set of extended
420: registers do not overlap.
421: Extended register mode is a non-portable extension.
1.1 otto 422: .Sh EXAMPLES
423: An example which prints the first ten values of
1.2 jmc 424: .Ic n! :
425: .Bd -literal -offset indent
1.1 otto 426: [la1+dsa*pla10>y]sy
427: 0sa1
428: lyx
429: .Ed
430: .Pp
431: Independent of the current input base, the command
1.2 jmc 432: .Bd -literal -offset indent
1.1 otto 433: Ai
434: .Ed
435: .Pp
436: will reset the input base to decimal 10.
437: .Sh DIAGNOSTICS
1.2 jmc 438: .Bl -diag
439: .It %c (0%o) is unimplemented
1.1 otto 440: an undefined operation was called.
1.2 jmc 441: .It stack empty
1.1 otto 442: for not enough elements on the stack to do what was asked.
1.2 jmc 443: .It stack register '%c' (0%o) is empty
444: for an
1.1 otto 445: .Ar L
446: operation from a stack register that is empty.
1.2 jmc 447: .It Runtime warning: non-zero scale in exponent
1.1 otto 448: for a fractional part of an exponent that is being ignored.
1.2 jmc 449: .It divide by zero
1.1 otto 450: for trying to divide by zero.
1.2 jmc 451: .It remainder by zero
1.1 otto 452: for trying to take a remainder by zero.
1.2 jmc 453: .It square root of negative number
1.1 otto 454: for trying to take the square root of a negative number.
1.2 jmc 455: .It index too big
1.1 otto 456: for an array index that is larger than 2048.
1.2 jmc 457: .It negative index
1.1 otto 458: for a negative array index.
1.13 jmc 459: .It "input base must be a number between 2 and 16"
1.1 otto 460: for trying to set an illegal input base.
1.2 jmc 461: .It output base must be a number greater than 1
1.18 otto 462: for trying to set an illegal output base.
1.2 jmc 463: .It scale must be a nonnegative number
1.1 otto 464: for trying to set a negative or zero scale.
1.2 jmc 465: .It scale too large
1.1 otto 466: for trying to set a scale that is too large.
1.2 jmc 467: A scale must be representable as a 32-bit unsigned number.
468: .It Q command argument exceeded string execution depth
1.1 otto 469: for trying to pop the recursion level more than the current
470: recursion level.
1.2 jmc 471: .It Q command requires a number >= 1
1.1 otto 472: for trying to pop an illegal number of recursion levels.
1.2 jmc 473: .It recursion too deep
1.1 otto 474: for too many levels of nested execution.
475: .Pp
476: The recursion level is increased by one if the
477: .Ar x
478: or
1.2 jmc 479: .Ar ?\&
1.1 otto 480: operation or one of the compare operations resulting in the execution
481: of register is executed.
482: As an exception, the recursion level is not increased if the operation
483: is executed as the last command of a string.
1.2 jmc 484: For example, the commands
485: .Bd -literal -offset indent
1.1 otto 486: [lax]sa
487: 1 lax
488: .Ed
489: .Pp
490: will execute an endless loop, while the commands
1.2 jmc 491: .Bd -literal -offset indent
1.1 otto 492: [laxp]sa
493: 1 lax
494: .Ed
495: .Pp
496: will terminate because of a too deep recursion level.
1.8 otto 497: .It J command argument exceeded string execution depth
498: for trying to pop the recursion level more than the current
499: recursion level.
500: .It mark not found
1.9 jmc 501: for a failed scan for an occurrence of the
1.8 otto 502: .Ic M
503: operator.
1.1 otto 504: .El
505: .Sh SEE ALSO
1.2 jmc 506: .Xr bc 1
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