commit 85721b5a334484e2da0d8c21e343e5aaf7082d61
parent 42ebd643f6628ed4b0ef21f77d98368a2b0deab6
Author: Roberto E. Vargas Caballero <k0ga@shike2.net>
Date: Sat, 13 Dec 2025 16:03:58 +0100
bc: Add man page
Diffstat:
| A | bc.1 | | | 275 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
1 file changed, 275 insertions(+), 0 deletions(-)
diff --git a/bc.1 b/bc.1
@@ -0,0 +1,275 @@
+.Dd December 12, 2025
+.Dt BC 1
+.Os sbase
+.Sh NAME
+.Nm bc
+.Nd arbitrary-precision arithmetic language
+.Sh SYNOPSIS
+.Nm
+.Op Fl cdls
+.Op Ar file ...
+.Sh DESCRIPTION
+.Nm
+is an arbitrary-precision arithmetic language with syntax similar to C.
+.Nm
+reads each
+.Ar file
+in sequence and compiles the bc code into dc code,
+which is then executed
+by spawning
+.Xr dc 1
+as a subprocess.
+After all the files are loaded and executed then
+it reads from stdin.
+.Sh OPTIONS
+.Bl -tag -width Ds
+.It Fl c
+Compile only mode.
+Generate dc code without spawning a dc subprocess.
+The compiled dc code is written to stdout.
+.It Fl d
+Debug mode.
+Enable yacc parser debugging output.
+.It Fl l
+Load the mathematical library
+that is loaded before any file from the command line.
+.It Fl s
+Suppresses the automatic printing of expression results.
+In this mode, only explicit
+.Ic print
+statements produce output.
+.El
+.Sh LANGUAGE
+.Ss Comments
+Comments are enclosed in
+.Ql /*
+and
+.Ql */ .
+.Ss Numbers
+Numbers may contain digits 0-9 and, when the input base is greater than 10,
+letters A-F as hexadecimal digits.
+Numbers may include a decimal point.
+.Ss Variables
+Variables are single lowercase letters
+.Ql a
+through
+.Ql z .
+Variables hold arbitrary-precision numbers and are automatically initialized to 0.
+.Ss Arrays
+Array elements are referenced as
+.Ar name Ns Oo Ar expr Oc .
+Arrays are single lowercase letters
+.Ql a
+through
+.Ql z .
+Array indices may be any expression.
+Arrays are automatically initialized with all elements set to 0.
+.Ss Special Variables
+.Bl -tag -width "scale"
+.It Ic scale
+The number of digits after the decimal point in results.
+Default is 0.
+Affects division, modulus, power, and square root operations.
+.It Ic ibase
+The input number base.
+Must be between 2 and 16 inclusive.
+Default is 10.
+.It Ic obase
+The output number base.
+Must be at least 2.
+Default is 10.
+.El
+.Ss Operators
+Arithmetic operators in order of precedence (highest to lowest):
+.Bl -tag -width "^"
+.It Ic \&^ or ^=
+Exponentiation (right associative).
+The exponent is truncated to an integer.
+.It Ic * / % or *= /= %=
+Multiplication, division, modulus.
+.It Ic + \- or += \-=
+Addition, subtraction.
+.It Ic ++ \-\-
+Increment and decrement (prefix or postfix).
+.It Ic =
+Assignment.
+.El
+.Pp
+Relational operators:
+.Bl -tag -width "!="
+.It Ic ==
+Equal to.
+.It Ic !=
+Not equal to.
+.It Ic <
+Less than.
+.It Ic <=
+Less than or equal to.
+.It Ic >
+Greater than.
+.It Ic >=
+Greater than or equal to.
+.El
+.Ss Built-in Functions
+.Bl -tag -width "length(expr)"
+.It Fn sqrt expr
+Square root of
+.Ar expr .
+.It Fn length expr
+Number of significant decimal digits in
+.Ar expr .
+.It Fn scale expr
+Number of digits after the decimal point in
+.Ar expr .
+.El
+.Ss Statements
+.Bl -tag -width Ds
+.It Ic print expr
+Print the value of
+.Ar expr
+followed by a newline.
+.It Ic print Qo Ar string Qc
+Print
+.Ar string
+without a newline.
+.It Ic print Qo Ar string Qc , expr
+Print
+.Ar string
+without a newline, then print
+.Ar expr
+with a newline.
+.It Qo Ar string Qc
+A string by itself is printed without a newline.
+.It Ic if ( Ar rel ) Ar stat
+Execute
+.Ar stat
+if
+.Ar rel
+is non-zero.
+.It Ic while ( Ar rel ) Ar stat
+Execute
+.Ar stat
+repeatedly while
+.Ar rel
+is non-zero.
+.It Ic for ( Ar expr1 ; Ar rel ; Ar expr2 ) Ar stat
+Equivalent to
+.Ql Ar expr1 ; while ( Ar rel ) { Ar stat ; Ar expr2 } .
+The 3 components of the for loop are required.
+.It Ic break
+Exit from the innermost
+.Ic while
+or
+.Ic for
+loop.
+.It Ic quit
+Exit
+.Nm
+when the statement is read,
+independently of being under an if statement or in a function.
+.It Ic return
+Return 0 from a function.
+.It Ic return ( Ar expr )
+Return
+.Ar expr
+from a function.
+.It Ic { Ar stat-list }
+Group statements.
+.El
+.Ss Function Definitions
+Functions are defined as:
+.Bd -literal -offset indent
+define name(parameters) {
+ auto local-variables
+ statements
+}
+.Ed
+.Pp
+Notice that the opening brace must be in the same line
+than the define statement.
+Function names are single lowercase letters.
+Parameters and local variables are comma-separated lists of simple
+variables or arrays (denoted by
+.Ar name Ns Ic [] ) .
+The
+.Ic auto
+statement is optional and must appear first in the function body if present.
+.Pp
+Functions are called as
+.Fn name arguments .
+Array arguments must be passed as
+.Ar name Ns Ic [] .
+Functions return a value using the
+.Ic return
+statement.
+If no
+.Ic return
+is executed, the function returns 0.
+.Sh LIBRARY
+When invoked with the
+.Fl l
+option,
+.Nm
+preloads a mathematical library that defines the following functions:
+.Bl -tag -width "j(n,x)"
+.It Fn e x
+Exponential function.
+Returns e raised to the power
+.Ar x .
+.It Fn l x
+Natural logarithm of
+.Ar x .
+.It Fn s x
+Sine of
+.Ar x
+where
+.Ar x
+is in radians.
+.It Fn c x
+Cosine of
+.Ar x
+where
+.Ar x
+is in radians.
+.It Fn a x
+Arctangent of
+.Ar x .
+Returns the value in radians.
+.It Fn j n,x
+Bessel function of order
+.Ar n
+of
+.Ar x .
+.El
+.Pp
+The library also sets
+.Ic scale
+to 20 by default.
+.Sh IMPLEMENTATION NOTES
+This implementation of
+.Nm
+is a compiler that translates bc language into dc commands.
+.Pp
+Variables are mapped to dc registers.
+Functions are compiled to dc macros stored in registers identified by
+function name.
+Control flow statements are implemented using dc's conditional macro
+execution commands.
+.Pp
+The maximum nesting level for control structures and function calls is 32.
+.Sh SEE ALSO
+.Xr dc 1
+.Rs
+.%A L. L. Cherry
+.%A R. H. Morris
+.%T "BC \(em An Arbitrary Precision Desk-Calculator Language"
+.Re
+.Sh STANDARDS
+POSIX.1-2013.
+The
+.Ic print
+statement and the
+.Fl d
+and
+.Fl s
+flags are extensions to the POSIX specification.
