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