usr.bin/bc/bc.1

   1 .\"     $OpenBSD: bc.1,v 1.22 2007/05/31 19:20:07 jmc Exp $
   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 November 14, 2009
  38 .Dt BC 1
  39 .Os
  40 .Sh NAME
  41 .Nm bc
  42 .Nd arbitrary-precision arithmetic language and calculator
  43 .Sh SYNOPSIS
  44 .Nm
  45 .Op Fl cl
  46 .Op Fl e Ar expression
  47 .Op Ar file ...
  48 .Sh DESCRIPTION
  49 .Nm
  50 is an interactive processor for a language which resembles
  51 C but provides unlimited precision arithmetic.
  52 It takes input from any expressions on the command line and
  53 any files given, then reads the standard input.
  54 .Pp
  55 Options available:
  56 .Bl -tag -width Ds
  57 .It Fl c
  58 .Nm
  59 is actually a preprocessor for
  60 .Xr dc 1 ,
  61 which it invokes automatically, unless the
  62 .Fl c
  63 .Pq compile only
  64 option is present.
  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.
  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.
  78 .It Fl l
  79 Allow specification of an arbitrary precision math library.
  80 The definitions in the library are available to command line
  81 expressions.
  82 .El
  83 .Pp
  84 The syntax for
  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.
  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.
 100 .Pp
 101 Comments
 102 .Bd -unfilled -offset indent -compact
 103 are enclosed in /* and */
 104 are enclosed in # and the next newline
 105 .Ed
 106 .Pp
 107 The newline is not part of the line comment,
 108 which in itself is a non-portable extension.
 109 .Pp
 110 Names
 111 .Bd -unfilled -offset indent -compact
 112 simple variables: L
 113 array elements: L [ E ]
 114 The words `ibase', `obase', and `scale'
 115 The word `last' or a single dot
 116 .Ed
 117 .Pp
 118 Other operands
 119 .Bd -unfilled -offset indent -compact
 120 arbitrarily long numbers with optional sign and decimal point
 121 ( E )
 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
 128 The sequence
 129 .Sq \e<newline><whitespace>
 130 is ignored within numbers.
 131 .Pp
 132 Operators
 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 "= += \-= *= /= %= ^=" "Associativity" "multiply, divide, modulus" -offset indent
 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.
 184 This has the consequence that the expression
 185 .Sy !a < b
 186 is interpreted as
 187 .Sy !(a < b) .
 188 Prudent programmers use parentheses when writing expressions involving
 189 boolean operators.
 190 .El
 191 .Pp
 192 Statements
 193 .Bd -unfilled -offset indent -compact
 194 E
 195 { S ; ... ; S }
 196 if ( E ) S
 197 if ( E ) S else S
 198 while ( E ) S
 199 for ( E ; E ; E ) S
 200 null statement
 201 break
 202 continue
 203 quit
 204 a string of characters, enclosed in double quotes
 205 print E ,..., E
 206 .Ed
 207 .Pp
 208 A string may contain any character, except a double quote.
 209 The if statement with an else branch is a non-portable extension.
 210 All three E's in a for statement may be empty.
 211 This is a non-portable extension.
 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'.
 238 .Pp
 239 Function definitions
 240 .Bd -unfilled -offset indent
 241 define L ( L ,..., L ) {
 242         auto L, ... , L
 243         S; ... S
 244         return ( E )
 245 }
 246 .Ed
 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) .
 262 .Pp
 263 Functions available in the math library, which is loaded by specifying the
 264 .Fl l
 265 flag on the command line
 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.
 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'.
 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
 294 .Xr dc 1 .
 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
 306 or defining them as automatic variables,
 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.
 334 .Bd -literal -offset indent
 335 $ bc -l -e 'scale = 500; 2 * a(2^10000)' -e quit
 336 .Ed
 337 prints an approximation of pi.
 338 .Sh FILES
 339 .Bl -tag -width /usr/share/misc/bc.library -compact
 340 .It Pa /usr/share/misc/bc.library
 341 math library, read when the
 342 .Fl l
 343 option is specified on the command line.
 344 .El
 345 .Sh SEE ALSO
 346 .Xr dc 1
 347 .Rs
 348 .%A "Lorinda Cherry"
 349 .%A "Robert Morris"
 350 .%B "4.4BSD Users's Supplementary Documents (USD)"
 351 .%T "BC \- An Arbitrary Precision Desk-Calculator Language"
 352 .Re
 353 .Sh STANDARDS
 354 The
 355 .Nm
 356 utility is compliant with the
 357 .St -p1003.1-2004
 358 specification.
 359 .Pp
 360 The flags
 361 .Op Fl ce
 362 are extensions to that specification.
 363 .Sh HISTORY
 364 The
 365 .Nm
 366 command first appeared in
 367 .At v6 .
 368 A complete rewrite of the
 369 .Nm
 370 command first appeared in
 371 .Ox 3.5 .
 372 .Sh AUTHORS
 373 .An -nosplit
 374 The original version of the
 375 .Nm
 376 command was written by
 377 .An Robert Morris
 378 and
 379 .An Lorinda Cherry .
 380 The current version of the
 381 .Nm
 382 utility was written by
 383 .An Otto Moerbeek .
 384 .Sh BUGS
 385 .Ql Quit
 386 is interpreted when read, not when executed.
 387 .Pp
 388 Some non-portable extensions, as found in the GNU version of the
 389 .Nm
 390 utility are not implemented (yet).