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