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