xref: /dragonfly/usr.bin/bc/bc.1 (revision 6e278935) 
1.\"	$OpenBSD: bc.1,v 1.22 2007/05/31 19:20:07 jmc Exp $
2.\"	$DragonFly: src/usr.bin/bc/bc.1,v 1.6 2007/09/01 18:42:08 pavalos Exp $
3.\"
4.\" Copyright (C) Caldera International Inc.  2001-2002.
5.\" All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code and documentation must retain the above
11.\"    copyright notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\"    notice, this list of conditions and the following disclaimer in the
14.\"    documentation and/or other materials provided with the distribution.
15.\" 3. All advertising materials mentioning features or use of this software
16.\"    must display the following acknowledgement:
17.\"	This product includes software developed or owned by Caldera
18.\"	International, Inc.
19.\" 4. Neither the name of Caldera International, Inc. nor the names of other
20.\"    contributors may be used to endorse or promote products derived from
21.\"    this software without specific prior written permission.
22.\"
23.\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA
24.\" INTERNATIONAL, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR
25.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
26.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
27.\" IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE FOR ANY DIRECT,
28.\" INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
29.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
30.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
31.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
32.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
33.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
34.\" POSSIBILITY OF SUCH DAMAGE.
35.\"
36.\"	@(#)bc.1	6.8 (Berkeley) 8/8/91
37.\"
38.Dd November 14, 2009
39.Dt BC 1
40.Os
41.Sh NAME
42.Nm bc
43.Nd arbitrary-precision arithmetic language and calculator
44.Sh SYNOPSIS
45.Nm
46.Op Fl cl
47.Op Fl e Ar expression
48.Op Ar file ...
49.Sh DESCRIPTION
50.Nm
51is an interactive processor for a language which resembles
52C but provides unlimited precision arithmetic.
53It takes input from any expressions on the command line and
54any files given, then reads the standard input.
55.Pp
56Options available:
57.Bl -tag -width Ds
58.It Fl c
59.Nm
60is actually a preprocessor for
61.Xr dc 1 ,
62which it invokes automatically, unless the
63.Fl c
64.Pq compile only
65option is present.
66In this case the generated
67.Xr dc 1
68instructions are sent to the standard output,
69instead of being interpreted by a running
70.Xr dc 1
71process.
72.It Fl e Ar expression
73Evaluate
74.Ar expression .
75If multiple
76.Fl e
77options are specified, they are processed in the order given,
78separated by newlines.
79.It Fl l
80Allow specification of an arbitrary precision math library.
81The definitions in the library are available to command line
82expressions.
83.El
84.Pp
85The syntax for
86.Nm
87programs is as follows:
88.Sq L
89means letter a-z;
90.Sq E
91means expression;
92.Sq S
93means statement.
94As a non-portable extension, it is possible to use long names
95in addition to single letter names.
96A long name is a sequence starting with a lowercase letter
97followed by any number of lowercase letters and digits.
98The underscore character
99.Pq Sq _
100counts as a letter.
101.Pp
102Comments
103.Bd -unfilled -offset indent -compact
104are enclosed in /* and */
105are enclosed in # and the next newline
106.Ed
107.Pp
108The newline is not part of the line comment,
109which in itself is a non-portable extension.
110.Pp
111Names
112.Bd -unfilled -offset indent -compact
113simple variables: L
114array elements: L [ E ]
115The words `ibase', `obase', and `scale'
116The word `last' or a single dot
117.Ed
118.Pp
119Other operands
120.Bd -unfilled -offset indent -compact
121arbitrarily long numbers with optional sign and decimal point
122( E )
123sqrt ( E )
124length ( E )	number of significant decimal digits
125scale ( E )	number of digits right of decimal point
126L ( E , ... , E )
127.Ed
128.Pp
129The sequence
130.Sq \e<newline><whitespace>
131is ignored within numbers.
132.Pp
133Operators
134.Pp
135The following arithmetic and logical operators can be used.
136The semantics of the operators is the same as in the C language.
137They are listed in order of decreasing precedence.
138Operators in the same group have the same precedence.
139.Bl -column -offset indent "= += \-= *= /= %= ^=" "Associativity" \
140"multiply, divide, modulus"
141.It Sy "Operator" Ta Sy "Associativity" Ta Sy "Description"
142.It "++ \-\-" Ta "none" Ta "increment, decrement"
143.It "\-" Ta "none" Ta "unary minus"
144.It "^" Ta "right" Ta "power"
145.It "* / %" Ta "left" Ta "multiply, divide, modulus"
146.It "+ \-" Ta "left" Ta "plus, minus"
147.It "= += -= *= /= %= ^=" Ta "right" Ta "assignment"
148.It "== <= >= != < >" Ta "none" Ta "relational"
149.It "!" Ta "none" Ta "boolean not"
150.It "&&" Ta "left" Ta "boolean and"
151.It "||" Ta "left" Ta "boolean or"
152.El
153.Pp
154Note the following:
155.Bl -bullet -offset indent
156.It
157The relational operators may appear in any expression.
158The
159.St -p1003.2
160standard only allows them in the conditional expression of an
161.Sq if ,
162.Sq while
163or
164.Sq for
165statement.
166.It
167The relational operators have a lower precedence than the assignment
168operators.
169This has the consequence that the expression
170.Sy a = b < c
171is interpreted as
172.Sy (a = b) < c ,
173which is probably not what the programmer intended.
174.It
175In contrast with the C language, the relational operators all have
176the same precedence, and are non-associative.
177The expression
178.Sy a < b < c
179will produce a syntax error.
180.It
181The boolean operators (!, && and ||) are non-portable extensions.
182.It
183The boolean not
184(!) operator has much lower precedence than the same operator in the
185C language.
186This has the consequence that the expression
187.Sy !a < b
188is interpreted as
189.Sy !(a < b) .
190Prudent programmers use parentheses when writing expressions involving
191boolean operators.
192.El
193.Pp
194Statements
195.Bd -unfilled -offset indent -compact
196E
197{ S ; ... ; S }
198if ( E ) S
199if ( E ) S else S
200while ( E ) S
201for ( E ; E ; E ) S
202null statement
203break
204continue
205quit
206a string of characters, enclosed in double quotes
207print E ,..., E
208.Ed
209.Pp
210A string may contain any character, except a double quote.
211The if statement with an else branch is a non-portable extension.
212All three E's in a for statement may be empty.
213This is a non-portable extension.
214The continue and print statements are also non-portable extensions.
215.Pp
216The print statement takes a list of comma-separated expressions.
217Each expression in the list is evaluated and the computed
218value is printed and assigned to the variable `last'.
219No trailing newline is printed.
220The expression may also be a string enclosed in double quotes.
221Within these strings the following escape sequences may be used:
222.Sq \ea
223for bell (alert),
224.Sq \eb
225for backspace,
226.Sq \ef
227for formfeed,
228.Sq \en
229for newline,
230.Sq \er
231for carriage return,
232.Sq \et
233for tab,
234.Sq \eq
235for double quote and
236.Sq \e\e
237for backslash.
238Any other character following a backslash will be ignored.
239Strings will not be assigned to `last'.
240.Pp
241Function definitions
242.Bd -unfilled -offset indent
243define L ( L ,..., L ) {
244	auto L, ... , L
245	S; ... S
246	return ( E )
247}
248.Ed
249.Pp
250As a non-portable extension, the opening brace of the define statement
251may appear on the next line.
252The return statement may also appear in the following forms:
253.Bd -unfilled -offset indent
254return
255return ()
256return E
257.Ed
258.Pp
259The first two are equivalent to the statement
260.Dq return 0 .
261The last form is a non-portable extension.
262Not specifying a return statement is equivalent to writing
263.Dq return (0) .
264.Pp
265Functions available in the math library, which is loaded by specifying the
266.Fl l
267flag on the command line
268.Pp
269.Bl -tag -width j(n,x) -offset indent -compact
270.It s(x)
271sine
272.It c(x)
273cosine
274.It e(x)
275exponential
276.It l(x)
277log
278.It a(x)
279arctangent
280.It j(n,x)
281Bessel function
282.El
283.Pp
284All function arguments are passed by value.
285.Pp
286The value of a statement that is an expression is printed
287unless the main operator is an assignment.
288The value printed is assigned to the special variable `last'.
289This is a non-portable extension.
290A single dot may be used as a synonym for `last'.
291Either semicolons or newlines may separate statements.
292Assignment to
293.Ar scale
294influences the number of digits to be retained on arithmetic
295operations in the manner of
296.Xr dc 1 .
297Assignments to
298.Ar ibase
299or
300.Ar obase
301set the input and output number radix respectively.
302.Pp
303The same letter may be used as an array, a function,
304and a simple variable simultaneously.
305All variables are global to the program.
306`Auto' variables are pushed down during function calls.
307When using arrays as function arguments
308or defining them as automatic variables,
309empty square brackets must follow the array name.
310.Pp
311For example
312.Bd -literal -offset indent
313scale = 20
314define e(x){
315	auto a, b, c, i, s
316	a = 1
317	b = 1
318	s = 1
319	for(i=1; 1==1; i++){
320		a = a*x
321		b = b*i
322		c = a/b
323		if(c == 0) return(s)
324		s = s+c
325	}
326}
327.Ed
328.Pp
329defines a function to compute an approximate value of
330the exponential function and
331.Pp
332.Dl for(i=1; i<=10; i++) e(i)
333.Pp
334prints approximate values of the exponential function of
335the first ten integers.
336.Bd -literal -offset indent
337$ bc -l -e 'scale = 500; 2 * a(2^10000)' -e quit
338.Ed
339.Pp
340prints an approximation of pi.
341.Sh FILES
342.Bl -tag -width /usr/share/misc/bc.library -compact
343.It Pa /usr/share/misc/bc.library
344math library, read when the
345.Fl l
346option is specified on the command line.
347.El
348.Sh SEE ALSO
349.Xr dc 1
350.Rs
351.%A "Lorinda Cherry"
352.%A "Robert Morris"
353.%B "4.4BSD Users's Supplementary Documents (USD)"
354.%T "BC \- An Arbitrary Precision Desk-Calculator Language"
355.Re
356.\" .Pa /usr/share/doc/usd/06.bc/ .
357.Sh STANDARDS
358The
359.Nm
360utility is compliant with the
361.St -p1003.1-2004
362specification.
363.Pp
364The flags
365.Op Fl ce
366are extensions to that specification.
367.Sh HISTORY
368The
369.Nm
370command first appeared in
371.At v6 .
372A complete rewrite of the
373.Nm
374command first appeared in
375.Ox 3.5 .
376.Sh AUTHORS
377.An -nosplit
378The original version of the
379.Nm
380command was written by
381.An Robert Morris
382and
383.An Lorinda Cherry .
384The current version of the
385.Nm
386utility was written by
387.An Otto Moerbeek .
388.Sh BUGS
389.Ql Quit
390is interpreted when read, not when executed.
391.Pp
392Some non-portable extensions, as found in the GNU version of the
393.Nm
394utility are not implemented (yet).
395