bc.1 - sbase - suckless unix tools
HTML git clone git://git.suckless.org/sbase
DIR Log
DIR Files
DIR Refs
DIR README
DIR LICENSE
---
bc.1 (5585B)
---
1 .Dd December 12, 2025
2 .Dt BC 1
3 .Os sbase
4 .Sh NAME
5 .Nm bc
6 .Nd arbitrary-precision arithmetic language
7 .Sh SYNOPSIS
8 .Nm
9 .Op Fl cdls
10 .Op Ar file ...
11 .Sh DESCRIPTION
12 .Nm
13 is an arbitrary-precision arithmetic language with syntax similar to C.
14 .Nm
15 reads each
16 .Ar file
17 in sequence and compiles the bc code into dc code,
18 which is then executed
19 by spawning
20 .Xr dc 1
21 as a subprocess.
22 After all the files are loaded and executed then
23 it reads from stdin.
24 .Sh OPTIONS
25 .Bl -tag -width Ds
26 .It Fl c
27 Compile only mode.
28 Generate dc code without spawning a dc subprocess.
29 The compiled dc code is written to stdout.
30 .It Fl d
31 Debug mode.
32 Enable yacc parser debugging output.
33 .It Fl l
34 Load the mathematical library
35 that is loaded before any file from the command line.
36 .It Fl s
37 Suppresses the automatic printing of expression results.
38 In this mode, only explicit
39 .Ic print
40 statements produce output.
41 .El
42 .Sh LANGUAGE
43 .Ss Comments
44 Comments are enclosed in
45 .Ql /*
46 and
47 .Ql */ .
48 .Ss Numbers
49 Numbers may contain digits 0-9 and, when the input base is greater than 10,
50 letters A-F as hexadecimal digits.
51 Numbers may include a decimal point.
52 .Ss Variables
53 Variables are single lowercase letters
54 .Ql a
55 through
56 .Ql z .
57 Variables hold arbitrary-precision numbers and are automatically initialized to 0.
58 .Ss Arrays
59 Array elements are referenced as
60 .Ar name Ns Oo Ar expr Oc .
61 Arrays are single lowercase letters
62 .Ql a
63 through
64 .Ql z .
65 Array indices may be any expression.
66 Arrays are automatically initialized with all elements set to 0.
67 .Ss Special Variables
68 .Bl -tag -width "scale"
69 .It Ic scale
70 The number of digits after the decimal point in results.
71 Default is 0.
72 Affects division, modulus, power, and square root operations.
73 .It Ic ibase
74 The input number base.
75 Must be between 2 and 16 inclusive.
76 Default is 10.
77 .It Ic obase
78 The output number base.
79 Must be at least 2.
80 Default is 10.
81 .El
82 .Ss Operators
83 Arithmetic operators in order of precedence (highest to lowest):
84 .Bl -tag -width "^"
85 .It Ic \&^ or ^=
86 Exponentiation (right associative).
87 The exponent is truncated to an integer.
88 .It Ic * / % or *= /= %=
89 Multiplication, division, modulus.
90 .It Ic + \- or += \-=
91 Addition, subtraction.
92 .It Ic ++ \-\-
93 Increment and decrement (prefix or postfix).
94 .It Ic =
95 Assignment.
96 .El
97 .Pp
98 Relational operators:
99 .Bl -tag -width "!="
100 .It Ic ==
101 Equal to.
102 .It Ic !=
103 Not equal to.
104 .It Ic <
105 Less than.
106 .It Ic <=
107 Less than or equal to.
108 .It Ic >
109 Greater than.
110 .It Ic >=
111 Greater than or equal to.
112 .El
113 .Ss Built-in Functions
114 .Bl -tag -width "length(expr)"
115 .It Fn sqrt expr
116 Square root of
117 .Ar expr .
118 .It Fn length expr
119 Number of significant decimal digits in
120 .Ar expr .
121 .It Fn scale expr
122 Number of digits after the decimal point in
123 .Ar expr .
124 .El
125 .Ss Statements
126 .Bl -tag -width Ds
127 .It Ic print expr
128 Print the value of
129 .Ar expr
130 followed by a newline.
131 .It Ic print Qo Ar string Qc
132 Print
133 .Ar string
134 without a newline.
135 .It Ic print Qo Ar string Qc , expr
136 Print
137 .Ar string
138 without a newline, then print
139 .Ar expr
140 with a newline.
141 .It Qo Ar string Qc
142 A string by itself is printed without a newline.
143 .It Ic if ( Ar rel ) Ar stat
144 Execute
145 .Ar stat
146 if
147 .Ar rel
148 is non-zero.
149 .It Ic while ( Ar rel ) Ar stat
150 Execute
151 .Ar stat
152 repeatedly while
153 .Ar rel
154 is non-zero.
155 .It Ic for ( Ar expr1 ; Ar rel ; Ar expr2 ) Ar stat
156 Equivalent to
157 .Ql Ar expr1 ; while ( Ar rel ) { Ar stat ; Ar expr2 } .
158 The 3 components of the for loop are required.
159 .It Ic break
160 Exit from the innermost
161 .Ic while
162 or
163 .Ic for
164 loop.
165 .It Ic quit
166 Exit
167 .Nm
168 when the statement is read,
169 independently of being under an if statement or in a function.
170 .It Ic return
171 Return 0 from a function.
172 .It Ic return ( Ar expr )
173 Return
174 .Ar expr
175 from a function.
176 .It Ic { Ar stat-list }
177 Group statements.
178 .El
179 .Ss Function Definitions
180 Functions are defined as:
181 .Bd -literal -offset indent
182 define name(parameters) {
183 auto local-variables
184 statements
185 }
186 .Ed
187 .Pp
188 Notice that the opening brace must be in the same line
189 than the define statement.
190 Function names are single lowercase letters.
191 Parameters and local variables are comma-separated lists of simple
192 variables or arrays (denoted by
193 .Ar name Ns Ic [] ) .
194 The
195 .Ic auto
196 statement is optional and must appear first in the function body if present.
197 .Pp
198 Functions are called as
199 .Fn name arguments .
200 Array arguments must be passed as
201 .Ar name Ns Ic [] .
202 Functions return a value using the
203 .Ic return
204 statement.
205 If no
206 .Ic return
207 is executed, the function returns 0.
208 .Sh LIBRARY
209 When invoked with the
210 .Fl l
211 option,
212 .Nm
213 preloads a mathematical library that defines the following functions:
214 .Bl -tag -width "j(n,x)"
215 .It Fn e x
216 Exponential function.
217 Returns e raised to the power
218 .Ar x .
219 .It Fn l x
220 Natural logarithm of
221 .Ar x .
222 .It Fn s x
223 Sine of
224 .Ar x
225 where
226 .Ar x
227 is in radians.
228 .It Fn c x
229 Cosine of
230 .Ar x
231 where
232 .Ar x
233 is in radians.
234 .It Fn a x
235 Arctangent of
236 .Ar x .
237 Returns the value in radians.
238 .It Fn j n,x
239 Bessel function of order
240 .Ar n
241 of
242 .Ar x .
243 .El
244 .Pp
245 The library also sets
246 .Ic scale
247 to 20 by default.
248 .Sh IMPLEMENTATION NOTES
249 This implementation of
250 .Nm
251 is a compiler that translates bc language into dc commands.
252 .Pp
253 Variables are mapped to dc registers.
254 Functions are compiled to dc macros stored in registers identified by
255 function name.
256 Control flow statements are implemented using dc's conditional macro
257 execution commands.
258 .Pp
259 The maximum nesting level for control structures and function calls is 32.
260 .Sh SEE ALSO
261 .Xr dc 1
262 .Rs
263 .%A L. L. Cherry
264 .%A R. H. Morris
265 .%T "BC \(em An Arbitrary Precision Desk-Calculator Language"
266 .Re
267 .Sh STANDARDS
268 POSIX.1-2013.
269 The
270 .Ic print
271 statement and the
272 .Fl d
273 and
274 .Fl s
275 flags are extensions to the POSIX specification.