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