contrib/bc/manuals/bc/EH.1

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