contrib/bc/manuals/bc/EHP.1

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