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