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