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