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