contrib/bc/manuals/bc/NP.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" "April 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]-ghilPqRsvVw\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]--no-read-prompt\f[R]] [\f[B]--quiet\f[R]]
  37 [\f[B]--standard\f[R]] [\f[B]--warn\f[R]] [\f[B]--version\f[R]]
  38 [\f[B]-e\f[R] \f[I]expr\f[R]] [\f[B]--expression\f[R]=\f[I]expr\f[R]...]
  39 [\f[B]-f\f[R] \f[I]file\f[R]...] [\f[B]--file\f[R]=\f[I]file\f[R]...]
  40 [\f[I]file\f[R]...]
  41 .SH DESCRIPTION
  42 .PP
  43 bc(1) is an interactive processor for a language first standardized in
  44 1991 by POSIX.
  45 (The current standard is
  46 here (https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html).)
  47 The language provides unlimited precision decimal arithmetic and is
  48 somewhat C-like, but there are differences.
  49 Such differences will be noted in this document.
  50 .PP
  51 After parsing and handling options, this bc(1) reads any files given on
  52 the command line and executes them before reading from \f[B]stdin\f[R].
  53 .PP
  54 This bc(1) is a drop-in replacement for \f[I]any\f[R] bc(1), including
  55 (and especially) the GNU bc(1).
  56 It also has many extensions and extra features beyond other
  57 implementations.
  58 .SH OPTIONS
  59 .PP
  60 The following are the options that bc(1) accepts.
  61 .PP
  62 \f[B]-g\f[R], \f[B]--global-stacks\f[R]
  63 .PP
  64 : Turns the globals \f[B]ibase\f[R], \f[B]obase\f[R], \f[B]scale\f[R],
  65 and \f[B]seed\f[R] into stacks.
  66 .IP
  67 .nf
  68 \f[C]
  69 This has the effect that a copy of the current value of all four are pushed
  70 onto a stack for every function call, as well as popped when every function
  71 returns. This means that functions can assign to any and all of those
  72 globals without worrying that the change will affect other functions.
  73 Thus, a hypothetical function named **output(x,b)** that simply printed
  74 **x** in base **b** could be written like this:
  75
  76     define void output(x, b) {
  77         obase=b
  78         x
  79     }
  80
  81 instead of like this:
  82
  83     define void output(x, b) {
  84         auto c
  85         c=obase
  86         obase=b
  87         x
  88         obase=c
  89     }
  90
  91 This makes writing functions much easier.
  92
  93 (**Note**: the function **output(x,b)** exists in the extended math library.
  94  See the **LIBRARY** section.)
  95
  96 However, since using this flag means that functions cannot set **ibase**,
  97 **obase**, **scale**, or **seed** globally, functions that are made to do so
  98 cannot work anymore. There are two possible use cases for that, and each has
  99 a solution.
 100
 101 First, if a function is called on startup to turn bc(1) into a number
 102 converter, it is possible to replace that capability with various shell
 103 aliases. Examples:
 104
 105     alias d2o=\[dq]bc -e ibase=A -e obase=8\[dq]
 106     alias h2b=\[dq]bc -e ibase=G -e obase=2\[dq]
 107
 108 Second, if the purpose of a function is to set **ibase**, **obase**,
 109 **scale**, or **seed** globally for any other purpose, it could be split
 110 into one to four functions (based on how many globals it sets) and each of
 111 those functions could return the desired value for a global.
 112
 113 For functions that set **seed**, the value assigned to **seed** is not
 114 propagated to parent functions. This means that the sequence of
 115 pseudo-random numbers that they see will not be the same sequence of
 116 pseudo-random numbers that any parent sees. This is only the case once
 117 **seed** has been set.
 118
 119 If a function desires to not affect the sequence of pseudo-random numbers
 120 of its parents, but wants to use the same **seed**, it can use the following
 121 line:
 122
 123     seed = seed
 124
 125 If the behavior of this option is desired for every run of bc(1), then users
 126 could make sure to define **BC_ENV_ARGS** and include this option (see the
 127 **ENVIRONMENT VARIABLES** section for more details).
 128
 129 If **-s**, **-w**, or any equivalents are used, this option is ignored.
 130
 131 This is a **non-portable extension**.
 132 \f[R]
 133 .fi
 134 .PP
 135 \f[B]-h\f[R], \f[B]--help\f[R]
 136 .PP
 137 : Prints a usage message and quits.
 138 .PP
 139 \f[B]-i\f[R], \f[B]--interactive\f[R]
 140 .PP
 141 : Forces interactive mode.
 142 (See the \f[B]INTERACTIVE MODE\f[R] section.)
 143 .IP
 144 .nf
 145 \f[C]
 146 This is a **non-portable extension**.
 147 \f[R]
 148 .fi
 149 .PP
 150 \f[B]-l\f[R], \f[B]--mathlib\f[R]
 151 .PP
 152 : Sets \f[B]scale\f[R] (see the \f[B]SYNTAX\f[R] section) to
 153 \f[B]20\f[R] and loads the included math library and the extended math
 154 library before running any code, including any expressions or files
 155 specified on the command line.
 156 .IP
 157 .nf
 158 \f[C]
 159 To learn what is in the libraries, see the **LIBRARY** section.
 160 \f[R]
 161 .fi
 162 .PP
 163 \f[B]-P\f[R], \f[B]--no-prompt\f[R]
 164 .PP
 165 : This option is a no-op.
 166 .IP
 167 .nf
 168 \f[C]
 169 This is a **non-portable extension**.
 170 \f[R]
 171 .fi
 172 .PP
 173 \f[B]-R\f[R], \f[B]--no-read-prompt\f[R]
 174 .PP
 175 : Because bc(1) was built without support for prompts, this option is a
 176 no-op.
 177 .IP
 178 .nf
 179 \f[C]
 180 This is a **non-portable extension**.
 181 \f[R]
 182 .fi
 183 .PP
 184 \f[B]-q\f[R], \f[B]--quiet\f[R]
 185 .PP
 186 : This option is for compatibility with the GNU
 187 bc(1) (https://www.gnu.org/software/bc/); it is a no-op.
 188 Without this option, GNU bc(1) prints a copyright header.
 189 This bc(1) only prints the copyright header if one or more of the
 190 \f[B]-v\f[R], \f[B]-V\f[R], or \f[B]--version\f[R] options are given.
 191 .IP
 192 .nf
 193 \f[C]
 194 This is a **non-portable extension**.
 195 \f[R]
 196 .fi
 197 .PP
 198 \f[B]-s\f[R], \f[B]--standard\f[R]
 199 .PP
 200 : Process exactly the language defined by the
 201 standard (https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html)
 202 and error if any extensions are used.
 203 .IP
 204 .nf
 205 \f[C]
 206 This is a **non-portable extension**.
 207 \f[R]
 208 .fi
 209 .PP
 210 \f[B]-v\f[R], \f[B]-V\f[R], \f[B]--version\f[R]
 211 .PP
 212 : Print the version information (copyright header) and exit.
 213 .IP
 214 .nf
 215 \f[C]
 216 This is a **non-portable extension**.
 217 \f[R]
 218 .fi
 219 .PP
 220 \f[B]-w\f[R], \f[B]--warn\f[R]
 221 .PP
 222 : Like \f[B]-s\f[R] and \f[B]--standard\f[R], except that warnings (and
 223 not errors) are printed for non-standard extensions and execution
 224 continues normally.
 225 .IP
 226 .nf
 227 \f[C]
 228 This is a **non-portable extension**.
 229 \f[R]
 230 .fi
 231 .PP
 232 \f[B]-e\f[R] \f[I]expr\f[R], \f[B]--expression\f[R]=\f[I]expr\f[R]
 233 .PP
 234 : Evaluates \f[I]expr\f[R].
 235 If multiple expressions are given, they are evaluated in order.
 236 If files are given as well (see below), the expressions and files are
 237 evaluated in the order given.
 238 This means that if a file is given before an expression, the file is
 239 read in and evaluated first.
 240 .IP
 241 .nf
 242 \f[C]
 243 If this option is given on the command-line (i.e., not in **BC_ENV_ARGS**,
 244 see the **ENVIRONMENT VARIABLES** section), then after processing all
 245 expressions and files, bc(1) will exit, unless **-** (**stdin**) was given
 246 as an argument at least once to **-f** or **-\[rs]-file**, whether on the
 247 command-line or in **BC_ENV_ARGS**. However, if any other **-e**,
 248 **-\[rs]-expression**, **-f**, or **-\[rs]-file** arguments are given after **-f-**
 249 or equivalent is given, bc(1) will give a fatal error and exit.
 250
 251 This is a **non-portable extension**.
 252 \f[R]
 253 .fi
 254 .PP
 255 \f[B]-f\f[R] \f[I]file\f[R], \f[B]--file\f[R]=\f[I]file\f[R]
 256 .PP
 257 : Reads in \f[I]file\f[R] and evaluates it, line by line, as though it
 258 were read through \f[B]stdin\f[R].
 259 If expressions are also given (see above), the expressions are evaluated
 260 in the order given.
 261 .IP
 262 .nf
 263 \f[C]
 264 If this option is given on the command-line (i.e., not in **BC_ENV_ARGS**,
 265 see the **ENVIRONMENT VARIABLES** section), then after processing all
 266 expressions and files, bc(1) will exit, unless **-** (**stdin**) was given
 267 as an argument at least once to **-f** or **-\[rs]-file**. However, if any other
 268 **-e**, **-\[rs]-expression**, **-f**, or **-\[rs]-file** arguments are given after
 269 **-f-** or equivalent is given, bc(1) will give a fatal error and exit.
 270
 271 This is a **non-portable extension**.
 272 \f[R]
 273 .fi
 274 .PP
 275 All long options are \f[B]non-portable extensions\f[R].
 276 .SH STDOUT
 277 .PP
 278 Any non-error output is written to \f[B]stdout\f[R].
 279 In addition, if history (see the \f[B]HISTORY\f[R] section) and the
 280 prompt (see the \f[B]TTY MODE\f[R] section) are enabled, both are output
 281 to \f[B]stdout\f[R].
 282 .PP
 283 \f[B]Note\f[R]: Unlike other bc(1) implementations, this bc(1) will
 284 issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot
 285 write to \f[B]stdout\f[R], so if \f[B]stdout\f[R] is closed, as in
 286 \f[B]bc >&-\f[R], it will quit with an error.
 287 This is done so that bc(1) can report problems when \f[B]stdout\f[R] is
 288 redirected to a file.
 289 .PP
 290 If there are scripts that depend on the behavior of other bc(1)
 291 implementations, it is recommended that those scripts be changed to
 292 redirect \f[B]stdout\f[R] to \f[B]/dev/null\f[R].
 293 .SH STDERR
 294 .PP
 295 Any error output is written to \f[B]stderr\f[R].
 296 .PP
 297 \f[B]Note\f[R]: Unlike other bc(1) implementations, this bc(1) will
 298 issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot
 299 write to \f[B]stderr\f[R], so if \f[B]stderr\f[R] is closed, as in
 300 \f[B]bc 2>&-\f[R], it will quit with an error.
 301 This is done so that bc(1) can exit with an error code when
 302 \f[B]stderr\f[R] is redirected to a file.
 303 .PP
 304 If there are scripts that depend on the behavior of other bc(1)
 305 implementations, it is recommended that those scripts be changed to
 306 redirect \f[B]stderr\f[R] to \f[B]/dev/null\f[R].
 307 .SH SYNTAX
 308 .PP
 309 The syntax for bc(1) programs is mostly C-like, with some differences.
 310 This bc(1) follows the POSIX
 311 standard (https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html),
 312 which is a much more thorough resource for the language this bc(1)
 313 accepts.
 314 This section is meant to be a summary and a listing of all the
 315 extensions to the standard.
 316 .PP
 317 In the sections below, \f[B]E\f[R] means expression, \f[B]S\f[R] means
 318 statement, and \f[B]I\f[R] means identifier.
 319 .PP
 320 Identifiers (\f[B]I\f[R]) start with a lowercase letter and can be
 321 followed by any number (up to \f[B]BC_NAME_MAX-1\f[R]) of lowercase
 322 letters (\f[B]a-z\f[R]), digits (\f[B]0-9\f[R]), and underscores
 323 (\f[B]_\f[R]).
 324 The regex is \f[B][a-z][a-z0-9_]*\f[R].
 325 Identifiers with more than one character (letter) are a
 326 \f[B]non-portable extension\f[R].
 327 .PP
 328 \f[B]ibase\f[R] is a global variable determining how to interpret
 329 constant numbers.
 330 It is the \[dq]input\[dq] base, or the number base used for interpreting
 331 input numbers.
 332 \f[B]ibase\f[R] is initially \f[B]10\f[R].
 333 If the \f[B]-s\f[R] (\f[B]--standard\f[R]) and \f[B]-w\f[R]
 334 (\f[B]--warn\f[R]) flags were not given on the command line, the max
 335 allowable value for \f[B]ibase\f[R] is \f[B]36\f[R].
 336 Otherwise, it is \f[B]16\f[R].
 337 The min allowable value for \f[B]ibase\f[R] is \f[B]2\f[R].
 338 The max allowable value for \f[B]ibase\f[R] can be queried in bc(1)
 339 programs with the \f[B]maxibase()\f[R] built-in function.
 340 .PP
 341 \f[B]obase\f[R] is a global variable determining how to output results.
 342 It is the \[dq]output\[dq] base, or the number base used for outputting
 343 numbers.
 344 \f[B]obase\f[R] is initially \f[B]10\f[R].
 345 The max allowable value for \f[B]obase\f[R] is \f[B]BC_BASE_MAX\f[R] and
 346 can be queried in bc(1) programs with the \f[B]maxobase()\f[R] built-in
 347 function.
 348 The min allowable value for \f[B]obase\f[R] is \f[B]0\f[R].
 349 If \f[B]obase\f[R] is \f[B]0\f[R], values are output in scientific
 350 notation, and if \f[B]obase\f[R] is \f[B]1\f[R], values are output in
 351 engineering notation.
 352 Otherwise, values are output in the specified base.
 353 .PP
 354 Outputting in scientific and engineering notations are \f[B]non-portable
 355 extensions\f[R].
 356 .PP
 357 The \f[I]scale\f[R] of an expression is the number of digits in the
 358 result of the expression right of the decimal point, and \f[B]scale\f[R]
 359 is a global variable that sets the precision of any operations, with
 360 exceptions.
 361 \f[B]scale\f[R] is initially \f[B]0\f[R].
 362 \f[B]scale\f[R] cannot be negative.
 363 The max allowable value for \f[B]scale\f[R] is \f[B]BC_SCALE_MAX\f[R]
 364 and can be queried in bc(1) programs with the \f[B]maxscale()\f[R]
 365 built-in function.
 366 .PP
 367 bc(1) has both \f[I]global\f[R] variables and \f[I]local\f[R] variables.
 368 All \f[I]local\f[R] variables are local to the function; they are
 369 parameters or are introduced in the \f[B]auto\f[R] list of a function
 370 (see the \f[B]FUNCTIONS\f[R] section).
 371 If a variable is accessed which is not a parameter or in the
 372 \f[B]auto\f[R] list, it is assumed to be \f[I]global\f[R].
 373 If a parent function has a \f[I]local\f[R] variable version of a
 374 variable that a child function considers \f[I]global\f[R], the value of
 375 that \f[I]global\f[R] variable in the child function is the value of the
 376 variable in the parent function, not the value of the actual
 377 \f[I]global\f[R] variable.
 378 .PP
 379 All of the above applies to arrays as well.
 380 .PP
 381 The value of a statement that is an expression (i.e., any of the named
 382 expressions or operands) is printed unless the lowest precedence
 383 operator is an assignment operator \f[I]and\f[R] the expression is
 384 notsurrounded by parentheses.
 385 .PP
 386 The value that is printed is also assigned to the special variable
 387 \f[B]last\f[R].
 388 A single dot (\f[B].\f[R]) may also be used as a synonym for
 389 \f[B]last\f[R].
 390 These are \f[B]non-portable extensions\f[R].
 391 .PP
 392 Either semicolons or newlines may separate statements.
 393 .SS Comments
 394 .PP
 395 There are two kinds of comments:
 396 .IP "1." 3
 397 Block comments are enclosed in \f[B]/*\f[R] and \f[B]*/\f[R].
 398 .IP "2." 3
 399 Line comments go from \f[B]#\f[R] until, and not including, the next
 400 newline.
 401 This is a \f[B]non-portable extension\f[R].
 402 .SS Named Expressions
 403 .PP
 404 The following are named expressions in bc(1):
 405 .IP "1." 3
 406 Variables: \f[B]I\f[R]
 407 .IP "2." 3
 408 Array Elements: \f[B]I[E]\f[R]
 409 .IP "3." 3
 410 \f[B]ibase\f[R]
 411 .IP "4." 3
 412 \f[B]obase\f[R]
 413 .IP "5." 3
 414 \f[B]scale\f[R]
 415 .IP "6." 3
 416 \f[B]seed\f[R]
 417 .IP "7." 3
 418 \f[B]last\f[R] or a single dot (\f[B].\f[R])
 419 .PP
 420 Numbers 6 and 7 are \f[B]non-portable extensions\f[R].
 421 .PP
 422 The meaning of \f[B]seed\f[R] is dependent on the current pseudo-random
 423 number generator but is guaranteed to not change except for new major
 424 versions.
 425 .PP
 426 The \f[I]scale\f[R] and sign of the value may be significant.
 427 .PP
 428 If a previously used \f[B]seed\f[R] value is assigned to \f[B]seed\f[R]
 429 and used again, the pseudo-random number generator is guaranteed to
 430 produce the same sequence of pseudo-random numbers as it did when the
 431 \f[B]seed\f[R] value was previously used.
 432 .PP
 433 The exact value assigned to \f[B]seed\f[R] is not guaranteed to be
 434 returned if \f[B]seed\f[R] is queried again immediately.
 435 However, if \f[B]seed\f[R] \f[I]does\f[R] return a different value, both
 436 values, when assigned to \f[B]seed\f[R], are guaranteed to produce the
 437 same sequence of pseudo-random numbers.
 438 This means that certain values assigned to \f[B]seed\f[R] will
 439 \f[I]not\f[R] produce unique sequences of pseudo-random numbers.
 440 The value of \f[B]seed\f[R] will change after any use of the
 441 \f[B]rand()\f[R] and \f[B]irand(E)\f[R] operands (see the
 442 \f[I]Operands\f[R] subsection below), except if the parameter passed to
 443 \f[B]irand(E)\f[R] is \f[B]0\f[R], \f[B]1\f[R], or negative.
 444 .PP
 445 There is no limit to the length (number of significant decimal digits)
 446 or \f[I]scale\f[R] of the value that can be assigned to \f[B]seed\f[R].
 447 .PP
 448 Variables and arrays do not interfere; users can have arrays named the
 449 same as variables.
 450 This also applies to functions (see the \f[B]FUNCTIONS\f[R] section), so
 451 a user can have a variable, array, and function that all have the same
 452 name, and they will not shadow each other, whether inside of functions
 453 or not.
 454 .PP
 455 Named expressions are required as the operand of
 456 \f[B]increment\f[R]/\f[B]decrement\f[R] operators and as the left side
 457 of \f[B]assignment\f[R] operators (see the \f[I]Operators\f[R]
 458 subsection).
 459 .SS Operands
 460 .PP
 461 The following are valid operands in bc(1):
 462 .IP " 1." 4
 463 Numbers (see the \f[I]Numbers\f[R] subsection below).
 464 .IP " 2." 4
 465 Array indices (\f[B]I[E]\f[R]).
 466 .IP " 3." 4
 467 \f[B](E)\f[R]: The value of \f[B]E\f[R] (used to change precedence).
 468 .IP " 4." 4
 469 \f[B]sqrt(E)\f[R]: The square root of \f[B]E\f[R].
 470 \f[B]E\f[R] must be non-negative.
 471 .IP " 5." 4
 472 \f[B]length(E)\f[R]: The number of significant decimal digits in
 473 \f[B]E\f[R].
 474 .IP " 6." 4
 475 \f[B]length(I[])\f[R]: The number of elements in the array \f[B]I\f[R].
 476 This is a \f[B]non-portable extension\f[R].
 477 .IP " 7." 4
 478 \f[B]scale(E)\f[R]: The \f[I]scale\f[R] of \f[B]E\f[R].
 479 .IP " 8." 4
 480 \f[B]abs(E)\f[R]: The absolute value of \f[B]E\f[R].
 481 This is a \f[B]non-portable extension\f[R].
 482 .IP " 9." 4
 483 \f[B]I()\f[R], \f[B]I(E)\f[R], \f[B]I(E, E)\f[R], and so on, where
 484 \f[B]I\f[R] is an identifier for a non-\f[B]void\f[R] function (see the
 485 \f[I]Void Functions\f[R] subsection of the \f[B]FUNCTIONS\f[R] section).
 486 The \f[B]E\f[R] argument(s) may also be arrays of the form
 487 \f[B]I[]\f[R], which will automatically be turned into array references
 488 (see the \f[I]Array References\f[R] subsection of the
 489 \f[B]FUNCTIONS\f[R] section) if the corresponding parameter in the
 490 function definition is an array reference.
 491 .IP "10." 4
 492 \f[B]read()\f[R]: Reads a line from \f[B]stdin\f[R] and uses that as an
 493 expression.
 494 The result of that expression is the result of the \f[B]read()\f[R]
 495 operand.
 496 This is a \f[B]non-portable extension\f[R].
 497 .IP "11." 4
 498 \f[B]maxibase()\f[R]: The max allowable \f[B]ibase\f[R].
 499 This is a \f[B]non-portable extension\f[R].
 500 .IP "12." 4
 501 \f[B]maxobase()\f[R]: The max allowable \f[B]obase\f[R].
 502 This is a \f[B]non-portable extension\f[R].
 503 .IP "13." 4
 504 \f[B]maxscale()\f[R]: The max allowable \f[B]scale\f[R].
 505 This is a \f[B]non-portable extension\f[R].
 506 .IP "14." 4
 507 \f[B]rand()\f[R]: A pseudo-random integer between \f[B]0\f[R]
 508 (inclusive) and \f[B]BC_RAND_MAX\f[R] (inclusive).
 509 Using this operand will change the value of \f[B]seed\f[R].
 510 This is a \f[B]non-portable extension\f[R].
 511 .IP "15." 4
 512 \f[B]irand(E)\f[R]: A pseudo-random integer between \f[B]0\f[R]
 513 (inclusive) and the value of \f[B]E\f[R] (exclusive).
 514 If \f[B]E\f[R] is negative or is a non-integer (\f[B]E\f[R]\[aq]s
 515 \f[I]scale\f[R] is not \f[B]0\f[R]), an error is raised, and bc(1)
 516 resets (see the \f[B]RESET\f[R] section) while \f[B]seed\f[R] remains
 517 unchanged.
 518 If \f[B]E\f[R] is larger than \f[B]BC_RAND_MAX\f[R], the higher bound is
 519 honored by generating several pseudo-random integers, multiplying them
 520 by appropriate powers of \f[B]BC_RAND_MAX+1\f[R], and adding them
 521 together.
 522 Thus, the size of integer that can be generated with this operand is
 523 unbounded.
 524 Using this operand will change the value of \f[B]seed\f[R], unless the
 525 value of \f[B]E\f[R] is \f[B]0\f[R] or \f[B]1\f[R].
 526 In that case, \f[B]0\f[R] is returned, and \f[B]seed\f[R] is
 527 \f[I]not\f[R] changed.
 528 This is a \f[B]non-portable extension\f[R].
 529 .IP "16." 4
 530 \f[B]maxrand()\f[R]: The max integer returned by \f[B]rand()\f[R].
 531 This is a \f[B]non-portable extension\f[R].
 532 .PP
 533 The integers generated by \f[B]rand()\f[R] and \f[B]irand(E)\f[R] are
 534 guaranteed to be as unbiased as possible, subject to the limitations of
 535 the pseudo-random number generator.
 536 .PP
 537 \f[B]Note\f[R]: The values returned by the pseudo-random number
 538 generator with \f[B]rand()\f[R] and \f[B]irand(E)\f[R] are guaranteed to
 539 \f[I]NOT\f[R] be cryptographically secure.
 540 This is a consequence of using a seeded pseudo-random number generator.
 541 However, they \f[I]are\f[R] guaranteed to be reproducible with identical
 542 \f[B]seed\f[R] values.
 543 This means that the pseudo-random values from bc(1) should only be used
 544 where a reproducible stream of pseudo-random numbers is
 545 \f[I]ESSENTIAL\f[R].
 546 In any other case, use a non-seeded pseudo-random number generator.
 547 .SS Numbers
 548 .PP
 549 Numbers are strings made up of digits, uppercase letters, and at most
 550 \f[B]1\f[R] period for a radix.
 551 Numbers can have up to \f[B]BC_NUM_MAX\f[R] digits.
 552 Uppercase letters are equal to \f[B]9\f[R] + their position in the
 553 alphabet (i.e., \f[B]A\f[R] equals \f[B]10\f[R], or \f[B]9+1\f[R]).
 554 If a digit or letter makes no sense with the current value of
 555 \f[B]ibase\f[R], they are set to the value of the highest valid digit in
 556 \f[B]ibase\f[R].
 557 .PP
 558 Single-character numbers (i.e., \f[B]A\f[R] alone) take the value that
 559 they would have if they were valid digits, regardless of the value of
 560 \f[B]ibase\f[R].
 561 This means that \f[B]A\f[R] alone always equals decimal \f[B]10\f[R] and
 562 \f[B]Z\f[R] alone always equals decimal \f[B]35\f[R].
 563 .PP
 564 In addition, bc(1) accepts numbers in scientific notation.
 565 These have the form \f[B]<number>e<integer>\f[R].
 566 The exponent (the portion after the \f[B]e\f[R]) must be an integer.
 567 An example is \f[B]1.89237e9\f[R], which is equal to
 568 \f[B]1892370000\f[R].
 569 Negative exponents are also allowed, so \f[B]4.2890e-3\f[R] is equal to
 570 \f[B]0.0042890\f[R].
 571 .PP
 572 Using scientific notation is an error or warning if the \f[B]-s\f[R] or
 573 \f[B]-w\f[R], respectively, command-line options (or equivalents) are
 574 given.
 575 .PP
 576 \f[B]WARNING\f[R]: Both the number and the exponent in scientific
 577 notation are interpreted according to the current \f[B]ibase\f[R], but
 578 the number is still multiplied by \f[B]10\[ha]exponent\f[R] regardless
 579 of the current \f[B]ibase\f[R].
 580 For example, if \f[B]ibase\f[R] is \f[B]16\f[R] and bc(1) is given the
 581 number string \f[B]FFeA\f[R], the resulting decimal number will be
 582 \f[B]2550000000000\f[R], and if bc(1) is given the number string
 583 \f[B]10e-4\f[R], the resulting decimal number will be \f[B]0.0016\f[R].
 584 .PP
 585 Accepting input as scientific notation is a \f[B]non-portable
 586 extension\f[R].
 587 .SS Operators
 588 .PP
 589 The following arithmetic and logical operators can be used.
 590 They are listed in order of decreasing precedence.
 591 Operators in the same group have the same precedence.
 592 .PP
 593 \f[B]++\f[R] \f[B]--\f[R]
 594 .PP
 595 : Type: Prefix and Postfix
 596 .IP
 597 .nf
 598 \f[C]
 599 Associativity: None
 600
 601 Description: **increment**, **decrement**
 602 \f[R]
 603 .fi
 604 .PP
 605 \f[B]-\f[R] \f[B]!\f[R]
 606 .PP
 607 : Type: Prefix
 608 .IP
 609 .nf
 610 \f[C]
 611 Associativity: None
 612
 613 Description: **negation**, **boolean not**
 614 \f[R]
 615 .fi
 616 .PP
 617 \f[B]$\f[R]
 618 .PP
 619 : Type: Postfix
 620 .IP
 621 .nf
 622 \f[C]
 623 Associativity: None
 624
 625 Description: **truncation**
 626 \f[R]
 627 .fi
 628 .PP
 629 \f[B]\[at]\f[R]
 630 .PP
 631 : Type: Binary
 632 .IP
 633 .nf
 634 \f[C]
 635 Associativity: Right
 636
 637 Description: **set precision**
 638 \f[R]
 639 .fi
 640 .PP
 641 \f[B]\[ha]\f[R]
 642 .PP
 643 : Type: Binary
 644 .IP
 645 .nf
 646 \f[C]
 647 Associativity: Right
 648
 649 Description: **power**
 650 \f[R]
 651 .fi
 652 .PP
 653 \f[B]*\f[R] \f[B]/\f[R] \f[B]%\f[R]
 654 .PP
 655 : Type: Binary
 656 .IP
 657 .nf
 658 \f[C]
 659 Associativity: Left
 660
 661 Description: **multiply**, **divide**, **modulus**
 662 \f[R]
 663 .fi
 664 .PP
 665 \f[B]+\f[R] \f[B]-\f[R]
 666 .PP
 667 : Type: Binary
 668 .IP
 669 .nf
 670 \f[C]
 671 Associativity: Left
 672
 673 Description: **add**, **subtract**
 674 \f[R]
 675 .fi
 676 .PP
 677 \f[B]<<\f[R] \f[B]>>\f[R]
 678 .PP
 679 : Type: Binary
 680 .IP
 681 .nf
 682 \f[C]
 683 Associativity: Left
 684
 685 Description: **shift left**, **shift right**
 686 \f[R]
 687 .fi
 688 .PP
 689 \f[B]=\f[R] \f[B]<<=\f[R] \f[B]>>=\f[R] \f[B]+=\f[R] \f[B]-=\f[R]
 690 \f[B]*=\f[R] \f[B]/=\f[R] \f[B]%=\f[R] \f[B]\[ha]=\f[R] \f[B]\[at]=\f[R]
 691 .PP
 692 : Type: Binary
 693 .IP
 694 .nf
 695 \f[C]
 696 Associativity: Right
 697
 698 Description: **assignment**
 699 \f[R]
 700 .fi
 701 .PP
 702 \f[B]==\f[R] \f[B]<=\f[R] \f[B]>=\f[R] \f[B]!=\f[R] \f[B]<\f[R]
 703 \f[B]>\f[R]
 704 .PP
 705 : Type: Binary
 706 .IP
 707 .nf
 708 \f[C]
 709 Associativity: Left
 710
 711 Description: **relational**
 712 \f[R]
 713 .fi
 714 .PP
 715 \f[B]&&\f[R]
 716 .PP
 717 : Type: Binary
 718 .IP
 719 .nf
 720 \f[C]
 721 Associativity: Left
 722
 723 Description: **boolean and**
 724 \f[R]
 725 .fi
 726 .PP
 727 \f[B]||\f[R]
 728 .PP
 729 : Type: Binary
 730 .IP
 731 .nf
 732 \f[C]
 733 Associativity: Left
 734
 735 Description: **boolean or**
 736 \f[R]
 737 .fi
 738 .PP
 739 The operators will be described in more detail below.
 740 .PP
 741 \f[B]++\f[R] \f[B]--\f[R]
 742 .PP
 743 : The prefix and postfix \f[B]increment\f[R] and \f[B]decrement\f[R]
 744 operators behave exactly like they would in C.
 745 They require a named expression (see the \f[I]Named Expressions\f[R]
 746 subsection) as an operand.
 747 .IP
 748 .nf
 749 \f[C]
 750 The prefix versions of these operators are more efficient; use them where
 751 possible.
 752 \f[R]
 753 .fi
 754 .PP
 755 \f[B]-\f[R]
 756 .PP
 757 : The \f[B]negation\f[R] operator returns \f[B]0\f[R] if a user attempts
 758 to negate any expression with the value \f[B]0\f[R].
 759 Otherwise, a copy of the expression with its sign flipped is returned.
 760 .PP
 761 \f[B]!\f[R]
 762 .PP
 763 : The \f[B]boolean not\f[R] operator returns \f[B]1\f[R] if the
 764 expression is \f[B]0\f[R], or \f[B]0\f[R] otherwise.
 765 .IP
 766 .nf
 767 \f[C]
 768 This is a **non-portable extension**.
 769 \f[R]
 770 .fi
 771 .PP
 772 \f[B]$\f[R]
 773 .PP
 774 : The \f[B]truncation\f[R] operator returns a copy of the given
 775 expression with all of its \f[I]scale\f[R] removed.
 776 .IP
 777 .nf
 778 \f[C]
 779 This is a **non-portable extension**.
 780 \f[R]
 781 .fi
 782 .PP
 783 \f[B]\[at]\f[R]
 784 .PP
 785 : The \f[B]set precision\f[R] operator takes two expressions and returns
 786 a copy of the first with its \f[I]scale\f[R] equal to the value of the
 787 second expression.
 788 That could either mean that the number is returned without change (if
 789 the \f[I]scale\f[R] of the first expression matches the value of the
 790 second expression), extended (if it is less), or truncated (if it is
 791 more).
 792 .IP
 793 .nf
 794 \f[C]
 795 The second expression must be an integer (no *scale*) and non-negative.
 796
 797 This is a **non-portable extension**.
 798 \f[R]
 799 .fi
 800 .PP
 801 \f[B]\[ha]\f[R]
 802 .PP
 803 : The \f[B]power\f[R] operator (not the \f[B]exclusive or\f[R] operator,
 804 as it would be in C) takes two expressions and raises the first to the
 805 power of the value of the second.
 806 The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R].
 807 .IP
 808 .nf
 809 \f[C]
 810 The second expression must be an integer (no *scale*), and if it is
 811 negative, the first value must be non-zero.
 812 \f[R]
 813 .fi
 814 .PP
 815 \f[B]*\f[R]
 816 .PP
 817 : The \f[B]multiply\f[R] operator takes two expressions, multiplies
 818 them, and returns the product.
 819 If \f[B]a\f[R] is the \f[I]scale\f[R] of the first expression and
 820 \f[B]b\f[R] is the \f[I]scale\f[R] of the second expression, the
 821 \f[I]scale\f[R] of the result is equal to
 822 \f[B]min(a+b,max(scale,a,b))\f[R] where \f[B]min()\f[R] and
 823 \f[B]max()\f[R] return the obvious values.
 824 .PP
 825 \f[B]/\f[R]
 826 .PP
 827 : The \f[B]divide\f[R] operator takes two expressions, divides them, and
 828 returns the quotient.
 829 The \f[I]scale\f[R] of the result shall be the value of \f[B]scale\f[R].
 830 .IP
 831 .nf
 832 \f[C]
 833 The second expression must be non-zero.
 834 \f[R]
 835 .fi
 836 .PP
 837 \f[B]%\f[R]
 838 .PP
 839 : The \f[B]modulus\f[R] operator takes two expressions, \f[B]a\f[R] and
 840 \f[B]b\f[R], and evaluates them by 1) Computing \f[B]a/b\f[R] to current
 841 \f[B]scale\f[R] and 2) Using the result of step 1 to calculate
 842 \f[B]a-(a/b)*b\f[R] to \f[I]scale\f[R]
 843 \f[B]max(scale+scale(b),scale(a))\f[R].
 844 .IP
 845 .nf
 846 \f[C]
 847 The second expression must be non-zero.
 848 \f[R]
 849 .fi
 850 .PP
 851 \f[B]+\f[R]
 852 .PP
 853 : The \f[B]add\f[R] operator takes two expressions, \f[B]a\f[R] and
 854 \f[B]b\f[R], and returns the sum, with a \f[I]scale\f[R] equal to the
 855 max of the \f[I]scale\f[R]s of \f[B]a\f[R] and \f[B]b\f[R].
 856 .PP
 857 \f[B]-\f[R]
 858 .PP
 859 : The \f[B]subtract\f[R] operator takes two expressions, \f[B]a\f[R] and
 860 \f[B]b\f[R], and returns the difference, with a \f[I]scale\f[R] equal to
 861 the max of the \f[I]scale\f[R]s of \f[B]a\f[R] and \f[B]b\f[R].
 862 .PP
 863 \f[B]<<\f[R]
 864 .PP
 865 : The \f[B]left shift\f[R] operator takes two expressions, \f[B]a\f[R]
 866 and \f[B]b\f[R], and returns a copy of the value of \f[B]a\f[R] with its
 867 decimal point moved \f[B]b\f[R] places to the right.
 868 .IP
 869 .nf
 870 \f[C]
 871 The second expression must be an integer (no *scale*) and non-negative.
 872
 873 This is a **non-portable extension**.
 874 \f[R]
 875 .fi
 876 .PP
 877 \f[B]>>\f[R]
 878 .PP
 879 : The \f[B]right shift\f[R] operator takes two expressions, \f[B]a\f[R]
 880 and \f[B]b\f[R], and returns a copy of the value of \f[B]a\f[R] with its
 881 decimal point moved \f[B]b\f[R] places to the left.
 882 .IP
 883 .nf
 884 \f[C]
 885 The second expression must be an integer (no *scale*) and non-negative.
 886
 887 This is a **non-portable extension**.
 888 \f[R]
 889 .fi
 890 .PP
 891 \f[B]=\f[R] \f[B]<<=\f[R] \f[B]>>=\f[R] \f[B]+=\f[R] \f[B]-=\f[R]
 892 \f[B]*=\f[R] \f[B]/=\f[R] \f[B]%=\f[R] \f[B]\[ha]=\f[R] \f[B]\[at]=\f[R]
 893 .PP
 894 : The \f[B]assignment\f[R] operators take two expressions, \f[B]a\f[R]
 895 and \f[B]b\f[R] where \f[B]a\f[R] is a named expression (see the
 896 \f[I]Named Expressions\f[R] subsection).
 897 .IP
 898 .nf
 899 \f[C]
 900 For **=**, **b** is copied and the result is assigned to **a**. For all
 901 others, **a** and **b** are applied as operands to the corresponding
 902 arithmetic operator and the result is assigned to **a**.
 903
 904 The **assignment** operators that correspond to operators that are
 905 extensions are themselves **non-portable extensions**.
 906 \f[R]
 907 .fi
 908 .PP
 909 \f[B]==\f[R] \f[B]<=\f[R] \f[B]>=\f[R] \f[B]!=\f[R] \f[B]<\f[R]
 910 \f[B]>\f[R]
 911 .PP
 912 : The \f[B]relational\f[R] operators compare two expressions,
 913 \f[B]a\f[R] and \f[B]b\f[R], and if the relation holds, according to C
 914 language semantics, the result is \f[B]1\f[R].
 915 Otherwise, it is \f[B]0\f[R].
 916 .IP
 917 .nf
 918 \f[C]
 919 Note that unlike in C, these operators have a lower precedence than the
 920 **assignment** operators, which means that **a=b\[rs]>c** is interpreted as
 921 **(a=b)\[rs]>c**.
 922
 923 Also, unlike the [standard][1] requires, these operators can appear anywhere
 924 any other expressions can be used. This allowance is a
 925 **non-portable extension**.
 926 \f[R]
 927 .fi
 928 .PP
 929 \f[B]&&\f[R]
 930 .PP
 931 : The \f[B]boolean and\f[R] operator takes two expressions and returns
 932 \f[B]1\f[R] if both expressions are non-zero, \f[B]0\f[R] otherwise.
 933 .IP
 934 .nf
 935 \f[C]
 936 This is *not* a short-circuit operator.
 937
 938 This is a **non-portable extension**.
 939 \f[R]
 940 .fi
 941 .PP
 942 \f[B]||\f[R]
 943 .PP
 944 : The \f[B]boolean or\f[R] operator takes two expressions and returns
 945 \f[B]1\f[R] if one of the expressions is non-zero, \f[B]0\f[R]
 946 otherwise.
 947 .IP
 948 .nf
 949 \f[C]
 950 This is *not* a short-circuit operator.
 951
 952 This is a **non-portable extension**.
 953 \f[R]
 954 .fi
 955 .SS Statements
 956 .PP
 957 The following items are statements:
 958 .IP " 1." 4
 959 \f[B]E\f[R]
 960 .IP " 2." 4
 961 \f[B]{\f[R] \f[B]S\f[R] \f[B];\f[R] ...
 962 \f[B];\f[R] \f[B]S\f[R] \f[B]}\f[R]
 963 .IP " 3." 4
 964 \f[B]if\f[R] \f[B](\f[R] \f[B]E\f[R] \f[B])\f[R] \f[B]S\f[R]
 965 .IP " 4." 4
 966 \f[B]if\f[R] \f[B](\f[R] \f[B]E\f[R] \f[B])\f[R] \f[B]S\f[R]
 967 \f[B]else\f[R] \f[B]S\f[R]
 968 .IP " 5." 4
 969 \f[B]while\f[R] \f[B](\f[R] \f[B]E\f[R] \f[B])\f[R] \f[B]S\f[R]
 970 .IP " 6." 4
 971 \f[B]for\f[R] \f[B](\f[R] \f[B]E\f[R] \f[B];\f[R] \f[B]E\f[R]
 972 \f[B];\f[R] \f[B]E\f[R] \f[B])\f[R] \f[B]S\f[R]
 973 .IP " 7." 4
 974 An empty statement
 975 .IP " 8." 4
 976 \f[B]break\f[R]
 977 .IP " 9." 4
 978 \f[B]continue\f[R]
 979 .IP "10." 4
 980 \f[B]quit\f[R]
 981 .IP "11." 4
 982 \f[B]halt\f[R]
 983 .IP "12." 4
 984 \f[B]limits\f[R]
 985 .IP "13." 4
 986 A string of characters, enclosed in double quotes
 987 .IP "14." 4
 988 \f[B]print\f[R] \f[B]E\f[R] \f[B],\f[R] ...
 989 \f[B],\f[R] \f[B]E\f[R]
 990 .IP "15." 4
 991 \f[B]I()\f[R], \f[B]I(E)\f[R], \f[B]I(E, E)\f[R], and so on, where
 992 \f[B]I\f[R] is an identifier for a \f[B]void\f[R] function (see the
 993 \f[I]Void Functions\f[R] subsection of the \f[B]FUNCTIONS\f[R] section).
 994 The \f[B]E\f[R] argument(s) may also be arrays of the form
 995 \f[B]I[]\f[R], which will automatically be turned into array references
 996 (see the \f[I]Array References\f[R] subsection of the
 997 \f[B]FUNCTIONS\f[R] section) if the corresponding parameter in the
 998 function definition is an array reference.
 999 .PP
1000 Numbers 4, 9, 11, 12, 14, and 15 are \f[B]non-portable extensions\f[R].
1001 .PP
1002 Also, as a \f[B]non-portable extension\f[R], any or all of the
1003 expressions in the header of a for loop may be omitted.
1004 If the condition (second expression) is omitted, it is assumed to be a
1005 constant \f[B]1\f[R].
1006 .PP
1007 The \f[B]break\f[R] statement causes a loop to stop iterating and resume
1008 execution immediately following a loop.
1009 This is only allowed in loops.
1010 .PP
1011 The \f[B]continue\f[R] statement causes a loop iteration to stop early
1012 and returns to the start of the loop, including testing the loop
1013 condition.
1014 This is only allowed in loops.
1015 .PP
1016 The \f[B]if\f[R] \f[B]else\f[R] statement does the same thing as in C.
1017 .PP
1018 The \f[B]quit\f[R] statement causes bc(1) to quit, even if it is on a
1019 branch that will not be executed (it is a compile-time command).
1020 .PP
1021 The \f[B]halt\f[R] statement causes bc(1) to quit, if it is executed.
1022 (Unlike \f[B]quit\f[R] if it is on a branch of an \f[B]if\f[R] statement
1023 that is not executed, bc(1) does not quit.)
1024 .PP
1025 The \f[B]limits\f[R] statement prints the limits that this bc(1) is
1026 subject to.
1027 This is like the \f[B]quit\f[R] statement in that it is a compile-time
1028 command.
1029 .PP
1030 An expression by itself is evaluated and printed, followed by a newline.
1031 .PP
1032 Both scientific notation and engineering notation are available for
1033 printing the results of expressions.
1034 Scientific notation is activated by assigning \f[B]0\f[R] to
1035 \f[B]obase\f[R], and engineering notation is activated by assigning
1036 \f[B]1\f[R] to \f[B]obase\f[R].
1037 To deactivate them, just assign a different value to \f[B]obase\f[R].
1038 .PP
1039 Scientific notation and engineering notation are disabled if bc(1) is
1040 run with either the \f[B]-s\f[R] or \f[B]-w\f[R] command-line options
1041 (or equivalents).
1042 .PP
1043 Printing numbers in scientific notation and/or engineering notation is a
1044 \f[B]non-portable extension\f[R].
1045 .SS Print Statement
1046 .PP
1047 The \[dq]expressions\[dq] in a \f[B]print\f[R] statement may also be
1048 strings.
1049 If they are, there are backslash escape sequences that are interpreted
1050 specially.
1051 What those sequences are, and what they cause to be printed, are shown
1052 below:
1053 .PP
1054    *   *   *   *   *
1055 .PP
1056 \f[B]\[rs]a\f[R] \f[B]\[rs]a\f[R] \f[B]\[rs]b\f[R] \f[B]\[rs]b\f[R]
1057 \f[B]\[rs]\[rs]\f[R] \f[B]\[rs]\f[R] \f[B]\[rs]e\f[R] \f[B]\[rs]\f[R]
1058 \f[B]\[rs]f\f[R] \f[B]\[rs]f\f[R] \f[B]\[rs]n\f[R] \f[B]\[rs]n\f[R]
1059 \f[B]\[rs]q\f[R] \f[B]\[dq]\f[R] \f[B]\[rs]r\f[R] \f[B]\[rs]r\f[R]
1060 \f[B]\[rs]t\f[R] \f[B]\[rs]t\f[R]
1061 .PP
1062    *   *   *   *   *
1063 .PP
1064 Any other character following a backslash causes the backslash and
1065 character to be printed as-is.
1066 .PP
1067 Any non-string expression in a print statement shall be assigned to
1068 \f[B]last\f[R], like any other expression that is printed.
1069 .SS Order of Evaluation
1070 .PP
1071 All expressions in a statment are evaluated left to right, except as
1072 necessary to maintain order of operations.
1073 This means, for example, assuming that \f[B]i\f[R] is equal to
1074 \f[B]0\f[R], in the expression
1075 .IP
1076 .nf
1077 \f[C]
1078 a[i++] = i++
1079 \f[R]
1080 .fi
1081 .PP
1082 the first (or 0th) element of \f[B]a\f[R] is set to \f[B]1\f[R], and
1083 \f[B]i\f[R] is equal to \f[B]2\f[R] at the end of the expression.
1084 .PP
1085 This includes function arguments.
1086 Thus, assuming \f[B]i\f[R] is equal to \f[B]0\f[R], this means that in
1087 the expression
1088 .IP
1089 .nf
1090 \f[C]
1091 x(i++, i++)
1092 \f[R]
1093 .fi
1094 .PP
1095 the first argument passed to \f[B]x()\f[R] is \f[B]0\f[R], and the
1096 second argument is \f[B]1\f[R], while \f[B]i\f[R] is equal to
1097 \f[B]2\f[R] before the function starts executing.
1098 .SH FUNCTIONS
1099 .PP
1100 Function definitions are as follows:
1101 .IP
1102 .nf
1103 \f[C]
1104 define I(I,...,I){
1105     auto I,...,I
1106     S;...;S
1107     return(E)
1108 }
1109 \f[R]
1110 .fi
1111 .PP
1112 Any \f[B]I\f[R] in the parameter list or \f[B]auto\f[R] list may be
1113 replaced with \f[B]I[]\f[R] to make a parameter or \f[B]auto\f[R] var an
1114 array, and any \f[B]I\f[R] in the parameter list may be replaced with
1115 \f[B]*I[]\f[R] to make a parameter an array reference.
1116 Callers of functions that take array references should not put an
1117 asterisk in the call; they must be called with just \f[B]I[]\f[R] like
1118 normal array parameters and will be automatically converted into
1119 references.
1120 .PP
1121 As a \f[B]non-portable extension\f[R], the opening brace of a
1122 \f[B]define\f[R] statement may appear on the next line.
1123 .PP
1124 As a \f[B]non-portable extension\f[R], the return statement may also be
1125 in one of the following forms:
1126 .IP "1." 3
1127 \f[B]return\f[R]
1128 .IP "2." 3
1129 \f[B]return\f[R] \f[B](\f[R] \f[B])\f[R]
1130 .IP "3." 3
1131 \f[B]return\f[R] \f[B]E\f[R]
1132 .PP
1133 The first two, or not specifying a \f[B]return\f[R] statement, is
1134 equivalent to \f[B]return (0)\f[R], unless the function is a
1135 \f[B]void\f[R] function (see the \f[I]Void Functions\f[R] subsection
1136 below).
1137 .SS Void Functions
1138 .PP
1139 Functions can also be \f[B]void\f[R] functions, defined as follows:
1140 .IP
1141 .nf
1142 \f[C]
1143 define void I(I,...,I){
1144     auto I,...,I
1145     S;...;S
1146     return
1147 }
1148 \f[R]
1149 .fi
1150 .PP
1151 They can only be used as standalone expressions, where such an
1152 expression would be printed alone, except in a print statement.
1153 .PP
1154 Void functions can only use the first two \f[B]return\f[R] statements
1155 listed above.
1156 They can also omit the return statement entirely.
1157 .PP
1158 The word \[dq]void\[dq] is not treated as a keyword; it is still
1159 possible to have variables, arrays, and functions named \f[B]void\f[R].
1160 The word \[dq]void\[dq] is only treated specially right after the
1161 \f[B]define\f[R] keyword.
1162 .PP
1163 This is a \f[B]non-portable extension\f[R].
1164 .SS Array References
1165 .PP
1166 For any array in the parameter list, if the array is declared in the
1167 form
1168 .IP
1169 .nf
1170 \f[C]
1171 *I[]
1172 \f[R]
1173 .fi
1174 .PP
1175 it is a \f[B]reference\f[R].
1176 Any changes to the array in the function are reflected, when the
1177 function returns, to the array that was passed in.
1178 .PP
1179 Other than this, all function arguments are passed by value.
1180 .PP
1181 This is a \f[B]non-portable extension\f[R].
1182 .SH LIBRARY
1183 .PP
1184 All of the functions below, including the functions in the extended math
1185 library (see the \f[I]Extended Library\f[R] subsection below), are
1186 available when the \f[B]-l\f[R] or \f[B]--mathlib\f[R] command-line
1187 flags are given, except that the extended math library is not available
1188 when the \f[B]-s\f[R] option, the \f[B]-w\f[R] option, or equivalents
1189 are given.
1190 .SS Standard Library
1191 .PP
1192 The
1193 standard (https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html)
1194 defines the following functions for the math library:
1195 .PP
1196 \f[B]s(x)\f[R]
1197 .PP
1198 : Returns the sine of \f[B]x\f[R], which is assumed to be in radians.
1199 .IP
1200 .nf
1201 \f[C]
1202 This is a transcendental function (see the *Transcendental Functions*
1203 subsection below).
1204 \f[R]
1205 .fi
1206 .PP
1207 \f[B]c(x)\f[R]
1208 .PP
1209 : Returns the cosine of \f[B]x\f[R], which is assumed to be in radians.
1210 .IP
1211 .nf
1212 \f[C]
1213 This is a transcendental function (see the *Transcendental Functions*
1214 subsection below).
1215 \f[R]
1216 .fi
1217 .PP
1218 \f[B]a(x)\f[R]
1219 .PP
1220 : Returns the arctangent of \f[B]x\f[R], in radians.
1221 .IP
1222 .nf
1223 \f[C]
1224 This is a transcendental function (see the *Transcendental Functions*
1225 subsection below).
1226 \f[R]
1227 .fi
1228 .PP
1229 \f[B]l(x)\f[R]
1230 .PP
1231 : Returns the natural logarithm of \f[B]x\f[R].
1232 .IP
1233 .nf
1234 \f[C]
1235 This is a transcendental function (see the *Transcendental Functions*
1236 subsection below).
1237 \f[R]
1238 .fi
1239 .PP
1240 \f[B]e(x)\f[R]
1241 .PP
1242 : Returns the mathematical constant \f[B]e\f[R] raised to the power of
1243 \f[B]x\f[R].
1244 .IP
1245 .nf
1246 \f[C]
1247 This is a transcendental function (see the *Transcendental Functions*
1248 subsection below).
1249 \f[R]
1250 .fi
1251 .PP
1252 \f[B]j(x, n)\f[R]
1253 .PP
1254 : Returns the bessel integer order \f[B]n\f[R] (truncated) of
1255 \f[B]x\f[R].
1256 .IP
1257 .nf
1258 \f[C]
1259 This is a transcendental function (see the *Transcendental Functions*
1260 subsection below).
1261 \f[R]
1262 .fi
1263 .SS Extended Library
1264 .PP
1265 The extended library is \f[I]not\f[R] loaded when the
1266 \f[B]-s\f[R]/\f[B]--standard\f[R] or \f[B]-w\f[R]/\f[B]--warn\f[R]
1267 options are given since they are not part of the library defined by the
1268 standard (https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html).
1269 .PP
1270 The extended library is a \f[B]non-portable extension\f[R].
1271 .PP
1272 \f[B]p(x, y)\f[R]
1273 .PP
1274 : Calculates \f[B]x\f[R] to the power of \f[B]y\f[R], even if
1275 \f[B]y\f[R] is not an integer, and returns the result to the current
1276 \f[B]scale\f[R].
1277 .IP
1278 .nf
1279 \f[C]
1280 It is an error if **y** is negative and **x** is **0**.
1281
1282 This is a transcendental function (see the *Transcendental Functions*
1283 subsection below).
1284 \f[R]
1285 .fi
1286 .PP
1287 \f[B]r(x, p)\f[R]
1288 .PP
1289 : Returns \f[B]x\f[R] rounded to \f[B]p\f[R] decimal places according to
1290 the rounding mode round half away from
1291 \f[B]0\f[R] (https://en.wikipedia.org/wiki/Rounding#Round_half_away_from_zero).
1292 .PP
1293 \f[B]ceil(x, p)\f[R]
1294 .PP
1295 : Returns \f[B]x\f[R] rounded to \f[B]p\f[R] decimal places according to
1296 the rounding mode round away from
1297 \f[B]0\f[R] (https://en.wikipedia.org/wiki/Rounding#Rounding_away_from_zero).
1298 .PP
1299 \f[B]f(x)\f[R]
1300 .PP
1301 : Returns the factorial of the truncated absolute value of \f[B]x\f[R].
1302 .PP
1303 \f[B]perm(n, k)\f[R]
1304 .PP
1305 : Returns the permutation of the truncated absolute value of \f[B]n\f[R]
1306 of the truncated absolute value of \f[B]k\f[R], if \f[B]k <= n\f[R].
1307 If not, it returns \f[B]0\f[R].
1308 .PP
1309 \f[B]comb(n, k)\f[R]
1310 .PP
1311 : Returns the combination of the truncated absolute value of \f[B]n\f[R]
1312 of the truncated absolute value of \f[B]k\f[R], if \f[B]k <= n\f[R].
1313 If not, it returns \f[B]0\f[R].
1314 .PP
1315 \f[B]l2(x)\f[R]
1316 .PP
1317 : Returns the logarithm base \f[B]2\f[R] of \f[B]x\f[R].
1318 .IP
1319 .nf
1320 \f[C]
1321 This is a transcendental function (see the *Transcendental Functions*
1322 subsection below).
1323 \f[R]
1324 .fi
1325 .PP
1326 \f[B]l10(x)\f[R]
1327 .PP
1328 : Returns the logarithm base \f[B]10\f[R] of \f[B]x\f[R].
1329 .IP
1330 .nf
1331 \f[C]
1332 This is a transcendental function (see the *Transcendental Functions*
1333 subsection below).
1334 \f[R]
1335 .fi
1336 .PP
1337 \f[B]log(x, b)\f[R]
1338 .PP
1339 : Returns the logarithm base \f[B]b\f[R] of \f[B]x\f[R].
1340 .IP
1341 .nf
1342 \f[C]
1343 This is a transcendental function (see the *Transcendental Functions*
1344 subsection below).
1345 \f[R]
1346 .fi
1347 .PP
1348 \f[B]cbrt(x)\f[R]
1349 .PP
1350 : Returns the cube root of \f[B]x\f[R].
1351 .PP
1352 \f[B]root(x, n)\f[R]
1353 .PP
1354 : Calculates the truncated value of \f[B]n\f[R], \f[B]r\f[R], and
1355 returns the \f[B]r\f[R]th root of \f[B]x\f[R] to the current
1356 \f[B]scale\f[R].
1357 .IP
1358 .nf
1359 \f[C]
1360 If **r** is **0** or negative, this raises an error and causes bc(1) to
1361 reset (see the **RESET** section). It also raises an error and causes bc(1)
1362 to reset if **r** is even and **x** is negative.
1363 \f[R]
1364 .fi
1365 .PP
1366 \f[B]pi(p)\f[R]
1367 .PP
1368 : Returns \f[B]pi\f[R] to \f[B]p\f[R] decimal places.
1369 .IP
1370 .nf
1371 \f[C]
1372 This is a transcendental function (see the *Transcendental Functions*
1373 subsection below).
1374 \f[R]
1375 .fi
1376 .PP
1377 \f[B]t(x)\f[R]
1378 .PP
1379 : Returns the tangent of \f[B]x\f[R], which is assumed to be in radians.
1380 .IP
1381 .nf
1382 \f[C]
1383 This is a transcendental function (see the *Transcendental Functions*
1384 subsection below).
1385 \f[R]
1386 .fi
1387 .PP
1388 \f[B]a2(y, x)\f[R]
1389 .PP
1390 : Returns the arctangent of \f[B]y/x\f[R], in radians.
1391 If both \f[B]y\f[R] and \f[B]x\f[R] are equal to \f[B]0\f[R], it raises
1392 an error and causes bc(1) to reset (see the \f[B]RESET\f[R] section).
1393 Otherwise, if \f[B]x\f[R] is greater than \f[B]0\f[R], it returns
1394 \f[B]a(y/x)\f[R].
1395 If \f[B]x\f[R] is less than \f[B]0\f[R], and \f[B]y\f[R] is greater than
1396 or equal to \f[B]0\f[R], it returns \f[B]a(y/x)+pi\f[R].
1397 If \f[B]x\f[R] is less than \f[B]0\f[R], and \f[B]y\f[R] is less than
1398 \f[B]0\f[R], it returns \f[B]a(y/x)-pi\f[R].
1399 If \f[B]x\f[R] is equal to \f[B]0\f[R], and \f[B]y\f[R] is greater than
1400 \f[B]0\f[R], it returns \f[B]pi/2\f[R].
1401 If \f[B]x\f[R] is equal to \f[B]0\f[R], and \f[B]y\f[R] is less than
1402 \f[B]0\f[R], it returns \f[B]-pi/2\f[R].
1403 .IP
1404 .nf
1405 \f[C]
1406 This function is the same as the **atan2()** function in many programming
1407 languages.
1408
1409 This is a transcendental function (see the *Transcendental Functions*
1410 subsection below).
1411 \f[R]
1412 .fi
1413 .PP
1414 \f[B]sin(x)\f[R]
1415 .PP
1416 : Returns the sine of \f[B]x\f[R], which is assumed to be in radians.
1417 .IP
1418 .nf
1419 \f[C]
1420 This is an alias of **s(x)**.
1421
1422 This is a transcendental function (see the *Transcendental Functions*
1423 subsection below).
1424 \f[R]
1425 .fi
1426 .PP
1427 \f[B]cos(x)\f[R]
1428 .PP
1429 : Returns the cosine of \f[B]x\f[R], which is assumed to be in radians.
1430 .IP
1431 .nf
1432 \f[C]
1433 This is an alias of **c(x)**.
1434
1435 This is a transcendental function (see the *Transcendental Functions*
1436 subsection below).
1437 \f[R]
1438 .fi
1439 .PP
1440 \f[B]tan(x)\f[R]
1441 .PP
1442 : Returns the tangent of \f[B]x\f[R], which is assumed to be in radians.
1443 .IP
1444 .nf
1445 \f[C]
1446 If **x** is equal to **1** or **-1**, this raises an error and causes bc(1)
1447 to reset (see the **RESET** section).
1448
1449 This is an alias of **t(x)**.
1450
1451 This is a transcendental function (see the *Transcendental Functions*
1452 subsection below).
1453 \f[R]
1454 .fi
1455 .PP
1456 \f[B]atan(x)\f[R]
1457 .PP
1458 : Returns the arctangent of \f[B]x\f[R], in radians.
1459 .IP
1460 .nf
1461 \f[C]
1462 This is an alias of **a(x)**.
1463
1464 This is a transcendental function (see the *Transcendental Functions*
1465 subsection below).
1466 \f[R]
1467 .fi
1468 .PP
1469 \f[B]atan2(y, x)\f[R]
1470 .PP
1471 : Returns the arctangent of \f[B]y/x\f[R], in radians.
1472 If both \f[B]y\f[R] and \f[B]x\f[R] are equal to \f[B]0\f[R], it raises
1473 an error and causes bc(1) to reset (see the \f[B]RESET\f[R] section).
1474 Otherwise, if \f[B]x\f[R] is greater than \f[B]0\f[R], it returns
1475 \f[B]a(y/x)\f[R].
1476 If \f[B]x\f[R] is less than \f[B]0\f[R], and \f[B]y\f[R] is greater than
1477 or equal to \f[B]0\f[R], it returns \f[B]a(y/x)+pi\f[R].
1478 If \f[B]x\f[R] is less than \f[B]0\f[R], and \f[B]y\f[R] is less than
1479 \f[B]0\f[R], it returns \f[B]a(y/x)-pi\f[R].
1480 If \f[B]x\f[R] is equal to \f[B]0\f[R], and \f[B]y\f[R] is greater than
1481 \f[B]0\f[R], it returns \f[B]pi/2\f[R].
1482 If \f[B]x\f[R] is equal to \f[B]0\f[R], and \f[B]y\f[R] is less than
1483 \f[B]0\f[R], it returns \f[B]-pi/2\f[R].
1484 .IP
1485 .nf
1486 \f[C]
1487 This function is the same as the **atan2()** function in many programming
1488 languages.
1489
1490 This is an alias of **a2(y, x)**.
1491
1492 This is a transcendental function (see the *Transcendental Functions*
1493 subsection below).
1494 \f[R]
1495 .fi
1496 .PP
1497 \f[B]r2d(x)\f[R]
1498 .PP
1499 : Converts \f[B]x\f[R] from radians to degrees and returns the result.
1500 .IP
1501 .nf
1502 \f[C]
1503 This is a transcendental function (see the *Transcendental Functions*
1504 subsection below).
1505 \f[R]
1506 .fi
1507 .PP
1508 \f[B]d2r(x)\f[R]
1509 .PP
1510 : Converts \f[B]x\f[R] from degrees to radians and returns the result.
1511 .IP
1512 .nf
1513 \f[C]
1514 This is a transcendental function (see the *Transcendental Functions*
1515 subsection below).
1516 \f[R]
1517 .fi
1518 .PP
1519 \f[B]frand(p)\f[R]
1520 .PP
1521 : Generates a pseudo-random number between \f[B]0\f[R] (inclusive) and
1522 \f[B]1\f[R] (exclusive) with the number of decimal digits after the
1523 decimal point equal to the truncated absolute value of \f[B]p\f[R].
1524 If \f[B]p\f[R] is not \f[B]0\f[R], then calling this function will
1525 change the value of \f[B]seed\f[R].
1526 If \f[B]p\f[R] is \f[B]0\f[R], then \f[B]0\f[R] is returned, and
1527 \f[B]seed\f[R] is \f[I]not\f[R] changed.
1528 .PP
1529 \f[B]ifrand(i, p)\f[R]
1530 .PP
1531 : Generates a pseudo-random number that is between \f[B]0\f[R]
1532 (inclusive) and the truncated absolute value of \f[B]i\f[R] (exclusive)
1533 with the number of decimal digits after the decimal point equal to the
1534 truncated absolute value of \f[B]p\f[R].
1535 If the absolute value of \f[B]i\f[R] is greater than or equal to
1536 \f[B]2\f[R], and \f[B]p\f[R] is not \f[B]0\f[R], then calling this
1537 function will change the value of \f[B]seed\f[R]; otherwise, \f[B]0\f[R]
1538 is returned and \f[B]seed\f[R] is not changed.
1539 .PP
1540 \f[B]srand(x)\f[R]
1541 .PP
1542 : Returns \f[B]x\f[R] with its sign flipped with probability
1543 \f[B]0.5\f[R].
1544 In other words, it randomizes the sign of \f[B]x\f[R].
1545 .PP
1546 \f[B]brand()\f[R]
1547 .PP
1548 : Returns a random boolean value (either \f[B]0\f[R] or \f[B]1\f[R]).
1549 .PP
1550 \f[B]ubytes(x)\f[R]
1551 .PP
1552 : Returns the numbers of unsigned integer bytes required to hold the
1553 truncated absolute value of \f[B]x\f[R].
1554 .PP
1555 \f[B]sbytes(x)\f[R]
1556 .PP
1557 : Returns the numbers of signed, two\[aq]s-complement integer bytes
1558 required to hold the truncated value of \f[B]x\f[R].
1559 .PP
1560 \f[B]hex(x)\f[R]
1561 .PP
1562 : Outputs the hexadecimal (base \f[B]16\f[R]) representation of
1563 \f[B]x\f[R].
1564 .IP
1565 .nf
1566 \f[C]
1567 This is a **void** function (see the *Void Functions* subsection of the
1568 **FUNCTIONS** section).
1569 \f[R]
1570 .fi
1571 .PP
1572 \f[B]binary(x)\f[R]
1573 .PP
1574 : Outputs the binary (base \f[B]2\f[R]) representation of \f[B]x\f[R].
1575 .IP
1576 .nf
1577 \f[C]
1578 This is a **void** function (see the *Void Functions* subsection of the
1579 **FUNCTIONS** section).
1580 \f[R]
1581 .fi
1582 .PP
1583 \f[B]output(x, b)\f[R]
1584 .PP
1585 : Outputs the base \f[B]b\f[R] representation of \f[B]x\f[R].
1586 .IP
1587 .nf
1588 \f[C]
1589 This is a **void** function (see the *Void Functions* subsection of the
1590 **FUNCTIONS** section).
1591 \f[R]
1592 .fi
1593 .PP
1594 \f[B]uint(x)\f[R]
1595 .PP
1596 : Outputs the representation, in binary and hexadecimal, of \f[B]x\f[R]
1597 as an unsigned integer in as few power of two bytes as possible.
1598 Both outputs are split into bytes separated by spaces.
1599 .IP
1600 .nf
1601 \f[C]
1602 If **x** is not an integer or is negative, an error message is printed
1603 instead, but bc(1) is not reset (see the **RESET** section).
1604
1605 This is a **void** function (see the *Void Functions* subsection of the
1606 **FUNCTIONS** section).
1607 \f[R]
1608 .fi
1609 .PP
1610 \f[B]int(x)\f[R]
1611 .PP
1612 : Outputs the representation, in binary and hexadecimal, of \f[B]x\f[R]
1613 as a signed, two\[aq]s-complement integer in as few power of two bytes
1614 as possible.
1615 Both outputs are split into bytes separated by spaces.
1616 .IP
1617 .nf
1618 \f[C]
1619 If **x** is not an integer, an error message is printed instead, but bc(1)
1620 is not reset (see the **RESET** section).
1621
1622 This is a **void** function (see the *Void Functions* subsection of the
1623 **FUNCTIONS** section).
1624 \f[R]
1625 .fi
1626 .PP
1627 \f[B]uintn(x, n)\f[R]
1628 .PP
1629 : Outputs the representation, in binary and hexadecimal, of \f[B]x\f[R]
1630 as an unsigned integer in \f[B]n\f[R] bytes.
1631 Both outputs are split into bytes separated by spaces.
1632 .IP
1633 .nf
1634 \f[C]
1635 If **x** is not an integer, is negative, or cannot fit into **n** bytes, an
1636 error message is printed instead, but bc(1) is not reset (see the **RESET**
1637 section).
1638
1639 This is a **void** function (see the *Void Functions* subsection of the
1640 **FUNCTIONS** section).
1641 \f[R]
1642 .fi
1643 .PP
1644 \f[B]intn(x, n)\f[R]
1645 .PP
1646 : Outputs the representation, in binary and hexadecimal, of \f[B]x\f[R]
1647 as a signed, two\[aq]s-complement integer in \f[B]n\f[R] bytes.
1648 Both outputs are split into bytes separated by spaces.
1649 .IP
1650 .nf
1651 \f[C]
1652 If **x** is not an integer or cannot fit into **n** bytes, an error message
1653 is printed instead, but bc(1) is not reset (see the **RESET** section).
1654
1655 This is a **void** function (see the *Void Functions* subsection of the
1656 **FUNCTIONS** section).
1657 \f[R]
1658 .fi
1659 .PP
1660 \f[B]uint8(x)\f[R]
1661 .PP
1662 : Outputs the representation, in binary and hexadecimal, of \f[B]x\f[R]
1663 as an unsigned integer in \f[B]1\f[R] byte.
1664 Both outputs are split into bytes separated by spaces.
1665 .IP
1666 .nf
1667 \f[C]
1668 If **x** is not an integer, is negative, or cannot fit into **1** byte, an
1669 error message is printed instead, but bc(1) is not reset (see the **RESET**
1670 section).
1671
1672 This is a **void** function (see the *Void Functions* subsection of the
1673 **FUNCTIONS** section).
1674 \f[R]
1675 .fi
1676 .PP
1677 \f[B]int8(x)\f[R]
1678 .PP
1679 : Outputs the representation, in binary and hexadecimal, of \f[B]x\f[R]
1680 as a signed, two\[aq]s-complement integer in \f[B]1\f[R] byte.
1681 Both outputs are split into bytes separated by spaces.
1682 .IP
1683 .nf
1684 \f[C]
1685 If **x** is not an integer or cannot fit into **1** byte, an error message
1686 is printed instead, but bc(1) is not reset (see the **RESET** section).
1687
1688 This is a **void** function (see the *Void Functions* subsection of the
1689 **FUNCTIONS** section).
1690 \f[R]
1691 .fi
1692 .PP
1693 \f[B]uint16(x)\f[R]
1694 .PP
1695 : Outputs the representation, in binary and hexadecimal, of \f[B]x\f[R]
1696 as an unsigned integer in \f[B]2\f[R] bytes.
1697 Both outputs are split into bytes separated by spaces.
1698 .IP
1699 .nf
1700 \f[C]
1701 If **x** is not an integer, is negative, or cannot fit into **2** bytes, an
1702 error message is printed instead, but bc(1) is not reset (see the **RESET**
1703 section).
1704
1705 This is a **void** function (see the *Void Functions* subsection of the
1706 **FUNCTIONS** section).
1707 \f[R]
1708 .fi
1709 .PP
1710 \f[B]int16(x)\f[R]
1711 .PP
1712 : Outputs the representation, in binary and hexadecimal, of \f[B]x\f[R]
1713 as a signed, two\[aq]s-complement integer in \f[B]2\f[R] bytes.
1714 Both outputs are split into bytes separated by spaces.
1715 .IP
1716 .nf
1717 \f[C]
1718 If **x** is not an integer or cannot fit into **2** bytes, an error message
1719 is printed instead, but bc(1) is not reset (see the **RESET** section).
1720
1721 This is a **void** function (see the *Void Functions* subsection of the
1722 **FUNCTIONS** section).
1723 \f[R]
1724 .fi
1725 .PP
1726 \f[B]uint32(x)\f[R]
1727 .PP
1728 : Outputs the representation, in binary and hexadecimal, of \f[B]x\f[R]
1729 as an unsigned integer in \f[B]4\f[R] bytes.
1730 Both outputs are split into bytes separated by spaces.
1731 .IP
1732 .nf
1733 \f[C]
1734 If **x** is not an integer, is negative, or cannot fit into **4** bytes, an
1735 error message is printed instead, but bc(1) is not reset (see the **RESET**
1736 section).
1737
1738 This is a **void** function (see the *Void Functions* subsection of the
1739 **FUNCTIONS** section).
1740 \f[R]
1741 .fi
1742 .PP
1743 \f[B]int32(x)\f[R]
1744 .PP
1745 : Outputs the representation, in binary and hexadecimal, of \f[B]x\f[R]
1746 as a signed, two\[aq]s-complement integer in \f[B]4\f[R] bytes.
1747 Both outputs are split into bytes separated by spaces.
1748 .IP
1749 .nf
1750 \f[C]
1751 If **x** is not an integer or cannot fit into **4** bytes, an error message
1752 is printed instead, but bc(1) is not reset (see the **RESET** section).
1753
1754 This is a **void** function (see the *Void Functions* subsection of the
1755 **FUNCTIONS** section).
1756 \f[R]
1757 .fi
1758 .PP
1759 \f[B]uint64(x)\f[R]
1760 .PP
1761 : Outputs the representation, in binary and hexadecimal, of \f[B]x\f[R]
1762 as an unsigned integer in \f[B]8\f[R] bytes.
1763 Both outputs are split into bytes separated by spaces.
1764 .IP
1765 .nf
1766 \f[C]
1767 If **x** is not an integer, is negative, or cannot fit into **8** bytes, an
1768 error message is printed instead, but bc(1) is not reset (see the **RESET**
1769 section).
1770
1771 This is a **void** function (see the *Void Functions* subsection of the
1772 **FUNCTIONS** section).
1773 \f[R]
1774 .fi
1775 .PP
1776 \f[B]int64(x)\f[R]
1777 .PP
1778 : Outputs the representation, in binary and hexadecimal, of \f[B]x\f[R]
1779 as a signed, two\[aq]s-complement integer in \f[B]8\f[R] bytes.
1780 Both outputs are split into bytes separated by spaces.
1781 .IP
1782 .nf
1783 \f[C]
1784 If **x** is not an integer or cannot fit into **8** bytes, an error message
1785 is printed instead, but bc(1) is not reset (see the **RESET** section).
1786
1787 This is a **void** function (see the *Void Functions* subsection of the
1788 **FUNCTIONS** section).
1789 \f[R]
1790 .fi
1791 .PP
1792 \f[B]hex_uint(x, n)\f[R]
1793 .PP
1794 : Outputs the representation of the truncated absolute value of
1795 \f[B]x\f[R] as an unsigned integer in hexadecimal using \f[B]n\f[R]
1796 bytes.
1797 Not all of the value will be output if \f[B]n\f[R] is too small.
1798 .IP
1799 .nf
1800 \f[C]
1801 This is a **void** function (see the *Void Functions* subsection of the
1802 **FUNCTIONS** section).
1803 \f[R]
1804 .fi
1805 .PP
1806 \f[B]binary_uint(x, n)\f[R]
1807 .PP
1808 : Outputs the representation of the truncated absolute value of
1809 \f[B]x\f[R] as an unsigned integer in binary using \f[B]n\f[R] bytes.
1810 Not all of the value will be output if \f[B]n\f[R] is too small.
1811 .IP
1812 .nf
1813 \f[C]
1814 This is a **void** function (see the *Void Functions* subsection of the
1815 **FUNCTIONS** section).
1816 \f[R]
1817 .fi
1818 .PP
1819 \f[B]output_uint(x, n)\f[R]
1820 .PP
1821 : Outputs the representation of the truncated absolute value of
1822 \f[B]x\f[R] as an unsigned integer in the current \f[B]obase\f[R] (see
1823 the \f[B]SYNTAX\f[R] section) using \f[B]n\f[R] bytes.
1824 Not all of the value will be output if \f[B]n\f[R] is too small.
1825 .IP
1826 .nf
1827 \f[C]
1828 This is a **void** function (see the *Void Functions* subsection of the
1829 **FUNCTIONS** section).
1830 \f[R]
1831 .fi
1832 .PP
1833 \f[B]output_byte(x, i)\f[R]
1834 .PP
1835 : Outputs byte \f[B]i\f[R] of the truncated absolute value of
1836 \f[B]x\f[R], where \f[B]0\f[R] is the least significant byte and
1837 \f[B]number_of_bytes - 1\f[R] is the most significant byte.
1838 .IP
1839 .nf
1840 \f[C]
1841 This is a **void** function (see the *Void Functions* subsection of the
1842 **FUNCTIONS** section).
1843 \f[R]
1844 .fi
1845 .SS Transcendental Functions
1846 .PP
1847 All transcendental functions can return slightly inaccurate results (up
1848 to 1 ULP (https://en.wikipedia.org/wiki/Unit_in_the_last_place)).
1849 This is unavoidable, and this
1850 article (https://people.eecs.berkeley.edu/~wkahan/LOG10HAF.TXT) explains
1851 why it is impossible and unnecessary to calculate exact results for the
1852 transcendental functions.
1853 .PP
1854 Because of the possible inaccuracy, I recommend that users call those
1855 functions with the precision (\f[B]scale\f[R]) set to at least 1 higher
1856 than is necessary.
1857 If exact results are \f[I]absolutely\f[R] required, users can double the
1858 precision (\f[B]scale\f[R]) and then truncate.
1859 .PP
1860 The transcendental functions in the standard math library are:
1861 .IP \[bu] 2
1862 \f[B]s(x)\f[R]
1863 .IP \[bu] 2
1864 \f[B]c(x)\f[R]
1865 .IP \[bu] 2
1866 \f[B]a(x)\f[R]
1867 .IP \[bu] 2
1868 \f[B]l(x)\f[R]
1869 .IP \[bu] 2
1870 \f[B]e(x)\f[R]
1871 .IP \[bu] 2
1872 \f[B]j(x, n)\f[R]
1873 .PP
1874 The transcendental functions in the extended math library are:
1875 .IP \[bu] 2
1876 \f[B]l2(x)\f[R]
1877 .IP \[bu] 2
1878 \f[B]l10(x)\f[R]
1879 .IP \[bu] 2
1880 \f[B]log(x, b)\f[R]
1881 .IP \[bu] 2
1882 \f[B]pi(p)\f[R]
1883 .IP \[bu] 2
1884 \f[B]t(x)\f[R]
1885 .IP \[bu] 2
1886 \f[B]a2(y, x)\f[R]
1887 .IP \[bu] 2
1888 \f[B]sin(x)\f[R]
1889 .IP \[bu] 2
1890 \f[B]cos(x)\f[R]
1891 .IP \[bu] 2
1892 \f[B]tan(x)\f[R]
1893 .IP \[bu] 2
1894 \f[B]atan(x)\f[R]
1895 .IP \[bu] 2
1896 \f[B]atan2(y, x)\f[R]
1897 .IP \[bu] 2
1898 \f[B]r2d(x)\f[R]
1899 .IP \[bu] 2
1900 \f[B]d2r(x)\f[R]
1901 .SH RESET
1902 .PP
1903 When bc(1) encounters an error or a signal that it has a non-default
1904 handler for, it resets.
1905 This means that several things happen.
1906 .PP
1907 First, any functions that are executing are stopped and popped off the
1908 stack.
1909 The behavior is not unlike that of exceptions in programming languages.
1910 Then the execution point is set so that any code waiting to execute
1911 (after all functions returned) is skipped.
1912 .PP
1913 Thus, when bc(1) resets, it skips any remaining code waiting to be
1914 executed.
1915 Then, if it is interactive mode, and the error was not a fatal error
1916 (see the \f[B]EXIT STATUS\f[R] section), it asks for more input;
1917 otherwise, it exits with the appropriate return code.
1918 .PP
1919 Note that this reset behavior is different from the GNU bc(1), which
1920 attempts to start executing the statement right after the one that
1921 caused an error.
1922 .SH PERFORMANCE
1923 .PP
1924 Most bc(1) implementations use \f[B]char\f[R] types to calculate the
1925 value of \f[B]1\f[R] decimal digit at a time, but that can be slow.
1926 This bc(1) does something different.
1927 .PP
1928 It uses large integers to calculate more than \f[B]1\f[R] decimal digit
1929 at a time.
1930 If built in a environment where \f[B]BC_LONG_BIT\f[R] (see the
1931 \f[B]LIMITS\f[R] section) is \f[B]64\f[R], then each integer has
1932 \f[B]9\f[R] decimal digits.
1933 If built in an environment where \f[B]BC_LONG_BIT\f[R] is \f[B]32\f[R]
1934 then each integer has \f[B]4\f[R] decimal digits.
1935 This value (the number of decimal digits per large integer) is called
1936 \f[B]BC_BASE_DIGS\f[R].
1937 .PP
1938 The actual values of \f[B]BC_LONG_BIT\f[R] and \f[B]BC_BASE_DIGS\f[R]
1939 can be queried with the \f[B]limits\f[R] statement.
1940 .PP
1941 In addition, this bc(1) uses an even larger integer for overflow
1942 checking.
1943 This integer type depends on the value of \f[B]BC_LONG_BIT\f[R], but is
1944 always at least twice as large as the integer type used to store digits.
1945 .SH LIMITS
1946 .PP
1947 The following are the limits on bc(1):
1948 .PP
1949 \f[B]BC_LONG_BIT\f[R]
1950 .PP
1951 : The number of bits in the \f[B]long\f[R] type in the environment where
1952 bc(1) was built.
1953 This determines how many decimal digits can be stored in a single large
1954 integer (see the \f[B]PERFORMANCE\f[R] section).
1955 .PP
1956 \f[B]BC_BASE_DIGS\f[R]
1957 .PP
1958 : The number of decimal digits per large integer (see the
1959 \f[B]PERFORMANCE\f[R] section).
1960 Depends on \f[B]BC_LONG_BIT\f[R].
1961 .PP
1962 \f[B]BC_BASE_POW\f[R]
1963 .PP
1964 : The max decimal number that each large integer can store (see
1965 \f[B]BC_BASE_DIGS\f[R]) plus \f[B]1\f[R].
1966 Depends on \f[B]BC_BASE_DIGS\f[R].
1967 .PP
1968 \f[B]BC_OVERFLOW_MAX\f[R]
1969 .PP
1970 : The max number that the overflow type (see the \f[B]PERFORMANCE\f[R]
1971 section) can hold.
1972 Depends on \f[B]BC_LONG_BIT\f[R].
1973 .PP
1974 \f[B]BC_BASE_MAX\f[R]
1975 .PP
1976 : The maximum output base.
1977 Set at \f[B]BC_BASE_POW\f[R].
1978 .PP
1979 \f[B]BC_DIM_MAX\f[R]
1980 .PP
1981 : The maximum size of arrays.
1982 Set at \f[B]SIZE_MAX-1\f[R].
1983 .PP
1984 \f[B]BC_SCALE_MAX\f[R]
1985 .PP
1986 : The maximum \f[B]scale\f[R].
1987 Set at \f[B]BC_OVERFLOW_MAX-1\f[R].
1988 .PP
1989 \f[B]BC_STRING_MAX\f[R]
1990 .PP
1991 : The maximum length of strings.
1992 Set at \f[B]BC_OVERFLOW_MAX-1\f[R].
1993 .PP
1994 \f[B]BC_NAME_MAX\f[R]
1995 .PP
1996 : The maximum length of identifiers.
1997 Set at \f[B]BC_OVERFLOW_MAX-1\f[R].
1998 .PP
1999 \f[B]BC_NUM_MAX\f[R]
2000 .PP
2001 : The maximum length of a number (in decimal digits), which includes
2002 digits after the decimal point.
2003 Set at \f[B]BC_OVERFLOW_MAX-1\f[R].
2004 .PP
2005 \f[B]BC_RAND_MAX\f[R]
2006 .PP
2007 : The maximum integer (inclusive) returned by the \f[B]rand()\f[R]
2008 operand.
2009 Set at \f[B]2\[ha]BC_LONG_BIT-1\f[R].
2010 .PP
2011 Exponent
2012 .PP
2013 : The maximum allowable exponent (positive or negative).
2014 Set at \f[B]BC_OVERFLOW_MAX\f[R].
2015 .PP
2016 Number of vars
2017 .PP
2018 : The maximum number of vars/arrays.
2019 Set at \f[B]SIZE_MAX-1\f[R].
2020 .PP
2021 The actual values can be queried with the \f[B]limits\f[R] statement.
2022 .PP
2023 These limits are meant to be effectively non-existent; the limits are so
2024 large (at least on 64-bit machines) that there should not be any point
2025 at which they become a problem.
2026 In fact, memory should be exhausted before these limits should be hit.
2027 .SH ENVIRONMENT VARIABLES
2028 .PP
2029 bc(1) recognizes the following environment variables:
2030 .PP
2031 \f[B]POSIXLY_CORRECT\f[R]
2032 .PP
2033 : If this variable exists (no matter the contents), bc(1) behaves as if
2034 the \f[B]-s\f[R] option was given.
2035 .PP
2036 \f[B]BC_ENV_ARGS\f[R]
2037 .PP
2038 : This is another way to give command-line arguments to bc(1).
2039 They should be in the same format as all other command-line arguments.
2040 These are always processed first, so any files given in
2041 \f[B]BC_ENV_ARGS\f[R] will be processed before arguments and files given
2042 on the command-line.
2043 This gives the user the ability to set up \[dq]standard\[dq] options and
2044 files to be used at every invocation.
2045 The most useful thing for such files to contain would be useful
2046 functions that the user might want every time bc(1) runs.
2047 .IP
2048 .nf
2049 \f[C]
2050 The code that parses **BC_ENV_ARGS** will correctly handle quoted arguments,
2051 but it does not understand escape sequences. For example, the string
2052 **\[dq]/home/gavin/some bc file.bc\[dq]** will be correctly parsed, but the string
2053 **\[dq]/home/gavin/some \[rs]\[dq]bc\[rs]\[dq] file.bc\[dq]** will include the backslashes.
2054
2055 The quote parsing will handle either kind of quotes, **\[aq]** or **\[dq]**. Thus,
2056 if you have a file with any number of single quotes in the name, you can use
2057 double quotes as the outside quotes, as in **\[dq]some \[aq]bc\[aq] file.bc\[dq]**, and vice
2058 versa if you have a file with double quotes. However, handling a file with
2059 both kinds of quotes in **BC_ENV_ARGS** is not supported due to the
2060 complexity of the parsing, though such files are still supported on the
2061 command-line where the parsing is done by the shell.
2062 \f[R]
2063 .fi
2064 .PP
2065 \f[B]BC_LINE_LENGTH\f[R]
2066 .PP
2067 : If this environment variable exists and contains an integer that is
2068 greater than \f[B]1\f[R] and is less than \f[B]UINT16_MAX\f[R]
2069 (\f[B]2\[ha]16-1\f[R]), bc(1) will output lines to that length,
2070 including the backslash (\f[B]\[rs]\f[R]).
2071 The default line length is \f[B]70\f[R].
2072 .SH EXIT STATUS
2073 .PP
2074 bc(1) returns the following exit statuses:
2075 .PP
2076 \f[B]0\f[R]
2077 .PP
2078 : No error.
2079 .PP
2080 \f[B]1\f[R]
2081 .PP
2082 : A math error occurred.
2083 This follows standard practice of using \f[B]1\f[R] for expected errors,
2084 since math errors will happen in the process of normal execution.
2085 .IP
2086 .nf
2087 \f[C]
2088 Math errors include divide by **0**, taking the square root of a negative
2089 number, using a negative number as a bound for the pseudo-random number
2090 generator, attempting to convert a negative number to a hardware integer,
2091 overflow when converting a number to a hardware integer, and attempting to
2092 use a non-integer where an integer is required.
2093
2094 Converting to a hardware integer happens for the second operand of the power
2095 (**\[rs]\[ha]**), places (**\[rs]\[at]**), left shift (**\[rs]<\[rs]<**), and right shift (**\[rs]>\[rs]>**)
2096 operators and their corresponding assignment operators.
2097 \f[R]
2098 .fi
2099 .PP
2100 \f[B]2\f[R]
2101 .PP
2102 : A parse error occurred.
2103 .IP
2104 .nf
2105 \f[C]
2106 Parse errors include unexpected **EOF**, using an invalid character, failing
2107 to find the end of a string or comment, using a token where it is invalid,
2108 giving an invalid expression, giving an invalid print statement, giving an
2109 invalid function definition, attempting to assign to an expression that is
2110 not a named expression (see the *Named Expressions* subsection of the
2111 **SYNTAX** section), giving an invalid **auto** list, having a duplicate
2112 **auto**/function parameter, failing to find the end of a code block,
2113 attempting to return a value from a **void** function, attempting to use a
2114 variable as a reference, and using any extensions when the option **-s** or
2115 any equivalents were given.
2116 \f[R]
2117 .fi
2118 .PP
2119 \f[B]3\f[R]
2120 .PP
2121 : A runtime error occurred.
2122 .IP
2123 .nf
2124 \f[C]
2125 Runtime errors include assigning an invalid number to **ibase**, **obase**,
2126 or **scale**; give a bad expression to a **read()** call, calling **read()**
2127 inside of a **read()** call, type errors, passing the wrong number of
2128 arguments to functions, attempting to call an undefined function, and
2129 attempting to use a **void** function call as a value in an expression.
2130 \f[R]
2131 .fi
2132 .PP
2133 \f[B]4\f[R]
2134 .PP
2135 : A fatal error occurred.
2136 .IP
2137 .nf
2138 \f[C]
2139 Fatal errors include memory allocation errors, I/O errors, failing to open
2140 files, attempting to use files that do not have only ASCII characters (bc(1)
2141 only accepts ASCII characters), attempting to open a directory as a file,
2142 and giving invalid command-line options.
2143 \f[R]
2144 .fi
2145 .PP
2146 The exit status \f[B]4\f[R] is special; when a fatal error occurs, bc(1)
2147 always exits and returns \f[B]4\f[R], no matter what mode bc(1) is in.
2148 .PP
2149 The other statuses will only be returned when bc(1) is not in
2150 interactive mode (see the \f[B]INTERACTIVE MODE\f[R] section), since
2151 bc(1) resets its state (see the \f[B]RESET\f[R] section) and accepts
2152 more input when one of those errors occurs in interactive mode.
2153 This is also the case when interactive mode is forced by the
2154 \f[B]-i\f[R] flag or \f[B]--interactive\f[R] option.
2155 .PP
2156 These exit statuses allow bc(1) to be used in shell scripting with error
2157 checking, and its normal behavior can be forced by using the
2158 \f[B]-i\f[R] flag or \f[B]--interactive\f[R] option.
2159 .SH INTERACTIVE MODE
2160 .PP
2161 Per the
2162 standard (https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html),
2163 bc(1) has an interactive mode and a non-interactive mode.
2164 Interactive mode is turned on automatically when both \f[B]stdin\f[R]
2165 and \f[B]stdout\f[R] are hooked to a terminal, but the \f[B]-i\f[R] flag
2166 and \f[B]--interactive\f[R] option can turn it on in other cases.
2167 .PP
2168 In interactive mode, bc(1) attempts to recover from errors (see the
2169 \f[B]RESET\f[R] section), and in normal execution, flushes
2170 \f[B]stdout\f[R] as soon as execution is done for the current input.
2171 .SH TTY MODE
2172 .PP
2173 If \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all
2174 connected to a TTY, bc(1) turns on \[dq]TTY mode.\[dq]
2175 .PP
2176 TTY mode is required for history to be enabled (see the \f[B]COMMAND
2177 LINE HISTORY\f[R] section).
2178 It is also required to enable special handling for \f[B]SIGINT\f[R]
2179 signals.
2180 .PP
2181 TTY mode is different from interactive mode because interactive mode is
2182 required in the bc(1)
2183 specification (https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html),
2184 and interactive mode requires only \f[B]stdin\f[R] and \f[B]stdout\f[R]
2185 to be connected to a terminal.
2186 .SH SIGNAL HANDLING
2187 .PP
2188 Sending a \f[B]SIGINT\f[R] will cause bc(1) to stop execution of the
2189 current input.
2190 If bc(1) is in TTY mode (see the \f[B]TTY MODE\f[R] section), it will
2191 reset (see the \f[B]RESET\f[R] section).
2192 Otherwise, it will clean up and exit.
2193 .PP
2194 Note that \[dq]current input\[dq] can mean one of two things.
2195 If bc(1) is processing input from \f[B]stdin\f[R] in TTY mode, it will
2196 ask for more input.
2197 If bc(1) is processing input from a file in TTY mode, it will stop
2198 processing the file and start processing the next file, if one exists,
2199 or ask for input from \f[B]stdin\f[R] if no other file exists.
2200 .PP
2201 This means that if a \f[B]SIGINT\f[R] is sent to bc(1) as it is
2202 executing a file, it can seem as though bc(1) did not respond to the
2203 signal since it will immediately start executing the next file.
2204 This is by design; most files that users execute when interacting with
2205 bc(1) have function definitions, which are quick to parse.
2206 If a file takes a long time to execute, there may be a bug in that file.
2207 The rest of the files could still be executed without problem, allowing
2208 the user to continue.
2209 .PP
2210 \f[B]SIGTERM\f[R] and \f[B]SIGQUIT\f[R] cause bc(1) to clean up and
2211 exit, and it uses the default handler for all other signals.
2212 The one exception is \f[B]SIGHUP\f[R]; in that case, when bc(1) is in
2213 TTY mode, a \f[B]SIGHUP\f[R] will cause bc(1) to clean up and exit.
2214 .SH COMMAND LINE HISTORY
2215 .PP
2216 bc(1) supports interactive command-line editing.
2217 If bc(1) is in TTY mode (see the \f[B]TTY MODE\f[R] section), history is
2218 enabled.
2219 Previous lines can be recalled and edited with the arrow keys.
2220 .PP
2221 \f[B]Note\f[R]: tabs are converted to 8 spaces.
2222 .SH SEE ALSO
2223 .PP
2224 dc(1)
2225 .SH STANDARDS
2226 .PP
2227 bc(1) is compliant with the IEEE Std 1003.1-2017
2228 (\[lq]POSIX.1-2017\[rq]) (https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html)
2229 specification.
2230 The flags \f[B]-efghiqsvVw\f[R], all long options, and the extensions
2231 noted above are extensions to that specification.
2232 .PP
2233 Note that the specification explicitly says that bc(1) only accepts
2234 numbers that use a period (\f[B].\f[R]) as a radix point, regardless of
2235 the value of \f[B]LC_NUMERIC\f[R].
2236 .SH BUGS
2237 .PP
2238 None are known.
2239 Report bugs at https://git.yzena.com/gavin/bc.
2240 .SH AUTHORS
2241 .PP
2242 Gavin D.
2243 Howard <gavin@yzena.com> and contributors.