| .\" |
| .\" SPDX-License-Identifier: BSD-2-Clause |
| .\" |
| .\" Copyright (c) 2018-2021 Gavin D. Howard and contributors. |
| .\" |
| .\" Redistribution and use in source and binary forms, with or without |
| .\" modification, are permitted provided that the following conditions are met: |
| .\" |
| .\" * Redistributions of source code must retain the above copyright notice, |
| .\" this list of conditions and the following disclaimer. |
| .\" |
| .\" * Redistributions in binary form must reproduce the above copyright notice, |
| .\" this list of conditions and the following disclaimer in the documentation |
| .\" and/or other materials provided with the distribution. |
| .\" |
| .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" |
| .\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
| .\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE |
| .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR |
| .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF |
| .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS |
| .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN |
| .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) |
| .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE |
| .\" POSSIBILITY OF SUCH DAMAGE. |
| .\" |
| .TH "DC" "1" "August 2022" "Gavin D. Howard" "General Commands Manual" |
| .nh |
| .ad l |
| .SH Name |
| .PP |
| dc - arbitrary-precision decimal reverse-Polish notation calculator |
| .SH SYNOPSIS |
| .PP |
| \f[B]dc\f[R] [\f[B]-cChiPRvVx\f[R]] [\f[B]--version\f[R]] |
| [\f[B]--help\f[R]] [\f[B]--digit-clamp\f[R]] |
| [\f[B]--no-digit-clamp\f[R]] [\f[B]--interactive\f[R]] |
| [\f[B]--no-prompt\f[R]] [\f[B]--no-read-prompt\f[R]] |
| [\f[B]--extended-register\f[R]] [\f[B]-e\f[R] \f[I]expr\f[R]] |
| [\f[B]--expression\f[R]=\f[I]expr\f[R]\&...] |
| [\f[B]-f\f[R] \f[I]file\f[R]\&...] |
| [\f[B]--file\f[R]=\f[I]file\f[R]\&...] |
| [\f[I]file\f[R]\&...] |
| [\f[B]-I\f[R] \f[I]ibase\f[R]] [\f[B]--ibase\f[R]=\f[I]ibase\f[R]] |
| [\f[B]-O\f[R] \f[I]obase\f[R]] [\f[B]--obase\f[R]=\f[I]obase\f[R]] |
| [\f[B]-S\f[R] \f[I]scale\f[R]] [\f[B]--scale\f[R]=\f[I]scale\f[R]] |
| [\f[B]-E\f[R] \f[I]seed\f[R]] [\f[B]--seed\f[R]=\f[I]seed\f[R]] |
| .SH DESCRIPTION |
| .PP |
| dc(1) is an arbitrary-precision calculator. |
| It uses a stack (reverse Polish notation) to store numbers and results |
| of computations. |
| Arithmetic operations pop arguments off of the stack and push the |
| results. |
| .PP |
| If no files are given on the command-line, then dc(1) reads from |
| \f[B]stdin\f[R] (see the \f[B]STDIN\f[R] section). |
| Otherwise, those files are processed, and dc(1) will then exit. |
| .PP |
| If a user wants to set up a standard environment, they can use |
| \f[B]DC_ENV_ARGS\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). |
| For example, if a user wants the \f[B]scale\f[R] always set to |
| \f[B]10\f[R], they can set \f[B]DC_ENV_ARGS\f[R] to \f[B]-e 10k\f[R], |
| and this dc(1) will always start with a \f[B]scale\f[R] of \f[B]10\f[R]. |
| .SH OPTIONS |
| .PP |
| The following are the options that dc(1) accepts. |
| .TP |
| \f[B]-C\f[R], \f[B]--no-digit-clamp\f[R] |
| Disables clamping of digits greater than or equal to the current |
| \f[B]ibase\f[R] when parsing numbers. |
| .RS |
| .PP |
| This means that the value added to a number from a digit is always that |
| digit\[cq]s value multiplied by the value of ibase raised to the power |
| of the digit\[cq]s position, which starts from 0 at the least |
| significant digit. |
| .PP |
| If this and/or the \f[B]-c\f[R] or \f[B]--digit-clamp\f[R] options are |
| given multiple times, the last one given is used. |
| .PP |
| This option overrides the \f[B]DC_DIGIT_CLAMP\f[R] environment variable |
| (see the \f[B]ENVIRONMENT VARIABLES\f[R] section) and the default, which |
| can be queried with the \f[B]-h\f[R] or \f[B]--help\f[R] options. |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .TP |
| \f[B]-c\f[R], \f[B]--digit-clamp\f[R] |
| Enables clamping of digits greater than or equal to the current |
| \f[B]ibase\f[R] when parsing numbers. |
| .RS |
| .PP |
| This means that digits that the value added to a number from a digit |
| that is greater than or equal to the ibase is the value of ibase minus 1 |
| all multiplied by the value of ibase raised to the power of the |
| digit\[cq]s position, which starts from 0 at the least significant |
| digit. |
| .PP |
| If this and/or the \f[B]-C\f[R] or \f[B]--no-digit-clamp\f[R] options |
| are given multiple times, the last one given is used. |
| .PP |
| This option overrides the \f[B]DC_DIGIT_CLAMP\f[R] environment variable |
| (see the \f[B]ENVIRONMENT VARIABLES\f[R] section) and the default, which |
| can be queried with the \f[B]-h\f[R] or \f[B]--help\f[R] options. |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .TP |
| \f[B]-E\f[R] \f[I]seed\f[R], \f[B]--seed\f[R]=\f[I]seed\f[R] |
| Sets the builtin variable \f[B]seed\f[R] to the value \f[I]seed\f[R] |
| assuming that \f[I]seed\f[R] is in base 10. |
| It is a fatal error if \f[I]seed\f[R] is not a valid number. |
| .RS |
| .PP |
| If multiple instances of this option are given, the last is used. |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .TP |
| \f[B]-e\f[R] \f[I]expr\f[R], \f[B]--expression\f[R]=\f[I]expr\f[R] |
| Evaluates \f[I]expr\f[R]. |
| If multiple expressions are given, they are evaluated in order. |
| If files are given as well (see below), the expressions and files are |
| evaluated in the order given. |
| This means that if a file is given before an expression, the file is |
| read in and evaluated first. |
| .RS |
| .PP |
| If this option is given on the command-line (i.e., not in |
| \f[B]DC_ENV_ARGS\f[R], see the \f[B]ENVIRONMENT VARIABLES\f[R] section), |
| then after processing all expressions and files, dc(1) will exit, unless |
| \f[B]-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to |
| \f[B]-f\f[R] or \f[B]--file\f[R], whether on the command-line or in |
| \f[B]DC_ENV_ARGS\f[R]. |
| However, if any other \f[B]-e\f[R], \f[B]--expression\f[R], |
| \f[B]-f\f[R], or \f[B]--file\f[R] arguments are given after |
| \f[B]-f-\f[R] or equivalent is given, dc(1) will give a fatal error and |
| exit. |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .TP |
| \f[B]-f\f[R] \f[I]file\f[R], \f[B]--file\f[R]=\f[I]file\f[R] |
| Reads in \f[I]file\f[R] and evaluates it, line by line, as though it |
| were read through \f[B]stdin\f[R]. |
| If expressions are also given (see above), the expressions are evaluated |
| in the order given. |
| .RS |
| .PP |
| If this option is given on the command-line (i.e., not in |
| \f[B]DC_ENV_ARGS\f[R], see the \f[B]ENVIRONMENT VARIABLES\f[R] section), |
| then after processing all expressions and files, dc(1) will exit, unless |
| \f[B]-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to |
| \f[B]-f\f[R] or \f[B]--file\f[R]. |
| However, if any other \f[B]-e\f[R], \f[B]--expression\f[R], |
| \f[B]-f\f[R], or \f[B]--file\f[R] arguments are given after |
| \f[B]-f-\f[R] or equivalent is given, dc(1) will give a fatal error and |
| exit. |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .TP |
| \f[B]-h\f[R], \f[B]--help\f[R] |
| Prints a usage message and exits. |
| .TP |
| \f[B]-I\f[R] \f[I]ibase\f[R], \f[B]--ibase\f[R]=\f[I]ibase\f[R] |
| Sets the builtin variable \f[B]ibase\f[R] to the value \f[I]ibase\f[R] |
| assuming that \f[I]ibase\f[R] is in base 10. |
| It is a fatal error if \f[I]ibase\f[R] is not a valid number. |
| .RS |
| .PP |
| If multiple instances of this option are given, the last is used. |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .TP |
| \f[B]-i\f[R], \f[B]--interactive\f[R] |
| Forces interactive mode. |
| (See the \f[B]INTERACTIVE MODE\f[R] section.) |
| .RS |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .TP |
| \f[B]-L\f[R], \f[B]--no-line-length\f[R] |
| Disables line length checking and prints numbers without backslashes and |
| newlines. |
| In other words, this option sets \f[B]BC_LINE_LENGTH\f[R] to \f[B]0\f[R] |
| (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). |
| .RS |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .TP |
| \f[B]-O\f[R] \f[I]obase\f[R], \f[B]--obase\f[R]=\f[I]obase\f[R] |
| Sets the builtin variable \f[B]obase\f[R] to the value \f[I]obase\f[R] |
| assuming that \f[I]obase\f[R] is in base 10. |
| It is a fatal error if \f[I]obase\f[R] is not a valid number. |
| .RS |
| .PP |
| If multiple instances of this option are given, the last is used. |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .TP |
| \f[B]-P\f[R], \f[B]--no-prompt\f[R] |
| Disables the prompt in TTY mode. |
| (The prompt is only enabled in TTY mode. |
| See the \f[B]TTY MODE\f[R] section.) |
| This is mostly for those users that do not want a prompt or are not used |
| to having them in dc(1). |
| Most of those users would want to put this option in |
| \f[B]DC_ENV_ARGS\f[R]. |
| .RS |
| .PP |
| These options override the \f[B]DC_PROMPT\f[R] and \f[B]DC_TTY_MODE\f[R] |
| environment variables (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .TP |
| \f[B]-R\f[R], \f[B]--no-read-prompt\f[R] |
| Disables the read prompt in TTY mode. |
| (The read prompt is only enabled in TTY mode. |
| See the \f[B]TTY MODE\f[R] section.) |
| This is mostly for those users that do not want a read prompt or are not |
| used to having them in dc(1). |
| Most of those users would want to put this option in |
| \f[B]BC_ENV_ARGS\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). |
| This option is also useful in hash bang lines of dc(1) scripts that |
| prompt for user input. |
| .RS |
| .PP |
| This option does not disable the regular prompt because the read prompt |
| is only used when the \f[B]?\f[R] command is used. |
| .PP |
| These options \f[I]do\f[R] override the \f[B]DC_PROMPT\f[R] and |
| \f[B]DC_TTY_MODE\f[R] environment variables (see the \f[B]ENVIRONMENT |
| VARIABLES\f[R] section), but only for the read prompt. |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .TP |
| \f[B]-S\f[R] \f[I]scale\f[R], \f[B]--scale\f[R]=\f[I]scale\f[R] |
| Sets the builtin variable \f[B]scale\f[R] to the value \f[I]scale\f[R] |
| assuming that \f[I]scale\f[R] is in base 10. |
| It is a fatal error if \f[I]scale\f[R] is not a valid number. |
| .RS |
| .PP |
| If multiple instances of this option are given, the last is used. |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .TP |
| \f[B]-v\f[R], \f[B]-V\f[R], \f[B]--version\f[R] |
| Print the version information (copyright header) and exits. |
| .TP |
| \f[B]-x\f[R] \f[B]--extended-register\f[R] |
| Enables extended register mode. |
| See the \f[I]Extended Register Mode\f[R] subsection of the |
| \f[B]REGISTERS\f[R] section for more information. |
| .RS |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .TP |
| \f[B]-z\f[R], \f[B]--leading-zeroes\f[R] |
| Makes dc(1) print all numbers greater than \f[B]-1\f[R] and less than |
| \f[B]1\f[R], and not equal to \f[B]0\f[R], with a leading zero. |
| .RS |
| .PP |
| This can be set for individual numbers with the \f[B]plz(x)\f[R], |
| plznl(x)**, \f[B]pnlz(x)\f[R], and \f[B]pnlznl(x)\f[R] functions in the |
| extended math library (see the \f[B]LIBRARY\f[R] section). |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .PP |
| All long options are \f[B]non-portable extensions\f[R]. |
| .SH STDIN |
| .PP |
| If no files are given on the command-line and no files or expressions |
| are given by the \f[B]-f\f[R], \f[B]--file\f[R], \f[B]-e\f[R], or |
| \f[B]--expression\f[R] options, then dc(1) reads from \f[B]stdin\f[R]. |
| .PP |
| However, there is a caveat to this. |
| .PP |
| First, \f[B]stdin\f[R] is evaluated a line at a time. |
| The only exception to this is if a string has been finished, but not |
| ended. |
| This means that, except for escaped brackets, all brackets must be |
| balanced before dc(1) parses and executes. |
| .SH STDOUT |
| .PP |
| Any non-error output is written to \f[B]stdout\f[R]. |
| In addition, if history (see the \f[B]HISTORY\f[R] section) and the |
| prompt (see the \f[B]TTY MODE\f[R] section) are enabled, both are output |
| to \f[B]stdout\f[R]. |
| .PP |
| \f[B]Note\f[R]: Unlike other dc(1) implementations, this dc(1) will |
| issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot |
| write to \f[B]stdout\f[R], so if \f[B]stdout\f[R] is closed, as in |
| \f[B]dc >&-\f[R], it will quit with an error. |
| This is done so that dc(1) can report problems when \f[B]stdout\f[R] is |
| redirected to a file. |
| .PP |
| If there are scripts that depend on the behavior of other dc(1) |
| implementations, it is recommended that those scripts be changed to |
| redirect \f[B]stdout\f[R] to \f[B]/dev/null\f[R]. |
| .SH STDERR |
| .PP |
| Any error output is written to \f[B]stderr\f[R]. |
| .PP |
| \f[B]Note\f[R]: Unlike other dc(1) implementations, this dc(1) will |
| issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot |
| write to \f[B]stderr\f[R], so if \f[B]stderr\f[R] is closed, as in |
| \f[B]dc 2>&-\f[R], it will quit with an error. |
| This is done so that dc(1) can exit with an error code when |
| \f[B]stderr\f[R] is redirected to a file. |
| .PP |
| If there are scripts that depend on the behavior of other dc(1) |
| implementations, it is recommended that those scripts be changed to |
| redirect \f[B]stderr\f[R] to \f[B]/dev/null\f[R]. |
| .SH SYNTAX |
| .PP |
| Each item in the input source code, either a number (see the |
| \f[B]NUMBERS\f[R] section) or a command (see the \f[B]COMMANDS\f[R] |
| section), is processed and executed, in order. |
| Input is processed immediately when entered. |
| .PP |
| \f[B]ibase\f[R] is a register (see the \f[B]REGISTERS\f[R] section) that |
| determines how to interpret constant numbers. |
| It is the \[lq]input\[rq] base, or the number base used for interpreting |
| input numbers. |
| \f[B]ibase\f[R] is initially \f[B]10\f[R]. |
| The max allowable value for \f[B]ibase\f[R] is \f[B]16\f[R]. |
| The min allowable value for \f[B]ibase\f[R] is \f[B]2\f[R]. |
| The max allowable value for \f[B]ibase\f[R] can be queried in dc(1) |
| programs with the \f[B]T\f[R] command. |
| .PP |
| \f[B]obase\f[R] is a register (see the \f[B]REGISTERS\f[R] section) that |
| determines how to output results. |
| It is the \[lq]output\[rq] base, or the number base used for outputting |
| numbers. |
| \f[B]obase\f[R] is initially \f[B]10\f[R]. |
| The max allowable value for \f[B]obase\f[R] is \f[B]DC_BASE_MAX\f[R] and |
| can be queried with the \f[B]U\f[R] command. |
| The min allowable value for \f[B]obase\f[R] is \f[B]0\f[R]. |
| If \f[B]obase\f[R] is \f[B]0\f[R], values are output in scientific |
| notation, and if \f[B]obase\f[R] is \f[B]1\f[R], values are output in |
| engineering notation. |
| Otherwise, values are output in the specified base. |
| .PP |
| Outputting in scientific and engineering notations are \f[B]non-portable |
| extensions\f[R]. |
| .PP |
| The \f[I]scale\f[R] of an expression is the number of digits in the |
| result of the expression right of the decimal point, and \f[B]scale\f[R] |
| is a register (see the \f[B]REGISTERS\f[R] section) that sets the |
| precision of any operations (with exceptions). |
| \f[B]scale\f[R] is initially \f[B]0\f[R]. |
| \f[B]scale\f[R] cannot be negative. |
| The max allowable value for \f[B]scale\f[R] can be queried in dc(1) |
| programs with the \f[B]V\f[R] command. |
| .PP |
| \f[B]seed\f[R] is a register containing the current seed for the |
| pseudo-random number generator. |
| If the current value of \f[B]seed\f[R] is queried and stored, then if it |
| is assigned to \f[B]seed\f[R] later, the pseudo-random number generator |
| is guaranteed to produce the same sequence of pseudo-random numbers that |
| were generated after the value of \f[B]seed\f[R] was first queried. |
| .PP |
| Multiple values assigned to \f[B]seed\f[R] can produce the same sequence |
| of pseudo-random numbers. |
| Likewise, when a value is assigned to \f[B]seed\f[R], it is not |
| guaranteed that querying \f[B]seed\f[R] immediately after will return |
| the same value. |
| In addition, the value of \f[B]seed\f[R] will change after any call to |
| the \f[B]\[cq]\f[R] command or the \f[B]\[lq]\f[R] command that does not |
| get receive a value of \f[B]0\f[R] or \f[B]1\f[R]. |
| The maximum integer returned by the \f[B]\[cq]\f[R] command can be |
| queried with the \f[B]W\f[R] command. |
| .PP |
| \f[B]Note\f[R]: The values returned by the pseudo-random number |
| generator with the \f[B]\[cq]\f[R] and \f[B]\[lq]\f[R] commands are |
| guaranteed to \f[B]NOT\f[R] be cryptographically secure. |
| This is a consequence of using a seeded pseudo-random number generator. |
| However, they \f[I]are\f[R] guaranteed to be reproducible with identical |
| \f[B]seed\f[R] values. |
| This means that the pseudo-random values from dc(1) should only be used |
| where a reproducible stream of pseudo-random numbers is |
| \f[I]ESSENTIAL\f[R]. |
| In any other case, use a non-seeded pseudo-random number generator. |
| .PP |
| The pseudo-random number generator, \f[B]seed\f[R], and all associated |
| operations are \f[B]non-portable extensions\f[R]. |
| .SS Comments |
| .PP |
| Comments go from \f[B]#\f[R] until, and not including, the next newline. |
| This is a \f[B]non-portable extension\f[R]. |
| .SH NUMBERS |
| .PP |
| Numbers are strings made up of digits, uppercase letters up to |
| \f[B]F\f[R], and at most \f[B]1\f[R] period for a radix. |
| Numbers can have up to \f[B]DC_NUM_MAX\f[R] digits. |
| Uppercase letters are equal to \f[B]9\f[R] plus their position in the |
| alphabet (i.e., \f[B]A\f[R] equals \f[B]10\f[R], or \f[B]9+1\f[R]). |
| .PP |
| If a digit or letter makes no sense with the current value of |
| \f[B]ibase\f[R] (i.e., they are greater than or equal to the current |
| value of \f[B]ibase\f[R]), then the behavior depends on the existence of |
| the \f[B]-c\f[R]/\f[B]--digit-clamp\f[R] or |
| \f[B]-C\f[R]/\f[B]--no-digit-clamp\f[R] options (see the |
| \f[B]OPTIONS\f[R] section), the existence and setting of the |
| \f[B]DC_DIGIT_CLAMP\f[R] environment variable (see the \f[B]ENVIRONMENT |
| VARIABLES\f[R] section), or the default, which can be queried with the |
| \f[B]-h\f[R]/\f[B]--help\f[R] option. |
| .PP |
| If clamping is off, then digits or letters that are greater than or |
| equal to the current value of \f[B]ibase\f[R] are not changed. |
| Instead, their given value is multiplied by the appropriate power of |
| \f[B]ibase\f[R] and added into the number. |
| This means that, with an \f[B]ibase\f[R] of \f[B]3\f[R], the number |
| \f[B]AB\f[R] is equal to \f[B]3\[ha]1*A+3\[ha]0*B\f[R], which is |
| \f[B]3\f[R] times \f[B]10\f[R] plus \f[B]11\f[R], or \f[B]41\f[R]. |
| .PP |
| If clamping is on, then digits or letters that are greater than or equal |
| to the current value of \f[B]ibase\f[R] are set to the value of the |
| highest valid digit in \f[B]ibase\f[R] before being multiplied by the |
| appropriate power of \f[B]ibase\f[R] and added into the number. |
| This means that, with an \f[B]ibase\f[R] of \f[B]3\f[R], the number |
| \f[B]AB\f[R] is equal to \f[B]3\[ha]1*2+3\[ha]0*2\f[R], which is |
| \f[B]3\f[R] times \f[B]2\f[R] plus \f[B]2\f[R], or \f[B]8\f[R]. |
| .PP |
| There is one exception to clamping: single-character numbers (i.e., |
| \f[B]A\f[R] alone). |
| Such numbers are never clamped and always take the value they would have |
| in the highest possible \f[B]ibase\f[R]. |
| This means that \f[B]A\f[R] alone always equals decimal \f[B]10\f[R] and |
| \f[B]Z\f[R] alone always equals decimal \f[B]35\f[R]. |
| This behavior is mandated by the standard for bc(1) (see the STANDARDS |
| section) and is meant to provide an easy way to set the current |
| \f[B]ibase\f[R] (with the \f[B]i\f[R] command) regardless of the current |
| value of \f[B]ibase\f[R]. |
| .PP |
| If clamping is on, and the clamped value of a character is needed, use a |
| leading zero, i.e., for \f[B]A\f[R], use \f[B]0A\f[R]. |
| .PP |
| In addition, dc(1) accepts numbers in scientific notation. |
| These have the form \f[B]<number>e<integer>\f[R]. |
| The exponent (the portion after the \f[B]e\f[R]) must be an integer. |
| An example is \f[B]1.89237e9\f[R], which is equal to |
| \f[B]1892370000\f[R]. |
| Negative exponents are also allowed, so \f[B]4.2890e_3\f[R] is equal to |
| \f[B]0.0042890\f[R]. |
| .PP |
| \f[B]WARNING\f[R]: Both the number and the exponent in scientific |
| notation are interpreted according to the current \f[B]ibase\f[R], but |
| the number is still multiplied by \f[B]10\[ha]exponent\f[R] regardless |
| of the current \f[B]ibase\f[R]. |
| For example, if \f[B]ibase\f[R] is \f[B]16\f[R] and dc(1) is given the |
| number string \f[B]FFeA\f[R], the resulting decimal number will be |
| \f[B]2550000000000\f[R], and if dc(1) is given the number string |
| \f[B]10e_4\f[R], the resulting decimal number will be \f[B]0.0016\f[R]. |
| .PP |
| Accepting input as scientific notation is a \f[B]non-portable |
| extension\f[R]. |
| .SH COMMANDS |
| .PP |
| The valid commands are listed below. |
| .SS Printing |
| .PP |
| These commands are used for printing. |
| .PP |
| Note that both scientific notation and engineering notation are |
| available for printing numbers. |
| Scientific notation is activated by assigning \f[B]0\f[R] to |
| \f[B]obase\f[R] using \f[B]0o\f[R], and engineering notation is |
| activated by assigning \f[B]1\f[R] to \f[B]obase\f[R] using |
| \f[B]1o\f[R]. |
| To deactivate them, just assign a different value to \f[B]obase\f[R]. |
| .PP |
| Printing numbers in scientific notation and/or engineering notation is a |
| \f[B]non-portable extension\f[R]. |
| .TP |
| \f[B]p\f[R] |
| Prints the value on top of the stack, whether number or string, and |
| prints a newline after. |
| .RS |
| .PP |
| This does not alter the stack. |
| .RE |
| .TP |
| \f[B]n\f[R] |
| Prints the value on top of the stack, whether number or string, and pops |
| it off of the stack. |
| .TP |
| \f[B]P\f[R] |
| Pops a value off the stack. |
| .RS |
| .PP |
| If the value is a number, it is truncated and the absolute value of the |
| result is printed as though \f[B]obase\f[R] is \f[B]256\f[R] and each |
| digit is interpreted as an 8-bit ASCII character, making it a byte |
| stream. |
| .PP |
| If the value is a string, it is printed without a trailing newline. |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .TP |
| \f[B]f\f[R] |
| Prints the entire contents of the stack, in order from newest to oldest, |
| without altering anything. |
| .RS |
| .PP |
| Users should use this command when they get lost. |
| .RE |
| .SS Arithmetic |
| .PP |
| These are the commands used for arithmetic. |
| .TP |
| \f[B]+\f[R] |
| The top two values are popped off the stack, added, and the result is |
| pushed onto the stack. |
| The \f[I]scale\f[R] of the result is equal to the max \f[I]scale\f[R] of |
| both operands. |
| .TP |
| \f[B]-\f[R] |
| The top two values are popped off the stack, subtracted, and the result |
| is pushed onto the stack. |
| The \f[I]scale\f[R] of the result is equal to the max \f[I]scale\f[R] of |
| both operands. |
| .TP |
| \f[B]*\f[R] |
| The top two values are popped off the stack, multiplied, and the result |
| is pushed onto the stack. |
| If \f[B]a\f[R] is the \f[I]scale\f[R] of the first expression and |
| \f[B]b\f[R] is the \f[I]scale\f[R] of the second expression, the |
| \f[I]scale\f[R] of the result is equal to |
| \f[B]min(a+b,max(scale,a,b))\f[R] where \f[B]min()\f[R] and |
| \f[B]max()\f[R] return the obvious values. |
| .TP |
| \f[B]/\f[R] |
| The top two values are popped off the stack, divided, and the result is |
| pushed onto the stack. |
| The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R]. |
| .RS |
| .PP |
| The first value popped off of the stack must be non-zero. |
| .RE |
| .TP |
| \f[B]%\f[R] |
| The top two values are popped off the stack, remaindered, and the result |
| is pushed onto the stack. |
| .RS |
| .PP |
| Remaindering is equivalent to 1) Computing \f[B]a/b\f[R] to current |
| \f[B]scale\f[R], and 2) Using the result of step 1 to calculate |
| \f[B]a-(a/b)*b\f[R] to \f[I]scale\f[R] |
| \f[B]max(scale+scale(b),scale(a))\f[R]. |
| .PP |
| The first value popped off of the stack must be non-zero. |
| .RE |
| .TP |
| \f[B]\[ti]\f[R] |
| The top two values are popped off the stack, divided and remaindered, |
| and the results (divided first, remainder second) are pushed onto the |
| stack. |
| This is equivalent to \f[B]x y / x y %\f[R] except that \f[B]x\f[R] and |
| \f[B]y\f[R] are only evaluated once. |
| .RS |
| .PP |
| The first value popped off of the stack must be non-zero. |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .TP |
| \f[B]\[ha]\f[R] |
| The top two values are popped off the stack, the second is raised to the |
| power of the first, and the result is pushed onto the stack. |
| The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R]. |
| .RS |
| .PP |
| The first value popped off of the stack must be an integer, and if that |
| value is negative, the second value popped off of the stack must be |
| non-zero. |
| .RE |
| .TP |
| \f[B]v\f[R] |
| The top value is popped off the stack, its square root is computed, and |
| the result is pushed onto the stack. |
| The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R]. |
| .RS |
| .PP |
| The value popped off of the stack must be non-negative. |
| .RE |
| .TP |
| \f[B]_\f[R] |
| If this command \f[I]immediately\f[R] precedes a number (i.e., no spaces |
| or other commands), then that number is input as a negative number. |
| .RS |
| .PP |
| Otherwise, the top value on the stack is popped and copied, and the copy |
| is negated and pushed onto the stack. |
| This behavior without a number is a \f[B]non-portable extension\f[R]. |
| .RE |
| .TP |
| \f[B]b\f[R] |
| The top value is popped off the stack, and if it is zero, it is pushed |
| back onto the stack. |
| Otherwise, its absolute value is pushed onto the stack. |
| .RS |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .TP |
| \f[B]|\f[R] |
| The top three values are popped off the stack, a modular exponentiation |
| is computed, and the result is pushed onto the stack. |
| .RS |
| .PP |
| The first value popped is used as the reduction modulus and must be an |
| integer and non-zero. |
| The second value popped is used as the exponent and must be an integer |
| and non-negative. |
| The third value popped is the base and must be an integer. |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .TP |
| \f[B]$\f[R] |
| The top value is popped off the stack and copied, and the copy is |
| truncated and pushed onto the stack. |
| .RS |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .TP |
| \f[B]\[at]\f[R] |
| The top two values are popped off the stack, and the precision of the |
| second is set to the value of the first, whether by truncation or |
| extension. |
| .RS |
| .PP |
| The first value popped off of the stack must be an integer and |
| non-negative. |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .TP |
| \f[B]H\f[R] |
| The top two values are popped off the stack, and the second is shifted |
| left (radix shifted right) to the value of the first. |
| .RS |
| .PP |
| The first value popped off of the stack must be an integer and |
| non-negative. |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .TP |
| \f[B]h\f[R] |
| The top two values are popped off the stack, and the second is shifted |
| right (radix shifted left) to the value of the first. |
| .RS |
| .PP |
| The first value popped off of the stack must be an integer and |
| non-negative. |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .TP |
| \f[B]G\f[R] |
| The top two values are popped off of the stack, they are compared, and a |
| \f[B]1\f[R] is pushed if they are equal, or \f[B]0\f[R] otherwise. |
| .RS |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .TP |
| \f[B]N\f[R] |
| The top value is popped off of the stack, and if it a \f[B]0\f[R], a |
| \f[B]1\f[R] is pushed; otherwise, a \f[B]0\f[R] is pushed. |
| .RS |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .TP |
| \f[B](\f[R] |
| The top two values are popped off of the stack, they are compared, and a |
| \f[B]1\f[R] is pushed if the first is less than the second, or |
| \f[B]0\f[R] otherwise. |
| .RS |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .TP |
| \f[B]{\f[R] |
| The top two values are popped off of the stack, they are compared, and a |
| \f[B]1\f[R] is pushed if the first is less than or equal to the second, |
| or \f[B]0\f[R] otherwise. |
| .RS |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .TP |
| \f[B])\f[R] |
| The top two values are popped off of the stack, they are compared, and a |
| \f[B]1\f[R] is pushed if the first is greater than the second, or |
| \f[B]0\f[R] otherwise. |
| .RS |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .TP |
| \f[B]}\f[R] |
| The top two values are popped off of the stack, they are compared, and a |
| \f[B]1\f[R] is pushed if the first is greater than or equal to the |
| second, or \f[B]0\f[R] otherwise. |
| .RS |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .TP |
| \f[B]M\f[R] |
| The top two values are popped off of the stack. |
| If they are both non-zero, a \f[B]1\f[R] is pushed onto the stack. |
| If either of them is zero, or both of them are, then a \f[B]0\f[R] is |
| pushed onto the stack. |
| .RS |
| .PP |
| This is like the \f[B]&&\f[R] operator in bc(1), and it is \f[I]not\f[R] |
| a short-circuit operator. |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .TP |
| \f[B]m\f[R] |
| The top two values are popped off of the stack. |
| If at least one of them is non-zero, a \f[B]1\f[R] is pushed onto the |
| stack. |
| If both of them are zero, then a \f[B]0\f[R] is pushed onto the stack. |
| .RS |
| .PP |
| This is like the \f[B]||\f[R] operator in bc(1), and it is \f[I]not\f[R] |
| a short-circuit operator. |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .SS Pseudo-Random Number Generator |
| .PP |
| dc(1) has a built-in pseudo-random number generator. |
| These commands query the pseudo-random number generator. |
| (See Parameters for more information about the \f[B]seed\f[R] value that |
| controls the pseudo-random number generator.) |
| .PP |
| The pseudo-random number generator is guaranteed to \f[B]NOT\f[R] be |
| cryptographically secure. |
| .TP |
| \f[B]\[cq]\f[R] |
| Generates an integer between 0 and \f[B]DC_RAND_MAX\f[R], inclusive (see |
| the \f[B]LIMITS\f[R] section). |
| .RS |
| .PP |
| The generated integer is made as unbiased as possible, subject to the |
| limitations of the pseudo-random number generator. |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .TP |
| \f[B]\[lq]\f[R] |
| Pops a value off of the stack, which is used as an \f[B]exclusive\f[R] |
| upper bound on the integer that will be generated. |
| If the bound is negative or is a non-integer, an error is raised, and |
| dc(1) resets (see the \f[B]RESET\f[R] section) while \f[B]seed\f[R] |
| remains unchanged. |
| If the bound is larger than \f[B]DC_RAND_MAX\f[R], the higher bound is |
| honored by generating several pseudo-random integers, multiplying them |
| by appropriate powers of \f[B]DC_RAND_MAX+1\f[R], and adding them |
| together. |
| Thus, the size of integer that can be generated with this command is |
| unbounded. |
| Using this command will change the value of \f[B]seed\f[R], unless the |
| operand is \f[B]0\f[R] or \f[B]1\f[R]. |
| In that case, \f[B]0\f[R] is pushed onto the stack, and \f[B]seed\f[R] |
| is \f[I]not\f[R] changed. |
| .RS |
| .PP |
| The generated integer is made as unbiased as possible, subject to the |
| limitations of the pseudo-random number generator. |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .SS Stack Control |
| .PP |
| These commands control the stack. |
| .TP |
| \f[B]c\f[R] |
| Removes all items from (\[lq]clears\[rq]) the stack. |
| .TP |
| \f[B]d\f[R] |
| Copies the item on top of the stack (\[lq]duplicates\[rq]) and pushes |
| the copy onto the stack. |
| .TP |
| \f[B]r\f[R] |
| Swaps (\[lq]reverses\[rq]) the two top items on the stack. |
| .TP |
| \f[B]R\f[R] |
| Pops (\[lq]removes\[rq]) the top value from the stack. |
| .SS Register Control |
| .PP |
| These commands control registers (see the \f[B]REGISTERS\f[R] section). |
| .TP |
| \f[B]s\f[R]\f[I]r\f[R] |
| Pops the value off the top of the stack and stores it into register |
| \f[I]r\f[R]. |
| .TP |
| \f[B]l\f[R]\f[I]r\f[R] |
| Copies the value in register \f[I]r\f[R] and pushes it onto the stack. |
| This does not alter the contents of \f[I]r\f[R]. |
| .TP |
| \f[B]S\f[R]\f[I]r\f[R] |
| Pops the value off the top of the (main) stack and pushes it onto the |
| stack of register \f[I]r\f[R]. |
| The previous value of the register becomes inaccessible. |
| .TP |
| \f[B]L\f[R]\f[I]r\f[R] |
| Pops the value off the top of the stack for register \f[I]r\f[R] and |
| push it onto the main stack. |
| The previous value in the stack for register \f[I]r\f[R], if any, is now |
| accessible via the \f[B]l\f[R]\f[I]r\f[R] command. |
| .SS Parameters |
| .PP |
| These commands control the values of \f[B]ibase\f[R], \f[B]obase\f[R], |
| \f[B]scale\f[R], and \f[B]seed\f[R]. |
| Also see the \f[B]SYNTAX\f[R] section. |
| .TP |
| \f[B]i\f[R] |
| Pops the value off of the top of the stack and uses it to set |
| \f[B]ibase\f[R], which must be between \f[B]2\f[R] and \f[B]16\f[R], |
| inclusive. |
| .RS |
| .PP |
| If the value on top of the stack has any \f[I]scale\f[R], the |
| \f[I]scale\f[R] is ignored. |
| .RE |
| .TP |
| \f[B]o\f[R] |
| Pops the value off of the top of the stack and uses it to set |
| \f[B]obase\f[R], which must be between \f[B]0\f[R] and |
| \f[B]DC_BASE_MAX\f[R], inclusive (see the \f[B]LIMITS\f[R] section and |
| the \f[B]NUMBERS\f[R] section). |
| .RS |
| .PP |
| If the value on top of the stack has any \f[I]scale\f[R], the |
| \f[I]scale\f[R] is ignored. |
| .RE |
| .TP |
| \f[B]k\f[R] |
| Pops the value off of the top of the stack and uses it to set |
| \f[B]scale\f[R], which must be non-negative. |
| .RS |
| .PP |
| If the value on top of the stack has any \f[I]scale\f[R], the |
| \f[I]scale\f[R] is ignored. |
| .RE |
| .TP |
| \f[B]j\f[R] |
| Pops the value off of the top of the stack and uses it to set |
| \f[B]seed\f[R]. |
| The meaning of \f[B]seed\f[R] is dependent on the current pseudo-random |
| number generator but is guaranteed to not change except for new major |
| versions. |
| .RS |
| .PP |
| The \f[I]scale\f[R] and sign of the value may be significant. |
| .PP |
| If a previously used \f[B]seed\f[R] value is used again, the |
| pseudo-random number generator is guaranteed to produce the same |
| sequence of pseudo-random numbers as it did when the \f[B]seed\f[R] |
| value was previously used. |
| .PP |
| The exact value assigned to \f[B]seed\f[R] is not guaranteed to be |
| returned if the \f[B]J\f[R] command is used. |
| However, if \f[B]seed\f[R] \f[I]does\f[R] return a different value, both |
| values, when assigned to \f[B]seed\f[R], are guaranteed to produce the |
| same sequence of pseudo-random numbers. |
| This means that certain values assigned to \f[B]seed\f[R] will not |
| produce unique sequences of pseudo-random numbers. |
| .PP |
| There is no limit to the length (number of significant decimal digits) |
| or \f[I]scale\f[R] of the value that can be assigned to \f[B]seed\f[R]. |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .TP |
| \f[B]I\f[R] |
| Pushes the current value of \f[B]ibase\f[R] onto the main stack. |
| .TP |
| \f[B]O\f[R] |
| Pushes the current value of \f[B]obase\f[R] onto the main stack. |
| .TP |
| \f[B]K\f[R] |
| Pushes the current value of \f[B]scale\f[R] onto the main stack. |
| .TP |
| \f[B]J\f[R] |
| Pushes the current value of \f[B]seed\f[R] onto the main stack. |
| .RS |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .TP |
| \f[B]T\f[R] |
| Pushes the maximum allowable value of \f[B]ibase\f[R] onto the main |
| stack. |
| .RS |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .TP |
| \f[B]U\f[R] |
| Pushes the maximum allowable value of \f[B]obase\f[R] onto the main |
| stack. |
| .RS |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .TP |
| \f[B]V\f[R] |
| Pushes the maximum allowable value of \f[B]scale\f[R] onto the main |
| stack. |
| .RS |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .TP |
| \f[B]W\f[R] |
| Pushes the maximum (inclusive) integer that can be generated with the |
| \f[B]\[cq]\f[R] pseudo-random number generator command. |
| .RS |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .SS Strings |
| .PP |
| The following commands control strings. |
| .PP |
| dc(1) can work with both numbers and strings, and registers (see the |
| \f[B]REGISTERS\f[R] section) can hold both strings and numbers. |
| dc(1) always knows whether the contents of a register are a string or a |
| number. |
| .PP |
| While arithmetic operations have to have numbers, and will print an |
| error if given a string, other commands accept strings. |
| .PP |
| Strings can also be executed as macros. |
| For example, if the string \f[B][1pR]\f[R] is executed as a macro, then |
| the code \f[B]1pR\f[R] is executed, meaning that the \f[B]1\f[R] will be |
| printed with a newline after and then popped from the stack. |
| .TP |
| \f[B][\f[R]\f[I]characters\f[R]\f[B]]\f[R] |
| Makes a string containing \f[I]characters\f[R] and pushes it onto the |
| stack. |
| .RS |
| .PP |
| If there are brackets (\f[B][\f[R] and \f[B]]\f[R]) in the string, then |
| they must be balanced. |
| Unbalanced brackets can be escaped using a backslash (\f[B]\[rs]\f[R]) |
| character. |
| .PP |
| If there is a backslash character in the string, the character after it |
| (even another backslash) is put into the string verbatim, but the |
| (first) backslash is not. |
| .RE |
| .TP |
| \f[B]a\f[R] |
| The value on top of the stack is popped. |
| .RS |
| .PP |
| If it is a number, it is truncated and its absolute value is taken. |
| The result mod \f[B]256\f[R] is calculated. |
| If that result is \f[B]0\f[R], push an empty string; otherwise, push a |
| one-character string where the character is the result of the mod |
| interpreted as an ASCII character. |
| .PP |
| If it is a string, then a new string is made. |
| If the original string is empty, the new string is empty. |
| If it is not, then the first character of the original string is used to |
| create the new string as a one-character string. |
| The new string is then pushed onto the stack. |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .TP |
| \f[B]x\f[R] |
| Pops a value off of the top of the stack. |
| .RS |
| .PP |
| If it is a number, it is pushed back onto the stack. |
| .PP |
| If it is a string, it is executed as a macro. |
| .PP |
| This behavior is the norm whenever a macro is executed, whether by this |
| command or by the conditional execution commands below. |
| .RE |
| .TP |
| \f[B]>\f[R]\f[I]r\f[R] |
| Pops two values off of the stack that must be numbers and compares them. |
| If the first value is greater than the second, then the contents of |
| register \f[I]r\f[R] are executed. |
| .RS |
| .PP |
| For example, \f[B]0 1>a\f[R] will execute the contents of register |
| \f[B]a\f[R], and \f[B]1 0>a\f[R] will not. |
| .PP |
| If either or both of the values are not numbers, dc(1) will raise an |
| error and reset (see the \f[B]RESET\f[R] section). |
| .RE |
| .TP |
| \f[B]>\f[R]\f[I]r\f[R]\f[B]e\f[R]\f[I]s\f[R] |
| Like the above, but will execute register \f[I]s\f[R] if the comparison |
| fails. |
| .RS |
| .PP |
| If either or both of the values are not numbers, dc(1) will raise an |
| error and reset (see the \f[B]RESET\f[R] section). |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .TP |
| \f[B]!>\f[R]\f[I]r\f[R] |
| Pops two values off of the stack that must be numbers and compares them. |
| If the first value is not greater than the second (less than or equal |
| to), then the contents of register \f[I]r\f[R] are executed. |
| .RS |
| .PP |
| If either or both of the values are not numbers, dc(1) will raise an |
| error and reset (see the \f[B]RESET\f[R] section). |
| .RE |
| .TP |
| \f[B]!>\f[R]\f[I]r\f[R]\f[B]e\f[R]\f[I]s\f[R] |
| Like the above, but will execute register \f[I]s\f[R] if the comparison |
| fails. |
| .RS |
| .PP |
| If either or both of the values are not numbers, dc(1) will raise an |
| error and reset (see the \f[B]RESET\f[R] section). |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .TP |
| \f[B]<\f[R]\f[I]r\f[R] |
| Pops two values off of the stack that must be numbers and compares them. |
| If the first value is less than the second, then the contents of |
| register \f[I]r\f[R] are executed. |
| .RS |
| .PP |
| If either or both of the values are not numbers, dc(1) will raise an |
| error and reset (see the \f[B]RESET\f[R] section). |
| .RE |
| .TP |
| \f[B]<\f[R]\f[I]r\f[R]\f[B]e\f[R]\f[I]s\f[R] |
| Like the above, but will execute register \f[I]s\f[R] if the comparison |
| fails. |
| .RS |
| .PP |
| If either or both of the values are not numbers, dc(1) will raise an |
| error and reset (see the \f[B]RESET\f[R] section). |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .TP |
| \f[B]!<\f[R]\f[I]r\f[R] |
| Pops two values off of the stack that must be numbers and compares them. |
| If the first value is not less than the second (greater than or equal |
| to), then the contents of register \f[I]r\f[R] are executed. |
| .RS |
| .PP |
| If either or both of the values are not numbers, dc(1) will raise an |
| error and reset (see the \f[B]RESET\f[R] section). |
| .RE |
| .TP |
| \f[B]!<\f[R]\f[I]r\f[R]\f[B]e\f[R]\f[I]s\f[R] |
| Like the above, but will execute register \f[I]s\f[R] if the comparison |
| fails. |
| .RS |
| .PP |
| If either or both of the values are not numbers, dc(1) will raise an |
| error and reset (see the \f[B]RESET\f[R] section). |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .TP |
| \f[B]=\f[R]\f[I]r\f[R] |
| Pops two values off of the stack that must be numbers and compares them. |
| If the first value is equal to the second, then the contents of register |
| \f[I]r\f[R] are executed. |
| .RS |
| .PP |
| If either or both of the values are not numbers, dc(1) will raise an |
| error and reset (see the \f[B]RESET\f[R] section). |
| .RE |
| .TP |
| \f[B]=\f[R]\f[I]r\f[R]\f[B]e\f[R]\f[I]s\f[R] |
| Like the above, but will execute register \f[I]s\f[R] if the comparison |
| fails. |
| .RS |
| .PP |
| If either or both of the values are not numbers, dc(1) will raise an |
| error and reset (see the \f[B]RESET\f[R] section). |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .TP |
| \f[B]!=\f[R]\f[I]r\f[R] |
| Pops two values off of the stack that must be numbers and compares them. |
| If the first value is not equal to the second, then the contents of |
| register \f[I]r\f[R] are executed. |
| .RS |
| .PP |
| If either or both of the values are not numbers, dc(1) will raise an |
| error and reset (see the \f[B]RESET\f[R] section). |
| .RE |
| .TP |
| \f[B]!=\f[R]\f[I]r\f[R]\f[B]e\f[R]\f[I]s\f[R] |
| Like the above, but will execute register \f[I]s\f[R] if the comparison |
| fails. |
| .RS |
| .PP |
| If either or both of the values are not numbers, dc(1) will raise an |
| error and reset (see the \f[B]RESET\f[R] section). |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .TP |
| \f[B]?\f[R] |
| Reads a line from the \f[B]stdin\f[R] and executes it. |
| This is to allow macros to request input from users. |
| .TP |
| \f[B]q\f[R] |
| During execution of a macro, this exits the execution of that macro and |
| the execution of the macro that executed it. |
| If there are no macros, or only one macro executing, dc(1) exits. |
| .TP |
| \f[B]Q\f[R] |
| Pops a value from the stack which must be non-negative and is used the |
| number of macro executions to pop off of the execution stack. |
| If the number of levels to pop is greater than the number of executing |
| macros, dc(1) exits. |
| .TP |
| \f[B],\f[R] |
| Pushes the depth of the execution stack onto the stack. |
| The execution stack is the stack of string executions. |
| The number that is pushed onto the stack is exactly as many as is needed |
| to make dc(1) exit with the \f[B]Q\f[R] command, so the sequence |
| \f[B],Q\f[R] will make dc(1) exit. |
| .SS Status |
| .PP |
| These commands query status of the stack or its top value. |
| .TP |
| \f[B]Z\f[R] |
| Pops a value off of the stack. |
| .RS |
| .PP |
| If it is a number, calculates the number of significant decimal digits |
| it has and pushes the result. |
| It will push \f[B]1\f[R] if the argument is \f[B]0\f[R] with no decimal |
| places. |
| .PP |
| If it is a string, pushes the number of characters the string has. |
| .RE |
| .TP |
| \f[B]X\f[R] |
| Pops a value off of the stack. |
| .RS |
| .PP |
| If it is a number, pushes the \f[I]scale\f[R] of the value onto the |
| stack. |
| .PP |
| If it is a string, pushes \f[B]0\f[R]. |
| .RE |
| .TP |
| \f[B]z\f[R] |
| Pushes the current depth of the stack (before execution of this command) |
| onto the stack. |
| .TP |
| \f[B]y\f[R]\f[I]r\f[R] |
| Pushes the current stack depth of the register \f[I]r\f[R] onto the main |
| stack. |
| .RS |
| .PP |
| Because each register has a depth of \f[B]1\f[R] (with the value |
| \f[B]0\f[R] in the top item) when dc(1) starts, dc(1) requires that each |
| register\[cq]s stack must always have at least one item; dc(1) will give |
| an error and reset otherwise (see the \f[B]RESET\f[R] section). |
| This means that this command will never push \f[B]0\f[R]. |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .SS Arrays |
| .PP |
| These commands manipulate arrays. |
| .TP |
| \f[B]:\f[R]\f[I]r\f[R] |
| Pops the top two values off of the stack. |
| The second value will be stored in the array \f[I]r\f[R] (see the |
| \f[B]REGISTERS\f[R] section), indexed by the first value. |
| .TP |
| \f[B];\f[R]\f[I]r\f[R] |
| Pops the value on top of the stack and uses it as an index into the |
| array \f[I]r\f[R]. |
| The selected value is then pushed onto the stack. |
| .TP |
| \f[B]Y\f[R]\f[I]r\f[R] |
| Pushes the length of the array \f[I]r\f[R] onto the stack. |
| .RS |
| .PP |
| This is a \f[B]non-portable extension\f[R]. |
| .RE |
| .SS Global Settings |
| .PP |
| These commands retrieve global settings. |
| These are the only commands that require multiple specific characters, |
| and all of them begin with the letter \f[B]g\f[R]. |
| Only the characters below are allowed after the character \f[B]g\f[R]; |
| any other character produces a parse error (see the \f[B]ERRORS\f[R] |
| section). |
| .TP |
| \f[B]gl\f[R] |
| Pushes the line length set by \f[B]DC_LINE_LENGTH\f[R] (see the |
| \f[B]ENVIRONMENT VARIABLES\f[R] section) onto the stack. |
| .TP |
| \f[B]gz\f[R] |
| Pushes \f[B]0\f[R] onto the stack if the leading zero setting has not |
| been enabled with the \f[B]-z\f[R] or \f[B]--leading-zeroes\f[R] options |
| (see the \f[B]OPTIONS\f[R] section), non-zero otherwise. |
| .SH REGISTERS |
| .PP |
| Registers are names that can store strings, numbers, and arrays. |
| (Number/string registers do not interfere with array registers.) |
| .PP |
| Each register is also its own stack, so the current register value is |
| the top of the stack for the register. |
| All registers, when first referenced, have one value (\f[B]0\f[R]) in |
| their stack, and it is a runtime error to attempt to pop that item off |
| of the register stack. |
| .PP |
| In non-extended register mode, a register name is just the single |
| character that follows any command that needs a register name. |
| The only exceptions are: a newline (\f[B]`\[rs]n'\f[R]) and a left |
| bracket (\f[B]`['\f[R]); it is a parse error for a newline or a left |
| bracket to be used as a register name. |
| .SS Extended Register Mode |
| .PP |
| Unlike most other dc(1) implentations, this dc(1) provides nearly |
| unlimited amounts of registers, if extended register mode is enabled. |
| .PP |
| If extended register mode is enabled (\f[B]-x\f[R] or |
| \f[B]--extended-register\f[R] command-line arguments are given), then |
| normal single character registers are used \f[I]unless\f[R] the |
| character immediately following a command that needs a register name is |
| a space (according to \f[B]isspace()\f[R]) and not a newline |
| (\f[B]`\[rs]n'\f[R]). |
| .PP |
| In that case, the register name is found according to the regex |
| \f[B][a-z][a-z0-9_]*\f[R] (like bc(1) identifiers), and it is a parse |
| error if the next non-space characters do not match that regex. |
| .SH RESET |
| .PP |
| When dc(1) encounters an error or a signal that it has a non-default |
| handler for, it resets. |
| This means that several things happen. |
| .PP |
| First, any macros that are executing are stopped and popped off the |
| stack. |
| The behavior is not unlike that of exceptions in programming languages. |
| Then the execution point is set so that any code waiting to execute |
| (after all macros returned) is skipped. |
| .PP |
| Thus, when dc(1) resets, it skips any remaining code waiting to be |
| executed. |
| Then, if it is interactive mode, and the error was not a fatal error |
| (see the \f[B]EXIT STATUS\f[R] section), it asks for more input; |
| otherwise, it exits with the appropriate return code. |
| .SH PERFORMANCE |
| .PP |
| Most dc(1) implementations use \f[B]char\f[R] types to calculate the |
| value of \f[B]1\f[R] decimal digit at a time, but that can be slow. |
| This dc(1) does something different. |
| .PP |
| It uses large integers to calculate more than \f[B]1\f[R] decimal digit |
| at a time. |
| If built in a environment where \f[B]DC_LONG_BIT\f[R] (see the |
| \f[B]LIMITS\f[R] section) is \f[B]64\f[R], then each integer has |
| \f[B]9\f[R] decimal digits. |
| If built in an environment where \f[B]DC_LONG_BIT\f[R] is \f[B]32\f[R] |
| then each integer has \f[B]4\f[R] decimal digits. |
| This value (the number of decimal digits per large integer) is called |
| \f[B]DC_BASE_DIGS\f[R]. |
| .PP |
| In addition, this dc(1) uses an even larger integer for overflow |
| checking. |
| This integer type depends on the value of \f[B]DC_LONG_BIT\f[R], but is |
| always at least twice as large as the integer type used to store digits. |
| .SH LIMITS |
| .PP |
| The following are the limits on dc(1): |
| .TP |
| \f[B]DC_LONG_BIT\f[R] |
| The number of bits in the \f[B]long\f[R] type in the environment where |
| dc(1) was built. |
| This determines how many decimal digits can be stored in a single large |
| integer (see the \f[B]PERFORMANCE\f[R] section). |
| .TP |
| \f[B]DC_BASE_DIGS\f[R] |
| The number of decimal digits per large integer (see the |
| \f[B]PERFORMANCE\f[R] section). |
| Depends on \f[B]DC_LONG_BIT\f[R]. |
| .TP |
| \f[B]DC_BASE_POW\f[R] |
| The max decimal number that each large integer can store (see |
| \f[B]DC_BASE_DIGS\f[R]) plus \f[B]1\f[R]. |
| Depends on \f[B]DC_BASE_DIGS\f[R]. |
| .TP |
| \f[B]DC_OVERFLOW_MAX\f[R] |
| The max number that the overflow type (see the \f[B]PERFORMANCE\f[R] |
| section) can hold. |
| Depends on \f[B]DC_LONG_BIT\f[R]. |
| .TP |
| \f[B]DC_BASE_MAX\f[R] |
| The maximum output base. |
| Set at \f[B]DC_BASE_POW\f[R]. |
| .TP |
| \f[B]DC_DIM_MAX\f[R] |
| The maximum size of arrays. |
| Set at \f[B]SIZE_MAX-1\f[R]. |
| .TP |
| \f[B]DC_SCALE_MAX\f[R] |
| The maximum \f[B]scale\f[R]. |
| Set at \f[B]DC_OVERFLOW_MAX-1\f[R]. |
| .TP |
| \f[B]DC_STRING_MAX\f[R] |
| The maximum length of strings. |
| Set at \f[B]DC_OVERFLOW_MAX-1\f[R]. |
| .TP |
| \f[B]DC_NAME_MAX\f[R] |
| The maximum length of identifiers. |
| Set at \f[B]DC_OVERFLOW_MAX-1\f[R]. |
| .TP |
| \f[B]DC_NUM_MAX\f[R] |
| The maximum length of a number (in decimal digits), which includes |
| digits after the decimal point. |
| Set at \f[B]DC_OVERFLOW_MAX-1\f[R]. |
| .TP |
| \f[B]DC_RAND_MAX\f[R] |
| The maximum integer (inclusive) returned by the \f[B]\[cq]\f[R] command, |
| if dc(1). |
| Set at \f[B]2\[ha]DC_LONG_BIT-1\f[R]. |
| .TP |
| Exponent |
| The maximum allowable exponent (positive or negative). |
| Set at \f[B]DC_OVERFLOW_MAX\f[R]. |
| .TP |
| Number of vars |
| The maximum number of vars/arrays. |
| Set at \f[B]SIZE_MAX-1\f[R]. |
| .PP |
| These limits are meant to be effectively non-existent; the limits are so |
| large (at least on 64-bit machines) that there should not be any point |
| at which they become a problem. |
| In fact, memory should be exhausted before these limits should be hit. |
| .SH ENVIRONMENT VARIABLES |
| .PP |
| As \f[B]non-portable extensions\f[R], dc(1) recognizes the following |
| environment variables: |
| .TP |
| \f[B]DC_ENV_ARGS\f[R] |
| This is another way to give command-line arguments to dc(1). |
| They should be in the same format as all other command-line arguments. |
| These are always processed first, so any files given in |
| \f[B]DC_ENV_ARGS\f[R] will be processed before arguments and files given |
| on the command-line. |
| This gives the user the ability to set up \[lq]standard\[rq] options and |
| files to be used at every invocation. |
| The most useful thing for such files to contain would be useful |
| functions that the user might want every time dc(1) runs. |
| Another use would be to use the \f[B]-e\f[R] option to set |
| \f[B]scale\f[R] to a value other than \f[B]0\f[R]. |
| .RS |
| .PP |
| The code that parses \f[B]DC_ENV_ARGS\f[R] will correctly handle quoted |
| arguments, but it does not understand escape sequences. |
| For example, the string \f[B]\[lq]/home/gavin/some dc file.dc\[rq]\f[R] |
| will be correctly parsed, but the string \f[B]\[lq]/home/gavin/some |
| \[dq]dc\[dq] file.dc\[rq]\f[R] will include the backslashes. |
| .PP |
| The quote parsing will handle either kind of quotes, \f[B]\[cq]\f[R] or |
| \f[B]\[lq]\f[R]. |
| Thus, if you have a file with any number of single quotes in the name, |
| you can use double quotes as the outside quotes, as in \f[B]\[lq]some |
| `dc' file.dc\[rq]\f[R], and vice versa if you have a file with double |
| quotes. |
| However, handling a file with both kinds of quotes in |
| \f[B]DC_ENV_ARGS\f[R] is not supported due to the complexity of the |
| parsing, though such files are still supported on the command-line where |
| the parsing is done by the shell. |
| .RE |
| .TP |
| \f[B]DC_LINE_LENGTH\f[R] |
| If this environment variable exists and contains an integer that is |
| greater than \f[B]1\f[R] and is less than \f[B]UINT16_MAX\f[R] |
| (\f[B]2\[ha]16-1\f[R]), dc(1) will output lines to that length, |
| including the backslash newline combo. |
| The default line length is \f[B]70\f[R]. |
| .RS |
| .PP |
| The special value of \f[B]0\f[R] will disable line length checking and |
| print numbers without regard to line length and without backslashes and |
| newlines. |
| .RE |
| .TP |
| \f[B]DC_SIGINT_RESET\f[R] |
| If dc(1) is not in interactive mode (see the \f[B]INTERACTIVE MODE\f[R] |
| section), then this environment variable has no effect because dc(1) |
| exits on \f[B]SIGINT\f[R] when not in interactive mode. |
| .RS |
| .PP |
| However, when dc(1) is in interactive mode, then if this environment |
| variable exists and contains an integer, a non-zero value makes dc(1) |
| reset on \f[B]SIGINT\f[R], rather than exit, and zero makes dc(1) exit. |
| If this environment variable exists and is \f[I]not\f[R] an integer, |
| then dc(1) will exit on \f[B]SIGINT\f[R]. |
| .PP |
| This environment variable overrides the default, which can be queried |
| with the \f[B]-h\f[R] or \f[B]--help\f[R] options. |
| .RE |
| .TP |
| \f[B]DC_TTY_MODE\f[R] |
| If TTY mode is \f[I]not\f[R] available (see the \f[B]TTY MODE\f[R] |
| section), then this environment variable has no effect. |
| .RS |
| .PP |
| However, when TTY mode is available, then if this environment variable |
| exists and contains an integer, then a non-zero value makes dc(1) use |
| TTY mode, and zero makes dc(1) not use TTY mode. |
| .PP |
| This environment variable overrides the default, which can be queried |
| with the \f[B]-h\f[R] or \f[B]--help\f[R] options. |
| .RE |
| .TP |
| \f[B]DC_PROMPT\f[R] |
| If TTY mode is \f[I]not\f[R] available (see the \f[B]TTY MODE\f[R] |
| section), then this environment variable has no effect. |
| .RS |
| .PP |
| However, when TTY mode is available, then if this environment variable |
| exists and contains an integer, a non-zero value makes dc(1) use a |
| prompt, and zero or a non-integer makes dc(1) not use a prompt. |
| If this environment variable does not exist and \f[B]DC_TTY_MODE\f[R] |
| does, then the value of the \f[B]DC_TTY_MODE\f[R] environment variable |
| is used. |
| .PP |
| This environment variable and the \f[B]DC_TTY_MODE\f[R] environment |
| variable override the default, which can be queried with the |
| \f[B]-h\f[R] or \f[B]--help\f[R] options. |
| .RE |
| .TP |
| \f[B]DC_EXPR_EXIT\f[R] |
| If any expressions or expression files are given on the command-line |
| with \f[B]-e\f[R], \f[B]--expression\f[R], \f[B]-f\f[R], or |
| \f[B]--file\f[R], then if this environment variable exists and contains |
| an integer, a non-zero value makes dc(1) exit after executing the |
| expressions and expression files, and a zero value makes dc(1) not exit. |
| .RS |
| .PP |
| This environment variable overrides the default, which can be queried |
| with the \f[B]-h\f[R] or \f[B]--help\f[R] options. |
| .RE |
| .TP |
| \f[B]DC_DIGIT_CLAMP\f[R] |
| When parsing numbers and if this environment variable exists and |
| contains an integer, a non-zero value makes dc(1) clamp digits that are |
| greater than or equal to the current \f[B]ibase\f[R] so that all such |
| digits are considered equal to the \f[B]ibase\f[R] minus 1, and a zero |
| value disables such clamping so that those digits are always equal to |
| their value, which is multiplied by the power of the \f[B]ibase\f[R]. |
| .RS |
| .PP |
| This never applies to single-digit numbers, as per the bc(1) standard |
| (see the \f[B]STANDARDS\f[R] section). |
| .PP |
| This environment variable overrides the default, which can be queried |
| with the \f[B]-h\f[R] or \f[B]--help\f[R] options. |
| .RE |
| .SH EXIT STATUS |
| .PP |
| dc(1) returns the following exit statuses: |
| .TP |
| \f[B]0\f[R] |
| No error. |
| .TP |
| \f[B]1\f[R] |
| A math error occurred. |
| This follows standard practice of using \f[B]1\f[R] for expected errors, |
| since math errors will happen in the process of normal execution. |
| .RS |
| .PP |
| Math errors include divide by \f[B]0\f[R], taking the square root of a |
| negative number, using a negative number as a bound for the |
| pseudo-random number generator, attempting to convert a negative number |
| to a hardware integer, overflow when converting a number to a hardware |
| integer, overflow when calculating the size of a number, and attempting |
| to use a non-integer where an integer is required. |
| .PP |
| Converting to a hardware integer happens for the second operand of the |
| power (\f[B]\[ha]\f[R]), places (\f[B]\[at]\f[R]), left shift |
| (\f[B]H\f[R]), and right shift (\f[B]h\f[R]) operators. |
| .RE |
| .TP |
| \f[B]2\f[R] |
| A parse error occurred. |
| .RS |
| .PP |
| Parse errors include unexpected \f[B]EOF\f[R], using an invalid |
| character, failing to find the end of a string or comment, and using a |
| token where it is invalid. |
| .RE |
| .TP |
| \f[B]3\f[R] |
| A runtime error occurred. |
| .RS |
| .PP |
| Runtime errors include assigning an invalid number to any global |
| (\f[B]ibase\f[R], \f[B]obase\f[R], or \f[B]scale\f[R]), giving a bad |
| expression to a \f[B]read()\f[R] call, calling \f[B]read()\f[R] inside |
| of a \f[B]read()\f[R] call, type errors (including attempting to execute |
| a number), and attempting an operation when the stack has too few |
| elements. |
| .RE |
| .TP |
| \f[B]4\f[R] |
| A fatal error occurred. |
| .RS |
| .PP |
| Fatal errors include memory allocation errors, I/O errors, failing to |
| open files, attempting to use files that do not have only ASCII |
| characters (dc(1) only accepts ASCII characters), attempting to open a |
| directory as a file, and giving invalid command-line options. |
| .RE |
| .PP |
| The exit status \f[B]4\f[R] is special; when a fatal error occurs, dc(1) |
| always exits and returns \f[B]4\f[R], no matter what mode dc(1) is in. |
| .PP |
| The other statuses will only be returned when dc(1) is not in |
| interactive mode (see the \f[B]INTERACTIVE MODE\f[R] section), since |
| dc(1) resets its state (see the \f[B]RESET\f[R] section) and accepts |
| more input when one of those errors occurs in interactive mode. |
| This is also the case when interactive mode is forced by the |
| \f[B]-i\f[R] flag or \f[B]--interactive\f[R] option. |
| .PP |
| These exit statuses allow dc(1) to be used in shell scripting with error |
| checking, and its normal behavior can be forced by using the |
| \f[B]-i\f[R] flag or \f[B]--interactive\f[R] option. |
| .SH INTERACTIVE MODE |
| .PP |
| Like bc(1), dc(1) has an interactive mode and a non-interactive mode. |
| Interactive mode is turned on automatically when both \f[B]stdin\f[R] |
| and \f[B]stdout\f[R] are hooked to a terminal, but the \f[B]-i\f[R] flag |
| and \f[B]--interactive\f[R] option can turn it on in other situations. |
| .PP |
| In interactive mode, dc(1) attempts to recover from errors (see the |
| \f[B]RESET\f[R] section), and in normal execution, flushes |
| \f[B]stdout\f[R] as soon as execution is done for the current input. |
| dc(1) may also reset on \f[B]SIGINT\f[R] instead of exit, depending on |
| the contents of, or default for, the \f[B]DC_SIGINT_RESET\f[R] |
| environment variable (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). |
| .SH TTY MODE |
| .PP |
| If \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all |
| connected to a TTY, then \[lq]TTY mode\[rq] is considered to be |
| available, and thus, dc(1) can turn on TTY mode, subject to some |
| settings. |
| .PP |
| If there is the environment variable \f[B]DC_TTY_MODE\f[R] in the |
| environment (see the \f[B]ENVIRONMENT VARIABLES\f[R] section), then if |
| that environment variable contains a non-zero integer, dc(1) will turn |
| on TTY mode when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] |
| are all connected to a TTY. |
| If the \f[B]DC_TTY_MODE\f[R] environment variable exists but is |
| \f[I]not\f[R] a non-zero integer, then dc(1) will not turn TTY mode on. |
| .PP |
| If the environment variable \f[B]DC_TTY_MODE\f[R] does \f[I]not\f[R] |
| exist, the default setting is used. |
| The default setting can be queried with the \f[B]-h\f[R] or |
| \f[B]--help\f[R] options. |
| .PP |
| TTY mode is different from interactive mode because interactive mode is |
| required in the bc(1) specification (see the \f[B]STANDARDS\f[R] |
| section), and interactive mode requires only \f[B]stdin\f[R] and |
| \f[B]stdout\f[R] to be connected to a terminal. |
| .SS Command-Line History |
| .PP |
| Command-line history is only enabled if TTY mode is, i.e., that |
| \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are connected to |
| a TTY and the \f[B]DC_TTY_MODE\f[R] environment variable (see the |
| \f[B]ENVIRONMENT VARIABLES\f[R] section) and its default do not disable |
| TTY mode. |
| See the \f[B]COMMAND LINE HISTORY\f[R] section for more information. |
| .SS Prompt |
| .PP |
| If TTY mode is available, then a prompt can be enabled. |
| Like TTY mode itself, it can be turned on or off with an environment |
| variable: \f[B]DC_PROMPT\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] |
| section). |
| .PP |
| If the environment variable \f[B]DC_PROMPT\f[R] exists and is a non-zero |
| integer, then the prompt is turned on when \f[B]stdin\f[R], |
| \f[B]stdout\f[R], and \f[B]stderr\f[R] are connected to a TTY and the |
| \f[B]-P\f[R] and \f[B]--no-prompt\f[R] options were not used. |
| The read prompt will be turned on under the same conditions, except that |
| the \f[B]-R\f[R] and \f[B]--no-read-prompt\f[R] options must also not be |
| used. |
| .PP |
| However, if \f[B]DC_PROMPT\f[R] does not exist, the prompt can be |
| enabled or disabled with the \f[B]DC_TTY_MODE\f[R] environment variable, |
| the \f[B]-P\f[R] and \f[B]--no-prompt\f[R] options, and the \f[B]-R\f[R] |
| and \f[B]--no-read-prompt\f[R] options. |
| See the \f[B]ENVIRONMENT VARIABLES\f[R] and \f[B]OPTIONS\f[R] sections |
| for more details. |
| .SH SIGNAL HANDLING |
| .PP |
| Sending a \f[B]SIGINT\f[R] will cause dc(1) to do one of two things. |
| .PP |
| If dc(1) is not in interactive mode (see the \f[B]INTERACTIVE MODE\f[R] |
| section), or the \f[B]DC_SIGINT_RESET\f[R] environment variable (see the |
| \f[B]ENVIRONMENT VARIABLES\f[R] section), or its default, is either not |
| an integer or it is zero, dc(1) will exit. |
| .PP |
| However, if dc(1) is in interactive mode, and the |
| \f[B]DC_SIGINT_RESET\f[R] or its default is an integer and non-zero, |
| then dc(1) will stop executing the current input and reset (see the |
| \f[B]RESET\f[R] section) upon receiving a \f[B]SIGINT\f[R]. |
| .PP |
| Note that \[lq]current input\[rq] can mean one of two things. |
| If dc(1) is processing input from \f[B]stdin\f[R] in interactive mode, |
| it will ask for more input. |
| If dc(1) is processing input from a file in interactive mode, it will |
| stop processing the file and start processing the next file, if one |
| exists, or ask for input from \f[B]stdin\f[R] if no other file exists. |
| .PP |
| This means that if a \f[B]SIGINT\f[R] is sent to dc(1) as it is |
| executing a file, it can seem as though dc(1) did not respond to the |
| signal since it will immediately start executing the next file. |
| This is by design; most files that users execute when interacting with |
| dc(1) have function definitions, which are quick to parse. |
| If a file takes a long time to execute, there may be a bug in that file. |
| The rest of the files could still be executed without problem, allowing |
| the user to continue. |
| .PP |
| \f[B]SIGTERM\f[R] and \f[B]SIGQUIT\f[R] cause dc(1) to clean up and |
| exit, and it uses the default handler for all other signals. |
| The one exception is \f[B]SIGHUP\f[R]; in that case, and only when dc(1) |
| is in TTY mode (see the \f[B]TTY MODE\f[R] section), a \f[B]SIGHUP\f[R] |
| will cause dc(1) to clean up and exit. |
| .SH COMMAND LINE HISTORY |
| .PP |
| dc(1) supports interactive command-line editing. |
| .PP |
| If dc(1) can be in TTY mode (see the \f[B]TTY MODE\f[R] section), |
| history can be enabled. |
| This means that command-line history can only be enabled when |
| \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all |
| connected to a TTY. |
| .PP |
| Like TTY mode itself, it can be turned on or off with the environment |
| variable \f[B]DC_TTY_MODE\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] |
| section). |
| .PP |
| \f[B]Note\f[R]: tabs are converted to 8 spaces. |
| .SH LOCALES |
| .PP |
| This dc(1) ships with support for adding error messages for different |
| locales and thus, supports \f[B]LC_MESSAGES\f[R]. |
| .SH SEE ALSO |
| .PP |
| bc(1) |
| .SH STANDARDS |
| .PP |
| The dc(1) utility operators and some behavior are compliant with the |
| operators in the IEEE Std 1003.1-2017 (\[lq]POSIX.1-2017\[rq]) bc(1) |
| specification at |
| https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html . |
| .SH BUGS |
| .PP |
| None are known. |
| Report bugs at https://git.yzena.com/gavin/bc. |
| .SH AUTHOR |
| .PP |
| Gavin D. |
| Howard <gavin@yzena.com> and contributors. |