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 .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 -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.
 185 This has the consequence that the expression
 186 .Sy !a < b
 187 is interpreted as
 188 .Sy !(a < b) .
 189 Prudent programmers use parentheses when writing expressions involving
 190 boolean operators.
 191 .El
 192 .Pp
 193 Statements
 194 .Bd -unfilled -offset indent -compact
 195 E
 196 { S ; ... ; S }
 197 if ( E ) S
 198 if ( E ) S else S
 199 while ( E ) S
 200 for ( E ; E ; E ) S
 201 null statement
 202 break
 203 continue
 204 quit
 205 a string of characters, enclosed in double quotes
 206 print E ,..., E
 207 .Ed
 208 .Pp
 209 A string may contain any character, except a double quote.
 210 The if statement with an else branch is a non-portable extension.
 211 All three E's in a for statement may be empty.
 212 This is a non-portable extension.
 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'.
 239 .Pp
 240 Function definitions
 241 .Bd -unfilled -offset indent
 242 define L ( L ,..., L ) {
 243         auto L, ... , L
 244         S; ... S
 245         return ( E )
 246 }
 247 .Ed
 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) .
 263 .Pp
 264 Functions available in the math library, which is loaded by specifying the
 265 .Fl l
 266 flag on the command line
 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.
 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'.
 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
 295 .Xr dc 1 .
 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
 307 or defining them as automatic variables,
 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.
 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.
 340 .Sh FILES
 341 .Bl -tag -width /usr/share/misc/bc.library -compact
 342 .It Pa /usr/share/misc/bc.library
 343 math library, read when the
 344 .Fl l
 345 option is specified on the command line.
 346 .El
 347 .Sh SEE ALSO
 348 .Xr dc 1
 349 .Pp
 350 "BC \- An Arbitrary Precision Desk-Calculator Language",
 351 .Pa /usr/share/doc/usd/06.bc/ .
 352 .Sh STANDARDS
 353 The
 354 .Nm
 355 utility is compliant with the
 356 .St -p1003.1-2004
 357 specification.
 358 .Pp
 359 The flags
 360 .Op Fl ce
 361 are extensions to that specification.
 362 .Sh HISTORY
 363 The
 364 .Nm
 365 command first appeared in
 366 .At v6 .
 367 A complete rewrite of the
 368 .Nm
 369 command first appeared in
 370 .Ox 3.5 .
 371 .Sh AUTHORS
 372 .An -nosplit
 373 The original version of the
 374 .Nm
 375 command was written by
 376 .An Robert Morris
 377 and
 378 .An Lorinda Cherry .
 379 The current version of the
 380 .Nm
 381 utility was written by
 382 .An Otto Moerbeek .
 383 .Sh BUGS
 384 .Ql Quit
 385 is interpreted when read, not when executed.
 386 .Pp
 387 Some non-portable extensions, as found in the GNU version of the
 388 .Nm
 389 utility are not implemented (yet).