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