contrib/bc/manuals/bc/EN.1

   1 .\"
   2 .\" SPDX-License-Identifier: BSD-2-Clause
   3 .\"
   4 .\" Copyright (c) 2018-2020 Gavin D. Howard and contributors.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions are met:
   8 .\"
   9 .\" * Redistributions of source code must retain the above copyright notice,
  10 .\"   this list of conditions and the following disclaimer.
  11 .\"
  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.
  15 .\"
  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.
  27 .\"
  28 .TH "BC" "1" "October 2020" "Gavin D. Howard" "General Commands Manual"
  29 .SH NAME
  30 .PP
  31 bc - arbitrary-precision decimal arithmetic language and calculator
  32 .SH SYNOPSIS
  33 .PP
  34 \f[B]bc\f[R] [\f[B]-ghilPqsvVw\f[R]] [\f[B]\[en]global-stacks\f[R]]
  35 [\f[B]\[en]help\f[R]] [\f[B]\[en]interactive\f[R]]
  36 [\f[B]\[en]mathlib\f[R]] [\f[B]\[en]no-prompt\f[R]]
  37 [\f[B]\[en]quiet\f[R]] [\f[B]\[en]standard\f[R]] [\f[B]\[en]warn\f[R]]
  38 [\f[B]\[en]version\f[R]] [\f[B]-e\f[R] \f[I]expr\f[R]]
  39 [\f[B]\[en]expression\f[R]=\f[I]expr\f[R]\&...] [\f[B]-f\f[R]
  40 \f[I]file\f[R]\&...] [\f[B]-file\f[R]=\f[I]file\f[R]\&...]
  41 [\f[I]file\f[R]\&...]
  42 .SH DESCRIPTION
  43 .PP
  44 bc(1) is an interactive processor for a language first standardized in
  45 1991 by POSIX.
  46 (The current standard is
  47 here (https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html).)
  48 The language provides unlimited precision decimal arithmetic and is
  49 somewhat C-like, but there are differences.
  50 Such differences will be noted in this document.
  51 .PP
  52 After parsing and handling options, this bc(1) reads any files given on
  53 the command line and executes them before reading from \f[B]stdin\f[R].
  54 .PP
  55 This bc(1) is a drop-in replacement for \f[I]any\f[R] bc(1), including
  56 (and especially) the GNU bc(1).
  57 .SH OPTIONS
  58 .PP
  59 The following are the options that bc(1) accepts.
  60 .PP
  61 \f[B]-g\f[R], \f[B]\[en]global-stacks\f[R]
  62 .IP
  63 .nf
  64 \f[C]
  65 Turns the globals **ibase**, **obase**, and **scale** into stacks.
  66
  67 This has the effect that a copy of the current value of all three are pushed
  68 onto a stack for every function call, as well as popped when every function
  69 returns. This means that functions can assign to any and all of those
  70 globals without worrying that the change will affect other functions.
  71 Thus, a hypothetical function named **output(x,b)** that simply printed
  72 **x** in base **b** could be written like this:
  73
  74     define void output(x, b) {
  75         obase=b
  76         x
  77     }
  78
  79 instead of like this:
  80
  81     define void output(x, b) {
  82         auto c
  83         c=obase
  84         obase=b
  85         x
  86         obase=c
  87     }
  88
  89 This makes writing functions much easier.
  90
  91 However, since using this flag means that functions cannot set **ibase**,
  92 **obase**, or **scale** globally, functions that are made to do so cannot
  93 work anymore. There are two possible use cases for that, and each has a
  94 solution.
  95
  96 First, if a function is called on startup to turn bc(1) into a number
  97 converter, it is possible to replace that capability with various shell
  98 aliases. Examples:
  99
 100     alias d2o=\[dq]bc -e ibase=A -e obase=8\[dq]
 101     alias h2b=\[dq]bc -e ibase=G -e obase=2\[dq]
 102
 103 Second, if the purpose of a function is to set **ibase**, **obase**, or
 104 **scale** globally for any other purpose, it could be split into one to
 105 three functions (based on how many globals it sets) and each of those
 106 functions could return the desired value for a global.
 107
 108 If the behavior of this option is desired for every run of bc(1), then users
 109 could make sure to define **BC_ENV_ARGS** and include this option (see the
 110 **ENVIRONMENT VARIABLES** section for more details).
 111
 112 If **-s**, **-w**, or any equivalents are used, this option is ignored.
 113
 114 This is a **non-portable extension**.
 115 \f[R]
 116 .fi
 117 .TP
 118 \f[B]-h\f[R], \f[B]\[en]help\f[R]
 119 Prints a usage message and quits.
 120 .TP
 121 \f[B]-i\f[R], \f[B]\[en]interactive\f[R]
 122 Forces interactive mode.
 123 (See the \f[B]INTERACTIVE MODE\f[R] section.)
 124 .RS
 125 .PP
 126 This is a \f[B]non-portable extension\f[R].
 127 .RE
 128 .TP
 129 \f[B]-l\f[R], \f[B]\[en]mathlib\f[R]
 130 Sets \f[B]scale\f[R] (see the \f[B]SYNTAX\f[R] section) to \f[B]20\f[R]
 131 and loads the included math library before running any code, including
 132 any expressions or files specified on the command line.
 133 .RS
 134 .PP
 135 To learn what is in the library, see the \f[B]LIBRARY\f[R] section.
 136 .RE
 137 .TP
 138 \f[B]-P\f[R], \f[B]\[en]no-prompt\f[R]
 139 Disables the prompt in TTY mode.
 140 (The prompt is only enabled in TTY mode.
 141 See the \f[B]TTY MODE\f[R] section) This is mostly for those users that
 142 do not want a prompt or are not used to having them in bc(1).
 143 Most of those users would want to put this option in
 144 \f[B]BC_ENV_ARGS\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section).
 145 .RS
 146 .PP
 147 This is a \f[B]non-portable extension\f[R].
 148 .RE
 149 .TP
 150 \f[B]-q\f[R], \f[B]\[en]quiet\f[R]
 151 This option is for compatibility with the GNU
 152 bc(1) (https://www.gnu.org/software/bc/); it is a no-op.
 153 Without this option, GNU bc(1) prints a copyright header.
 154 This bc(1) only prints the copyright header if one or more of the
 155 \f[B]-v\f[R], \f[B]-V\f[R], or \f[B]\[en]version\f[R] options are given.
 156 .RS
 157 .PP
 158 This is a \f[B]non-portable extension\f[R].
 159 .RE
 160 .TP
 161 \f[B]-s\f[R], \f[B]\[en]standard\f[R]
 162 Process exactly the language defined by the
 163 standard (https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html)
 164 and error if any extensions are used.
 165 .RS
 166 .PP
 167 This is a \f[B]non-portable extension\f[R].
 168 .RE
 169 .TP
 170 \f[B]-v\f[R], \f[B]-V\f[R], \f[B]\[en]version\f[R]
 171 Print the version information (copyright header) and exit.
 172 .RS
 173 .PP
 174 This is a \f[B]non-portable extension\f[R].
 175 .RE
 176 .TP
 177 \f[B]-w\f[R], \f[B]\[en]warn\f[R]
 178 Like \f[B]-s\f[R] and \f[B]\[en]standard\f[R], except that warnings (and
 179 not errors) are printed for non-standard extensions and execution
 180 continues normally.
 181 .RS
 182 .PP
 183 This is a \f[B]non-portable extension\f[R].
 184 .RE
 185 .TP
 186 \f[B]-e\f[R] \f[I]expr\f[R], \f[B]\[en]expression\f[R]=\f[I]expr\f[R]
 187 Evaluates \f[I]expr\f[R].
 188 If multiple expressions are given, they are evaluated in order.
 189 If files are given as well (see below), the expressions and files are
 190 evaluated in the order given.
 191 This means that if a file is given before an expression, the file is
 192 read in and evaluated first.
 193 .RS
 194 .PP
 195 After processing all expressions and files, bc(1) will exit, unless
 196 \f[B]-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to
 197 \f[B]-f\f[R] or \f[B]\[en]file\f[R].
 198 However, if any other \f[B]-e\f[R], \f[B]\[en]expression\f[R],
 199 \f[B]-f\f[R], or \f[B]\[en]file\f[R] arguments are given after that,
 200 bc(1) will give a fatal error and exit.
 201 .PP
 202 This is a \f[B]non-portable extension\f[R].
 203 .RE
 204 .TP
 205 \f[B]-f\f[R] \f[I]file\f[R], \f[B]\[en]file\f[R]=\f[I]file\f[R]
 206 Reads in \f[I]file\f[R] and evaluates it, line by line, as though it
 207 were read through \f[B]stdin\f[R].
 208 If expressions are also given (see above), the expressions are evaluated
 209 in the order given.
 210 .RS
 211 .PP
 212 After processing all expressions and files, bc(1) will exit, unless
 213 \f[B]-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to
 214 \f[B]-f\f[R] or \f[B]\[en]file\f[R].
 215 .PP
 216 This is a \f[B]non-portable extension\f[R].
 217 .RE
 218 .PP
 219 All long options are \f[B]non-portable extensions\f[R].
 220 .SH STDOUT
 221 .PP
 222 Any non-error output is written to \f[B]stdout\f[R].
 223 .PP
 224 \f[B]Note\f[R]: Unlike other bc(1) implementations, this bc(1) will
 225 issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot
 226 write to \f[B]stdout\f[R], so if \f[B]stdout\f[R] is closed, as in
 227 \f[B]bc >&-\f[R], it will quit with an error.
 228 This is done so that bc(1) can report problems when \f[B]stdout\f[R] is
 229 redirected to a file.
 230 .PP
 231 If there are scripts that depend on the behavior of other bc(1)
 232 implementations, it is recommended that those scripts be changed to
 233 redirect \f[B]stdout\f[R] to \f[B]/dev/null\f[R].
 234 .SH STDERR
 235 .PP
 236 Any error output is written to \f[B]stderr\f[R].
 237 .PP
 238 \f[B]Note\f[R]: Unlike other bc(1) implementations, this bc(1) will
 239 issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot
 240 write to \f[B]stderr\f[R], so if \f[B]stderr\f[R] is closed, as in
 241 \f[B]bc 2>&-\f[R], it will quit with an error.
 242 This is done so that bc(1) can exit with an error code when
 243 \f[B]stderr\f[R] is redirected to a file.
 244 .PP
 245 If there are scripts that depend on the behavior of other bc(1)
 246 implementations, it is recommended that those scripts be changed to
 247 redirect \f[B]stderr\f[R] to \f[B]/dev/null\f[R].
 248 .SH SYNTAX
 249 .PP
 250 The syntax for bc(1) programs is mostly C-like, with some differences.
 251 This bc(1) follows the POSIX
 252 standard (https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html),
 253 which is a much more thorough resource for the language this bc(1)
 254 accepts.
 255 This section is meant to be a summary and a listing of all the
 256 extensions to the standard.
 257 .PP
 258 In the sections below, \f[B]E\f[R] means expression, \f[B]S\f[R] means
 259 statement, and \f[B]I\f[R] means identifier.
 260 .PP
 261 Identifiers (\f[B]I\f[R]) start with a lowercase letter and can be
 262 followed by any number (up to \f[B]BC_NAME_MAX-1\f[R]) of lowercase
 263 letters (\f[B]a-z\f[R]), digits (\f[B]0-9\f[R]), and underscores
 264 (\f[B]_\f[R]).
 265 The regex is \f[B][a-z][a-z0-9_]*\f[R].
 266 Identifiers with more than one character (letter) are a
 267 \f[B]non-portable extension\f[R].
 268 .PP
 269 \f[B]ibase\f[R] is a global variable determining how to interpret
 270 constant numbers.
 271 It is the \[lq]input\[rq] base, or the number base used for interpreting
 272 input numbers.
 273 \f[B]ibase\f[R] is initially \f[B]10\f[R].
 274 If the \f[B]-s\f[R] (\f[B]\[en]standard\f[R]) and \f[B]-w\f[R]
 275 (\f[B]\[en]warn\f[R]) flags were not given on the command line, the max
 276 allowable value for \f[B]ibase\f[R] is \f[B]36\f[R].
 277 Otherwise, it is \f[B]16\f[R].
 278 The min allowable value for \f[B]ibase\f[R] is \f[B]2\f[R].
 279 The max allowable value for \f[B]ibase\f[R] can be queried in bc(1)
 280 programs with the \f[B]maxibase()\f[R] built-in function.
 281 .PP
 282 \f[B]obase\f[R] is a global variable determining how to output results.
 283 It is the \[lq]output\[rq] base, or the number base used for outputting
 284 numbers.
 285 \f[B]obase\f[R] is initially \f[B]10\f[R].
 286 The max allowable value for \f[B]obase\f[R] is \f[B]BC_BASE_MAX\f[R] and
 287 can be queried in bc(1) programs with the \f[B]maxobase()\f[R] built-in
 288 function.
 289 The min allowable value for \f[B]obase\f[R] is \f[B]2\f[R].
 290 Values are output in the specified base.
 291 .PP
 292 The \f[I]scale\f[R] of an expression is the number of digits in the
 293 result of the expression right of the decimal point, and \f[B]scale\f[R]
 294 is a global variable that sets the precision of any operations, with
 295 exceptions.
 296 \f[B]scale\f[R] is initially \f[B]0\f[R].
 297 \f[B]scale\f[R] cannot be negative.
 298 The max allowable value for \f[B]scale\f[R] is \f[B]BC_SCALE_MAX\f[R]
 299 and can be queried in bc(1) programs with the \f[B]maxscale()\f[R]
 300 built-in function.
 301 .PP
 302 bc(1) has both \f[I]global\f[R] variables and \f[I]local\f[R] variables.
 303 All \f[I]local\f[R] variables are local to the function; they are
 304 parameters or are introduced in the \f[B]auto\f[R] list of a function
 305 (see the \f[B]FUNCTIONS\f[R] section).
 306 If a variable is accessed which is not a parameter or in the
 307 \f[B]auto\f[R] list, it is assumed to be \f[I]global\f[R].
 308 If a parent function has a \f[I]local\f[R] variable version of a
 309 variable that a child function considers \f[I]global\f[R], the value of
 310 that \f[I]global\f[R] variable in the child function is the value of the
 311 variable in the parent function, not the value of the actual
 312 \f[I]global\f[R] variable.
 313 .PP
 314 All of the above applies to arrays as well.
 315 .PP
 316 The value of a statement that is an expression (i.e., any of the named
 317 expressions or operands) is printed unless the lowest precedence
 318 operator is an assignment operator \f[I]and\f[R] the expression is
 319 notsurrounded by parentheses.
 320 .PP
 321 The value that is printed is also assigned to the special variable
 322 \f[B]last\f[R].
 323 A single dot (\f[B].\f[R]) may also be used as a synonym for
 324 \f[B]last\f[R].
 325 These are \f[B]non-portable extensions\f[R].
 326 .PP
 327 Either semicolons or newlines may separate statements.
 328 .SS Comments
 329 .PP
 330 There are two kinds of comments:
 331 .IP "1." 3
 332 Block comments are enclosed in \f[B]/*\f[R] and \f[B]*/\f[R].
 333 .IP "2." 3
 334 Line comments go from \f[B]#\f[R] until, and not including, the next
 335 newline.
 336 This is a \f[B]non-portable extension\f[R].
 337 .SS Named Expressions
 338 .PP
 339 The following are named expressions in bc(1):
 340 .IP "1." 3
 341 Variables: \f[B]I\f[R]
 342 .IP "2." 3
 343 Array Elements: \f[B]I[E]\f[R]
 344 .IP "3." 3
 345 \f[B]ibase\f[R]
 346 .IP "4." 3
 347 \f[B]obase\f[R]
 348 .IP "5." 3
 349 \f[B]scale\f[R]
 350 .IP "6." 3
 351 \f[B]last\f[R] or a single dot (\f[B].\f[R])
 352 .PP
 353 Number 6 is a \f[B]non-portable extension\f[R].
 354 .PP
 355 Variables and arrays do not interfere; users can have arrays named the
 356 same as variables.
 357 This also applies to functions (see the \f[B]FUNCTIONS\f[R] section), so
 358 a user can have a variable, array, and function that all have the same
 359 name, and they will not shadow each other, whether inside of functions
 360 or not.
 361 .PP
 362 Named expressions are required as the operand of
 363 \f[B]increment\f[R]/\f[B]decrement\f[R] operators and as the left side
 364 of \f[B]assignment\f[R] operators (see the \f[I]Operators\f[R]
 365 subsection).
 366 .SS Operands
 367 .PP
 368 The following are valid operands in bc(1):
 369 .IP " 1." 4
 370 Numbers (see the \f[I]Numbers\f[R] subsection below).
 371 .IP " 2." 4
 372 Array indices (\f[B]I[E]\f[R]).
 373 .IP " 3." 4
 374 \f[B](E)\f[R]: The value of \f[B]E\f[R] (used to change precedence).
 375 .IP " 4." 4
 376 \f[B]sqrt(E)\f[R]: The square root of \f[B]E\f[R].
 377 \f[B]E\f[R] must be non-negative.
 378 .IP " 5." 4
 379 \f[B]length(E)\f[R]: The number of significant decimal digits in
 380 \f[B]E\f[R].
 381 .IP " 6." 4
 382 \f[B]length(I[])\f[R]: The number of elements in the array \f[B]I\f[R].
 383 This is a \f[B]non-portable extension\f[R].
 384 .IP " 7." 4
 385 \f[B]scale(E)\f[R]: The \f[I]scale\f[R] of \f[B]E\f[R].
 386 .IP " 8." 4
 387 \f[B]abs(E)\f[R]: The absolute value of \f[B]E\f[R].
 388 This is a \f[B]non-portable extension\f[R].
 389 .IP " 9." 4
 390 \f[B]I()\f[R], \f[B]I(E)\f[R], \f[B]I(E, E)\f[R], and so on, where
 391 \f[B]I\f[R] is an identifier for a non-\f[B]void\f[R] function (see the
 392 \f[I]Void Functions\f[R] subsection of the \f[B]FUNCTIONS\f[R] section).
 393 The \f[B]E\f[R] argument(s) may also be arrays of the form
 394 \f[B]I[]\f[R], which will automatically be turned into array references
 395 (see the \f[I]Array References\f[R] subsection of the
 396 \f[B]FUNCTIONS\f[R] section) if the corresponding parameter in the
 397 function definition is an array reference.
 398 .IP "10." 4
 399 \f[B]read()\f[R]: Reads a line from \f[B]stdin\f[R] and uses that as an
 400 expression.
 401 The result of that expression is the result of the \f[B]read()\f[R]
 402 operand.
 403 This is a \f[B]non-portable extension\f[R].
 404 .IP "11." 4
 405 \f[B]maxibase()\f[R]: The max allowable \f[B]ibase\f[R].
 406 This is a \f[B]non-portable extension\f[R].
 407 .IP "12." 4
 408 \f[B]maxobase()\f[R]: The max allowable \f[B]obase\f[R].
 409 This is a \f[B]non-portable extension\f[R].
 410 .IP "13." 4
 411 \f[B]maxscale()\f[R]: The max allowable \f[B]scale\f[R].
 412 This is a \f[B]non-portable extension\f[R].
 413 .SS Numbers
 414 .PP
 415 Numbers are strings made up of digits, uppercase letters, and at most
 416 \f[B]1\f[R] period for a radix.
 417 Numbers can have up to \f[B]BC_NUM_MAX\f[R] digits.
 418 Uppercase letters are equal to \f[B]9\f[R] + their position in the
 419 alphabet (i.e., \f[B]A\f[R] equals \f[B]10\f[R], or \f[B]9+1\f[R]).
 420 If a digit or letter makes no sense with the current value of
 421 \f[B]ibase\f[R], they are set to the value of the highest valid digit in
 422 \f[B]ibase\f[R].
 423 .PP
 424 Single-character numbers (i.e., \f[B]A\f[R] alone) take the value that
 425 they would have if they were valid digits, regardless of the value of
 426 \f[B]ibase\f[R].
 427 This means that \f[B]A\f[R] alone always equals decimal \f[B]10\f[R] and
 428 \f[B]Z\f[R] alone always equals decimal \f[B]35\f[R].
 429 .SS Operators
 430 .PP
 431 The following arithmetic and logical operators can be used.
 432 They are listed in order of decreasing precedence.
 433 Operators in the same group have the same precedence.
 434 .TP
 435 \f[B]++\f[R] \f[B]\[en]\f[R]
 436 Type: Prefix and Postfix
 437 .RS
 438 .PP
 439 Associativity: None
 440 .PP
 441 Description: \f[B]increment\f[R], \f[B]decrement\f[R]
 442 .RE
 443 .TP
 444 \f[B]-\f[R] \f[B]!\f[R]
 445 Type: Prefix
 446 .RS
 447 .PP
 448 Associativity: None
 449 .PP
 450 Description: \f[B]negation\f[R], \f[B]boolean not\f[R]
 451 .RE
 452 .TP
 453 \f[B]\[ha]\f[R]
 454 Type: Binary
 455 .RS
 456 .PP
 457 Associativity: Right
 458 .PP
 459 Description: \f[B]power\f[R]
 460 .RE
 461 .TP
 462 \f[B]*\f[R] \f[B]/\f[R] \f[B]%\f[R]
 463 Type: Binary
 464 .RS
 465 .PP
 466 Associativity: Left
 467 .PP
 468 Description: \f[B]multiply\f[R], \f[B]divide\f[R], \f[B]modulus\f[R]
 469 .RE
 470 .TP
 471 \f[B]+\f[R] \f[B]-\f[R]
 472 Type: Binary
 473 .RS
 474 .PP
 475 Associativity: Left
 476 .PP
 477 Description: \f[B]add\f[R], \f[B]subtract\f[R]
 478 .RE
 479 .TP
 480 \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]
 481 Type: Binary
 482 .RS
 483 .PP
 484 Associativity: Right
 485 .PP
 486 Description: \f[B]assignment\f[R]
 487 .RE
 488 .TP
 489 \f[B]==\f[R] \f[B]<=\f[R] \f[B]>=\f[R] \f[B]!=\f[R] \f[B]<\f[R] \f[B]>\f[R]
 490 Type: Binary
 491 .RS
 492 .PP
 493 Associativity: Left
 494 .PP
 495 Description: \f[B]relational\f[R]
 496 .RE
 497 .TP
 498 \f[B]&&\f[R]
 499 Type: Binary
 500 .RS
 501 .PP
 502 Associativity: Left
 503 .PP
 504 Description: \f[B]boolean and\f[R]
 505 .RE
 506 .TP
 507 \f[B]||\f[R]
 508 Type: Binary
 509 .RS
 510 .PP
 511 Associativity: Left
 512 .PP
 513 Description: \f[B]boolean or\f[R]
 514 .RE
 515 .PP
 516 The operators will be described in more detail below.
 517 .TP
 518 \f[B]++\f[R] \f[B]\[en]\f[R]
 519 The prefix and postfix \f[B]increment\f[R] and \f[B]decrement\f[R]
 520 operators behave exactly like they would in C.
 521 They require a named expression (see the \f[I]Named Expressions\f[R]
 522 subsection) as an operand.
 523 .RS
 524 .PP
 525 The prefix versions of these operators are more efficient; use them
 526 where possible.
 527 .RE
 528 .TP
 529 \f[B]-\f[R]
 530 The \f[B]negation\f[R] operator returns \f[B]0\f[R] if a user attempts
 531 to negate any expression with the value \f[B]0\f[R].
 532 Otherwise, a copy of the expression with its sign flipped is returned.
 533 .TP
 534 \f[B]!\f[R]
 535 The \f[B]boolean not\f[R] operator returns \f[B]1\f[R] if the expression
 536 is \f[B]0\f[R], or \f[B]0\f[R] otherwise.
 537 .RS
 538 .PP
 539 This is a \f[B]non-portable extension\f[R].
 540 .RE
 541 .TP
 542 \f[B]\[ha]\f[R]
 543 The \f[B]power\f[R] operator (not the \f[B]exclusive or\f[R] operator,
 544 as it would be in C) takes two expressions and raises the first to the
 545 power of the value of the second.
 546 The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R].
 547 .RS
 548 .PP
 549 The second expression must be an integer (no \f[I]scale\f[R]), and if it
 550 is negative, the first value must be non-zero.
 551 .RE
 552 .TP
 553 \f[B]*\f[R]
 554 The \f[B]multiply\f[R] operator takes two expressions, multiplies them,
 555 and returns the product.
 556 If \f[B]a\f[R] is the \f[I]scale\f[R] of the first expression and
 557 \f[B]b\f[R] is the \f[I]scale\f[R] of the second expression, the
 558 \f[I]scale\f[R] of the result is equal to
 559 \f[B]min(a+b,max(scale,a,b))\f[R] where \f[B]min()\f[R] and
 560 \f[B]max()\f[R] return the obvious values.
 561 .TP
 562 \f[B]/\f[R]
 563 The \f[B]divide\f[R] operator takes two expressions, divides them, and
 564 returns the quotient.
 565 The \f[I]scale\f[R] of the result shall be the value of \f[B]scale\f[R].
 566 .RS
 567 .PP
 568 The second expression must be non-zero.
 569 .RE
 570 .TP
 571 \f[B]%\f[R]
 572 The \f[B]modulus\f[R] operator takes two expressions, \f[B]a\f[R] and
 573 \f[B]b\f[R], and evaluates them by 1) Computing \f[B]a/b\f[R] to current
 574 \f[B]scale\f[R] and 2) Using the result of step 1 to calculate
 575 \f[B]a-(a/b)*b\f[R] to \f[I]scale\f[R]
 576 \f[B]max(scale+scale(b),scale(a))\f[R].
 577 .RS
 578 .PP
 579 The second expression must be non-zero.
 580 .RE
 581 .TP
 582 \f[B]+\f[R]
 583 The \f[B]add\f[R] operator takes two expressions, \f[B]a\f[R] and
 584 \f[B]b\f[R], and returns the sum, with a \f[I]scale\f[R] equal to the
 585 max of the \f[I]scale\f[R]s of \f[B]a\f[R] and \f[B]b\f[R].
 586 .TP
 587 \f[B]-\f[R]
 588 The \f[B]subtract\f[R] operator takes two expressions, \f[B]a\f[R] and
 589 \f[B]b\f[R], and returns the difference, with a \f[I]scale\f[R] equal to
 590 the max of the \f[I]scale\f[R]s of \f[B]a\f[R] and \f[B]b\f[R].
 591 .TP
 592 \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]
 593 The \f[B]assignment\f[R] operators take two expressions, \f[B]a\f[R] and
 594 \f[B]b\f[R] where \f[B]a\f[R] is a named expression (see the \f[I]Named
 595 Expressions\f[R] subsection).
 596 .RS
 597 .PP
 598 For \f[B]=\f[R], \f[B]b\f[R] is copied and the result is assigned to
 599 \f[B]a\f[R].
 600 For all others, \f[B]a\f[R] and \f[B]b\f[R] are applied as operands to
 601 the corresponding arithmetic operator and the result is assigned to
 602 \f[B]a\f[R].
 603 .RE
 604 .TP
 605 \f[B]==\f[R] \f[B]<=\f[R] \f[B]>=\f[R] \f[B]!=\f[R] \f[B]<\f[R] \f[B]>\f[R]
 606 The \f[B]relational\f[R] operators compare two expressions, \f[B]a\f[R]
 607 and \f[B]b\f[R], and if the relation holds, according to C language
 608 semantics, the result is \f[B]1\f[R].
 609 Otherwise, it is \f[B]0\f[R].
 610 .RS
 611 .PP
 612 Note that unlike in C, these operators have a lower precedence than the
 613 \f[B]assignment\f[R] operators, which means that \f[B]a=b>c\f[R] is
 614 interpreted as \f[B](a=b)>c\f[R].
 615 .PP
 616 Also, unlike the
 617 standard (https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html)
 618 requires, these operators can appear anywhere any other expressions can
 619 be used.
 620 This allowance is a \f[B]non-portable extension\f[R].
 621 .RE
 622 .TP
 623 \f[B]&&\f[R]
 624 The \f[B]boolean and\f[R] operator takes two expressions and returns
 625 \f[B]1\f[R] if both expressions are non-zero, \f[B]0\f[R] otherwise.
 626 .RS
 627 .PP
 628 This is \f[I]not\f[R] a short-circuit operator.
 629 .PP
 630 This is a \f[B]non-portable extension\f[R].
 631 .RE
 632 .TP
 633 \f[B]||\f[R]
 634 The \f[B]boolean or\f[R] operator takes two expressions and returns
 635 \f[B]1\f[R] if one of the expressions is non-zero, \f[B]0\f[R]
 636 otherwise.
 637 .RS
 638 .PP
 639 This is \f[I]not\f[R] a short-circuit operator.
 640 .PP
 641 This is a \f[B]non-portable extension\f[R].
 642 .RE
 643 .SS Statements
 644 .PP
 645 The following items are statements:
 646 .IP " 1." 4
 647 \f[B]E\f[R]
 648 .IP " 2." 4
 649 \f[B]{\f[R] \f[B]S\f[R] \f[B];\f[R] \&... \f[B];\f[R] \f[B]S\f[R]
 650 \f[B]}\f[R]
 651 .IP " 3." 4
 652 \f[B]if\f[R] \f[B](\f[R] \f[B]E\f[R] \f[B])\f[R] \f[B]S\f[R]
 653 .IP " 4." 4
 654 \f[B]if\f[R] \f[B](\f[R] \f[B]E\f[R] \f[B])\f[R] \f[B]S\f[R]
 655 \f[B]else\f[R] \f[B]S\f[R]
 656 .IP " 5." 4
 657 \f[B]while\f[R] \f[B](\f[R] \f[B]E\f[R] \f[B])\f[R] \f[B]S\f[R]
 658 .IP " 6." 4
 659 \f[B]for\f[R] \f[B](\f[R] \f[B]E\f[R] \f[B];\f[R] \f[B]E\f[R]
 660 \f[B];\f[R] \f[B]E\f[R] \f[B])\f[R] \f[B]S\f[R]
 661 .IP " 7." 4
 662 An empty statement
 663 .IP " 8." 4
 664 \f[B]break\f[R]
 665 .IP " 9." 4
 666 \f[B]continue\f[R]
 667 .IP "10." 4
 668 \f[B]quit\f[R]
 669 .IP "11." 4
 670 \f[B]halt\f[R]
 671 .IP "12." 4
 672 \f[B]limits\f[R]
 673 .IP "13." 4
 674 A string of characters, enclosed in double quotes
 675 .IP "14." 4
 676 \f[B]print\f[R] \f[B]E\f[R] \f[B],\f[R] \&... \f[B],\f[R] \f[B]E\f[R]
 677 .IP "15." 4
 678 \f[B]I()\f[R], \f[B]I(E)\f[R], \f[B]I(E, E)\f[R], and so on, where
 679 \f[B]I\f[R] is an identifier for a \f[B]void\f[R] function (see the
 680 \f[I]Void Functions\f[R] subsection of the \f[B]FUNCTIONS\f[R] section).
 681 The \f[B]E\f[R] argument(s) may also be arrays of the form
 682 \f[B]I[]\f[R], which will automatically be turned into array references
 683 (see the \f[I]Array References\f[R] subsection of the
 684 \f[B]FUNCTIONS\f[R] section) if the corresponding parameter in the
 685 function definition is an array reference.
 686 .PP
 687 Numbers 4, 9, 11, 12, 14, and 15 are \f[B]non-portable extensions\f[R].
 688 .PP
 689 Also, as a \f[B]non-portable extension\f[R], any or all of the
 690 expressions in the header of a for loop may be omitted.
 691 If the condition (second expression) is omitted, it is assumed to be a
 692 constant \f[B]1\f[R].
 693 .PP
 694 The \f[B]break\f[R] statement causes a loop to stop iterating and resume
 695 execution immediately following a loop.
 696 This is only allowed in loops.
 697 .PP
 698 The \f[B]continue\f[R] statement causes a loop iteration to stop early
 699 and returns to the start of the loop, including testing the loop
 700 condition.
 701 This is only allowed in loops.
 702 .PP
 703 The \f[B]if\f[R] \f[B]else\f[R] statement does the same thing as in C.
 704 .PP
 705 The \f[B]quit\f[R] statement causes bc(1) to quit, even if it is on a
 706 branch that will not be executed (it is a compile-time command).
 707 .PP
 708 The \f[B]halt\f[R] statement causes bc(1) to quit, if it is executed.
 709 (Unlike \f[B]quit\f[R] if it is on a branch of an \f[B]if\f[R] statement
 710 that is not executed, bc(1) does not quit.)
 711 .PP
 712 The \f[B]limits\f[R] statement prints the limits that this bc(1) is
 713 subject to.
 714 This is like the \f[B]quit\f[R] statement in that it is a compile-time
 715 command.
 716 .PP
 717 An expression by itself is evaluated and printed, followed by a newline.
 718 .SS Print Statement
 719 .PP
 720 The \[lq]expressions\[rq] in a \f[B]print\f[R] statement may also be
 721 strings.
 722 If they are, there are backslash escape sequences that are interpreted
 723 specially.
 724 What those sequences are, and what they cause to be printed, are shown
 725 below:
 726 .PP
 727 .TS
 728 tab(@);
 729 l l.
 730 T{
 731 \f[B]\[rs]a\f[R]
 732 T}@T{
 733 \f[B]\[rs]a\f[R]
 734 T}
 735 T{
 736 \f[B]\[rs]b\f[R]
 737 T}@T{
 738 \f[B]\[rs]b\f[R]
 739 T}
 740 T{
 741 \f[B]\[rs]\[rs]\f[R]
 742 T}@T{
 743 \f[B]\[rs]\f[R]
 744 T}
 745 T{
 746 \f[B]\[rs]e\f[R]
 747 T}@T{
 748 \f[B]\[rs]\f[R]
 749 T}
 750 T{
 751 \f[B]\[rs]f\f[R]
 752 T}@T{
 753 \f[B]\[rs]f\f[R]
 754 T}
 755 T{
 756 \f[B]\[rs]n\f[R]
 757 T}@T{
 758 \f[B]\[rs]n\f[R]
 759 T}
 760 T{
 761 \f[B]\[rs]q\f[R]
 762 T}@T{
 763 \f[B]\[dq]\f[R]
 764 T}
 765 T{
 766 \f[B]\[rs]r\f[R]
 767 T}@T{
 768 \f[B]\[rs]r\f[R]
 769 T}
 770 T{
 771 \f[B]\[rs]t\f[R]
 772 T}@T{
 773 \f[B]\[rs]t\f[R]
 774 T}
 775 .TE
 776 .PP
 777 Any other character following a backslash causes the backslash and
 778 character to be printed as-is.
 779 .PP
 780 Any non-string expression in a print statement shall be assigned to
 781 \f[B]last\f[R], like any other expression that is printed.
 782 .SS Order of Evaluation
 783 .PP
 784 All expressions in a statment are evaluated left to right, except as
 785 necessary to maintain order of operations.
 786 This means, for example, assuming that \f[B]i\f[R] is equal to
 787 \f[B]0\f[R], in the expression
 788 .IP
 789 .nf
 790 \f[C]
 791 a[i++] = i++
 792 \f[R]
 793 .fi
 794 .PP
 795 the first (or 0th) element of \f[B]a\f[R] is set to \f[B]1\f[R], and
 796 \f[B]i\f[R] is equal to \f[B]2\f[R] at the end of the expression.
 797 .PP
 798 This includes function arguments.
 799 Thus, assuming \f[B]i\f[R] is equal to \f[B]0\f[R], this means that in
 800 the expression
 801 .IP
 802 .nf
 803 \f[C]
 804 x(i++, i++)
 805 \f[R]
 806 .fi
 807 .PP
 808 the first argument passed to \f[B]x()\f[R] is \f[B]0\f[R], and the
 809 second argument is \f[B]1\f[R], while \f[B]i\f[R] is equal to
 810 \f[B]2\f[R] before the function starts executing.
 811 .SH FUNCTIONS
 812 .PP
 813 Function definitions are as follows:
 814 .IP
 815 .nf
 816 \f[C]
 817 define I(I,...,I){
 818     auto I,...,I
 819     S;...;S
 820     return(E)
 821 }
 822 \f[R]
 823 .fi
 824 .PP
 825 Any \f[B]I\f[R] in the parameter list or \f[B]auto\f[R] list may be
 826 replaced with \f[B]I[]\f[R] to make a parameter or \f[B]auto\f[R] var an
 827 array, and any \f[B]I\f[R] in the parameter list may be replaced with
 828 \f[B]*I[]\f[R] to make a parameter an array reference.
 829 Callers of functions that take array references should not put an
 830 asterisk in the call; they must be called with just \f[B]I[]\f[R] like
 831 normal array parameters and will be automatically converted into
 832 references.
 833 .PP
 834 As a \f[B]non-portable extension\f[R], the opening brace of a
 835 \f[B]define\f[R] statement may appear on the next line.
 836 .PP
 837 As a \f[B]non-portable extension\f[R], the return statement may also be
 838 in one of the following forms:
 839 .IP "1." 3
 840 \f[B]return\f[R]
 841 .IP "2." 3
 842 \f[B]return\f[R] \f[B](\f[R] \f[B])\f[R]
 843 .IP "3." 3
 844 \f[B]return\f[R] \f[B]E\f[R]
 845 .PP
 846 The first two, or not specifying a \f[B]return\f[R] statement, is
 847 equivalent to \f[B]return (0)\f[R], unless the function is a
 848 \f[B]void\f[R] function (see the \f[I]Void Functions\f[R] subsection
 849 below).
 850 .SS Void Functions
 851 .PP
 852 Functions can also be \f[B]void\f[R] functions, defined as follows:
 853 .IP
 854 .nf
 855 \f[C]
 856 define void I(I,...,I){
 857     auto I,...,I
 858     S;...;S
 859     return
 860 }
 861 \f[R]
 862 .fi
 863 .PP
 864 They can only be used as standalone expressions, where such an
 865 expression would be printed alone, except in a print statement.
 866 .PP
 867 Void functions can only use the first two \f[B]return\f[R] statements
 868 listed above.
 869 They can also omit the return statement entirely.
 870 .PP
 871 The word \[lq]void\[rq] is not treated as a keyword; it is still
 872 possible to have variables, arrays, and functions named \f[B]void\f[R].
 873 The word \[lq]void\[rq] is only treated specially right after the
 874 \f[B]define\f[R] keyword.
 875 .PP
 876 This is a \f[B]non-portable extension\f[R].
 877 .SS Array References
 878 .PP
 879 For any array in the parameter list, if the array is declared in the
 880 form
 881 .IP
 882 .nf
 883 \f[C]
 884 *I[]
 885 \f[R]
 886 .fi
 887 .PP
 888 it is a \f[B]reference\f[R].
 889 Any changes to the array in the function are reflected, when the
 890 function returns, to the array that was passed in.
 891 .PP
 892 Other than this, all function arguments are passed by value.
 893 .PP
 894 This is a \f[B]non-portable extension\f[R].
 895 .SH LIBRARY
 896 .PP
 897 All of the functions below are available when the \f[B]-l\f[R] or
 898 \f[B]\[en]mathlib\f[R] command-line flags are given.
 899 .SS Standard Library
 900 .PP
 901 The
 902 standard (https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html)
 903 defines the following functions for the math library:
 904 .TP
 905 \f[B]s(x)\f[R]
 906 Returns the sine of \f[B]x\f[R], which is assumed to be in radians.
 907 .RS
 908 .PP
 909 This is a transcendental function (see the \f[I]Transcendental
 910 Functions\f[R] subsection below).
 911 .RE
 912 .TP
 913 \f[B]c(x)\f[R]
 914 Returns the cosine of \f[B]x\f[R], which is assumed to be in radians.
 915 .RS
 916 .PP
 917 This is a transcendental function (see the \f[I]Transcendental
 918 Functions\f[R] subsection below).
 919 .RE
 920 .TP
 921 \f[B]a(x)\f[R]
 922 Returns the arctangent of \f[B]x\f[R], in radians.
 923 .RS
 924 .PP
 925 This is a transcendental function (see the \f[I]Transcendental
 926 Functions\f[R] subsection below).
 927 .RE
 928 .TP
 929 \f[B]l(x)\f[R]
 930 Returns the natural logarithm of \f[B]x\f[R].
 931 .RS
 932 .PP
 933 This is a transcendental function (see the \f[I]Transcendental
 934 Functions\f[R] subsection below).
 935 .RE
 936 .TP
 937 \f[B]e(x)\f[R]
 938 Returns the mathematical constant \f[B]e\f[R] raised to the power of
 939 \f[B]x\f[R].
 940 .RS
 941 .PP
 942 This is a transcendental function (see the \f[I]Transcendental
 943 Functions\f[R] subsection below).
 944 .RE
 945 .TP
 946 \f[B]j(x, n)\f[R]
 947 Returns the bessel integer order \f[B]n\f[R] (truncated) of \f[B]x\f[R].
 948 .RS
 949 .PP
 950 This is a transcendental function (see the \f[I]Transcendental
 951 Functions\f[R] subsection below).
 952 .RE
 953 .SS Transcendental Functions
 954 .PP
 955 All transcendental functions can return slightly inaccurate results (up
 956 to 1 ULP (https://en.wikipedia.org/wiki/Unit_in_the_last_place)).
 957 This is unavoidable, and this
 958 article (https://people.eecs.berkeley.edu/~wkahan/LOG10HAF.TXT) explains
 959 why it is impossible and unnecessary to calculate exact results for the
 960 transcendental functions.
 961 .PP
 962 Because of the possible inaccuracy, I recommend that users call those
 963 functions with the precision (\f[B]scale\f[R]) set to at least 1 higher
 964 than is necessary.
 965 If exact results are \f[I]absolutely\f[R] required, users can double the
 966 precision (\f[B]scale\f[R]) and then truncate.
 967 .PP
 968 The transcendental functions in the standard math library are:
 969 .IP \[bu] 2
 970 \f[B]s(x)\f[R]
 971 .IP \[bu] 2
 972 \f[B]c(x)\f[R]
 973 .IP \[bu] 2
 974 \f[B]a(x)\f[R]
 975 .IP \[bu] 2
 976 \f[B]l(x)\f[R]
 977 .IP \[bu] 2
 978 \f[B]e(x)\f[R]
 979 .IP \[bu] 2
 980 \f[B]j(x, n)\f[R]
 981 .SH RESET
 982 .PP
 983 When bc(1) encounters an error or a signal that it has a non-default
 984 handler for, it resets.
 985 This means that several things happen.
 986 .PP
 987 First, any functions that are executing are stopped and popped off the
 988 stack.
 989 The behavior is not unlike that of exceptions in programming languages.
 990 Then the execution point is set so that any code waiting to execute
 991 (after all functions returned) is skipped.
 992 .PP
 993 Thus, when bc(1) resets, it skips any remaining code waiting to be
 994 executed.
 995 Then, if it is interactive mode, and the error was not a fatal error
 996 (see the \f[B]EXIT STATUS\f[R] section), it asks for more input;
 997 otherwise, it exits with the appropriate return code.
 998 .PP
 999 Note that this reset behavior is different from the GNU bc(1), which
1000 attempts to start executing the statement right after the one that
1001 caused an error.
1002 .SH PERFORMANCE
1003 .PP
1004 Most bc(1) implementations use \f[B]char\f[R] types to calculate the
1005 value of \f[B]1\f[R] decimal digit at a time, but that can be slow.
1006 This bc(1) does something different.
1007 .PP
1008 It uses large integers to calculate more than \f[B]1\f[R] decimal digit
1009 at a time.
1010 If built in a environment where \f[B]BC_LONG_BIT\f[R] (see the
1011 \f[B]LIMITS\f[R] section) is \f[B]64\f[R], then each integer has
1012 \f[B]9\f[R] decimal digits.
1013 If built in an environment where \f[B]BC_LONG_BIT\f[R] is \f[B]32\f[R]
1014 then each integer has \f[B]4\f[R] decimal digits.
1015 This value (the number of decimal digits per large integer) is called
1016 \f[B]BC_BASE_DIGS\f[R].
1017 .PP
1018 The actual values of \f[B]BC_LONG_BIT\f[R] and \f[B]BC_BASE_DIGS\f[R]
1019 can be queried with the \f[B]limits\f[R] statement.
1020 .PP
1021 In addition, this bc(1) uses an even larger integer for overflow
1022 checking.
1023 This integer type depends on the value of \f[B]BC_LONG_BIT\f[R], but is
1024 always at least twice as large as the integer type used to store digits.
1025 .SH LIMITS
1026 .PP
1027 The following are the limits on bc(1):
1028 .TP
1029 \f[B]BC_LONG_BIT\f[R]
1030 The number of bits in the \f[B]long\f[R] type in the environment where
1031 bc(1) was built.
1032 This determines how many decimal digits can be stored in a single large
1033 integer (see the \f[B]PERFORMANCE\f[R] section).
1034 .TP
1035 \f[B]BC_BASE_DIGS\f[R]
1036 The number of decimal digits per large integer (see the
1037 \f[B]PERFORMANCE\f[R] section).
1038 Depends on \f[B]BC_LONG_BIT\f[R].
1039 .TP
1040 \f[B]BC_BASE_POW\f[R]
1041 The max decimal number that each large integer can store (see
1042 \f[B]BC_BASE_DIGS\f[R]) plus \f[B]1\f[R].
1043 Depends on \f[B]BC_BASE_DIGS\f[R].
1044 .TP
1045 \f[B]BC_OVERFLOW_MAX\f[R]
1046 The max number that the overflow type (see the \f[B]PERFORMANCE\f[R]
1047 section) can hold.
1048 Depends on \f[B]BC_LONG_BIT\f[R].
1049 .TP
1050 \f[B]BC_BASE_MAX\f[R]
1051 The maximum output base.
1052 Set at \f[B]BC_BASE_POW\f[R].
1053 .TP
1054 \f[B]BC_DIM_MAX\f[R]
1055 The maximum size of arrays.
1056 Set at \f[B]SIZE_MAX-1\f[R].
1057 .TP
1058 \f[B]BC_SCALE_MAX\f[R]
1059 The maximum \f[B]scale\f[R].
1060 Set at \f[B]BC_OVERFLOW_MAX-1\f[R].
1061 .TP
1062 \f[B]BC_STRING_MAX\f[R]
1063 The maximum length of strings.
1064 Set at \f[B]BC_OVERFLOW_MAX-1\f[R].
1065 .TP
1066 \f[B]BC_NAME_MAX\f[R]
1067 The maximum length of identifiers.
1068 Set at \f[B]BC_OVERFLOW_MAX-1\f[R].
1069 .TP
1070 \f[B]BC_NUM_MAX\f[R]
1071 The maximum length of a number (in decimal digits), which includes
1072 digits after the decimal point.
1073 Set at \f[B]BC_OVERFLOW_MAX-1\f[R].
1074 .TP
1075 Exponent
1076 The maximum allowable exponent (positive or negative).
1077 Set at \f[B]BC_OVERFLOW_MAX\f[R].
1078 .TP
1079 Number of vars
1080 The maximum number of vars/arrays.
1081 Set at \f[B]SIZE_MAX-1\f[R].
1082 .PP
1083 The actual values can be queried with the \f[B]limits\f[R] statement.
1084 .PP
1085 These limits are meant to be effectively non-existent; the limits are so
1086 large (at least on 64-bit machines) that there should not be any point
1087 at which they become a problem.
1088 In fact, memory should be exhausted before these limits should be hit.
1089 .SH ENVIRONMENT VARIABLES
1090 .PP
1091 bc(1) recognizes the following environment variables:
1092 .TP
1093 \f[B]POSIXLY_CORRECT\f[R]
1094 If this variable exists (no matter the contents), bc(1) behaves as if
1095 the \f[B]-s\f[R] option was given.
1096 .TP
1097 \f[B]BC_ENV_ARGS\f[R]
1098 This is another way to give command-line arguments to bc(1).
1099 They should be in the same format as all other command-line arguments.
1100 These are always processed first, so any files given in
1101 \f[B]BC_ENV_ARGS\f[R] will be processed before arguments and files given
1102 on the command-line.
1103 This gives the user the ability to set up \[lq]standard\[rq] options and
1104 files to be used at every invocation.
1105 The most useful thing for such files to contain would be useful
1106 functions that the user might want every time bc(1) runs.
1107 .RS
1108 .PP
1109 The code that parses \f[B]BC_ENV_ARGS\f[R] will correctly handle quoted
1110 arguments, but it does not understand escape sequences.
1111 For example, the string \f[B]\[lq]/home/gavin/some bc file.bc\[rq]\f[R]
1112 will be correctly parsed, but the string \f[B]\[lq]/home/gavin/some
1113 \[dq]bc\[dq] file.bc\[rq]\f[R] will include the backslashes.
1114 .PP
1115 The quote parsing will handle either kind of quotes, \f[B]\[cq]\f[R] or
1116 \f[B]\[lq]\f[R]. Thus, if you have a file with any number of single
1117 quotes in the name, you can use double quotes as the outside quotes, as
1118 in \f[B]\[rq]some `bc' file.bc\[dq]\f[R], and vice versa if you have a
1119 file with double quotes.
1120 However, handling a file with both kinds of quotes in
1121 \f[B]BC_ENV_ARGS\f[R] is not supported due to the complexity of the
1122 parsing, though such files are still supported on the command-line where
1123 the parsing is done by the shell.
1124 .RE
1125 .TP
1126 \f[B]BC_LINE_LENGTH\f[R]
1127 If this environment variable exists and contains an integer that is
1128 greater than \f[B]1\f[R] and is less than \f[B]UINT16_MAX\f[R]
1129 (\f[B]2\[ha]16-1\f[R]), bc(1) will output lines to that length,
1130 including the backslash (\f[B]\[rs]\f[R]).
1131 The default line length is \f[B]70\f[R].
1132 .SH EXIT STATUS
1133 .PP
1134 bc(1) returns the following exit statuses:
1135 .TP
1136 \f[B]0\f[R]
1137 No error.
1138 .TP
1139 \f[B]1\f[R]
1140 A math error occurred.
1141 This follows standard practice of using \f[B]1\f[R] for expected errors,
1142 since math errors will happen in the process of normal execution.
1143 .RS
1144 .PP
1145 Math errors include divide by \f[B]0\f[R], taking the square root of a
1146 negative number, attempting to convert a negative number to a hardware
1147 integer, overflow when converting a number to a hardware integer, and
1148 attempting to use a non-integer where an integer is required.
1149 .PP
1150 Converting to a hardware integer happens for the second operand of the
1151 power (\f[B]\[ha]\f[R]) operator and the corresponding assignment
1152 operator.
1153 .RE
1154 .TP
1155 \f[B]2\f[R]
1156 A parse error occurred.
1157 .RS
1158 .PP
1159 Parse errors include unexpected \f[B]EOF\f[R], using an invalid
1160 character, failing to find the end of a string or comment, using a token
1161 where it is invalid, giving an invalid expression, giving an invalid
1162 print statement, giving an invalid function definition, attempting to
1163 assign to an expression that is not a named expression (see the
1164 \f[I]Named Expressions\f[R] subsection of the \f[B]SYNTAX\f[R] section),
1165 giving an invalid \f[B]auto\f[R] list, having a duplicate
1166 \f[B]auto\f[R]/function parameter, failing to find the end of a code
1167 block, attempting to return a value from a \f[B]void\f[R] function,
1168 attempting to use a variable as a reference, and using any extensions
1169 when the option \f[B]-s\f[R] or any equivalents were given.
1170 .RE
1171 .TP
1172 \f[B]3\f[R]
1173 A runtime error occurred.
1174 .RS
1175 .PP
1176 Runtime errors include assigning an invalid number to \f[B]ibase\f[R],
1177 \f[B]obase\f[R], or \f[B]scale\f[R]; give a bad expression to a
1178 \f[B]read()\f[R] call, calling \f[B]read()\f[R] inside of a
1179 \f[B]read()\f[R] call, type errors, passing the wrong number of
1180 arguments to functions, attempting to call an undefined function, and
1181 attempting to use a \f[B]void\f[R] function call as a value in an
1182 expression.
1183 .RE
1184 .TP
1185 \f[B]4\f[R]
1186 A fatal error occurred.
1187 .RS
1188 .PP
1189 Fatal errors include memory allocation errors, I/O errors, failing to
1190 open files, attempting to use files that do not have only ASCII
1191 characters (bc(1) only accepts ASCII characters), attempting to open a
1192 directory as a file, and giving invalid command-line options.
1193 .RE
1194 .PP
1195 The exit status \f[B]4\f[R] is special; when a fatal error occurs, bc(1)
1196 always exits and returns \f[B]4\f[R], no matter what mode bc(1) is in.
1197 .PP
1198 The other statuses will only be returned when bc(1) is not in
1199 interactive mode (see the \f[B]INTERACTIVE MODE\f[R] section), since
1200 bc(1) resets its state (see the \f[B]RESET\f[R] section) and accepts
1201 more input when one of those errors occurs in interactive mode.
1202 This is also the case when interactive mode is forced by the
1203 \f[B]-i\f[R] flag or \f[B]\[en]interactive\f[R] option.
1204 .PP
1205 These exit statuses allow bc(1) to be used in shell scripting with error
1206 checking, and its normal behavior can be forced by using the
1207 \f[B]-i\f[R] flag or \f[B]\[en]interactive\f[R] option.
1208 .SH INTERACTIVE MODE
1209 .PP
1210 Per the
1211 standard (https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html),
1212 bc(1) has an interactive mode and a non-interactive mode.
1213 Interactive mode is turned on automatically when both \f[B]stdin\f[R]
1214 and \f[B]stdout\f[R] are hooked to a terminal, but the \f[B]-i\f[R] flag
1215 and \f[B]\[en]interactive\f[R] option can turn it on in other cases.
1216 .PP
1217 In interactive mode, bc(1) attempts to recover from errors (see the
1218 \f[B]RESET\f[R] section), and in normal execution, flushes
1219 \f[B]stdout\f[R] as soon as execution is done for the current input.
1220 .SH TTY MODE
1221 .PP
1222 If \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all
1223 connected to a TTY, bc(1) turns on \[lq]TTY mode.\[rq]
1224 .PP
1225 TTY mode is required for history to be enabled (see the \f[B]COMMAND
1226 LINE HISTORY\f[R] section).
1227 It is also required to enable special handling for \f[B]SIGINT\f[R]
1228 signals.
1229 .PP
1230 The prompt is enabled in TTY mode.
1231 .PP
1232 TTY mode is different from interactive mode because interactive mode is
1233 required in the bc(1)
1234 specification (https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html),
1235 and interactive mode requires only \f[B]stdin\f[R] and \f[B]stdout\f[R]
1236 to be connected to a terminal.
1237 .SH SIGNAL HANDLING
1238 .PP
1239 Sending a \f[B]SIGINT\f[R] will cause bc(1) to stop execution of the
1240 current input.
1241 If bc(1) is in TTY mode (see the \f[B]TTY MODE\f[R] section), it will
1242 reset (see the \f[B]RESET\f[R] section).
1243 Otherwise, it will clean up and exit.
1244 .PP
1245 Note that \[lq]current input\[rq] can mean one of two things.
1246 If bc(1) is processing input from \f[B]stdin\f[R] in TTY mode, it will
1247 ask for more input.
1248 If bc(1) is processing input from a file in TTY mode, it will stop
1249 processing the file and start processing the next file, if one exists,
1250 or ask for input from \f[B]stdin\f[R] if no other file exists.
1251 .PP
1252 This means that if a \f[B]SIGINT\f[R] is sent to bc(1) as it is
1253 executing a file, it can seem as though bc(1) did not respond to the
1254 signal since it will immediately start executing the next file.
1255 This is by design; most files that users execute when interacting with
1256 bc(1) have function definitions, which are quick to parse.
1257 If a file takes a long time to execute, there may be a bug in that file.
1258 The rest of the files could still be executed without problem, allowing
1259 the user to continue.
1260 .PP
1261 \f[B]SIGTERM\f[R] and \f[B]SIGQUIT\f[R] cause bc(1) to clean up and
1262 exit, and it uses the default handler for all other signals.
1263 The one exception is \f[B]SIGHUP\f[R]; in that case, when bc(1) is in
1264 TTY mode, a \f[B]SIGHUP\f[R] will cause bc(1) to clean up and exit.
1265 .SH COMMAND LINE HISTORY
1266 .PP
1267 bc(1) supports interactive command-line editing.
1268 If bc(1) is in TTY mode (see the \f[B]TTY MODE\f[R] section), history is
1269 enabled.
1270 Previous lines can be recalled and edited with the arrow keys.
1271 .PP
1272 \f[B]Note\f[R]: tabs are converted to 8 spaces.
1273 .SH SEE ALSO
1274 .PP
1275 dc(1)
1276 .SH STANDARDS
1277 .PP
1278 bc(1) is compliant with the IEEE Std 1003.1-2017
1279 (\[lq]POSIX.1-2017\[rq]) (https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html)
1280 specification.
1281 The flags \f[B]-efghiqsvVw\f[R], all long options, and the extensions
1282 noted above are extensions to that specification.
1283 .PP
1284 Note that the specification explicitly says that bc(1) only accepts
1285 numbers that use a period (\f[B].\f[R]) as a radix point, regardless of
1286 the value of \f[B]LC_NUMERIC\f[R].
1287 .SH BUGS
1288 .PP
1289 None are known.
1290 Report bugs at https://git.yzena.com/gavin/bc.
1291 .SH AUTHORS
1292 .PP
1293 Gavin D.
1294 Howard <gavin@yzena.com> and contributors.