contrib/bc/manuals/bc/ENP.1

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