contrib/bc/manuals/dc/EN.1

   1 .\"
   2 .\" SPDX-License-Identifier: BSD-2-Clause
   3 .\"
   4 .\" Copyright (c) 2018-2021 Gavin D. Howard and contributors.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions are met:
   8 .\"
   9 .\" * Redistributions of source code must retain the above copyright notice,
  10 .\"   this list of conditions and the following disclaimer.
  11 .\"
  12 .\" * Redistributions in binary form must reproduce the above copyright notice,
  13 .\"   this list of conditions and the following disclaimer in the documentation
  14 .\"   and/or other materials provided with the distribution.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  17 .\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
  20 .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  21 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  22 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  23 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  24 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  25 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  26 .\" POSSIBILITY OF SUCH DAMAGE.
  27 .\"
  28 .TH "DC" "1" "June 2021" "Gavin D. Howard" "General Commands Manual"
  29 .SH Name
  30 .PP
  31 dc - arbitrary-precision decimal reverse-Polish notation calculator
  32 .SH SYNOPSIS
  33 .PP
  34 \f[B]dc\f[R] [\f[B]-hiPRvVx\f[R]] [\f[B]--version\f[R]]
  35 [\f[B]--help\f[R]] [\f[B]--interactive\f[R]] [\f[B]--no-prompt\f[R]]
  36 [\f[B]--no-read-prompt\f[R]] [\f[B]--extended-register\f[R]]
  37 [\f[B]-e\f[R] \f[I]expr\f[R]]
  38 [\f[B]--expression\f[R]=\f[I]expr\f[R]\&...] [\f[B]-f\f[R]
  39 \f[I]file\f[R]\&...] [\f[B]--file\f[R]=\f[I]file\f[R]\&...]
  40 [\f[I]file\f[R]\&...]
  41 .SH DESCRIPTION
  42 .PP
  43 dc(1) is an arbitrary-precision calculator.
  44 It uses a stack (reverse Polish notation) to store numbers and results
  45 of computations.
  46 Arithmetic operations pop arguments off of the stack and push the
  47 results.
  48 .PP
  49 If no files are given on the command-line, then dc(1) reads from
  50 \f[B]stdin\f[R] (see the \f[B]STDIN\f[R] section).
  51 Otherwise, those files are processed, and dc(1) will then exit.
  52 .PP
  53 If a user wants to set up a standard environment, they can use
  54 \f[B]DC_ENV_ARGS\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section).
  55 For example, if a user wants the \f[B]scale\f[R] always set to
  56 \f[B]10\f[R], they can set \f[B]DC_ENV_ARGS\f[R] to \f[B]-e 10k\f[R],
  57 and this dc(1) will always start with a \f[B]scale\f[R] of \f[B]10\f[R].
  58 .SH OPTIONS
  59 .PP
  60 The following are the options that dc(1) accepts.
  61 .TP
  62 \f[B]-h\f[R], \f[B]--help\f[R]
  63 Prints a usage message and quits.
  64 .TP
  65 \f[B]-v\f[R], \f[B]-V\f[R], \f[B]--version\f[R]
  66 Print the version information (copyright header) and exit.
  67 .TP
  68 \f[B]-i\f[R], \f[B]--interactive\f[R]
  69 Forces interactive mode.
  70 (See the \f[B]INTERACTIVE MODE\f[R] section.)
  71 .RS
  72 .PP
  73 This is a \f[B]non-portable extension\f[R].
  74 .RE
  75 .TP
  76 \f[B]-L\f[R], \f[B]--no-line-length\f[R]
  77 Disables line length checking and prints numbers without backslashes and
  78 newlines.
  79 In other words, this option sets \f[B]BC_LINE_LENGTH\f[R] to \f[B]0\f[R]
  80 (see the \f[B]ENVIRONMENT VARIABLES\f[R] section).
  81 .RS
  82 .PP
  83 This is a \f[B]non-portable extension\f[R].
  84 .RE
  85 .TP
  86 \f[B]-P\f[R], \f[B]--no-prompt\f[R]
  87 Disables the prompt in TTY mode.
  88 (The prompt is only enabled in TTY mode.
  89 See the \f[B]TTY MODE\f[R] section.) This is mostly for those users that
  90 do not want a prompt or are not used to having them in dc(1).
  91 Most of those users would want to put this option in
  92 \f[B]DC_ENV_ARGS\f[R].
  93 .RS
  94 .PP
  95 These options override the \f[B]DC_PROMPT\f[R] and \f[B]DC_TTY_MODE\f[R]
  96 environment variables (see the \f[B]ENVIRONMENT VARIABLES\f[R] section).
  97 .PP
  98 This is a \f[B]non-portable extension\f[R].
  99 .RE
 100 .TP
 101 \f[B]-R\f[R], \f[B]--no-read-prompt\f[R]
 102 Disables the read prompt in TTY mode.
 103 (The read prompt is only enabled in TTY mode.
 104 See the \f[B]TTY MODE\f[R] section.) This is mostly for those users that
 105 do not want a read prompt or are not used to having them in dc(1).
 106 Most of those users would want to put this option in
 107 \f[B]BC_ENV_ARGS\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section).
 108 This option is also useful in hash bang lines of dc(1) scripts that
 109 prompt for user input.
 110 .RS
 111 .PP
 112 This option does not disable the regular prompt because the read prompt
 113 is only used when the \f[B]?\f[R] command is used.
 114 .PP
 115 These options \f[I]do\f[R] override the \f[B]DC_PROMPT\f[R] and
 116 \f[B]DC_TTY_MODE\f[R] environment variables (see the \f[B]ENVIRONMENT
 117 VARIABLES\f[R] section), but only for the read prompt.
 118 .PP
 119 This is a \f[B]non-portable extension\f[R].
 120 .RE
 121 .TP
 122 \f[B]-x\f[R] \f[B]--extended-register\f[R]
 123 Enables extended register mode.
 124 See the \f[I]Extended Register Mode\f[R] subsection of the
 125 \f[B]REGISTERS\f[R] section for more information.
 126 .RS
 127 .PP
 128 This is a \f[B]non-portable extension\f[R].
 129 .RE
 130 .TP
 131 \f[B]-z\f[R], \f[B]--leading-zeroes\f[R]
 132 Makes bc(1) print all numbers greater than \f[B]-1\f[R] and less than
 133 \f[B]1\f[R], and not equal to \f[B]0\f[R], with a leading zero.
 134 .RS
 135 .PP
 136 This can be set for individual numbers with the \f[B]plz(x)\f[R],
 137 plznl(x)**, \f[B]pnlz(x)\f[R], and \f[B]pnlznl(x)\f[R] functions in the
 138 extended math library (see the \f[B]LIBRARY\f[R] section).
 139 .PP
 140 This is a \f[B]non-portable extension\f[R].
 141 .RE
 142 .TP
 143 \f[B]-e\f[R] \f[I]expr\f[R], \f[B]--expression\f[R]=\f[I]expr\f[R]
 144 Evaluates \f[I]expr\f[R].
 145 If multiple expressions are given, they are evaluated in order.
 146 If files are given as well (see below), the expressions and files are
 147 evaluated in the order given.
 148 This means that if a file is given before an expression, the file is
 149 read in and evaluated first.
 150 .RS
 151 .PP
 152 If this option is given on the command-line (i.e., not in
 153 \f[B]DC_ENV_ARGS\f[R], see the \f[B]ENVIRONMENT VARIABLES\f[R] section),
 154 then after processing all expressions and files, dc(1) will exit, unless
 155 \f[B]-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to
 156 \f[B]-f\f[R] or \f[B]--file\f[R], whether on the command-line or in
 157 \f[B]DC_ENV_ARGS\f[R].
 158 However, if any other \f[B]-e\f[R], \f[B]--expression\f[R],
 159 \f[B]-f\f[R], or \f[B]--file\f[R] arguments are given after
 160 \f[B]-f-\f[R] or equivalent is given, dc(1) will give a fatal error and
 161 exit.
 162 .PP
 163 This is a \f[B]non-portable extension\f[R].
 164 .RE
 165 .TP
 166 \f[B]-f\f[R] \f[I]file\f[R], \f[B]--file\f[R]=\f[I]file\f[R]
 167 Reads in \f[I]file\f[R] and evaluates it, line by line, as though it
 168 were read through \f[B]stdin\f[R].
 169 If expressions are also given (see above), the expressions are evaluated
 170 in the order given.
 171 .RS
 172 .PP
 173 If this option is given on the command-line (i.e., not in
 174 \f[B]DC_ENV_ARGS\f[R], see the \f[B]ENVIRONMENT VARIABLES\f[R] section),
 175 then after processing all expressions and files, dc(1) will exit, unless
 176 \f[B]-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to
 177 \f[B]-f\f[R] or \f[B]--file\f[R].
 178 However, if any other \f[B]-e\f[R], \f[B]--expression\f[R],
 179 \f[B]-f\f[R], or \f[B]--file\f[R] arguments are given after
 180 \f[B]-f-\f[R] or equivalent is given, dc(1) will give a fatal error and
 181 exit.
 182 .PP
 183 This is a \f[B]non-portable extension\f[R].
 184 .RE
 185 .PP
 186 All long options are \f[B]non-portable extensions\f[R].
 187 .SH STDIN
 188 .PP
 189 If no files are given on the command-line and no files or expressions
 190 are given by the \f[B]-f\f[R], \f[B]--file\f[R], \f[B]-e\f[R], or
 191 \f[B]--expression\f[R] options, then dc(1) read from \f[B]stdin\f[R].
 192 .PP
 193 However, there is a caveat to this.
 194 .PP
 195 First, \f[B]stdin\f[R] is evaluated a line at a time.
 196 The only exception to this is if a string has been finished, but not
 197 ended.
 198 This means that, except for escaped brackets, all brackets must be
 199 balanced before dc(1) parses and executes.
 200 .SH STDOUT
 201 .PP
 202 Any non-error output is written to \f[B]stdout\f[R].
 203 In addition, if history (see the \f[B]HISTORY\f[R] section) and the
 204 prompt (see the \f[B]TTY MODE\f[R] section) are enabled, both are output
 205 to \f[B]stdout\f[R].
 206 .PP
 207 \f[B]Note\f[R]: Unlike other dc(1) implementations, this dc(1) will
 208 issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot
 209 write to \f[B]stdout\f[R], so if \f[B]stdout\f[R] is closed, as in
 210 \f[B]dc >&-\f[R], it will quit with an error.
 211 This is done so that dc(1) can report problems when \f[B]stdout\f[R] is
 212 redirected to a file.
 213 .PP
 214 If there are scripts that depend on the behavior of other dc(1)
 215 implementations, it is recommended that those scripts be changed to
 216 redirect \f[B]stdout\f[R] to \f[B]/dev/null\f[R].
 217 .SH STDERR
 218 .PP
 219 Any error output is written to \f[B]stderr\f[R].
 220 .PP
 221 \f[B]Note\f[R]: Unlike other dc(1) implementations, this dc(1) will
 222 issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot
 223 write to \f[B]stderr\f[R], so if \f[B]stderr\f[R] is closed, as in
 224 \f[B]dc 2>&-\f[R], it will quit with an error.
 225 This is done so that dc(1) can exit with an error code when
 226 \f[B]stderr\f[R] is redirected to a file.
 227 .PP
 228 If there are scripts that depend on the behavior of other dc(1)
 229 implementations, it is recommended that those scripts be changed to
 230 redirect \f[B]stderr\f[R] to \f[B]/dev/null\f[R].
 231 .SH SYNTAX
 232 .PP
 233 Each item in the input source code, either a number (see the
 234 \f[B]NUMBERS\f[R] section) or a command (see the \f[B]COMMANDS\f[R]
 235 section), is processed and executed, in order.
 236 Input is processed immediately when entered.
 237 .PP
 238 \f[B]ibase\f[R] is a register (see the \f[B]REGISTERS\f[R] section) that
 239 determines how to interpret constant numbers.
 240 It is the \[lq]input\[rq] base, or the number base used for interpreting
 241 input numbers.
 242 \f[B]ibase\f[R] is initially \f[B]10\f[R].
 243 The max allowable value for \f[B]ibase\f[R] is \f[B]16\f[R].
 244 The min allowable value for \f[B]ibase\f[R] is \f[B]2\f[R].
 245 The max allowable value for \f[B]ibase\f[R] can be queried in dc(1)
 246 programs with the \f[B]T\f[R] command.
 247 .PP
 248 \f[B]obase\f[R] is a register (see the \f[B]REGISTERS\f[R] section) that
 249 determines how to output results.
 250 It is the \[lq]output\[rq] base, or the number base used for outputting
 251 numbers.
 252 \f[B]obase\f[R] is initially \f[B]10\f[R].
 253 The max allowable value for \f[B]obase\f[R] is \f[B]DC_BASE_MAX\f[R] and
 254 can be queried with the \f[B]U\f[R] command.
 255 The min allowable value for \f[B]obase\f[R] is \f[B]2\f[R].
 256 Values are output in the specified base.
 257 .PP
 258 The \f[I]scale\f[R] of an expression is the number of digits in the
 259 result of the expression right of the decimal point, and \f[B]scale\f[R]
 260 is a register (see the \f[B]REGISTERS\f[R] section) that sets the
 261 precision of any operations (with exceptions).
 262 \f[B]scale\f[R] is initially \f[B]0\f[R].
 263 \f[B]scale\f[R] cannot be negative.
 264 The max allowable value for \f[B]scale\f[R] can be queried in dc(1)
 265 programs with the \f[B]V\f[R] command.
 266 .SS Comments
 267 .PP
 268 Comments go from \f[B]#\f[R] until, and not including, the next newline.
 269 This is a \f[B]non-portable extension\f[R].
 270 .SH NUMBERS
 271 .PP
 272 Numbers are strings made up of digits, uppercase letters up to
 273 \f[B]F\f[R], and at most \f[B]1\f[R] period for a radix.
 274 Numbers can have up to \f[B]DC_NUM_MAX\f[R] digits.
 275 Uppercase letters are equal to \f[B]9\f[R] + their position in the
 276 alphabet (i.e., \f[B]A\f[R] equals \f[B]10\f[R], or \f[B]9+1\f[R]).
 277 If a digit or letter makes no sense with the current value of
 278 \f[B]ibase\f[R], they are set to the value of the highest valid digit in
 279 \f[B]ibase\f[R].
 280 .PP
 281 Single-character numbers (i.e., \f[B]A\f[R] alone) take the value that
 282 they would have if they were valid digits, regardless of the value of
 283 \f[B]ibase\f[R].
 284 This means that \f[B]A\f[R] alone always equals decimal \f[B]10\f[R] and
 285 \f[B]F\f[R] alone always equals decimal \f[B]15\f[R].
 286 .SH COMMANDS
 287 .PP
 288 The valid commands are listed below.
 289 .SS Printing
 290 .PP
 291 These commands are used for printing.
 292 .TP
 293 \f[B]p\f[R]
 294 Prints the value on top of the stack, whether number or string, and
 295 prints a newline after.
 296 .RS
 297 .PP
 298 This does not alter the stack.
 299 .RE
 300 .TP
 301 \f[B]n\f[R]
 302 Prints the value on top of the stack, whether number or string, and pops
 303 it off of the stack.
 304 .TP
 305 \f[B]P\f[R]
 306 Pops a value off the stack.
 307 .RS
 308 .PP
 309 If the value is a number, it is truncated and the absolute value of the
 310 result is printed as though \f[B]obase\f[R] is \f[B]256\f[R] and each
 311 digit is interpreted as an 8-bit ASCII character, making it a byte
 312 stream.
 313 .PP
 314 If the value is a string, it is printed without a trailing newline.
 315 .PP
 316 This is a \f[B]non-portable extension\f[R].
 317 .RE
 318 .TP
 319 \f[B]f\f[R]
 320 Prints the entire contents of the stack, in order from newest to oldest,
 321 without altering anything.
 322 .RS
 323 .PP
 324 Users should use this command when they get lost.
 325 .RE
 326 .SS Arithmetic
 327 .PP
 328 These are the commands used for arithmetic.
 329 .TP
 330 \f[B]+\f[R]
 331 The top two values are popped off the stack, added, and the result is
 332 pushed onto the stack.
 333 The \f[I]scale\f[R] of the result is equal to the max \f[I]scale\f[R] of
 334 both operands.
 335 .TP
 336 \f[B]-\f[R]
 337 The top two values are popped off the stack, subtracted, and the result
 338 is pushed onto the stack.
 339 The \f[I]scale\f[R] of the result is equal to the max \f[I]scale\f[R] of
 340 both operands.
 341 .TP
 342 \f[B]*\f[R]
 343 The top two values are popped off the stack, multiplied, and the result
 344 is pushed onto the stack.
 345 If \f[B]a\f[R] is the \f[I]scale\f[R] of the first expression and
 346 \f[B]b\f[R] is the \f[I]scale\f[R] of the second expression, the
 347 \f[I]scale\f[R] of the result is equal to
 348 \f[B]min(a+b,max(scale,a,b))\f[R] where \f[B]min()\f[R] and
 349 \f[B]max()\f[R] return the obvious values.
 350 .TP
 351 \f[B]/\f[R]
 352 The top two values are popped off the stack, divided, and the result is
 353 pushed onto the stack.
 354 The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R].
 355 .RS
 356 .PP
 357 The first value popped off of the stack must be non-zero.
 358 .RE
 359 .TP
 360 \f[B]%\f[R]
 361 The top two values are popped off the stack, remaindered, and the result
 362 is pushed onto the stack.
 363 .RS
 364 .PP
 365 Remaindering is equivalent to 1) Computing \f[B]a/b\f[R] to current
 366 \f[B]scale\f[R], and 2) Using the result of step 1 to calculate
 367 \f[B]a-(a/b)*b\f[R] to \f[I]scale\f[R]
 368 \f[B]max(scale+scale(b),scale(a))\f[R].
 369 .PP
 370 The first value popped off of the stack must be non-zero.
 371 .RE
 372 .TP
 373 \f[B]\[ti]\f[R]
 374 The top two values are popped off the stack, divided and remaindered,
 375 and the results (divided first, remainder second) are pushed onto the
 376 stack.
 377 This is equivalent to \f[B]x y / x y %\f[R] except that \f[B]x\f[R] and
 378 \f[B]y\f[R] are only evaluated once.
 379 .RS
 380 .PP
 381 The first value popped off of the stack must be non-zero.
 382 .PP
 383 This is a \f[B]non-portable extension\f[R].
 384 .RE
 385 .TP
 386 \f[B]\[ha]\f[R]
 387 The top two values are popped off the stack, the second is raised to the
 388 power of the first, and the result is pushed onto the stack.
 389 The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R].
 390 .RS
 391 .PP
 392 The first value popped off of the stack must be an integer, and if that
 393 value is negative, the second value popped off of the stack must be
 394 non-zero.
 395 .RE
 396 .TP
 397 \f[B]v\f[R]
 398 The top value is popped off the stack, its square root is computed, and
 399 the result is pushed onto the stack.
 400 The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R].
 401 .RS
 402 .PP
 403 The value popped off of the stack must be non-negative.
 404 .RE
 405 .TP
 406 \f[B]_\f[R]
 407 If this command \f[I]immediately\f[R] precedes a number (i.e., no spaces
 408 or other commands), then that number is input as a negative number.
 409 .RS
 410 .PP
 411 Otherwise, the top value on the stack is popped and copied, and the copy
 412 is negated and pushed onto the stack.
 413 This behavior without a number is a \f[B]non-portable extension\f[R].
 414 .RE
 415 .TP
 416 \f[B]b\f[R]
 417 The top value is popped off the stack, and if it is zero, it is pushed
 418 back onto the stack.
 419 Otherwise, its absolute value is pushed onto the stack.
 420 .RS
 421 .PP
 422 This is a \f[B]non-portable extension\f[R].
 423 .RE
 424 .TP
 425 \f[B]|\f[R]
 426 The top three values are popped off the stack, a modular exponentiation
 427 is computed, and the result is pushed onto the stack.
 428 .RS
 429 .PP
 430 The first value popped is used as the reduction modulus and must be an
 431 integer and non-zero.
 432 The second value popped is used as the exponent and must be an integer
 433 and non-negative.
 434 The third value popped is the base and must be an integer.
 435 .PP
 436 This is a \f[B]non-portable extension\f[R].
 437 .RE
 438 .TP
 439 \f[B]G\f[R]
 440 The top two values are popped off of the stack, they are compared, and a
 441 \f[B]1\f[R] is pushed if they are equal, or \f[B]0\f[R] otherwise.
 442 .RS
 443 .PP
 444 This is a \f[B]non-portable extension\f[R].
 445 .RE
 446 .TP
 447 \f[B]N\f[R]
 448 The top value is popped off of the stack, and if it a \f[B]0\f[R], a
 449 \f[B]1\f[R] is pushed; otherwise, a \f[B]0\f[R] is pushed.
 450 .RS
 451 .PP
 452 This is a \f[B]non-portable extension\f[R].
 453 .RE
 454 .TP
 455 \f[B](\f[R]
 456 The top two values are popped off of the stack, they are compared, and a
 457 \f[B]1\f[R] is pushed if the first is less than the second, or
 458 \f[B]0\f[R] otherwise.
 459 .RS
 460 .PP
 461 This is a \f[B]non-portable extension\f[R].
 462 .RE
 463 .TP
 464 \f[B]{\f[R]
 465 The top two values are popped off of the stack, they are compared, and a
 466 \f[B]1\f[R] is pushed if the first is less than or equal to the second,
 467 or \f[B]0\f[R] otherwise.
 468 .RS
 469 .PP
 470 This is a \f[B]non-portable extension\f[R].
 471 .RE
 472 .TP
 473 \f[B])\f[R]
 474 The top two values are popped off of the stack, they are compared, and a
 475 \f[B]1\f[R] is pushed if the first is greater than the second, or
 476 \f[B]0\f[R] otherwise.
 477 .RS
 478 .PP
 479 This is a \f[B]non-portable extension\f[R].
 480 .RE
 481 .TP
 482 \f[B]}\f[R]
 483 The top two values are popped off of the stack, they are compared, and a
 484 \f[B]1\f[R] is pushed if the first is greater than or equal to the
 485 second, or \f[B]0\f[R] otherwise.
 486 .RS
 487 .PP
 488 This is a \f[B]non-portable extension\f[R].
 489 .RE
 490 .TP
 491 \f[B]M\f[R]
 492 The top two values are popped off of the stack.
 493 If they are both non-zero, a \f[B]1\f[R] is pushed onto the stack.
 494 If either of them is zero, or both of them are, then a \f[B]0\f[R] is
 495 pushed onto the stack.
 496 .RS
 497 .PP
 498 This is like the \f[B]&&\f[R] operator in bc(1), and it is \f[I]not\f[R]
 499 a short-circuit operator.
 500 .PP
 501 This is a \f[B]non-portable extension\f[R].
 502 .RE
 503 .TP
 504 \f[B]m\f[R]
 505 The top two values are popped off of the stack.
 506 If at least one of them is non-zero, a \f[B]1\f[R] is pushed onto the
 507 stack.
 508 If both of them are zero, then a \f[B]0\f[R] is pushed onto the stack.
 509 .RS
 510 .PP
 511 This is like the \f[B]||\f[R] operator in bc(1), and it is \f[I]not\f[R]
 512 a short-circuit operator.
 513 .PP
 514 This is a \f[B]non-portable extension\f[R].
 515 .RE
 516 .SS Stack Control
 517 .PP
 518 These commands control the stack.
 519 .TP
 520 \f[B]c\f[R]
 521 Removes all items from (\[lq]clears\[rq]) the stack.
 522 .TP
 523 \f[B]d\f[R]
 524 Copies the item on top of the stack (\[lq]duplicates\[rq]) and pushes
 525 the copy onto the stack.
 526 .TP
 527 \f[B]r\f[R]
 528 Swaps (\[lq]reverses\[rq]) the two top items on the stack.
 529 .TP
 530 \f[B]R\f[R]
 531 Pops (\[lq]removes\[rq]) the top value from the stack.
 532 .SS Register Control
 533 .PP
 534 These commands control registers (see the \f[B]REGISTERS\f[R] section).
 535 .TP
 536 \f[B]s\f[R]\f[I]r\f[R]
 537 Pops the value off the top of the stack and stores it into register
 538 \f[I]r\f[R].
 539 .TP
 540 \f[B]l\f[R]\f[I]r\f[R]
 541 Copies the value in register \f[I]r\f[R] and pushes it onto the stack.
 542 This does not alter the contents of \f[I]r\f[R].
 543 .TP
 544 \f[B]S\f[R]\f[I]r\f[R]
 545 Pops the value off the top of the (main) stack and pushes it onto the
 546 stack of register \f[I]r\f[R].
 547 The previous value of the register becomes inaccessible.
 548 .TP
 549 \f[B]L\f[R]\f[I]r\f[R]
 550 Pops the value off the top of the stack for register \f[I]r\f[R] and
 551 push it onto the main stack.
 552 The previous value in the stack for register \f[I]r\f[R], if any, is now
 553 accessible via the \f[B]l\f[R]\f[I]r\f[R] command.
 554 .SS Parameters
 555 .PP
 556 These commands control the values of \f[B]ibase\f[R], \f[B]obase\f[R],
 557 and \f[B]scale\f[R].
 558 Also see the \f[B]SYNTAX\f[R] section.
 559 .TP
 560 \f[B]i\f[R]
 561 Pops the value off of the top of the stack and uses it to set
 562 \f[B]ibase\f[R], which must be between \f[B]2\f[R] and \f[B]16\f[R],
 563 inclusive.
 564 .RS
 565 .PP
 566 If the value on top of the stack has any \f[I]scale\f[R], the
 567 \f[I]scale\f[R] is ignored.
 568 .RE
 569 .TP
 570 \f[B]o\f[R]
 571 Pops the value off of the top of the stack and uses it to set
 572 \f[B]obase\f[R], which must be between \f[B]2\f[R] and
 573 \f[B]DC_BASE_MAX\f[R], inclusive (see the \f[B]LIMITS\f[R] section).
 574 .RS
 575 .PP
 576 If the value on top of the stack has any \f[I]scale\f[R], the
 577 \f[I]scale\f[R] is ignored.
 578 .RE
 579 .TP
 580 \f[B]k\f[R]
 581 Pops the value off of the top of the stack and uses it to set
 582 \f[B]scale\f[R], which must be non-negative.
 583 .RS
 584 .PP
 585 If the value on top of the stack has any \f[I]scale\f[R], the
 586 \f[I]scale\f[R] is ignored.
 587 .RE
 588 .TP
 589 \f[B]I\f[R]
 590 Pushes the current value of \f[B]ibase\f[R] onto the main stack.
 591 .TP
 592 \f[B]O\f[R]
 593 Pushes the current value of \f[B]obase\f[R] onto the main stack.
 594 .TP
 595 \f[B]K\f[R]
 596 Pushes the current value of \f[B]scale\f[R] onto the main stack.
 597 .TP
 598 \f[B]T\f[R]
 599 Pushes the maximum allowable value of \f[B]ibase\f[R] onto the main
 600 stack.
 601 .RS
 602 .PP
 603 This is a \f[B]non-portable extension\f[R].
 604 .RE
 605 .TP
 606 \f[B]U\f[R]
 607 Pushes the maximum allowable value of \f[B]obase\f[R] onto the main
 608 stack.
 609 .RS
 610 .PP
 611 This is a \f[B]non-portable extension\f[R].
 612 .RE
 613 .TP
 614 \f[B]V\f[R]
 615 Pushes the maximum allowable value of \f[B]scale\f[R] onto the main
 616 stack.
 617 .RS
 618 .PP
 619 This is a \f[B]non-portable extension\f[R].
 620 .RE
 621 .SS Strings
 622 .PP
 623 The following commands control strings.
 624 .PP
 625 dc(1) can work with both numbers and strings, and registers (see the
 626 \f[B]REGISTERS\f[R] section) can hold both strings and numbers.
 627 dc(1) always knows whether the contents of a register are a string or a
 628 number.
 629 .PP
 630 While arithmetic operations have to have numbers, and will print an
 631 error if given a string, other commands accept strings.
 632 .PP
 633 Strings can also be executed as macros.
 634 For example, if the string \f[B][1pR]\f[R] is executed as a macro, then
 635 the code \f[B]1pR\f[R] is executed, meaning that the \f[B]1\f[R] will be
 636 printed with a newline after and then popped from the stack.
 637 .TP
 638 \f[B][\f[R]\f[I]characters\f[R]\f[B]]\f[R]
 639 Makes a string containing \f[I]characters\f[R] and pushes it onto the
 640 stack.
 641 .RS
 642 .PP
 643 If there are brackets (\f[B][\f[R] and \f[B]]\f[R]) in the string, then
 644 they must be balanced.
 645 Unbalanced brackets can be escaped using a backslash (\f[B]\[rs]\f[R])
 646 character.
 647 .PP
 648 If there is a backslash character in the string, the character after it
 649 (even another backslash) is put into the string verbatim, but the
 650 (first) backslash is not.
 651 .RE
 652 .TP
 653 \f[B]a\f[R]
 654 The value on top of the stack is popped.
 655 .RS
 656 .PP
 657 If it is a number, it is truncated and its absolute value is taken.
 658 The result mod \f[B]256\f[R] is calculated.
 659 If that result is \f[B]0\f[R], push an empty string; otherwise, push a
 660 one-character string where the character is the result of the mod
 661 interpreted as an ASCII character.
 662 .PP
 663 If it is a string, then a new string is made.
 664 If the original string is empty, the new string is empty.
 665 If it is not, then the first character of the original string is used to
 666 create the new string as a one-character string.
 667 The new string is then pushed onto the stack.
 668 .PP
 669 This is a \f[B]non-portable extension\f[R].
 670 .RE
 671 .TP
 672 \f[B]x\f[R]
 673 Pops a value off of the top of the stack.
 674 .RS
 675 .PP
 676 If it is a number, it is pushed back onto the stack.
 677 .PP
 678 If it is a string, it is executed as a macro.
 679 .PP
 680 This behavior is the norm whenever a macro is executed, whether by this
 681 command or by the conditional execution commands below.
 682 .RE
 683 .TP
 684 \f[B]>\f[R]\f[I]r\f[R]
 685 Pops two values off of the stack that must be numbers and compares them.
 686 If the first value is greater than the second, then the contents of
 687 register \f[I]r\f[R] are executed.
 688 .RS
 689 .PP
 690 For example, \f[B]0 1>a\f[R] will execute the contents of register
 691 \f[B]a\f[R], and \f[B]1 0>a\f[R] will not.
 692 .PP
 693 If either or both of the values are not numbers, dc(1) will raise an
 694 error and reset (see the \f[B]RESET\f[R] section).
 695 .RE
 696 .TP
 697 \f[B]>\f[R]\f[I]r\f[R]\f[B]e\f[R]\f[I]s\f[R]
 698 Like the above, but will execute register \f[I]s\f[R] if the comparison
 699 fails.
 700 .RS
 701 .PP
 702 If either or both of the values are not numbers, dc(1) will raise an
 703 error and reset (see the \f[B]RESET\f[R] section).
 704 .PP
 705 This is a \f[B]non-portable extension\f[R].
 706 .RE
 707 .TP
 708 \f[B]!>\f[R]\f[I]r\f[R]
 709 Pops two values off of the stack that must be numbers and compares them.
 710 If the first value is not greater than the second (less than or equal
 711 to), then the contents of register \f[I]r\f[R] are executed.
 712 .RS
 713 .PP
 714 If either or both of the values are not numbers, dc(1) will raise an
 715 error and reset (see the \f[B]RESET\f[R] section).
 716 .RE
 717 .TP
 718 \f[B]!>\f[R]\f[I]r\f[R]\f[B]e\f[R]\f[I]s\f[R]
 719 Like the above, but will execute register \f[I]s\f[R] if the comparison
 720 fails.
 721 .RS
 722 .PP
 723 If either or both of the values are not numbers, dc(1) will raise an
 724 error and reset (see the \f[B]RESET\f[R] section).
 725 .PP
 726 This is a \f[B]non-portable extension\f[R].
 727 .RE
 728 .TP
 729 \f[B]<\f[R]\f[I]r\f[R]
 730 Pops two values off of the stack that must be numbers and compares them.
 731 If the first value is less than the second, then the contents of
 732 register \f[I]r\f[R] are executed.
 733 .RS
 734 .PP
 735 If either or both of the values are not numbers, dc(1) will raise an
 736 error and reset (see the \f[B]RESET\f[R] section).
 737 .RE
 738 .TP
 739 \f[B]<\f[R]\f[I]r\f[R]\f[B]e\f[R]\f[I]s\f[R]
 740 Like the above, but will execute register \f[I]s\f[R] if the comparison
 741 fails.
 742 .RS
 743 .PP
 744 If either or both of the values are not numbers, dc(1) will raise an
 745 error and reset (see the \f[B]RESET\f[R] section).
 746 .PP
 747 This is a \f[B]non-portable extension\f[R].
 748 .RE
 749 .TP
 750 \f[B]!<\f[R]\f[I]r\f[R]
 751 Pops two values off of the stack that must be numbers and compares them.
 752 If the first value is not less than the second (greater than or equal
 753 to), then the contents of register \f[I]r\f[R] are executed.
 754 .RS
 755 .PP
 756 If either or both of the values are not numbers, dc(1) will raise an
 757 error and reset (see the \f[B]RESET\f[R] section).
 758 .RE
 759 .TP
 760 \f[B]!<\f[R]\f[I]r\f[R]\f[B]e\f[R]\f[I]s\f[R]
 761 Like the above, but will execute register \f[I]s\f[R] if the comparison
 762 fails.
 763 .RS
 764 .PP
 765 If either or both of the values are not numbers, dc(1) will raise an
 766 error and reset (see the \f[B]RESET\f[R] section).
 767 .PP
 768 This is a \f[B]non-portable extension\f[R].
 769 .RE
 770 .TP
 771 \f[B]=\f[R]\f[I]r\f[R]
 772 Pops two values off of the stack that must be numbers and compares them.
 773 If the first value is equal to the second, then the contents of register
 774 \f[I]r\f[R] are executed.
 775 .RS
 776 .PP
 777 If either or both of the values are not numbers, dc(1) will raise an
 778 error and reset (see the \f[B]RESET\f[R] section).
 779 .RE
 780 .TP
 781 \f[B]=\f[R]\f[I]r\f[R]\f[B]e\f[R]\f[I]s\f[R]
 782 Like the above, but will execute register \f[I]s\f[R] if the comparison
 783 fails.
 784 .RS
 785 .PP
 786 If either or both of the values are not numbers, dc(1) will raise an
 787 error and reset (see the \f[B]RESET\f[R] section).
 788 .PP
 789 This is a \f[B]non-portable extension\f[R].
 790 .RE
 791 .TP
 792 \f[B]!=\f[R]\f[I]r\f[R]
 793 Pops two values off of the stack that must be numbers and compares them.
 794 If the first value is not equal to the second, then the contents of
 795 register \f[I]r\f[R] are executed.
 796 .RS
 797 .PP
 798 If either or both of the values are not numbers, dc(1) will raise an
 799 error and reset (see the \f[B]RESET\f[R] section).
 800 .RE
 801 .TP
 802 \f[B]!=\f[R]\f[I]r\f[R]\f[B]e\f[R]\f[I]s\f[R]
 803 Like the above, but will execute register \f[I]s\f[R] if the comparison
 804 fails.
 805 .RS
 806 .PP
 807 If either or both of the values are not numbers, dc(1) will raise an
 808 error and reset (see the \f[B]RESET\f[R] section).
 809 .PP
 810 This is a \f[B]non-portable extension\f[R].
 811 .RE
 812 .TP
 813 \f[B]?\f[R]
 814 Reads a line from the \f[B]stdin\f[R] and executes it.
 815 This is to allow macros to request input from users.
 816 .TP
 817 \f[B]q\f[R]
 818 During execution of a macro, this exits the execution of that macro and
 819 the execution of the macro that executed it.
 820 If there are no macros, or only one macro executing, dc(1) exits.
 821 .TP
 822 \f[B]Q\f[R]
 823 Pops a value from the stack which must be non-negative and is used the
 824 number of macro executions to pop off of the execution stack.
 825 If the number of levels to pop is greater than the number of executing
 826 macros, dc(1) exits.
 827 .TP
 828 \f[B],\f[R]
 829 Pushes the depth of the execution stack onto the stack.
 830 The execution stack is the stack of string executions.
 831 The number that is pushed onto the stack is exactly as many as is needed
 832 to make dc(1) exit with the \f[B]Q\f[R] command, so the sequence
 833 \f[B],Q\f[R] will make dc(1) exit.
 834 .SS Status
 835 .PP
 836 These commands query status of the stack or its top value.
 837 .TP
 838 \f[B]Z\f[R]
 839 Pops a value off of the stack.
 840 .RS
 841 .PP
 842 If it is a number, calculates the number of significant decimal digits
 843 it has and pushes the result.
 844 It will push \f[B]1\f[R] if the argument is \f[B]0\f[R] with no decimal
 845 places.
 846 .PP
 847 If it is a string, pushes the number of characters the string has.
 848 .RE
 849 .TP
 850 \f[B]X\f[R]
 851 Pops a value off of the stack.
 852 .RS
 853 .PP
 854 If it is a number, pushes the \f[I]scale\f[R] of the value onto the
 855 stack.
 856 .PP
 857 If it is a string, pushes \f[B]0\f[R].
 858 .RE
 859 .TP
 860 \f[B]z\f[R]
 861 Pushes the current depth of the stack (before execution of this command)
 862 onto the stack.
 863 .TP
 864 \f[B]y\f[R]\f[I]r\f[R]
 865 Pushes the current stack depth of the register \f[I]r\f[R] onto the main
 866 stack.
 867 .RS
 868 .PP
 869 Because each register has a depth of \f[B]1\f[R] (with the value
 870 \f[B]0\f[R] in the top item) when dc(1) starts, dc(1) requires that each
 871 register\[cq]s stack must always have at least one item; dc(1) will give
 872 an error and reset otherwise (see the \f[B]RESET\f[R] section).
 873 This means that this command will never push \f[B]0\f[R].
 874 .PP
 875 This is a \f[B]non-portable extension\f[R].
 876 .RE
 877 .SS Arrays
 878 .PP
 879 These commands manipulate arrays.
 880 .TP
 881 \f[B]:\f[R]\f[I]r\f[R]
 882 Pops the top two values off of the stack.
 883 The second value will be stored in the array \f[I]r\f[R] (see the
 884 \f[B]REGISTERS\f[R] section), indexed by the first value.
 885 .TP
 886 \f[B];\f[R]\f[I]r\f[R]
 887 Pops the value on top of the stack and uses it as an index into the
 888 array \f[I]r\f[R].
 889 The selected value is then pushed onto the stack.
 890 .TP
 891 \f[B]Y\f[R]\f[I]r\f[R]
 892 Pushes the length of the array \f[I]r\f[R] onto the stack.
 893 .RS
 894 .PP
 895 This is a \f[B]non-portable extension\f[R].
 896 .RE
 897 .SS Global Settings
 898 .PP
 899 These commands retrieve global settings.
 900 These are the only commands that require multiple specific characters,
 901 and all of them begin with the letter \f[B]g\f[R].
 902 Only the characters below are allowed after the character \f[B]g\f[R];
 903 any other character produces a parse error (see the \f[B]ERRORS\f[R]
 904 section).
 905 .TP
 906 \f[B]gl\f[R]
 907 Pushes the line length set by \f[B]DC_LINE_LENGTH\f[R] (see the
 908 \f[B]ENVIRONMENT VARIABLES\f[R] section) onto the stack.
 909 .TP
 910 \f[B]gz\f[R]
 911 Pushes \f[B]0\f[R] onto the stack if the leading zero setting has not
 912 been enabled with the \f[B]-z\f[R] or \f[B]--leading-zeroes\f[R] options
 913 (see the \f[B]OPTIONS\f[R] section), non-zero otherwise.
 914 .SH REGISTERS
 915 .PP
 916 Registers are names that can store strings, numbers, and arrays.
 917 (Number/string registers do not interfere with array registers.)
 918 .PP
 919 Each register is also its own stack, so the current register value is
 920 the top of the stack for the register.
 921 All registers, when first referenced, have one value (\f[B]0\f[R]) in
 922 their stack, and it is a runtime error to attempt to pop that item off
 923 of the register stack.
 924 .PP
 925 In non-extended register mode, a register name is just the single
 926 character that follows any command that needs a register name.
 927 The only exceptions are: a newline (\f[B]`\[rs]n'\f[R]) and a left
 928 bracket (\f[B]`['\f[R]); it is a parse error for a newline or a left
 929 bracket to be used as a register name.
 930 .SS Extended Register Mode
 931 .PP
 932 Unlike most other dc(1) implentations, this dc(1) provides nearly
 933 unlimited amounts of registers, if extended register mode is enabled.
 934 .PP
 935 If extended register mode is enabled (\f[B]-x\f[R] or
 936 \f[B]--extended-register\f[R] command-line arguments are given), then
 937 normal single character registers are used \f[I]unless\f[R] the
 938 character immediately following a command that needs a register name is
 939 a space (according to \f[B]isspace()\f[R]) and not a newline
 940 (\f[B]`\[rs]n'\f[R]).
 941 .PP
 942 In that case, the register name is found according to the regex
 943 \f[B][a-z][a-z0-9_]*\f[R] (like bc(1) identifiers), and it is a parse
 944 error if the next non-space characters do not match that regex.
 945 .SH RESET
 946 .PP
 947 When dc(1) encounters an error or a signal that it has a non-default
 948 handler for, it resets.
 949 This means that several things happen.
 950 .PP
 951 First, any macros that are executing are stopped and popped off the
 952 stack.
 953 The behavior is not unlike that of exceptions in programming languages.
 954 Then the execution point is set so that any code waiting to execute
 955 (after all macros returned) is skipped.
 956 .PP
 957 Thus, when dc(1) resets, it skips any remaining code waiting to be
 958 executed.
 959 Then, if it is interactive mode, and the error was not a fatal error
 960 (see the \f[B]EXIT STATUS\f[R] section), it asks for more input;
 961 otherwise, it exits with the appropriate return code.
 962 .SH PERFORMANCE
 963 .PP
 964 Most dc(1) implementations use \f[B]char\f[R] types to calculate the
 965 value of \f[B]1\f[R] decimal digit at a time, but that can be slow.
 966 This dc(1) does something different.
 967 .PP
 968 It uses large integers to calculate more than \f[B]1\f[R] decimal digit
 969 at a time.
 970 If built in a environment where \f[B]DC_LONG_BIT\f[R] (see the
 971 \f[B]LIMITS\f[R] section) is \f[B]64\f[R], then each integer has
 972 \f[B]9\f[R] decimal digits.
 973 If built in an environment where \f[B]DC_LONG_BIT\f[R] is \f[B]32\f[R]
 974 then each integer has \f[B]4\f[R] decimal digits.
 975 This value (the number of decimal digits per large integer) is called
 976 \f[B]DC_BASE_DIGS\f[R].
 977 .PP
 978 In addition, this dc(1) uses an even larger integer for overflow
 979 checking.
 980 This integer type depends on the value of \f[B]DC_LONG_BIT\f[R], but is
 981 always at least twice as large as the integer type used to store digits.
 982 .SH LIMITS
 983 .PP
 984 The following are the limits on dc(1):
 985 .TP
 986 \f[B]DC_LONG_BIT\f[R]
 987 The number of bits in the \f[B]long\f[R] type in the environment where
 988 dc(1) was built.
 989 This determines how many decimal digits can be stored in a single large
 990 integer (see the \f[B]PERFORMANCE\f[R] section).
 991 .TP
 992 \f[B]DC_BASE_DIGS\f[R]
 993 The number of decimal digits per large integer (see the
 994 \f[B]PERFORMANCE\f[R] section).
 995 Depends on \f[B]DC_LONG_BIT\f[R].
 996 .TP
 997 \f[B]DC_BASE_POW\f[R]
 998 The max decimal number that each large integer can store (see
 999 \f[B]DC_BASE_DIGS\f[R]) plus \f[B]1\f[R].
1000 Depends on \f[B]DC_BASE_DIGS\f[R].
1001 .TP
1002 \f[B]DC_OVERFLOW_MAX\f[R]
1003 The max number that the overflow type (see the \f[B]PERFORMANCE\f[R]
1004 section) can hold.
1005 Depends on \f[B]DC_LONG_BIT\f[R].
1006 .TP
1007 \f[B]DC_BASE_MAX\f[R]
1008 The maximum output base.
1009 Set at \f[B]DC_BASE_POW\f[R].
1010 .TP
1011 \f[B]DC_DIM_MAX\f[R]
1012 The maximum size of arrays.
1013 Set at \f[B]SIZE_MAX-1\f[R].
1014 .TP
1015 \f[B]DC_SCALE_MAX\f[R]
1016 The maximum \f[B]scale\f[R].
1017 Set at \f[B]DC_OVERFLOW_MAX-1\f[R].
1018 .TP
1019 \f[B]DC_STRING_MAX\f[R]
1020 The maximum length of strings.
1021 Set at \f[B]DC_OVERFLOW_MAX-1\f[R].
1022 .TP
1023 \f[B]DC_NAME_MAX\f[R]
1024 The maximum length of identifiers.
1025 Set at \f[B]DC_OVERFLOW_MAX-1\f[R].
1026 .TP
1027 \f[B]DC_NUM_MAX\f[R]
1028 The maximum length of a number (in decimal digits), which includes
1029 digits after the decimal point.
1030 Set at \f[B]DC_OVERFLOW_MAX-1\f[R].
1031 .TP
1032 Exponent
1033 The maximum allowable exponent (positive or negative).
1034 Set at \f[B]DC_OVERFLOW_MAX\f[R].
1035 .TP
1036 Number of vars
1037 The maximum number of vars/arrays.
1038 Set at \f[B]SIZE_MAX-1\f[R].
1039 .PP
1040 These limits are meant to be effectively non-existent; the limits are so
1041 large (at least on 64-bit machines) that there should not be any point
1042 at which they become a problem.
1043 In fact, memory should be exhausted before these limits should be hit.
1044 .SH ENVIRONMENT VARIABLES
1045 .PP
1046 dc(1) recognizes the following environment variables:
1047 .TP
1048 \f[B]DC_ENV_ARGS\f[R]
1049 This is another way to give command-line arguments to dc(1).
1050 They should be in the same format as all other command-line arguments.
1051 These are always processed first, so any files given in
1052 \f[B]DC_ENV_ARGS\f[R] will be processed before arguments and files given
1053 on the command-line.
1054 This gives the user the ability to set up \[lq]standard\[rq] options and
1055 files to be used at every invocation.
1056 The most useful thing for such files to contain would be useful
1057 functions that the user might want every time dc(1) runs.
1058 Another use would be to use the \f[B]-e\f[R] option to set
1059 \f[B]scale\f[R] to a value other than \f[B]0\f[R].
1060 .RS
1061 .PP
1062 The code that parses \f[B]DC_ENV_ARGS\f[R] will correctly handle quoted
1063 arguments, but it does not understand escape sequences.
1064 For example, the string \f[B]\[lq]/home/gavin/some dc file.dc\[rq]\f[R]
1065 will be correctly parsed, but the string \f[B]\[lq]/home/gavin/some
1066 \[dq]dc\[dq] file.dc\[rq]\f[R] will include the backslashes.
1067 .PP
1068 The quote parsing will handle either kind of quotes, \f[B]\[cq]\f[R] or
1069 \f[B]\[lq]\f[R].
1070 Thus, if you have a file with any number of single quotes in the name,
1071 you can use double quotes as the outside quotes, as in \f[B]\[lq]some
1072 `dc' file.dc\[rq]\f[R], and vice versa if you have a file with double
1073 quotes.
1074 However, handling a file with both kinds of quotes in
1075 \f[B]DC_ENV_ARGS\f[R] is not supported due to the complexity of the
1076 parsing, though such files are still supported on the command-line where
1077 the parsing is done by the shell.
1078 .RE
1079 .TP
1080 \f[B]DC_LINE_LENGTH\f[R]
1081 If this environment variable exists and contains an integer that is
1082 greater than \f[B]1\f[R] and is less than \f[B]UINT16_MAX\f[R]
1083 (\f[B]2\[ha]16-1\f[R]), dc(1) will output lines to that length,
1084 including the backslash newline combo.
1085 The default line length is \f[B]70\f[R].
1086 .RS
1087 .PP
1088 The special value of \f[B]0\f[R] will disable line length checking and
1089 print numbers without regard to line length and without backslashes and
1090 newlines.
1091 .RE
1092 .TP
1093 \f[B]DC_SIGINT_RESET\f[R]
1094 If dc(1) is not in interactive mode (see the \f[B]INTERACTIVE MODE\f[R]
1095 section), then this environment variable has no effect because dc(1)
1096 exits on \f[B]SIGINT\f[R] when not in interactive mode.
1097 .RS
1098 .PP
1099 However, when dc(1) is in interactive mode, then if this environment
1100 variable exists and contains an integer, a non-zero value makes dc(1)
1101 reset on \f[B]SIGINT\f[R], rather than exit, and zero makes dc(1) exit.
1102 If this environment variable exists and is \f[I]not\f[R] an integer,
1103 then dc(1) will exit on \f[B]SIGINT\f[R].
1104 .PP
1105 This environment variable overrides the default, which can be queried
1106 with the \f[B]-h\f[R] or \f[B]--help\f[R] options.
1107 .RE
1108 .TP
1109 \f[B]DC_TTY_MODE\f[R]
1110 If TTY mode is \f[I]not\f[R] available (see the \f[B]TTY MODE\f[R]
1111 section), then this environment variable has no effect.
1112 .RS
1113 .PP
1114 However, when TTY mode is available, then if this environment variable
1115 exists and contains an integer, then a non-zero value makes dc(1) use
1116 TTY mode, and zero makes dc(1) not use TTY mode.
1117 .PP
1118 This environment variable overrides the default, which can be queried
1119 with the \f[B]-h\f[R] or \f[B]--help\f[R] options.
1120 .RE
1121 .TP
1122 \f[B]DC_PROMPT\f[R]
1123 If TTY mode is \f[I]not\f[R] available (see the \f[B]TTY MODE\f[R]
1124 section), then this environment variable has no effect.
1125 .RS
1126 .PP
1127 However, when TTY mode is available, then if this environment variable
1128 exists and contains an integer, a non-zero value makes dc(1) use a
1129 prompt, and zero or a non-integer makes dc(1) not use a prompt.
1130 If this environment variable does not exist and \f[B]DC_TTY_MODE\f[R]
1131 does, then the value of the \f[B]DC_TTY_MODE\f[R] environment variable
1132 is used.
1133 .PP
1134 This environment variable and the \f[B]DC_TTY_MODE\f[R] environment
1135 variable override the default, which can be queried with the
1136 \f[B]-h\f[R] or \f[B]--help\f[R] options.
1137 .RE
1138 .SH EXIT STATUS
1139 .PP
1140 dc(1) returns the following exit statuses:
1141 .TP
1142 \f[B]0\f[R]
1143 No error.
1144 .TP
1145 \f[B]1\f[R]
1146 A math error occurred.
1147 This follows standard practice of using \f[B]1\f[R] for expected errors,
1148 since math errors will happen in the process of normal execution.
1149 .RS
1150 .PP
1151 Math errors include divide by \f[B]0\f[R], taking the square root of a
1152 negative number, attempting to convert a negative number to a hardware
1153 integer, overflow when converting a number to a hardware integer,
1154 overflow when calculating the size of a number, and attempting to use a
1155 non-integer where an integer is required.
1156 .PP
1157 Converting to a hardware integer happens for the second operand of the
1158 power (\f[B]\[ha]\f[R]) operator.
1159 .RE
1160 .TP
1161 \f[B]2\f[R]
1162 A parse error occurred.
1163 .RS
1164 .PP
1165 Parse errors include unexpected \f[B]EOF\f[R], using an invalid
1166 character, failing to find the end of a string or comment, and using a
1167 token where it is invalid.
1168 .RE
1169 .TP
1170 \f[B]3\f[R]
1171 A runtime error occurred.
1172 .RS
1173 .PP
1174 Runtime errors include assigning an invalid number to any global
1175 (\f[B]ibase\f[R], \f[B]obase\f[R], or \f[B]scale\f[R]), giving a bad
1176 expression to a \f[B]read()\f[R] call, calling \f[B]read()\f[R] inside
1177 of a \f[B]read()\f[R] call, type errors (including attempting to execute
1178 a number), and attempting an operation when the stack has too few
1179 elements.
1180 .RE
1181 .TP
1182 \f[B]4\f[R]
1183 A fatal error occurred.
1184 .RS
1185 .PP
1186 Fatal errors include memory allocation errors, I/O errors, failing to
1187 open files, attempting to use files that do not have only ASCII
1188 characters (dc(1) only accepts ASCII characters), attempting to open a
1189 directory as a file, and giving invalid command-line options.
1190 .RE
1191 .PP
1192 The exit status \f[B]4\f[R] is special; when a fatal error occurs, dc(1)
1193 always exits and returns \f[B]4\f[R], no matter what mode dc(1) is in.
1194 .PP
1195 The other statuses will only be returned when dc(1) is not in
1196 interactive mode (see the \f[B]INTERACTIVE MODE\f[R] section), since
1197 dc(1) resets its state (see the \f[B]RESET\f[R] section) and accepts
1198 more input when one of those errors occurs in interactive mode.
1199 This is also the case when interactive mode is forced by the
1200 \f[B]-i\f[R] flag or \f[B]--interactive\f[R] option.
1201 .PP
1202 These exit statuses allow dc(1) to be used in shell scripting with error
1203 checking, and its normal behavior can be forced by using the
1204 \f[B]-i\f[R] flag or \f[B]--interactive\f[R] option.
1205 .SH INTERACTIVE MODE
1206 .PP
1207 Like bc(1), dc(1) has an interactive mode and a non-interactive mode.
1208 Interactive mode is turned on automatically when both \f[B]stdin\f[R]
1209 and \f[B]stdout\f[R] are hooked to a terminal, but the \f[B]-i\f[R] flag
1210 and \f[B]--interactive\f[R] option can turn it on in other situations.
1211 .PP
1212 In interactive mode, dc(1) attempts to recover from errors (see the
1213 \f[B]RESET\f[R] section), and in normal execution, flushes
1214 \f[B]stdout\f[R] as soon as execution is done for the current input.
1215 dc(1) may also reset on \f[B]SIGINT\f[R] instead of exit, depending on
1216 the contents of, or default for, the \f[B]DC_SIGINT_RESET\f[R]
1217 environment variable (see the \f[B]ENVIRONMENT VARIABLES\f[R] section).
1218 .SH TTY MODE
1219 .PP
1220 If \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all
1221 connected to a TTY, then \[lq]TTY mode\[rq] is considered to be
1222 available, and thus, dc(1) can turn on TTY mode, subject to some
1223 settings.
1224 .PP
1225 If there is the environment variable \f[B]DC_TTY_MODE\f[R] in the
1226 environment (see the \f[B]ENVIRONMENT VARIABLES\f[R] section), then if
1227 that environment variable contains a non-zero integer, dc(1) will turn
1228 on TTY mode when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R]
1229 are all connected to a TTY.
1230 If the \f[B]DC_TTY_MODE\f[R] environment variable exists but is
1231 \f[I]not\f[R] a non-zero integer, then dc(1) will not turn TTY mode on.
1232 .PP
1233 If the environment variable \f[B]DC_TTY_MODE\f[R] does \f[I]not\f[R]
1234 exist, the default setting is used.
1235 The default setting can be queried with the \f[B]-h\f[R] or
1236 \f[B]--help\f[R] options.
1237 .PP
1238 TTY mode is different from interactive mode because interactive mode is
1239 required in the bc(1)
1240 specification (https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html),
1241 and interactive mode requires only \f[B]stdin\f[R] and \f[B]stdout\f[R]
1242 to be connected to a terminal.
1243 .SS Command-Line History
1244 .PP
1245 Command-line history is only enabled if TTY mode is, i.e., that
1246 \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are connected to
1247 a TTY and the \f[B]DC_TTY_MODE\f[R] environment variable (see the
1248 \f[B]ENVIRONMENT VARIABLES\f[R] section) and its default do not disable
1249 TTY mode.
1250 See the \f[B]COMMAND LINE HISTORY\f[R] section for more information.
1251 .SS Prompt
1252 .PP
1253 If TTY mode is available, then a prompt can be enabled.
1254 Like TTY mode itself, it can be turned on or off with an environment
1255 variable: \f[B]DC_PROMPT\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R]
1256 section).
1257 .PP
1258 If the environment variable \f[B]DC_PROMPT\f[R] exists and is a non-zero
1259 integer, then the prompt is turned on when \f[B]stdin\f[R],
1260 \f[B]stdout\f[R], and \f[B]stderr\f[R] are connected to a TTY and the
1261 \f[B]-P\f[R] and \f[B]--no-prompt\f[R] options were not used.
1262 The read prompt will be turned on under the same conditions, except that
1263 the \f[B]-R\f[R] and \f[B]--no-read-prompt\f[R] options must also not be
1264 used.
1265 .PP
1266 However, if \f[B]DC_PROMPT\f[R] does not exist, the prompt can be
1267 enabled or disabled with the \f[B]DC_TTY_MODE\f[R] environment variable,
1268 the \f[B]-P\f[R] and \f[B]--no-prompt\f[R] options, and the \f[B]-R\f[R]
1269 and \f[B]--no-read-prompt\f[R] options.
1270 See the \f[B]ENVIRONMENT VARIABLES\f[R] and \f[B]OPTIONS\f[R] sections
1271 for more details.
1272 .SH SIGNAL HANDLING
1273 .PP
1274 Sending a \f[B]SIGINT\f[R] will cause dc(1) to do one of two things.
1275 .PP
1276 If dc(1) is not in interactive mode (see the \f[B]INTERACTIVE MODE\f[R]
1277 section), or the \f[B]DC_SIGINT_RESET\f[R] environment variable (see the
1278 \f[B]ENVIRONMENT VARIABLES\f[R] section), or its default, is either not
1279 an integer or it is zero, dc(1) will exit.
1280 .PP
1281 However, if dc(1) is in interactive mode, and the
1282 \f[B]DC_SIGINT_RESET\f[R] or its default is an integer and non-zero,
1283 then dc(1) will stop executing the current input and reset (see the
1284 \f[B]RESET\f[R] section) upon receiving a \f[B]SIGINT\f[R].
1285 .PP
1286 Note that \[lq]current input\[rq] can mean one of two things.
1287 If dc(1) is processing input from \f[B]stdin\f[R] in interactive mode,
1288 it will ask for more input.
1289 If dc(1) is processing input from a file in interactive mode, it will
1290 stop processing the file and start processing the next file, if one
1291 exists, or ask for input from \f[B]stdin\f[R] if no other file exists.
1292 .PP
1293 This means that if a \f[B]SIGINT\f[R] is sent to dc(1) as it is
1294 executing a file, it can seem as though dc(1) did not respond to the
1295 signal since it will immediately start executing the next file.
1296 This is by design; most files that users execute when interacting with
1297 dc(1) have function definitions, which are quick to parse.
1298 If a file takes a long time to execute, there may be a bug in that file.
1299 The rest of the files could still be executed without problem, allowing
1300 the user to continue.
1301 .PP
1302 \f[B]SIGTERM\f[R] and \f[B]SIGQUIT\f[R] cause dc(1) to clean up and
1303 exit, and it uses the default handler for all other signals.
1304 The one exception is \f[B]SIGHUP\f[R]; in that case, and only when dc(1)
1305 is in TTY mode (see the \f[B]TTY MODE\f[R] section), a \f[B]SIGHUP\f[R]
1306 will cause dc(1) to clean up and exit.
1307 .SH COMMAND LINE HISTORY
1308 .PP
1309 dc(1) supports interactive command-line editing.
1310 .PP
1311 If dc(1) can be in TTY mode (see the \f[B]TTY MODE\f[R] section),
1312 history can be enabled.
1313 This means that command-line history can only be enabled when
1314 \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all
1315 connected to a TTY.
1316 .PP
1317 Like TTY mode itself, it can be turned on or off with the environment
1318 variable \f[B]DC_TTY_MODE\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R]
1319 section).
1320 .PP
1321 \f[B]Note\f[R]: tabs are converted to 8 spaces.
1322 .SH SEE ALSO
1323 .PP
1324 bc(1)
1325 .SH STANDARDS
1326 .PP
1327 The dc(1) utility operators are compliant with the operators in the
1328 bc(1) IEEE Std 1003.1-2017
1329 (\[lq]POSIX.1-2017\[rq]) (https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html)
1330 specification.
1331 .SH BUGS
1332 .PP
1333 None are known.
1334 Report bugs at https://git.yzena.com/gavin/bc.
1335 .SH AUTHOR
1336 .PP
1337 Gavin D.
1338 Howard <gavin@yzena.com> and contributors.