Annotation of src/usr.bin/dc/dc.1, Revision 1.32
1.32 ! otto 1: .\" $OpenBSD: dc.1,v 1.31 2017/11/28 06:51:19 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: .\"
1.32 ! otto 37: .Dd $Mdocdate: November 28 2017 $
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.
1.30 otto 188: .It Ic e
189: Equivalent to
190: .Ic p ,
191: except that the output is written to the standard error stream.
1.31 otto 192: This is a non-portable extension.
1.10 otto 193: .It Ic f
194: All values on the stack are printed, separated by newlines.
1.16 otto 195: .It Ic G
196: The top two numbers are popped from the stack and compared.
197: A one is pushed if the top of the stack is equal to the second number
198: on the stack.
199: A zero is pushed otherwise.
200: This is a non-portable extension.
1.22 jmc 201: .It Ic I
202: Pushes the input base on the top of the stack.
1.10 otto 203: .It Ic i
204: The top value on the stack is popped and used as the
205: base for further input.
206: The initial input base is 10.
207: .It Ic J
1.15 otto 208: Pop the top value from the stack.
1.10 otto 209: The recursion level is popped by that value and, following that,
210: the input is skipped until the first occurrence of the
211: .Ic M
212: operator.
1.1 otto 213: The
1.10 otto 214: .Ic J
1.15 otto 215: operator is a non-portable extension, used by the
1.10 otto 216: .Xr bc 1
217: command.
218: .It Ic K
219: The current scale factor is pushed onto the stack.
220: .It Ic k
221: The top of the stack is popped, and that value is used as
222: a non-negative scale factor:
223: the appropriate number of places
224: are printed on output,
225: and maintained during multiplication, division, and exponentiation.
226: The interaction of scale factor,
227: input base, and output base will be reasonable if all are changed
228: together.
229: .It Ic L Ns Ar x
230: Register
1.1 otto 231: .Ar x
1.10 otto 232: is treated as a stack and its top value is popped onto the main stack.
1.1 otto 233: .It Ic l Ns Ar x
234: The
235: value in register
236: .Ar x
237: is pushed on the stack.
238: The register
239: .Ar x
240: is not altered.
1.4 otto 241: Initially, all registers contain the value zero.
1.10 otto 242: .It Ic M
243: Mark used by the
244: .Ic J
245: operator.
246: The
247: .Ic M
1.32 ! otto 248: operator is a non-portable extension, used by the
1.10 otto 249: .Xr bc 1
250: command.
1.16 otto 251: .It Ic N
252: The top of the stack is replaced by one if the top of the stack
253: is equal to zero.
254: If the top of the stack is unequal to zero, it is replaced by zero.
255: This is a non-portable extension.
1.15 otto 256: .It Ic n
257: The top value on the stack is popped and printed without a newline.
258: This is a non-portable extension.
1.10 otto 259: .It Ic O
260: Pushes the output base on the top of the stack.
261: .It Ic o
262: The top value on the stack is popped and used as the
263: base for further output.
264: The initial output base is 10.
1.1 otto 265: .It Ic P
266: The top of the stack is popped.
1.2 jmc 267: If the top of the stack is a string, it is printed without a trailing newline.
1.1 otto 268: If the top of the stack is a number, it is interpreted as a
269: base 256 number, and each digit of this base 256 number is printed as
270: an
271: .Tn ASCII
272: character, without a trailing newline.
1.10 otto 273: .It Ic p
274: The top value on the stack is printed with a trailing newline.
275: The top value remains unchanged.
276: .It Ic Q
277: The top value on the stack is popped and the string execution level is popped
278: by that value.
1.1 otto 279: .It Ic q
280: Exits the program.
281: If executing a string, the recursion level is
282: popped by two.
1.17 otto 283: .It Ic R
284: The top of the stack is removed (popped).
285: This is a non-portable extension.
1.14 otto 286: .It Ic r
287: The top two values on the stack are reversed (swapped).
288: This is a non-portable extension.
1.10 otto 289: .It Ic S Ns Ar x
290: Register
291: .Ar x
292: is treated as a stack.
293: The top value of the main stack is popped and pushed on it.
294: .It Ic s Ns Ar x
295: The
296: top of the stack is popped and stored into
297: a register named
1.18 otto 298: .Ar x .
1.10 otto 299: .It Ic v
300: Replaces the top element on the stack by its square root.
301: The scale of the result is the maximum of the scale of the argument
302: and the current value of scale.
303: .It Ic X
304: Replaces the number on the top of the stack with its scale factor.
305: If the top of the stack is a string, replace it with the integer 0.
1.1 otto 306: .It Ic x
307: Treats the top element of the stack as a character string
308: and executes it as a string of
309: .Nm
310: commands.
1.10 otto 311: .It Ic Z
312: Replaces the number on the top of the stack with its length.
313: The length of a string is its number of characters.
314: The length of a number is its number of digits, not counting the minus sign
315: and decimal point.
316: .It Ic z
317: The stack level is pushed onto the stack.
1.25 jmc 318: .It Cm \&[ Ns ... Ns Cm \&]
1.1 otto 319: Puts the bracketed
320: .Tn ASCII
321: string onto the top of the stack.
1.5 otto 322: If the string includes brackets, these must be properly balanced.
1.6 jmc 323: The backslash character
324: .Pq Sq \e
325: may be used as an escape character, making it
1.5 otto 326: possible to include unbalanced brackets in strings.
1.6 jmc 327: To include a backslash in a string, use a double backslash.
1.1 otto 328: .It Xo
329: .Cm < Ns Va x
330: .Cm > Ns Va x
331: .Cm = Ns Va x
332: .Cm !< Ns Va x
333: .Cm !> Ns Va x
334: .Cm != Ns Va x
335: .Xc
336: The top two elements of the stack are popped and compared.
337: Register
338: .Ar x
339: is executed if they obey the stated
340: relation.
1.12 otto 341: .It Xo
342: .Cm < Ns Va x Ns e Ns Va y
343: .Cm > Ns Va x Ns e Ns Va y
344: .Cm = Ns Va x Ns e Ns Va y
345: .Cm !< Ns Va x Ns e Ns Va y
346: .Cm !> Ns Va x Ns e Ns Va y
347: .Cm != Ns Va x Ns e Ns Va y
348: .Xc
349: These operations are variants of the comparison operations above.
350: The first register name is followed by the letter
351: .Sq e
352: and another register name.
353: Register
354: .Ar x
355: will be executed if the relation is true, and register
356: .Ar y
357: will be executed if the relation is false.
358: This is a non-portable extension.
1.16 otto 359: .It Ic \&(
360: The top two numbers are popped from the stack and compared.
361: A one is pushed if the top of the stack is less than the second number
362: on the stack.
363: A zero is pushed otherwise.
364: This is a non-portable extension.
365: .It Ic {
366: The top two numbers are popped from the stack and compared.
367: A one is pushed if the top of stack is less than or equal to the
368: second number on the stack.
369: A zero is pushed otherwise.
370: This is a non-portable extension.
1.2 jmc 371: .It Ic \&?
1.1 otto 372: A line of input is taken from the input source (usually the terminal)
373: and executed.
1.25 jmc 374: .It Ic \&: Ns Ar r
1.2 jmc 375: Pop two values from the stack.
376: The second value on the stack is stored into the array
1.1 otto 377: .Ar r
378: indexed by the top of stack.
1.25 jmc 379: .It Ic \&; Ns Ar r
1.2 jmc 380: Pop a value from the stack.
381: The value is used as an index into register
1.1 otto 382: .Ar r .
383: The value in this register is pushed onto the stack.
384: .Pp
1.2 jmc 385: Array elements initially have the value zero.
1.1 otto 386: Each level of a stacked register has its own array associated with
387: it.
388: The command sequence
1.2 jmc 389: .Bd -literal -offset indent
1.1 otto 390: [first] 0:a [dummy] Sa [second] 0:a 0;a p La 0;a p
391: .Ed
392: .Pp
393: will print
1.2 jmc 394: .Bd -literal -offset indent
1.1 otto 395: second
396: first
397: .Ed
398: .Pp
399: since the string
400: .Ql second
401: is written in an array that is later popped, to reveal the array that
402: stored
403: .Ql first .
1.15 otto 404: .It Ic #
405: Skip the rest of the line.
406: This is a non-portable extension.
1.1 otto 407: .El
1.18 otto 408: .Ss Registers
409: Registers have a single character name
410: .Ar x ,
411: where
412: .Ar x
413: may be any character, including space, tab or any other special character.
414: If extended register mode is enabled using the
415: .Fl x
416: option and the register identifier
417: .Ar x
418: has the value 255, the next two characters are interpreted as a
419: two-byte register index.
420: The set of standard single character registers and the set of extended
421: registers do not overlap.
422: Extended register mode is a non-portable extension.
1.1 otto 423: .Sh EXAMPLES
424: An example which prints the first ten values of
1.2 jmc 425: .Ic n! :
426: .Bd -literal -offset indent
1.1 otto 427: [la1+dsa*pla10>y]sy
428: 0sa1
429: lyx
430: .Ed
431: .Pp
432: Independent of the current input base, the command
1.2 jmc 433: .Bd -literal -offset indent
1.1 otto 434: Ai
435: .Ed
436: .Pp
437: will reset the input base to decimal 10.
438: .Sh DIAGNOSTICS
1.2 jmc 439: .Bl -diag
440: .It %c (0%o) is unimplemented
1.1 otto 441: an undefined operation was called.
1.2 jmc 442: .It stack empty
1.1 otto 443: for not enough elements on the stack to do what was asked.
1.2 jmc 444: .It stack register '%c' (0%o) is empty
445: for an
1.1 otto 446: .Ar L
447: operation from a stack register that is empty.
1.2 jmc 448: .It Runtime warning: non-zero scale in exponent
1.1 otto 449: for a fractional part of an exponent that is being ignored.
1.2 jmc 450: .It divide by zero
1.1 otto 451: for trying to divide by zero.
1.2 jmc 452: .It remainder by zero
1.1 otto 453: for trying to take a remainder by zero.
1.2 jmc 454: .It square root of negative number
1.1 otto 455: for trying to take the square root of a negative number.
1.2 jmc 456: .It index too big
1.1 otto 457: for an array index that is larger than 2048.
1.2 jmc 458: .It negative index
1.1 otto 459: for a negative array index.
1.13 jmc 460: .It "input base must be a number between 2 and 16"
1.1 otto 461: for trying to set an illegal input base.
1.2 jmc 462: .It output base must be a number greater than 1
1.18 otto 463: for trying to set an illegal output base.
1.2 jmc 464: .It scale must be a nonnegative number
1.1 otto 465: for trying to set a negative or zero scale.
1.2 jmc 466: .It scale too large
1.1 otto 467: for trying to set a scale that is too large.
1.2 jmc 468: A scale must be representable as a 32-bit unsigned number.
469: .It Q command argument exceeded string execution depth
1.1 otto 470: for trying to pop the recursion level more than the current
471: recursion level.
1.2 jmc 472: .It Q command requires a number >= 1
1.1 otto 473: for trying to pop an illegal number of recursion levels.
1.2 jmc 474: .It recursion too deep
1.1 otto 475: for too many levels of nested execution.
476: .Pp
477: The recursion level is increased by one if the
478: .Ar x
479: or
1.2 jmc 480: .Ar ?\&
1.1 otto 481: operation or one of the compare operations resulting in the execution
482: of register is executed.
483: As an exception, the recursion level is not increased if the operation
484: is executed as the last command of a string.
1.2 jmc 485: For example, the commands
486: .Bd -literal -offset indent
1.1 otto 487: [lax]sa
488: 1 lax
489: .Ed
490: .Pp
491: will execute an endless loop, while the commands
1.2 jmc 492: .Bd -literal -offset indent
1.1 otto 493: [laxp]sa
494: 1 lax
495: .Ed
496: .Pp
497: will terminate because of a too deep recursion level.
1.8 otto 498: .It J command argument exceeded string execution depth
499: for trying to pop the recursion level more than the current
500: recursion level.
501: .It mark not found
1.9 jmc 502: for a failed scan for an occurrence of the
1.8 otto 503: .Ic M
504: operator.
1.1 otto 505: .El
506: .Sh SEE ALSO
1.2 jmc 507: .Xr bc 1
1.1 otto 508: .Sh STANDARDS
509: The arithmetic operations of the
510: .Nm
511: utility are expected to conform to the definition listed in the
512: .Xr bc 1
513: section of the
514: .St -p1003.2
515: specification.
516: .Sh HISTORY
517: The
518: .Nm
519: command first appeared in
520: .At v6 .
521: A complete rewrite of the
522: .Nm
523: command using the
1.29 schwarze 524: .Xr BN_new 3
1.1 otto 525: big number routines first appeared in
526: .Ox 3.5 .
527: .Sh AUTHORS
1.20 jaredy 528: .An -nosplit
1.1 otto 529: The original version of the
530: .Nm
531: command was written by
532: .An Robert Morris
533: and
534: .An Lorinda Cherry .
535: The current version of the
536: .Nm
537: utility was written by
538: .An Otto Moerbeek .
1.32 ! otto 539: .Sh CAVEATS
! 540: While fractional input in base 10 is always exact,
! 541: other bases may suffer from unintuitive rounding.
! 542: To avoid surprising results, plain integer division can be used
! 543: instead of the corresponding floating point notation.
![[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