usr.bin/bc/bc.1

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