contrib/bc/manuals/bc/EHNP.1

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