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