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