contrib/bc/manuals/bc/ENP.1

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