usr.bin/bc/bc.1

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