xref: /freebsd/usr.bin/bc/bc.1 (revision aa0a1e58) 
1.\"	$FreeBSD$
2.\"	$OpenBSD: bc.1,v 1.25 2010/01/02 19:48:56 schwarze 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 January 22, 2010
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 bc
46.Op Fl chlqv
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 , Fl Fl expression 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 h , Fl Fl help
80Prints usage information.
81.It Fl l , Fl Fl mathlib
82Allow specification of an arbitrary precision math library.
83The definitions in the library are available to command line
84expressions.
85Synonym for
86.Fl l .
87.It Fl v , Fl Fl version
88Prints version information.
89.El
90.Pp
91The syntax for
92.Nm
93programs is as follows:
94.Sq L
95means letter a-z;
96.Sq E
97means expression;
98.Sq S
99means statement.
100As a non-portable extension, it is possible to use long names
101in addition to single letter names.
102A long name is a sequence starting with a lowercase letter
103followed by any number of lowercase letters and digits.
104The underscore character
105.Pq Sq _
106counts as a letter.
107.Pp
108Comments
109.Bd -unfilled -offset indent -compact
110are enclosed in /* and */
111are enclosed in # and the next newline
112.Ed
113.Pp
114The newline is not part of the line comment,
115which in itself is a non-portable extension.
116.Pp
117Names
118.Bd -unfilled -offset indent -compact
119simple variables: L
120array elements: L [ E ]
121The words `ibase', `obase', and `scale'
122The word `last' or a single dot
123.Ed
124.Pp
125Other operands
126.Bd -unfilled -offset indent -compact
127arbitrarily long numbers with optional sign and decimal point
128( E )
129sqrt ( E )
130length ( E )	number of significant decimal digits
131scale ( E )	number of digits right of decimal point
132L ( E , ... , E )
133.Ed
134.Pp
135The sequence
136.Sq \e<newline><whitespace>
137is ignored within numbers.
138.Pp
139Operators
140.Pp
141The following arithmetic and logical operators can be used.
142The semantics of the operators is the same as in the C language.
143They are listed in order of decreasing precedence.
144Operators in the same group have the same precedence.
145.Bl -column -offset indent "= += \-= *= /= %= ^=" "Associativity" \
146"multiply, divide, modulus"
147.It Sy "Operator" Ta Sy "Associativity" Ta Sy "Description"
148.It "++ \-\-" Ta "none" Ta "increment, decrement"
149.It "\-" Ta "none" Ta "unary minus"
150.It "^" Ta "right" Ta "power"
151.It "* / %" Ta "left" Ta "multiply, divide, modulus"
152.It "+ \-" Ta "left" Ta "plus, minus"
153.It "= += -= *= /= %= ^=" Ta "right" Ta "assignment"
154.It "== <= >= != < >" Ta "none" Ta "relational"
155.It "!" Ta "none" Ta "boolean not"
156.It "&&" Ta "left" Ta "boolean and"
157.It "||" Ta "left" Ta "boolean or"
158.El
159.Pp
160Note the following:
161.Bl -bullet -offset indent
162.It
163The relational operators may appear in any expression.
164The
165.St -p1003.2
166standard only allows them in the conditional expression of an
167.Sq if ,
168.Sq while
169or
170.Sq for
171statement.
172.It
173The relational operators have a lower precedence than the assignment
174operators.
175This has the consequence that the expression
176.Sy a = b < c
177is interpreted as
178.Sy (a = b) < c ,
179which is probably not what the programmer intended.
180.It
181In contrast with the C language, the relational operators all have
182the same precedence, and are non-associative.
183The expression
184.Sy a < b < c
185will produce a syntax error.
186.It
187The boolean operators (!, && and ||) are non-portable extensions.
188.It
189The boolean not
190(!) operator has much lower precedence than the same operator in the
191C language.
192This has the consequence that the expression
193.Sy !a < b
194is interpreted as
195.Sy !(a < b) .
196Prudent programmers use parentheses when writing expressions involving
197boolean operators.
198.El
199.Pp
200Statements
201.Bd -unfilled -offset indent -compact
202E
203{ S ; ... ; S }
204if ( E ) S
205if ( E ) S else S
206while ( E ) S
207for ( E ; E ; E ) S
208null statement
209break
210continue
211quit
212a string of characters, enclosed in double quotes
213print E ,..., E
214.Ed
215.Pp
216A string may contain any character, except double quote.
217The if statement with an else branch is a non-portable extension.
218All three E's in a for statement may be empty.
219This is a non-portable extension.
220The continue and print statements are also non-portable extensions.
221.Pp
222The print statement takes a list of comma-separated expressions.
223Each expression in the list is evaluated and the computed
224value is printed and assigned to the variable `last'.
225No trailing newline is printed.
226The expression may also be a string enclosed in double quotes.
227Within these strings the following escape sequences may be used:
228.Sq \ea
229for bell (alert),
230.Sq \eb
231for backspace,
232.Sq \ef
233for formfeed,
234.Sq \en
235for newline,
236.Sq \er
237for carriage return,
238.Sq \et
239for tab,
240.Sq \eq
241for double quote and
242.Sq \e\e
243for backslash.
244Any other character following a backslash will be ignored.
245Strings will not be assigned to `last'.
246.Pp
247Function definitions
248.Bd -unfilled -offset indent
249define L ( L ,..., L ) {
250	auto L, ... , L
251	S; ... S
252	return ( E )
253}
254.Ed
255.Pp
256As a non-portable extension, the opening brace of the define statement
257may appear on the next line.
258The return statement may also appear in the following forms:
259.Bd -unfilled -offset indent
260return
261return ()
262return E
263.Ed
264.Pp
265The first two are equivalent to the statement
266.Dq return 0 .
267The last form is a non-portable extension.
268Not specifying a return statement is equivalent to writing
269.Dq return (0) .
270.Pp
271Functions available in the math library, which is loaded by specifying the
272.Fl l
273flag on the command line
274.Pp
275.Bl -tag -width j(n,x) -offset indent -compact
276.It s(x)
277sine
278.It c(x)
279cosine
280.It e(x)
281exponential
282.It l(x)
283log
284.It a(x)
285arctangent
286.It j(n,x)
287Bessel function
288.El
289.Pp
290All function arguments are passed by value.
291.Pp
292The value of a statement that is an expression is printed
293unless the main operator is an assignment.
294The value printed is assigned to the special variable `last'.
295This is a non-portable extension.
296A single dot may be used as a synonym for `last'.
297Either semicolons or newlines may separate statements.
298Assignment to
299.Ar scale
300influences the number of digits to be retained on arithmetic
301operations in the manner of
302.Xr dc 1 .
303Assignments to
304.Ar ibase
305or
306.Ar obase
307set the input and output number radix respectively.
308.Pp
309The same letter may be used as an array, a function,
310and a simple variable simultaneously.
311All variables are global to the program.
312`Auto' variables are pushed down during function calls.
313When using arrays as function arguments
314or defining them as automatic variables,
315empty square brackets must follow the array name.
316.Pp
317For example
318.Bd -literal -offset indent
319scale = 20
320define e(x){
321	auto a, b, c, i, s
322	a = 1
323	b = 1
324	s = 1
325	for(i=1; 1==1; i++){
326		a = a*x
327		b = b*i
328		c = a/b
329		if(c == 0) return(s)
330		s = s+c
331	}
332}
333.Ed
334.Pp
335defines a function to compute an approximate value of
336the exponential function and
337.Pp
338.Dl for(i=1; i<=10; i++) e(i)
339.Pp
340prints approximate values of the exponential function of
341the first ten integers.
342.Bd -literal -offset indent
343$ bc -l -e 'scale = 500; 2 * a(2^10000)' -e quit
344.Ed
345.Pp
346prints an approximation of pi.
347.Sh FILES
348.Bl -tag -width /usr/share/misc/bc.library -compact
349.It Pa /usr/share/misc/bc.library
350math library, read when the
351.Fl l
352option is specified on the command line.
353.El
354.Sh SEE ALSO
355.Xr dc 1
356.Pp
357"BC \- An Arbitrary Precision Desk-Calculator Language",
358.Pa /usr/share/doc/usd/06.bc/ .
359.Sh STANDARDS
360The
361.Nm
362utility is compliant with the
363.St -p1003.1-2008
364specification.
365.Pp
366The flags
367.Op Fl ce
368are extensions to that specification.
369.Sh HISTORY
370The
371.Nm
372command first appeared in
373.At v6 .
374A complete rewrite of the
375.Nm
376command first appeared in
377.Ox 3.5 .
378.Sh AUTHORS
379.An -nosplit
380The original version of the
381.Nm
382command was written by
383.An Robert Morris
384and
385.An Lorinda Cherry .
386The current version of the
387.Nm
388utility was written by
389.An Otto Moerbeek .
390.Sh BUGS
391.Ql Quit
392is interpreted when read, not when executed.
393.Pp
394Some non-portable extensions, as found in the GNU version of the
395.Nm
396utility are not implemented (yet).
397