manuals/bc/EHP.1

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