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