contrib/bc/manuals/bc/EHNP.1

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