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