usr.bin/bc/bc.1

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