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