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