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