2 .\" SPDX-License-Identifier: BSD-2-Clause
4 .\" Copyright (c) 2018-2023 Gavin D. Howard and contributors.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions are met:
9 .\" * Redistributions of source code must retain the above copyright notice,
10 .\" this list of conditions and the following disclaimer.
12 .\" * Redistributions in binary form must reproduce the above copyright notice,
13 .\" this list of conditions and the following disclaimer in the documentation
14 .\" and/or other materials provided with the distribution.
16 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17 .\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
20 .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26 .\" POSSIBILITY OF SUCH DAMAGE.
28 .TH "BC" "1" "February 2023" "Gavin D. Howard" "General Commands Manual"
33 bc - arbitrary-precision decimal arithmetic language and calculator
36 \f[B]bc\f[R] [\f[B]-cCghilPqRsvVw\f[R]] [\f[B]--digit-clamp\f[R]]
37 [\f[B]--no-digit-clamp\f[R]] [\f[B]--global-stacks\f[R]]
38 [\f[B]--help\f[R]] [\f[B]--interactive\f[R]] [\f[B]--mathlib\f[R]]
39 [\f[B]--no-prompt\f[R]] [\f[B]--no-read-prompt\f[R]] [\f[B]--quiet\f[R]]
40 [\f[B]--standard\f[R]] [\f[B]--warn\f[R]] [\f[B]--version\f[R]]
41 [\f[B]-e\f[R] \f[I]expr\f[R]]
42 [\f[B]--expression\f[R]=\f[I]expr\f[R]\&...]
43 [\f[B]-f\f[R] \f[I]file\f[R]\&...]
44 [\f[B]--file\f[R]=\f[I]file\f[R]\&...]
48 bc(1) is an interactive processor for a language first standardized in
50 (See the \f[B]STANDARDS\f[R] section.)
51 The language provides unlimited precision decimal arithmetic and is
52 somewhat C-like, but there are differences.
53 Such differences will be noted in this document.
55 After parsing and handling options, this bc(1) reads any files given on
56 the command line and executes them before reading from \f[B]stdin\f[R].
58 This bc(1) is a drop-in replacement for \f[I]any\f[R] bc(1), including
59 (and especially) the GNU bc(1).
60 It also has many extensions and extra features beyond other
63 \f[B]Note\f[R]: If running this bc(1) on \f[I]any\f[R] script meant for
64 another bc(1) gives a parse error, it is probably because a word this
65 bc(1) reserves as a keyword is used as the name of a function, variable,
67 To fix that, use the command-line option \f[B]-r\f[R] \f[I]keyword\f[R],
68 where \f[I]keyword\f[R] is the keyword that is used as a name in the
70 For more information, see the \f[B]OPTIONS\f[R] section.
72 If parsing scripts meant for other bc(1) implementations still does not
73 work, that is a bug and should be reported.
74 See the \f[B]BUGS\f[R] section.
77 The following are the options that bc(1) accepts.
79 \f[B]-C\f[R], \f[B]--no-digit-clamp\f[R]
80 Disables clamping of digits greater than or equal to the current
81 \f[B]ibase\f[R] when parsing numbers.
84 This means that the value added to a number from a digit is always that
85 digit\[cq]s value multiplied by the value of ibase raised to the power
86 of the digit\[cq]s position, which starts from 0 at the least
89 If this and/or the \f[B]-c\f[R] or \f[B]--digit-clamp\f[R] options are
90 given multiple times, the last one given is used.
92 This option overrides the \f[B]BC_DIGIT_CLAMP\f[R] environment variable
93 (see the \f[B]ENVIRONMENT VARIABLES\f[R] section) and the default, which
94 can be queried with the \f[B]-h\f[R] or \f[B]--help\f[R] options.
96 This is a \f[B]non-portable extension\f[R].
99 \f[B]-c\f[R], \f[B]--digit-clamp\f[R]
100 Enables clamping of digits greater than or equal to the current
101 \f[B]ibase\f[R] when parsing numbers.
104 This means that digits that the value added to a number from a digit
105 that is greater than or equal to the ibase is the value of ibase minus 1
106 all multiplied by the value of ibase raised to the power of the
107 digit\[cq]s position, which starts from 0 at the least significant
110 If this and/or the \f[B]-C\f[R] or \f[B]--no-digit-clamp\f[R] options
111 are given multiple times, the last one given is used.
113 This option overrides the \f[B]BC_DIGIT_CLAMP\f[R] environment variable
114 (see the \f[B]ENVIRONMENT VARIABLES\f[R] section) and the default, which
115 can be queried with the \f[B]-h\f[R] or \f[B]--help\f[R] options.
117 This is a \f[B]non-portable extension\f[R].
120 \f[B]-e\f[R] \f[I]expr\f[R], \f[B]--expression\f[R]=\f[I]expr\f[R]
121 Evaluates \f[I]expr\f[R].
122 If multiple expressions are given, they are evaluated in order.
123 If files are given as well (see the \f[B]-f\f[R] and \f[B]--file\f[R]
124 options), the expressions and files are evaluated in the order given.
125 This means that if a file is given before an expression, the file is
126 read in and evaluated first.
129 If this option is given on the command-line (i.e., not in
130 \f[B]BC_ENV_ARGS\f[R], see the \f[B]ENVIRONMENT VARIABLES\f[R] section),
131 then after processing all expressions and files, bc(1) will exit, unless
132 \f[B]-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to
133 \f[B]-f\f[R] or \f[B]--file\f[R], whether on the command-line or in
134 \f[B]BC_ENV_ARGS\f[R].
135 However, if any other \f[B]-e\f[R], \f[B]--expression\f[R],
136 \f[B]-f\f[R], or \f[B]--file\f[R] arguments are given after
137 \f[B]-f-\f[R] or equivalent is given, bc(1) will give a fatal error and
140 This is a \f[B]non-portable extension\f[R].
143 \f[B]-f\f[R] \f[I]file\f[R], \f[B]--file\f[R]=\f[I]file\f[R]
144 Reads in \f[I]file\f[R] and evaluates it, line by line, as though it
145 were read through \f[B]stdin\f[R].
146 If expressions are also given (see the \f[B]-e\f[R] and
147 \f[B]--expression\f[R] options), the expressions are evaluated in the
151 If this option is given on the command-line (i.e., not in
152 \f[B]BC_ENV_ARGS\f[R], see the \f[B]ENVIRONMENT VARIABLES\f[R] section),
153 then after processing all expressions and files, bc(1) will exit, unless
154 \f[B]-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to
155 \f[B]-f\f[R] or \f[B]--file\f[R].
156 However, if any other \f[B]-e\f[R], \f[B]--expression\f[R],
157 \f[B]-f\f[R], or \f[B]--file\f[R] arguments are given after
158 \f[B]-f-\f[R] or equivalent is given, bc(1) will give a fatal error and
161 This is a \f[B]non-portable extension\f[R].
164 \f[B]-g\f[R], \f[B]--global-stacks\f[R]
165 Turns the globals \f[B]ibase\f[R], \f[B]obase\f[R], and \f[B]scale\f[R]
169 This has the effect that a copy of the current value of all three are
170 pushed onto a stack for every function call, as well as popped when
171 every function returns.
172 This means that functions can assign to any and all of those globals
173 without worrying that the change will affect other functions.
174 Thus, a hypothetical function named \f[B]output(x,b)\f[R] that simply
175 printed \f[B]x\f[R] in base \f[B]b\f[R] could be written like this:
179 define void output(x, b) {
186 instead of like this:
190 define void output(x, b) {
200 This makes writing functions much easier.
202 However, since using this flag means that functions cannot set
203 \f[B]ibase\f[R], \f[B]obase\f[R], or \f[B]scale\f[R] globally, functions
204 that are made to do so cannot work anymore.
205 There are two possible use cases for that, and each has a solution.
207 First, if a function is called on startup to turn bc(1) into a number
208 converter, it is possible to replace that capability with various shell
214 alias d2o=\[dq]bc -e ibase=A -e obase=8\[dq]
215 alias h2b=\[dq]bc -e ibase=G -e obase=2\[dq]
219 Second, if the purpose of a function is to set \f[B]ibase\f[R],
220 \f[B]obase\f[R], or \f[B]scale\f[R] globally for any other purpose, it
221 could be split into one to three functions (based on how many globals it
222 sets) and each of those functions could return the desired value for a
225 If the behavior of this option is desired for every run of bc(1), then
226 users could make sure to define \f[B]BC_ENV_ARGS\f[R] and include this
227 option (see the \f[B]ENVIRONMENT VARIABLES\f[R] section for more
230 If \f[B]-s\f[R], \f[B]-w\f[R], or any equivalents are used, this option
233 This is a \f[B]non-portable extension\f[R].
236 \f[B]-h\f[R], \f[B]--help\f[R]
237 Prints a usage message and exits.
239 \f[B]-I\f[R] \f[I]ibase\f[R], \f[B]--ibase\f[R]=\f[I]ibase\f[R]
240 Sets the builtin variable \f[B]ibase\f[R] to the value \f[I]ibase\f[R]
241 assuming that \f[I]ibase\f[R] is in base 10.
242 It is a fatal error if \f[I]ibase\f[R] is not a valid number.
245 If multiple instances of this option are given, the last is used.
247 This is a \f[B]non-portable extension\f[R].
250 \f[B]-i\f[R], \f[B]--interactive\f[R]
251 Forces interactive mode.
252 (See the \f[B]INTERACTIVE MODE\f[R] section.)
255 This is a \f[B]non-portable extension\f[R].
258 \f[B]-L\f[R], \f[B]--no-line-length\f[R]
259 Disables line length checking and prints numbers without backslashes and
261 In other words, this option sets \f[B]BC_LINE_LENGTH\f[R] to \f[B]0\f[R]
262 (see the \f[B]ENVIRONMENT VARIABLES\f[R] section).
265 This is a \f[B]non-portable extension\f[R].
268 \f[B]-l\f[R], \f[B]--mathlib\f[R]
269 Sets \f[B]scale\f[R] (see the \f[B]SYNTAX\f[R] section) to \f[B]20\f[R]
270 and loads the included math library before running any code, including
271 any expressions or files specified on the command line.
274 To learn what is in the library, see the \f[B]LIBRARY\f[R] section.
277 \f[B]-O\f[R] \f[I]obase\f[R], \f[B]--obase\f[R]=\f[I]obase\f[R]
278 Sets the builtin variable \f[B]obase\f[R] to the value \f[I]obase\f[R]
279 assuming that \f[I]obase\f[R] is in base 10.
280 It is a fatal error if \f[I]obase\f[R] is not a valid number.
283 If multiple instances of this option are given, the last is used.
285 This is a \f[B]non-portable extension\f[R].
288 \f[B]-P\f[R], \f[B]--no-prompt\f[R]
289 Disables the prompt in TTY mode.
290 (The prompt is only enabled in TTY mode.
291 See the \f[B]TTY MODE\f[R] section.)
292 This is mostly for those users that do not want a prompt or are not used
293 to having them in bc(1).
294 Most of those users would want to put this option in
295 \f[B]BC_ENV_ARGS\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section).
298 These options override the \f[B]BC_PROMPT\f[R] and \f[B]BC_TTY_MODE\f[R]
299 environment variables (see the \f[B]ENVIRONMENT VARIABLES\f[R] section).
301 This is a \f[B]non-portable extension\f[R].
304 \f[B]-q\f[R], \f[B]--quiet\f[R]
305 This option is for compatibility with the GNU bc(1)
306 (https://www.gnu.org/software/bc/); it is a no-op.
307 Without this option, GNU bc(1) prints a copyright header.
308 This bc(1) only prints the copyright header if one or more of the
309 \f[B]-v\f[R], \f[B]-V\f[R], or \f[B]--version\f[R] options are given
310 unless the \f[B]BC_BANNER\f[R] environment variable is set and contains
311 a non-zero integer or if this bc(1) was built with the header displayed
313 If \f[I]any\f[R] of that is the case, then this option \f[I]does\f[R]
314 prevent bc(1) from printing the header.
317 This is a \f[B]non-portable extension\f[R].
320 \f[B]-R\f[R], \f[B]--no-read-prompt\f[R]
321 Disables the read prompt in TTY mode.
322 (The read prompt is only enabled in TTY mode.
323 See the \f[B]TTY MODE\f[R] section.)
324 This is mostly for those users that do not want a read prompt or are not
325 used to having them in bc(1).
326 Most of those users would want to put this option in
327 \f[B]BC_ENV_ARGS\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section).
328 This option is also useful in hash bang lines of bc(1) scripts that
329 prompt for user input.
332 This option does not disable the regular prompt because the read prompt
333 is only used when the \f[B]read()\f[R] built-in function is called.
335 These options \f[I]do\f[R] override the \f[B]BC_PROMPT\f[R] and
336 \f[B]BC_TTY_MODE\f[R] environment variables (see the \f[B]ENVIRONMENT
337 VARIABLES\f[R] section), but only for the read prompt.
339 This is a \f[B]non-portable extension\f[R].
342 \f[B]-r\f[R] \f[I]keyword\f[R], \f[B]--redefine\f[R]=\f[I]keyword\f[R]
343 Redefines \f[I]keyword\f[R] in order to allow it to be used as a
344 function, variable, or array name.
345 This is useful when this bc(1) gives parse errors when parsing scripts
346 meant for other bc(1) implementations.
349 The keywords this bc(1) allows to be redefined are:
381 If any of those keywords are used as a function, variable, or array name
382 in a script, use this option with the keyword as the argument.
383 If multiple are used, use this option for all of them; it can be used
386 Keywords are \f[I]not\f[R] redefined when parsing the builtin math
387 library (see the \f[B]LIBRARY\f[R] section).
389 It is a fatal error to redefine keywords mandated by the POSIX standard
390 (see the \f[B]STANDARDS\f[R] section).
391 It is a fatal error to attempt to redefine words that this bc(1) does
392 not reserve as keywords.
395 \f[B]-S\f[R] \f[I]scale\f[R], \f[B]--scale\f[R]=\f[I]scale\f[R]
396 Sets the builtin variable \f[B]scale\f[R] to the value \f[I]scale\f[R]
397 assuming that \f[I]scale\f[R] is in base 10.
398 It is a fatal error if \f[I]scale\f[R] is not a valid number.
401 If multiple instances of this option are given, the last is used.
403 This is a \f[B]non-portable extension\f[R].
406 \f[B]-s\f[R], \f[B]--standard\f[R]
407 Process exactly the language defined by the standard (see the
408 \f[B]STANDARDS\f[R] section) and error if any extensions are used.
411 This is a \f[B]non-portable extension\f[R].
414 \f[B]-v\f[R], \f[B]-V\f[R], \f[B]--version\f[R]
415 Print the version information (copyright header) and exits.
418 This is a \f[B]non-portable extension\f[R].
421 \f[B]-w\f[R], \f[B]--warn\f[R]
422 Like \f[B]-s\f[R] and \f[B]--standard\f[R], except that warnings (and
423 not errors) are printed for non-standard extensions and execution
427 This is a \f[B]non-portable extension\f[R].
430 \f[B]-z\f[R], \f[B]--leading-zeroes\f[R]
431 Makes bc(1) print all numbers greater than \f[B]-1\f[R] and less than
432 \f[B]1\f[R], and not equal to \f[B]0\f[R], with a leading zero.
435 This can be set for individual numbers with the \f[B]plz(x)\f[R],
436 \f[B]plznl(x)\f[R], \f[B]pnlz(x)\f[R], and \f[B]pnlznl(x)\f[R] functions
437 in the extended math library (see the \f[B]LIBRARY\f[R] section).
439 This is a \f[B]non-portable extension\f[R].
442 All long options are \f[B]non-portable extensions\f[R].
445 If no files or expressions are given by the \f[B]-f\f[R],
446 \f[B]--file\f[R], \f[B]-e\f[R], or \f[B]--expression\f[R] options, then
447 bc(1) reads from \f[B]stdin\f[R].
449 However, there are a few caveats to this.
451 First, \f[B]stdin\f[R] is evaluated a line at a time.
452 The only exception to this is if the parse cannot complete.
453 That means that starting a string without ending it or starting a
454 function, \f[B]if\f[R] statement, or loop without ending it will also
455 cause bc(1) to not execute.
457 Second, after an \f[B]if\f[R] statement, bc(1) doesn\[cq]t know if an
458 \f[B]else\f[R] statement will follow, so it will not execute until it
459 knows there will not be an \f[B]else\f[R] statement.
462 Any non-error output is written to \f[B]stdout\f[R].
463 In addition, if history (see the \f[B]HISTORY\f[R] section) and the
464 prompt (see the \f[B]TTY MODE\f[R] section) are enabled, both are output
467 \f[B]Note\f[R]: Unlike other bc(1) implementations, this bc(1) will
468 issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot
469 write to \f[B]stdout\f[R], so if \f[B]stdout\f[R] is closed, as in
470 \f[B]bc >&-\f[R], it will quit with an error.
471 This is done so that bc(1) can report problems when \f[B]stdout\f[R] is
472 redirected to a file.
474 If there are scripts that depend on the behavior of other bc(1)
475 implementations, it is recommended that those scripts be changed to
476 redirect \f[B]stdout\f[R] to \f[B]/dev/null\f[R].
479 Any error output is written to \f[B]stderr\f[R].
481 \f[B]Note\f[R]: Unlike other bc(1) implementations, this bc(1) will
482 issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot
483 write to \f[B]stderr\f[R], so if \f[B]stderr\f[R] is closed, as in
484 \f[B]bc 2>&-\f[R], it will quit with an error.
485 This is done so that bc(1) can exit with an error code when
486 \f[B]stderr\f[R] is redirected to a file.
488 If there are scripts that depend on the behavior of other bc(1)
489 implementations, it is recommended that those scripts be changed to
490 redirect \f[B]stderr\f[R] to \f[B]/dev/null\f[R].
493 The syntax for bc(1) programs is mostly C-like, with some differences.
494 This bc(1) follows the POSIX standard (see the \f[B]STANDARDS\f[R]
495 section), which is a much more thorough resource for the language this
497 This section is meant to be a summary and a listing of all the
498 extensions to the standard.
500 In the sections below, \f[B]E\f[R] means expression, \f[B]S\f[R] means
501 statement, and \f[B]I\f[R] means identifier.
503 Identifiers (\f[B]I\f[R]) start with a lowercase letter and can be
504 followed by any number (up to \f[B]BC_NAME_MAX-1\f[R]) of lowercase
505 letters (\f[B]a-z\f[R]), digits (\f[B]0-9\f[R]), and underscores
507 The regex is \f[B][a-z][a-z0-9_]*\f[R].
508 Identifiers with more than one character (letter) are a
509 \f[B]non-portable extension\f[R].
511 \f[B]ibase\f[R] is a global variable determining how to interpret
513 It is the \[lq]input\[rq] base, or the number base used for interpreting
515 \f[B]ibase\f[R] is initially \f[B]10\f[R].
516 If the \f[B]-s\f[R] (\f[B]--standard\f[R]) and \f[B]-w\f[R]
517 (\f[B]--warn\f[R]) flags were not given on the command line, the max
518 allowable value for \f[B]ibase\f[R] is \f[B]36\f[R].
519 Otherwise, it is \f[B]16\f[R].
520 The min allowable value for \f[B]ibase\f[R] is \f[B]2\f[R].
521 The max allowable value for \f[B]ibase\f[R] can be queried in bc(1)
522 programs with the \f[B]maxibase()\f[R] built-in function.
524 \f[B]obase\f[R] is a global variable determining how to output results.
525 It is the \[lq]output\[rq] base, or the number base used for outputting
527 \f[B]obase\f[R] is initially \f[B]10\f[R].
528 The max allowable value for \f[B]obase\f[R] is \f[B]BC_BASE_MAX\f[R] and
529 can be queried in bc(1) programs with the \f[B]maxobase()\f[R] built-in
531 The min allowable value for \f[B]obase\f[R] is \f[B]2\f[R].
532 Values are output in the specified base.
534 The \f[I]scale\f[R] of an expression is the number of digits in the
535 result of the expression right of the decimal point, and \f[B]scale\f[R]
536 is a global variable that sets the precision of any operations, with
538 \f[B]scale\f[R] is initially \f[B]0\f[R].
539 \f[B]scale\f[R] cannot be negative.
540 The max allowable value for \f[B]scale\f[R] is \f[B]BC_SCALE_MAX\f[R]
541 and can be queried in bc(1) programs with the \f[B]maxscale()\f[R]
544 bc(1) has both \f[I]global\f[R] variables and \f[I]local\f[R] variables.
545 All \f[I]local\f[R] variables are local to the function; they are
546 parameters or are introduced in the \f[B]auto\f[R] list of a function
547 (see the \f[B]FUNCTIONS\f[R] section).
548 If a variable is accessed which is not a parameter or in the
549 \f[B]auto\f[R] list, it is assumed to be \f[I]global\f[R].
550 If a parent function has a \f[I]local\f[R] variable version of a
551 variable that a child function considers \f[I]global\f[R], the value of
552 that \f[I]global\f[R] variable in the child function is the value of the
553 variable in the parent function, not the value of the actual
554 \f[I]global\f[R] variable.
556 All of the above applies to arrays as well.
558 The value of a statement that is an expression (i.e., any of the named
559 expressions or operands) is printed unless the lowest precedence
560 operator is an assignment operator \f[I]and\f[R] the expression is
561 notsurrounded by parentheses.
563 The value that is printed is also assigned to the special variable
565 A single dot (\f[B].\f[R]) may also be used as a synonym for
567 These are \f[B]non-portable extensions\f[R].
569 Either semicolons or newlines may separate statements.
572 There are two kinds of comments:
574 Block comments are enclosed in \f[B]/*\f[R] and \f[B]*/\f[R].
576 Line comments go from \f[B]#\f[R] until, and not including, the next
578 This is a \f[B]non-portable extension\f[R].
579 .SS Named Expressions
581 The following are named expressions in bc(1):
583 Variables: \f[B]I\f[R]
585 Array Elements: \f[B]I[E]\f[R]
593 \f[B]last\f[R] or a single dot (\f[B].\f[R])
595 Number 6 is a \f[B]non-portable extension\f[R].
597 Variables and arrays do not interfere; users can have arrays named the
599 This also applies to functions (see the \f[B]FUNCTIONS\f[R] section), so
600 a user can have a variable, array, and function that all have the same
601 name, and they will not shadow each other, whether inside of functions
604 Named expressions are required as the operand of
605 \f[B]increment\f[R]/\f[B]decrement\f[R] operators and as the left side
606 of \f[B]assignment\f[R] operators (see the \f[I]Operators\f[R]
610 The following are valid operands in bc(1):
612 Numbers (see the \f[I]Numbers\f[R] subsection below).
614 Array indices (\f[B]I[E]\f[R]).
616 \f[B](E)\f[R]: The value of \f[B]E\f[R] (used to change precedence).
618 \f[B]sqrt(E)\f[R]: The square root of \f[B]E\f[R].
619 \f[B]E\f[R] must be non-negative.
621 \f[B]length(E)\f[R]: The number of significant decimal digits in
623 Returns \f[B]1\f[R] for \f[B]0\f[R] with no decimal places.
624 If given a string, the length of the string is returned.
625 Passing a string to \f[B]length(E)\f[R] is a \f[B]non-portable
628 \f[B]length(I[])\f[R]: The number of elements in the array \f[B]I\f[R].
629 This is a \f[B]non-portable extension\f[R].
631 \f[B]scale(E)\f[R]: The \f[I]scale\f[R] of \f[B]E\f[R].
633 \f[B]abs(E)\f[R]: The absolute value of \f[B]E\f[R].
634 This is a \f[B]non-portable extension\f[R].
636 \f[B]is_number(E)\f[R]: \f[B]1\f[R] if the given argument is a number,
637 \f[B]0\f[R] if it is a string.
638 This is a \f[B]non-portable extension\f[R].
640 \f[B]is_string(E)\f[R]: \f[B]1\f[R] if the given argument is a string,
641 \f[B]0\f[R] if it is a number.
642 This is a \f[B]non-portable extension\f[R].
644 \f[B]modexp(E, E, E)\f[R]: Modular exponentiation, where the first
645 expression is the base, the second is the exponent, and the third is the
647 All three values must be integers.
648 The second argument must be non-negative.
649 The third argument must be non-zero.
650 This is a \f[B]non-portable extension\f[R].
652 \f[B]divmod(E, E, I[])\f[R]: Division and modulus in one operation.
653 This is for optimization.
654 The first expression is the dividend, and the second is the divisor,
655 which must be non-zero.
656 The return value is the quotient, and the modulus is stored in index
657 \f[B]0\f[R] of the provided array (the last argument).
658 This is a \f[B]non-portable extension\f[R].
660 \f[B]asciify(E)\f[R]: If \f[B]E\f[R] is a string, returns a string that
661 is the first letter of its argument.
662 If it is a number, calculates the number mod \f[B]256\f[R] and returns
663 that number as a one-character string.
664 This is a \f[B]non-portable extension\f[R].
666 \f[B]asciify(I[])\f[R]: A string that is made up of the characters that
667 would result from running \f[B]asciify(E)\f[R] on each element of the
668 array identified by the argument.
669 This allows creating multi-character strings and storing them.
670 This is a \f[B]non-portable extension\f[R].
672 \f[B]I()\f[R], \f[B]I(E)\f[R], \f[B]I(E, E)\f[R], and so on, where
673 \f[B]I\f[R] is an identifier for a non-\f[B]void\f[R] function (see the
674 \f[I]Void Functions\f[R] subsection of the \f[B]FUNCTIONS\f[R] section).
675 The \f[B]E\f[R] argument(s) may also be arrays of the form
676 \f[B]I[]\f[R], which will automatically be turned into array references
677 (see the \f[I]Array References\f[R] subsection of the
678 \f[B]FUNCTIONS\f[R] section) if the corresponding parameter in the
679 function definition is an array reference.
681 \f[B]read()\f[R]: Reads a line from \f[B]stdin\f[R] and uses that as an
683 The result of that expression is the result of the \f[B]read()\f[R]
685 This is a \f[B]non-portable extension\f[R].
687 \f[B]maxibase()\f[R]: The max allowable \f[B]ibase\f[R].
688 This is a \f[B]non-portable extension\f[R].
690 \f[B]maxobase()\f[R]: The max allowable \f[B]obase\f[R].
691 This is a \f[B]non-portable extension\f[R].
693 \f[B]maxscale()\f[R]: The max allowable \f[B]scale\f[R].
694 This is a \f[B]non-portable extension\f[R].
696 \f[B]line_length()\f[R]: The line length set with
697 \f[B]BC_LINE_LENGTH\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R]
699 This is a \f[B]non-portable extension\f[R].
701 \f[B]global_stacks()\f[R]: \f[B]0\f[R] if global stacks are not enabled
702 with the \f[B]-g\f[R] or \f[B]--global-stacks\f[R] options, non-zero
704 See the \f[B]OPTIONS\f[R] section.
705 This is a \f[B]non-portable extension\f[R].
707 \f[B]leading_zero()\f[R]: \f[B]0\f[R] if leading zeroes are not enabled
708 with the \f[B]-z\f[R] or \f[B]\[en]leading-zeroes\f[R] options, non-zero
710 See the \f[B]OPTIONS\f[R] section.
711 This is a \f[B]non-portable extension\f[R].
714 Numbers are strings made up of digits, uppercase letters, and at most
715 \f[B]1\f[R] period for a radix.
716 Numbers can have up to \f[B]BC_NUM_MAX\f[R] digits.
717 Uppercase letters are equal to \f[B]9\f[R] plus their position in the
718 alphabet, starting from \f[B]1\f[R] (i.e., \f[B]A\f[R] equals
719 \f[B]10\f[R], or \f[B]9+1\f[R]).
721 If a digit or letter makes no sense with the current value of
722 \f[B]ibase\f[R] (i.e., they are greater than or equal to the current
723 value of \f[B]ibase\f[R]), then the behavior depends on the existence of
724 the \f[B]-c\f[R]/\f[B]--digit-clamp\f[R] or
725 \f[B]-C\f[R]/\f[B]--no-digit-clamp\f[R] options (see the
726 \f[B]OPTIONS\f[R] section), the existence and setting of the
727 \f[B]BC_DIGIT_CLAMP\f[R] environment variable (see the \f[B]ENVIRONMENT
728 VARIABLES\f[R] section), or the default, which can be queried with the
729 \f[B]-h\f[R]/\f[B]--help\f[R] option.
731 If clamping is off, then digits or letters that are greater than or
732 equal to the current value of \f[B]ibase\f[R] are not changed.
733 Instead, their given value is multiplied by the appropriate power of
734 \f[B]ibase\f[R] and added into the number.
735 This means that, with an \f[B]ibase\f[R] of \f[B]3\f[R], the number
736 \f[B]AB\f[R] is equal to \f[B]3\[ha]1*A+3\[ha]0*B\f[R], which is
737 \f[B]3\f[R] times \f[B]10\f[R] plus \f[B]11\f[R], or \f[B]41\f[R].
739 If clamping is on, then digits or letters that are greater than or equal
740 to the current value of \f[B]ibase\f[R] are set to the value of the
741 highest valid digit in \f[B]ibase\f[R] before being multiplied by the
742 appropriate power of \f[B]ibase\f[R] and added into the number.
743 This means that, with an \f[B]ibase\f[R] of \f[B]3\f[R], the number
744 \f[B]AB\f[R] is equal to \f[B]3\[ha]1*2+3\[ha]0*2\f[R], which is
745 \f[B]3\f[R] times \f[B]2\f[R] plus \f[B]2\f[R], or \f[B]8\f[R].
747 There is one exception to clamping: single-character numbers (i.e.,
749 Such numbers are never clamped and always take the value they would have
750 in the highest possible \f[B]ibase\f[R].
751 This means that \f[B]A\f[R] alone always equals decimal \f[B]10\f[R] and
752 \f[B]Z\f[R] alone always equals decimal \f[B]35\f[R].
753 This behavior is mandated by the standard (see the STANDARDS section)
754 and is meant to provide an easy way to set the current \f[B]ibase\f[R]
755 (with the \f[B]i\f[R] command) regardless of the current value of
758 If clamping is on, and the clamped value of a character is needed, use a
759 leading zero, i.e., for \f[B]A\f[R], use \f[B]0A\f[R].
762 The following arithmetic and logical operators can be used.
763 They are listed in order of decreasing precedence.
764 Operators in the same group have the same precedence.
766 \f[B]++\f[R] \f[B]--\f[R]
767 Type: Prefix and Postfix
772 Description: \f[B]increment\f[R], \f[B]decrement\f[R]
775 \f[B]-\f[R] \f[B]!\f[R]
781 Description: \f[B]negation\f[R], \f[B]boolean not\f[R]
790 Description: \f[B]power\f[R]
793 \f[B]*\f[R] \f[B]/\f[R] \f[B]%\f[R]
799 Description: \f[B]multiply\f[R], \f[B]divide\f[R], \f[B]modulus\f[R]
802 \f[B]+\f[R] \f[B]-\f[R]
808 Description: \f[B]add\f[R], \f[B]subtract\f[R]
811 \f[B]=\f[R] \f[B]+=\f[R] \f[B]-=\f[R] \f[B]*=\f[R] \f[B]/=\f[R] \f[B]%=\f[R] \f[B]\[ha]=\f[R]
817 Description: \f[B]assignment\f[R]
820 \f[B]==\f[R] \f[B]<=\f[R] \f[B]>=\f[R] \f[B]!=\f[R] \f[B]<\f[R] \f[B]>\f[R]
826 Description: \f[B]relational\f[R]
835 Description: \f[B]boolean and\f[R]
844 Description: \f[B]boolean or\f[R]
847 The operators will be described in more detail below.
849 \f[B]++\f[R] \f[B]--\f[R]
850 The prefix and postfix \f[B]increment\f[R] and \f[B]decrement\f[R]
851 operators behave exactly like they would in C.
852 They require a named expression (see the \f[I]Named Expressions\f[R]
853 subsection) as an operand.
856 The prefix versions of these operators are more efficient; use them
861 The \f[B]negation\f[R] operator returns \f[B]0\f[R] if a user attempts
862 to negate any expression with the value \f[B]0\f[R].
863 Otherwise, a copy of the expression with its sign flipped is returned.
866 The \f[B]boolean not\f[R] operator returns \f[B]1\f[R] if the expression
867 is \f[B]0\f[R], or \f[B]0\f[R] otherwise.
870 This is a \f[B]non-portable extension\f[R].
874 The \f[B]power\f[R] operator (not the \f[B]exclusive or\f[R] operator,
875 as it would be in C) takes two expressions and raises the first to the
876 power of the value of the second.
877 The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R].
880 The second expression must be an integer (no \f[I]scale\f[R]), and if it
881 is negative, the first value must be non-zero.
885 The \f[B]multiply\f[R] operator takes two expressions, multiplies them,
886 and returns the product.
887 If \f[B]a\f[R] is the \f[I]scale\f[R] of the first expression and
888 \f[B]b\f[R] is the \f[I]scale\f[R] of the second expression, the
889 \f[I]scale\f[R] of the result is equal to
890 \f[B]min(a+b,max(scale,a,b))\f[R] where \f[B]min()\f[R] and
891 \f[B]max()\f[R] return the obvious values.
894 The \f[B]divide\f[R] operator takes two expressions, divides them, and
895 returns the quotient.
896 The \f[I]scale\f[R] of the result shall be the value of \f[B]scale\f[R].
899 The second expression must be non-zero.
903 The \f[B]modulus\f[R] operator takes two expressions, \f[B]a\f[R] and
904 \f[B]b\f[R], and evaluates them by 1) Computing \f[B]a/b\f[R] to current
905 \f[B]scale\f[R] and 2) Using the result of step 1 to calculate
906 \f[B]a-(a/b)*b\f[R] to \f[I]scale\f[R]
907 \f[B]max(scale+scale(b),scale(a))\f[R].
910 The second expression must be non-zero.
914 The \f[B]add\f[R] operator takes two expressions, \f[B]a\f[R] and
915 \f[B]b\f[R], and returns the sum, with a \f[I]scale\f[R] equal to the
916 max of the \f[I]scale\f[R]s of \f[B]a\f[R] and \f[B]b\f[R].
919 The \f[B]subtract\f[R] operator takes two expressions, \f[B]a\f[R] and
920 \f[B]b\f[R], and returns the difference, with a \f[I]scale\f[R] equal to
921 the max of the \f[I]scale\f[R]s of \f[B]a\f[R] and \f[B]b\f[R].
923 \f[B]=\f[R] \f[B]+=\f[R] \f[B]-=\f[R] \f[B]*=\f[R] \f[B]/=\f[R] \f[B]%=\f[R] \f[B]\[ha]=\f[R]
924 The \f[B]assignment\f[R] operators take two expressions, \f[B]a\f[R] and
925 \f[B]b\f[R] where \f[B]a\f[R] is a named expression (see the \f[I]Named
926 Expressions\f[R] subsection).
929 For \f[B]=\f[R], \f[B]b\f[R] is copied and the result is assigned to
931 For all others, \f[B]a\f[R] and \f[B]b\f[R] are applied as operands to
932 the corresponding arithmetic operator and the result is assigned to
936 \f[B]==\f[R] \f[B]<=\f[R] \f[B]>=\f[R] \f[B]!=\f[R] \f[B]<\f[R] \f[B]>\f[R]
937 The \f[B]relational\f[R] operators compare two expressions, \f[B]a\f[R]
938 and \f[B]b\f[R], and if the relation holds, according to C language
939 semantics, the result is \f[B]1\f[R].
940 Otherwise, it is \f[B]0\f[R].
943 Note that unlike in C, these operators have a lower precedence than the
944 \f[B]assignment\f[R] operators, which means that \f[B]a=b>c\f[R] is
945 interpreted as \f[B](a=b)>c\f[R].
947 Also, unlike the standard (see the \f[B]STANDARDS\f[R] section)
948 requires, these operators can appear anywhere any other expressions can
950 This allowance is a \f[B]non-portable extension\f[R].
954 The \f[B]boolean and\f[R] operator takes two expressions and returns
955 \f[B]1\f[R] if both expressions are non-zero, \f[B]0\f[R] otherwise.
958 This is \f[I]not\f[R] a short-circuit operator.
960 This is a \f[B]non-portable extension\f[R].
964 The \f[B]boolean or\f[R] operator takes two expressions and returns
965 \f[B]1\f[R] if one of the expressions is non-zero, \f[B]0\f[R]
969 This is \f[I]not\f[R] a short-circuit operator.
971 This is a \f[B]non-portable extension\f[R].
975 The following items are statements:
979 \f[B]{\f[R] \f[B]S\f[R] \f[B];\f[R] \&...
980 \f[B];\f[R] \f[B]S\f[R] \f[B]}\f[R]
982 \f[B]if\f[R] \f[B](\f[R] \f[B]E\f[R] \f[B])\f[R] \f[B]S\f[R]
984 \f[B]if\f[R] \f[B](\f[R] \f[B]E\f[R] \f[B])\f[R] \f[B]S\f[R]
985 \f[B]else\f[R] \f[B]S\f[R]
987 \f[B]while\f[R] \f[B](\f[R] \f[B]E\f[R] \f[B])\f[R] \f[B]S\f[R]
989 \f[B]for\f[R] \f[B](\f[R] \f[B]E\f[R] \f[B];\f[R] \f[B]E\f[R]
990 \f[B];\f[R] \f[B]E\f[R] \f[B])\f[R] \f[B]S\f[R]
1004 A string of characters, enclosed in double quotes
1006 \f[B]print\f[R] \f[B]E\f[R] \f[B],\f[R] \&...
1007 \f[B],\f[R] \f[B]E\f[R]
1009 \f[B]stream\f[R] \f[B]E\f[R] \f[B],\f[R] \&...
1010 \f[B],\f[R] \f[B]E\f[R]
1012 \f[B]I()\f[R], \f[B]I(E)\f[R], \f[B]I(E, E)\f[R], and so on, where
1013 \f[B]I\f[R] is an identifier for a \f[B]void\f[R] function (see the
1014 \f[I]Void Functions\f[R] subsection of the \f[B]FUNCTIONS\f[R] section).
1015 The \f[B]E\f[R] argument(s) may also be arrays of the form
1016 \f[B]I[]\f[R], which will automatically be turned into array references
1017 (see the \f[I]Array References\f[R] subsection of the
1018 \f[B]FUNCTIONS\f[R] section) if the corresponding parameter in the
1019 function definition is an array reference.
1021 Numbers 4, 9, 11, 12, 14, 15, and 16 are \f[B]non-portable
1024 Also, as a \f[B]non-portable extension\f[R], any or all of the
1025 expressions in the header of a for loop may be omitted.
1026 If the condition (second expression) is omitted, it is assumed to be a
1027 constant \f[B]1\f[R].
1029 The \f[B]break\f[R] statement causes a loop to stop iterating and resume
1030 execution immediately following a loop.
1031 This is only allowed in loops.
1033 The \f[B]continue\f[R] statement causes a loop iteration to stop early
1034 and returns to the start of the loop, including testing the loop
1036 This is only allowed in loops.
1038 The \f[B]if\f[R] \f[B]else\f[R] statement does the same thing as in C.
1040 The \f[B]quit\f[R] statement causes bc(1) to quit, even if it is on a
1041 branch that will not be executed (it is a compile-time command).
1043 \f[B]Warning\f[R]: The behavior of this bc(1) on \f[B]quit\f[R] is
1044 slightly different from other bc(1) implementations.
1045 Other bc(1) implementations will exit as soon as they finish parsing the
1046 line that a \f[B]quit\f[R] command is on.
1047 This bc(1) will execute any completed and executable statements that
1048 occur before the \f[B]quit\f[R] statement before exiting.
1050 In other words, for the bc(1) code below:
1054 for (i = 0; i < 3; ++i) i; quit
1058 Other bc(1) implementations will print nothing, and this bc(1) will
1059 print \f[B]0\f[R], \f[B]1\f[R], and \f[B]2\f[R] on successive lines
1062 The \f[B]halt\f[R] statement causes bc(1) to quit, if it is executed.
1063 (Unlike \f[B]quit\f[R] if it is on a branch of an \f[B]if\f[R] statement
1064 that is not executed, bc(1) does not quit.)
1066 The \f[B]limits\f[R] statement prints the limits that this bc(1) is
1068 This is like the \f[B]quit\f[R] statement in that it is a compile-time
1071 An expression by itself is evaluated and printed, followed by a newline.
1074 If strings appear as a statement by themselves, they are printed without
1077 In addition to appearing as a lone statement by themselves, strings can
1078 be assigned to variables and array elements.
1079 They can also be passed to functions in variable parameters.
1081 If any statement that expects a string is given a variable that had a
1082 string assigned to it, the statement acts as though it had received a
1085 If any math operation is attempted on a string or a variable or array
1086 element that has been assigned a string, an error is raised, and bc(1)
1087 resets (see the \f[B]RESET\f[R] section).
1089 Assigning strings to variables and array elements and passing them to
1090 functions are \f[B]non-portable extensions\f[R].
1093 The \[lq]expressions\[rq] in a \f[B]print\f[R] statement may also be
1095 If they are, there are backslash escape sequences that are interpreted
1097 What those sequences are, and what they cause to be printed, are shown
1100 \f[B]\[rs]a\f[R]: \f[B]\[rs]a\f[R]
1102 \f[B]\[rs]b\f[R]: \f[B]\[rs]b\f[R]
1104 \f[B]\[rs]\[rs]\f[R]: \f[B]\[rs]\f[R]
1106 \f[B]\[rs]e\f[R]: \f[B]\[rs]\f[R]
1108 \f[B]\[rs]f\f[R]: \f[B]\[rs]f\f[R]
1110 \f[B]\[rs]n\f[R]: \f[B]\[rs]n\f[R]
1112 \f[B]\[rs]q\f[R]: \f[B]\[lq]\f[R]
1114 \f[B]\[rs]r\f[R]: \f[B]\[rs]r\f[R]
1116 \f[B]\[rs]t\f[R]: \f[B]\[rs]t\f[R]
1118 Any other character following a backslash causes the backslash and
1119 character to be printed as-is.
1121 Any non-string expression in a print statement shall be assigned to
1122 \f[B]last\f[R], like any other expression that is printed.
1123 .SS Stream Statement
1125 The \[lq]expressions in a \f[B]stream\f[R] statement may also be
1128 If a \f[B]stream\f[R] statement is given a string, it prints the string
1129 as though the string had appeared as its own statement.
1130 In other words, the \f[B]stream\f[R] statement prints strings normally,
1133 If a \f[B]stream\f[R] statement is given a number, a copy of it is
1134 truncated and its absolute value is calculated.
1135 The result is then printed as though \f[B]obase\f[R] is \f[B]256\f[R]
1136 and each digit is interpreted as an 8-bit ASCII character, making it a
1138 .SS Order of Evaluation
1140 All expressions in a statment are evaluated left to right, except as
1141 necessary to maintain order of operations.
1142 This means, for example, assuming that \f[B]i\f[R] is equal to
1143 \f[B]0\f[R], in the expression
1151 the first (or 0th) element of \f[B]a\f[R] is set to \f[B]1\f[R], and
1152 \f[B]i\f[R] is equal to \f[B]2\f[R] at the end of the expression.
1154 This includes function arguments.
1155 Thus, assuming \f[B]i\f[R] is equal to \f[B]0\f[R], this means that in
1164 the first argument passed to \f[B]x()\f[R] is \f[B]0\f[R], and the
1165 second argument is \f[B]1\f[R], while \f[B]i\f[R] is equal to
1166 \f[B]2\f[R] before the function starts executing.
1169 Function definitions are as follows:
1181 Any \f[B]I\f[R] in the parameter list or \f[B]auto\f[R] list may be
1182 replaced with \f[B]I[]\f[R] to make a parameter or \f[B]auto\f[R] var an
1183 array, and any \f[B]I\f[R] in the parameter list may be replaced with
1184 \f[B]*I[]\f[R] to make a parameter an array reference.
1185 Callers of functions that take array references should not put an
1186 asterisk in the call; they must be called with just \f[B]I[]\f[R] like
1187 normal array parameters and will be automatically converted into
1190 As a \f[B]non-portable extension\f[R], the opening brace of a
1191 \f[B]define\f[R] statement may appear on the next line.
1193 As a \f[B]non-portable extension\f[R], the return statement may also be
1194 in one of the following forms:
1198 \f[B]return\f[R] \f[B](\f[R] \f[B])\f[R]
1200 \f[B]return\f[R] \f[B]E\f[R]
1202 The first two, or not specifying a \f[B]return\f[R] statement, is
1203 equivalent to \f[B]return (0)\f[R], unless the function is a
1204 \f[B]void\f[R] function (see the \f[I]Void Functions\f[R] subsection
1208 Functions can also be \f[B]void\f[R] functions, defined as follows:
1212 define void I(I,...,I){
1220 They can only be used as standalone expressions, where such an
1221 expression would be printed alone, except in a print statement.
1223 Void functions can only use the first two \f[B]return\f[R] statements
1225 They can also omit the return statement entirely.
1227 The word \[lq]void\[rq] is not treated as a keyword; it is still
1228 possible to have variables, arrays, and functions named \f[B]void\f[R].
1229 The word \[lq]void\[rq] is only treated specially right after the
1230 \f[B]define\f[R] keyword.
1232 This is a \f[B]non-portable extension\f[R].
1233 .SS Array References
1235 For any array in the parameter list, if the array is declared in the
1244 it is a \f[B]reference\f[R].
1245 Any changes to the array in the function are reflected, when the
1246 function returns, to the array that was passed in.
1248 Other than this, all function arguments are passed by value.
1250 This is a \f[B]non-portable extension\f[R].
1253 All of the functions below are available when the \f[B]-l\f[R] or
1254 \f[B]--mathlib\f[R] command-line flags are given.
1255 .SS Standard Library
1257 The standard (see the \f[B]STANDARDS\f[R] section) defines the following
1258 functions for the math library:
1261 Returns the sine of \f[B]x\f[R], which is assumed to be in radians.
1264 This is a transcendental function (see the \f[I]Transcendental
1265 Functions\f[R] subsection below).
1269 Returns the cosine of \f[B]x\f[R], which is assumed to be in radians.
1272 This is a transcendental function (see the \f[I]Transcendental
1273 Functions\f[R] subsection below).
1277 Returns the arctangent of \f[B]x\f[R], in radians.
1280 This is a transcendental function (see the \f[I]Transcendental
1281 Functions\f[R] subsection below).
1285 Returns the natural logarithm of \f[B]x\f[R].
1288 This is a transcendental function (see the \f[I]Transcendental
1289 Functions\f[R] subsection below).
1293 Returns the mathematical constant \f[B]e\f[R] raised to the power of
1297 This is a transcendental function (see the \f[I]Transcendental
1298 Functions\f[R] subsection below).
1302 Returns the bessel integer order \f[B]n\f[R] (truncated) of \f[B]x\f[R].
1305 This is a transcendental function (see the \f[I]Transcendental
1306 Functions\f[R] subsection below).
1308 .SS Transcendental Functions
1310 All transcendental functions can return slightly inaccurate results, up
1311 to 1 ULP (https://en.wikipedia.org/wiki/Unit_in_the_last_place).
1312 This is unavoidable, and the article at
1313 https://people.eecs.berkeley.edu/\[ti]wkahan/LOG10HAF.TXT explains why
1314 it is impossible and unnecessary to calculate exact results for the
1315 transcendental functions.
1317 Because of the possible inaccuracy, I recommend that users call those
1318 functions with the precision (\f[B]scale\f[R]) set to at least 1 higher
1320 If exact results are \f[I]absolutely\f[R] required, users can double the
1321 precision (\f[B]scale\f[R]) and then truncate.
1323 The transcendental functions in the standard math library are:
1338 When bc(1) encounters an error or a signal that it has a non-default
1339 handler for, it resets.
1340 This means that several things happen.
1342 First, any functions that are executing are stopped and popped off the
1344 The behavior is not unlike that of exceptions in programming languages.
1345 Then the execution point is set so that any code waiting to execute
1346 (after all functions returned) is skipped.
1348 Thus, when bc(1) resets, it skips any remaining code waiting to be
1350 Then, if it is interactive mode, and the error was not a fatal error
1351 (see the \f[B]EXIT STATUS\f[R] section), it asks for more input;
1352 otherwise, it exits with the appropriate return code.
1354 Note that this reset behavior is different from the GNU bc(1), which
1355 attempts to start executing the statement right after the one that
1359 Most bc(1) implementations use \f[B]char\f[R] types to calculate the
1360 value of \f[B]1\f[R] decimal digit at a time, but that can be slow.
1361 This bc(1) does something different.
1363 It uses large integers to calculate more than \f[B]1\f[R] decimal digit
1365 If built in a environment where \f[B]BC_LONG_BIT\f[R] (see the
1366 \f[B]LIMITS\f[R] section) is \f[B]64\f[R], then each integer has
1367 \f[B]9\f[R] decimal digits.
1368 If built in an environment where \f[B]BC_LONG_BIT\f[R] is \f[B]32\f[R]
1369 then each integer has \f[B]4\f[R] decimal digits.
1370 This value (the number of decimal digits per large integer) is called
1371 \f[B]BC_BASE_DIGS\f[R].
1373 The actual values of \f[B]BC_LONG_BIT\f[R] and \f[B]BC_BASE_DIGS\f[R]
1374 can be queried with the \f[B]limits\f[R] statement.
1376 In addition, this bc(1) uses an even larger integer for overflow
1378 This integer type depends on the value of \f[B]BC_LONG_BIT\f[R], but is
1379 always at least twice as large as the integer type used to store digits.
1382 The following are the limits on bc(1):
1384 \f[B]BC_LONG_BIT\f[R]
1385 The number of bits in the \f[B]long\f[R] type in the environment where
1387 This determines how many decimal digits can be stored in a single large
1388 integer (see the \f[B]PERFORMANCE\f[R] section).
1390 \f[B]BC_BASE_DIGS\f[R]
1391 The number of decimal digits per large integer (see the
1392 \f[B]PERFORMANCE\f[R] section).
1393 Depends on \f[B]BC_LONG_BIT\f[R].
1395 \f[B]BC_BASE_POW\f[R]
1396 The max decimal number that each large integer can store (see
1397 \f[B]BC_BASE_DIGS\f[R]) plus \f[B]1\f[R].
1398 Depends on \f[B]BC_BASE_DIGS\f[R].
1400 \f[B]BC_OVERFLOW_MAX\f[R]
1401 The max number that the overflow type (see the \f[B]PERFORMANCE\f[R]
1403 Depends on \f[B]BC_LONG_BIT\f[R].
1405 \f[B]BC_BASE_MAX\f[R]
1406 The maximum output base.
1407 Set at \f[B]BC_BASE_POW\f[R].
1409 \f[B]BC_DIM_MAX\f[R]
1410 The maximum size of arrays.
1411 Set at \f[B]SIZE_MAX-1\f[R].
1413 \f[B]BC_SCALE_MAX\f[R]
1414 The maximum \f[B]scale\f[R].
1415 Set at \f[B]BC_OVERFLOW_MAX-1\f[R].
1417 \f[B]BC_STRING_MAX\f[R]
1418 The maximum length of strings.
1419 Set at \f[B]BC_OVERFLOW_MAX-1\f[R].
1421 \f[B]BC_NAME_MAX\f[R]
1422 The maximum length of identifiers.
1423 Set at \f[B]BC_OVERFLOW_MAX-1\f[R].
1425 \f[B]BC_NUM_MAX\f[R]
1426 The maximum length of a number (in decimal digits), which includes
1427 digits after the decimal point.
1428 Set at \f[B]BC_OVERFLOW_MAX-1\f[R].
1431 The maximum allowable exponent (positive or negative).
1432 Set at \f[B]BC_OVERFLOW_MAX\f[R].
1435 The maximum number of vars/arrays.
1436 Set at \f[B]SIZE_MAX-1\f[R].
1438 The actual values can be queried with the \f[B]limits\f[R] statement.
1440 These limits are meant to be effectively non-existent; the limits are so
1441 large (at least on 64-bit machines) that there should not be any point
1442 at which they become a problem.
1443 In fact, memory should be exhausted before these limits should be hit.
1444 .SH ENVIRONMENT VARIABLES
1446 As \f[B]non-portable extensions\f[R], bc(1) recognizes the following
1447 environment variables:
1449 \f[B]POSIXLY_CORRECT\f[R]
1450 If this variable exists (no matter the contents), bc(1) behaves as if
1451 the \f[B]-s\f[R] option was given.
1453 \f[B]BC_ENV_ARGS\f[R]
1454 This is another way to give command-line arguments to bc(1).
1455 They should be in the same format as all other command-line arguments.
1456 These are always processed first, so any files given in
1457 \f[B]BC_ENV_ARGS\f[R] will be processed before arguments and files given
1458 on the command-line.
1459 This gives the user the ability to set up \[lq]standard\[rq] options and
1460 files to be used at every invocation.
1461 The most useful thing for such files to contain would be useful
1462 functions that the user might want every time bc(1) runs.
1465 The code that parses \f[B]BC_ENV_ARGS\f[R] will correctly handle quoted
1466 arguments, but it does not understand escape sequences.
1467 For example, the string \f[B]\[lq]/home/gavin/some bc file.bc\[rq]\f[R]
1468 will be correctly parsed, but the string \f[B]\[lq]/home/gavin/some
1469 \[dq]bc\[dq] file.bc\[rq]\f[R] will include the backslashes.
1471 The quote parsing will handle either kind of quotes, \f[B]\[cq]\f[R] or
1473 Thus, if you have a file with any number of single quotes in the name,
1474 you can use double quotes as the outside quotes, as in \f[B]\[lq]some
1475 `bc' file.bc\[rq]\f[R], and vice versa if you have a file with double
1477 However, handling a file with both kinds of quotes in
1478 \f[B]BC_ENV_ARGS\f[R] is not supported due to the complexity of the
1479 parsing, though such files are still supported on the command-line where
1480 the parsing is done by the shell.
1483 \f[B]BC_LINE_LENGTH\f[R]
1484 If this environment variable exists and contains an integer that is
1485 greater than \f[B]1\f[R] and is less than \f[B]UINT16_MAX\f[R]
1486 (\f[B]2\[ha]16-1\f[R]), bc(1) will output lines to that length,
1487 including the backslash (\f[B]\[rs]\f[R]).
1488 The default line length is \f[B]70\f[R].
1491 The special value of \f[B]0\f[R] will disable line length checking and
1492 print numbers without regard to line length and without backslashes and
1497 If this environment variable exists and contains an integer, then a
1498 non-zero value activates the copyright banner when bc(1) is in
1499 interactive mode, while zero deactivates it.
1502 If bc(1) is not in interactive mode (see the \f[B]INTERACTIVE MODE\f[R]
1503 section), then this environment variable has no effect because bc(1)
1504 does not print the banner when not in interactive mode.
1506 This environment variable overrides the default, which can be queried
1507 with the \f[B]-h\f[R] or \f[B]--help\f[R] options.
1510 \f[B]BC_SIGINT_RESET\f[R]
1511 If bc(1) is not in interactive mode (see the \f[B]INTERACTIVE MODE\f[R]
1512 section), then this environment variable has no effect because bc(1)
1513 exits on \f[B]SIGINT\f[R] when not in interactive mode.
1516 However, when bc(1) is in interactive mode, then if this environment
1517 variable exists and contains an integer, a non-zero value makes bc(1)
1518 reset on \f[B]SIGINT\f[R], rather than exit, and zero makes bc(1) exit.
1519 If this environment variable exists and is \f[I]not\f[R] an integer,
1520 then bc(1) will exit on \f[B]SIGINT\f[R].
1522 This environment variable overrides the default, which can be queried
1523 with the \f[B]-h\f[R] or \f[B]--help\f[R] options.
1526 \f[B]BC_TTY_MODE\f[R]
1527 If TTY mode is \f[I]not\f[R] available (see the \f[B]TTY MODE\f[R]
1528 section), then this environment variable has no effect.
1531 However, when TTY mode is available, then if this environment variable
1532 exists and contains an integer, then a non-zero value makes bc(1) use
1533 TTY mode, and zero makes bc(1) not use TTY mode.
1535 This environment variable overrides the default, which can be queried
1536 with the \f[B]-h\f[R] or \f[B]--help\f[R] options.
1540 If TTY mode is \f[I]not\f[R] available (see the \f[B]TTY MODE\f[R]
1541 section), then this environment variable has no effect.
1544 However, when TTY mode is available, then if this environment variable
1545 exists and contains an integer, a non-zero value makes bc(1) use a
1546 prompt, and zero or a non-integer makes bc(1) not use a prompt.
1547 If this environment variable does not exist and \f[B]BC_TTY_MODE\f[R]
1548 does, then the value of the \f[B]BC_TTY_MODE\f[R] environment variable
1551 This environment variable and the \f[B]BC_TTY_MODE\f[R] environment
1552 variable override the default, which can be queried with the
1553 \f[B]-h\f[R] or \f[B]--help\f[R] options.
1556 \f[B]BC_EXPR_EXIT\f[R]
1557 If any expressions or expression files are given on the command-line
1558 with \f[B]-e\f[R], \f[B]--expression\f[R], \f[B]-f\f[R], or
1559 \f[B]--file\f[R], then if this environment variable exists and contains
1560 an integer, a non-zero value makes bc(1) exit after executing the
1561 expressions and expression files, and a zero value makes bc(1) not exit.
1564 This environment variable overrides the default, which can be queried
1565 with the \f[B]-h\f[R] or \f[B]--help\f[R] options.
1568 \f[B]BC_DIGIT_CLAMP\f[R]
1569 When parsing numbers and if this environment variable exists and
1570 contains an integer, a non-zero value makes bc(1) clamp digits that are
1571 greater than or equal to the current \f[B]ibase\f[R] so that all such
1572 digits are considered equal to the \f[B]ibase\f[R] minus 1, and a zero
1573 value disables such clamping so that those digits are always equal to
1574 their value, which is multiplied by the power of the \f[B]ibase\f[R].
1577 This never applies to single-digit numbers, as per the standard (see the
1578 \f[B]STANDARDS\f[R] section).
1580 This environment variable overrides the default, which can be queried
1581 with the \f[B]-h\f[R] or \f[B]--help\f[R] options.
1585 bc(1) returns the following exit statuses:
1591 A math error occurred.
1592 This follows standard practice of using \f[B]1\f[R] for expected errors,
1593 since math errors will happen in the process of normal execution.
1596 Math errors include divide by \f[B]0\f[R], taking the square root of a
1597 negative number, attempting to convert a negative number to a hardware
1598 integer, overflow when converting a number to a hardware integer,
1599 overflow when calculating the size of a number, and attempting to use a
1600 non-integer where an integer is required.
1602 Converting to a hardware integer happens for the second operand of the
1603 power (\f[B]\[ha]\f[R]) operator and the corresponding assignment
1608 A parse error occurred.
1611 Parse errors include unexpected \f[B]EOF\f[R], using an invalid
1612 character, failing to find the end of a string or comment, using a token
1613 where it is invalid, giving an invalid expression, giving an invalid
1614 print statement, giving an invalid function definition, attempting to
1615 assign to an expression that is not a named expression (see the
1616 \f[I]Named Expressions\f[R] subsection of the \f[B]SYNTAX\f[R] section),
1617 giving an invalid \f[B]auto\f[R] list, having a duplicate
1618 \f[B]auto\f[R]/function parameter, failing to find the end of a code
1619 block, attempting to return a value from a \f[B]void\f[R] function,
1620 attempting to use a variable as a reference, and using any extensions
1621 when the option \f[B]-s\f[R] or any equivalents were given.
1625 A runtime error occurred.
1628 Runtime errors include assigning an invalid number to any global
1629 (\f[B]ibase\f[R], \f[B]obase\f[R], or \f[B]scale\f[R]), giving a bad
1630 expression to a \f[B]read()\f[R] call, calling \f[B]read()\f[R] inside
1631 of a \f[B]read()\f[R] call, type errors, passing the wrong number of
1632 arguments to functions, attempting to call an undefined function, and
1633 attempting to use a \f[B]void\f[R] function call as a value in an
1638 A fatal error occurred.
1641 Fatal errors include memory allocation errors, I/O errors, failing to
1642 open files, attempting to use files that do not have only ASCII
1643 characters (bc(1) only accepts ASCII characters), attempting to open a
1644 directory as a file, and giving invalid command-line options.
1647 The exit status \f[B]4\f[R] is special; when a fatal error occurs, bc(1)
1648 always exits and returns \f[B]4\f[R], no matter what mode bc(1) is in.
1650 The other statuses will only be returned when bc(1) is not in
1651 interactive mode (see the \f[B]INTERACTIVE MODE\f[R] section), since
1652 bc(1) resets its state (see the \f[B]RESET\f[R] section) and accepts
1653 more input when one of those errors occurs in interactive mode.
1654 This is also the case when interactive mode is forced by the
1655 \f[B]-i\f[R] flag or \f[B]--interactive\f[R] option.
1657 These exit statuses allow bc(1) to be used in shell scripting with error
1658 checking, and its normal behavior can be forced by using the
1659 \f[B]-i\f[R] flag or \f[B]--interactive\f[R] option.
1660 .SH INTERACTIVE MODE
1662 Per the standard (see the \f[B]STANDARDS\f[R] section), bc(1) has an
1663 interactive mode and a non-interactive mode.
1664 Interactive mode is turned on automatically when both \f[B]stdin\f[R]
1665 and \f[B]stdout\f[R] are hooked to a terminal, but the \f[B]-i\f[R] flag
1666 and \f[B]--interactive\f[R] option can turn it on in other situations.
1668 In interactive mode, bc(1) attempts to recover from errors (see the
1669 \f[B]RESET\f[R] section), and in normal execution, flushes
1670 \f[B]stdout\f[R] as soon as execution is done for the current input.
1671 bc(1) may also reset on \f[B]SIGINT\f[R] instead of exit, depending on
1672 the contents of, or default for, the \f[B]BC_SIGINT_RESET\f[R]
1673 environment variable (see the \f[B]ENVIRONMENT VARIABLES\f[R] section).
1676 If \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all
1677 connected to a TTY, then \[lq]TTY mode\[rq] is considered to be
1678 available, and thus, bc(1) can turn on TTY mode, subject to some
1681 If there is the environment variable \f[B]BC_TTY_MODE\f[R] in the
1682 environment (see the \f[B]ENVIRONMENT VARIABLES\f[R] section), then if
1683 that environment variable contains a non-zero integer, bc(1) will turn
1684 on TTY mode when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R]
1685 are all connected to a TTY.
1686 If the \f[B]BC_TTY_MODE\f[R] environment variable exists but is
1687 \f[I]not\f[R] a non-zero integer, then bc(1) will not turn TTY mode on.
1689 If the environment variable \f[B]BC_TTY_MODE\f[R] does \f[I]not\f[R]
1690 exist, the default setting is used.
1691 The default setting can be queried with the \f[B]-h\f[R] or
1692 \f[B]--help\f[R] options.
1694 TTY mode is different from interactive mode because interactive mode is
1695 required in the bc(1) standard (see the \f[B]STANDARDS\f[R] section),
1696 and interactive mode requires only \f[B]stdin\f[R] and \f[B]stdout\f[R]
1697 to be connected to a terminal.
1700 If TTY mode is available, then a prompt can be enabled.
1701 Like TTY mode itself, it can be turned on or off with an environment
1702 variable: \f[B]BC_PROMPT\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R]
1705 If the environment variable \f[B]BC_PROMPT\f[R] exists and is a non-zero
1706 integer, then the prompt is turned on when \f[B]stdin\f[R],
1707 \f[B]stdout\f[R], and \f[B]stderr\f[R] are connected to a TTY and the
1708 \f[B]-P\f[R] and \f[B]--no-prompt\f[R] options were not used.
1709 The read prompt will be turned on under the same conditions, except that
1710 the \f[B]-R\f[R] and \f[B]--no-read-prompt\f[R] options must also not be
1713 However, if \f[B]BC_PROMPT\f[R] does not exist, the prompt can be
1714 enabled or disabled with the \f[B]BC_TTY_MODE\f[R] environment variable,
1715 the \f[B]-P\f[R] and \f[B]--no-prompt\f[R] options, and the \f[B]-R\f[R]
1716 and \f[B]--no-read-prompt\f[R] options.
1717 See the \f[B]ENVIRONMENT VARIABLES\f[R] and \f[B]OPTIONS\f[R] sections
1721 Sending a \f[B]SIGINT\f[R] will cause bc(1) to do one of two things.
1723 If bc(1) is not in interactive mode (see the \f[B]INTERACTIVE MODE\f[R]
1724 section), or the \f[B]BC_SIGINT_RESET\f[R] environment variable (see the
1725 \f[B]ENVIRONMENT VARIABLES\f[R] section), or its default, is either not
1726 an integer or it is zero, bc(1) will exit.
1728 However, if bc(1) is in interactive mode, and the
1729 \f[B]BC_SIGINT_RESET\f[R] or its default is an integer and non-zero,
1730 then bc(1) will stop executing the current input and reset (see the
1731 \f[B]RESET\f[R] section) upon receiving a \f[B]SIGINT\f[R].
1733 Note that \[lq]current input\[rq] can mean one of two things.
1734 If bc(1) is processing input from \f[B]stdin\f[R] in interactive mode,
1735 it will ask for more input.
1736 If bc(1) is processing input from a file in interactive mode, it will
1737 stop processing the file and start processing the next file, if one
1738 exists, or ask for input from \f[B]stdin\f[R] if no other file exists.
1740 This means that if a \f[B]SIGINT\f[R] is sent to bc(1) as it is
1741 executing a file, it can seem as though bc(1) did not respond to the
1742 signal since it will immediately start executing the next file.
1743 This is by design; most files that users execute when interacting with
1744 bc(1) have function definitions, which are quick to parse.
1745 If a file takes a long time to execute, there may be a bug in that file.
1746 The rest of the files could still be executed without problem, allowing
1747 the user to continue.
1749 \f[B]SIGTERM\f[R] and \f[B]SIGQUIT\f[R] cause bc(1) to clean up and
1750 exit, and it uses the default handler for all other signals.
1756 bc(1) is compliant with the IEEE Std 1003.1-2017
1757 (\[lq]POSIX.1-2017\[rq]) specification at
1758 https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html .
1759 The flags \f[B]-efghiqsvVw\f[R], all long options, and the extensions
1760 noted above are extensions to that specification.
1762 In addition, the behavior of the \f[B]quit\f[R] implements an
1763 interpretation of that specification that is different from all known
1765 For more information see the \f[B]Statements\f[R] subsection of the
1766 \f[B]SYNTAX\f[R] section.
1768 Note that the specification explicitly says that bc(1) only accepts
1769 numbers that use a period (\f[B].\f[R]) as a radix point, regardless of
1770 the value of \f[B]LC_NUMERIC\f[R].
1773 Before version \f[B]6.1.0\f[R], this bc(1) had incorrect behavior for
1774 the \f[B]quit\f[R] statement.
1776 No other bugs are known.
1777 Report bugs at https://git.gavinhoward.com/gavin/bc .
1781 Howard <gavin@gavinhoward.com> and contributors.