contrib/bc/manuals/bc/EHN.1

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