| dc(1) -- arbitrary-precision reverse-Polish notation calculator |
| =============================================================== |
| |
| SYNOPSIS |
| -------- |
| |
| `dc` [`-hiPvVx`] [`--version`] [`--help`] [`--interactive`] [`--no-prompt`] |
| [`--extended-register`] [`-e` *expr*] [`--expression=`*expr*...] |
| [`-f` *file*...] [`-file=`*file*...] [*file*...] |
| |
| DESCRIPTION |
| ----------- |
| |
| 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. |
| |
| If no files are given on the command-line as extra arguments (i.e., not as `-f` |
| or `--file` arguments), then dc(1) reads from `stdin`. Otherwise, those files |
| are processed, and dc(1) will then exit. |
| |
| This is different from the dc(1) on OpenBSD and possibly other dc(1) |
| implementations, where `-e` (`--expression`) and `-f` (`--file`) arguments cause |
| dc(1) to execute them and exit. The reason for this is that this dc(1) allows |
| users to set arguments in the environment variable `DC_ENV_ARGS` (see the |
| ENVIRONMENT VARIABLES section). Any expressions given on the command-line should |
| be used to set up a standard environment. For example, if a user wants the |
| `scale` always set to `10`, they can set `DC_ENV_ARGS` to "-e 10k", and this |
| dc(1) will always start with a `scale` of `10`. |
| |
| If users want to have dc(1) exit after processing all input from `-e` and `-f` |
| arguments (and their equivalents), then they can just simply add "-e q" as the |
| last command-line argument. |
| |
| OPTIONS |
| ------- |
| |
| The following are the options that dc(1) accepts. |
| |
| * `-h`, `--help`: |
| Prints a usage message and quits. |
| |
| * `-v`, `-V`, `--version`: |
| Print the version information (copyright header) and exit. |
| |
| * `-i`, `--interactive`: |
| Forces interactive mode. |
| |
| dc(1) has an interactive mode and a non-interactive mode. The interactive |
| mode is turned on automatically when both `stdin` and `stdout` are hooked to |
| a terminal, but this flag can turn it on in other cases. In interactive |
| mode, dc(1) attempts to recover from errors (see the RESET section), and in |
| normal execution, flushes `stdout` as soon as execution is done for the |
| current input. |
| |
| This is a **non-portable extension**. |
| |
| * `-P`, `--no-prompt`: |
| Disables the prompt in interactive mode. This is mostly for those users that |
| do not want a prompt or are not used to having them in `dc`. Most of those |
| users would want to put this option in `DC_ENV_ARGS`. |
| |
| If the prompt has been disabled while building dc(1), this option is a |
| no-op. |
| |
| This is a **non-portable extension**. |
| |
| * `-x` `--extended-register`: |
| Enables extended register mode. See the REGISTERS section for more |
| information. |
| |
| This is a **non-portable extension**. |
| |
| * `-e` *expr*, `--expression`=*expr*: |
| Evaluates `expr`. 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. |
| |
| In other dc(1) implementations, this option causes the program to execute |
| the expressions and then exit. This dc(1) does not, unless the |
| `DC_EXPR_EXIT` is defined (see the ENVIRONMENT VARIABLES section). |
| |
| This is a **non-portable extension**. |
| |
| * `-f` *file*, `--file`=*file*: |
| Reads in `file` and evaluates it. If expressions are also given (see above), |
| the expressions are evaluated in the order given. |
| |
| In other dc(1) implementations, this option causes the program to execute |
| the files and then exit. This dc(1) does not, unless the |
| `DC_EXPR_EXIT` is defined (see the ENVIRONMENT VARIABLES section). |
| |
| This is a **non-portable extension**. |
| |
| STDOUT |
| ------ |
| |
| Any non-error output is written to `stdout`. |
| |
| **Note**: Unlike other dc(1) implementations, this dc(1) will issue a fatal |
| error (see the EXIT STATUS section) if it cannot write to `stdout`, so if |
| `stdout` is closed, as in `dc <file> >&-`, it will quit with an error. This is |
| done so that dc(1) can report problems when `stdout` is redirected to a file. |
| |
| If there are scripts that depend on the behavior of other dc(1) implementations, |
| it is recommended that those scripts be changed to redirect `stdout` to |
| `/dev/null`. |
| |
| STDERR |
| ------ |
| |
| Any error output is written to `stderr`. |
| |
| **Note**: Unlike other dc(1) implementations, this dc(1) will issue a fatal |
| error (see the EXIT STATUS section) if it cannot write to `stderr`, so if |
| `stderr` is closed, as in `dc <file> 2>&-`, it will quit with an error. This is |
| done so that dc(1) can report problems when `stderr` is redirected to a file. |
| |
| If there are scripts that depend on the behavior of other dc(1) implementations, |
| it is recommended that those scripts be changed to redirect `stderr` to |
| `/dev/null`. |
| |
| SYNTAX |
| ------ |
| |
| `ibase` is a register (see the REGISTERS section) determining how to interpret |
| constant numbers. It is the "input" base, or the number base used for |
| interpreting input numbers. `ibase` is initially `10`. The max allowable value |
| for `ibase` is `16`. The min allowable value for `ibase` is `2`. The max |
| allowable value for `ibase` can be queried in dc(1) programs with the `T` |
| command. |
| |
| `obase` is a register (see the REGISTERS section) determining how to output |
| results. It is the "output" base, or the number base used for outputting |
| numbers. `obase` is initially `10`. The max allowable value for `obase` is |
| `DC_BASE_MAX`. The min allowable value for `obase` is `2` unless dc(1) was built |
| with the extra math option. If it was, then the min allowable value is `0`. In |
| this case, if `obase` is `0`, values are output in scientific notation, and if |
| `obase` is `1`, values are output in engineering notation. (Outputting in |
| scientific or engineering notation are **non-portable extensions**.) The max |
| allowable value for `obase` can be queried in dc(1) programs with the `U` |
| command. |
| |
| The **scale** of an expression is the number of digits in the result of the |
| expression right of the decimal point, and `scale` is a register (see the |
| REGISTERS section) that sets the precision of any operations (with exceptions). |
| `scale` is initially `0`. `scale` cannot be negative. The max allowable value |
| for `scale` can be queried in dc(1) programs with the `V` command. |
| |
| Each item in the input source code, either a number (see the NUMBERS section) or |
| a command (see the COMMANDS section), is processed and executed, in order. Input |
| is processed immediately when entered. |
| |
| ### Comments |
| |
| Comments go from `#` until, and not including, the next newline. This is a |
| **non-portable extension**. |
| |
| NUMBERS |
| ------- |
| |
| Numbers are strings made up of digits, uppercase letters up to `F`, and at most |
| `1` period for a radix. Numbers can have up to `DC_NUM_MAX` digits. Uppercase |
| letters equal `9` + their position in the alphabet (i.e., `A` equals `10`, or |
| `9 + 1`). If a digit or letter makes no sense with the current value of `ibase`, |
| they are set to the value of the highest valid digit in `ibase`. |
| |
| Single-character numbers (i.e., `A`) take the value that they would have if they |
| were valid digits, regardless of the value of `ibase`. This means that `A` |
| always equals decimal `10` and `F` always equals decimal `15`. |
| |
| In addition, if dc(1) was built with the extra math option, it accepts numbers |
| in scientific notation. For dc(1), an example is `1.89237e9`, which is equal to |
| `1892370000`. Negative exponents are also allowed, so `4.2890e_3` is equal to |
| `0.0042890`. |
| |
| **WARNING**: Both the number and the exponent in scientific notation are |
| interpreted according to the current `ibase`, but the number is still multiplied |
| by `10^exponent` regardless of the current `ibase`. For example, if `ibase` is |
| `16` and dc(1) is given the number string `"FFeA"`, the resulting decimal number |
| will be `2550000000000`, and if dc(1) is given the number string `"10e_4"`, the |
| resulting decimal number will be `0.0016`. |
| |
| Accepting input as scientific notation is a **non-portable extension**. |
| |
| COMMANDS |
| -------- |
| |
| The valid commands are listed below. |
| |
| ### Printing |
| |
| These commands are used for printing. |
| |
| Note that if dc(1) has been built with the extra math option enabled, both |
| scientific notation and engineering notation are available for printing numbers. |
| Scientific notation is activated by assigning `0` to `obase` using `0o` (in any |
| other context, an `obase` of `0` is invalid), and engineering notation is |
| activated by assigning `1` to `obase` using `1o` (which is also invalid in any |
| other context). To deactivate them, just assign a different value to `obase`. |
| |
| Printing numbers in scientific notation and/or engineering notation is a |
| **non-portable extension**. |
| |
| * `p`: |
| Prints the value on top of the stack, whether number or string, and prints a |
| newline after. |
| |
| This does not alter the stack. |
| |
| * `n`: |
| Prints the value on top of the stack, whether number or string, and pops it |
| off of the stack. |
| |
| * `P`: |
| Pops a value off the stack. |
| |
| If the value is a number, it is truncated and the absolute value of the |
| result is printed as though `obase` is `UCHAR_MAX + 1` and each digit is |
| interpreted as an ASCII character, making it a byte stream. |
| |
| If the value is a string, it is printed without a trailing newline. |
| |
| This is a **non-portable extension**. |
| |
| * `f`: |
| Prints the entire contents of the stack, in order from newest to oldest, |
| without altering anything. |
| |
| Users should use this command when they get lost. |
| |
| ### Arithmetic |
| |
| These are the commands used for arithmetic. |
| |
| * `+`: |
| The top two values are popped off the stack, added, and the result is pushed |
| onto the stack. The **scale** of the result is equal to the max **scale** of |
| both operands. |
| |
| * `-`: |
| The top two values are popped off the stack, subtracted, and the result is |
| pushed onto the stack. The **scale** of the result is equal to the max |
| **scale** of both operands. |
| |
| * `*`: |
| The top two values are popped off the stack, multiplied, and the result is |
| pushed onto the stack. If `a` is the **scale** of the first expression and |
| `b` is the **scale** of the second expression, the **scale** of the result |
| is equal to `min(a+b,max(scale,a,b))` where `min` and `max` return the |
| obvious values. |
| |
| * `/`: |
| The top two values are popped off the stack, divided, and the result is |
| pushed onto the stack. The **scale** of the result is equal to `scale`. |
| |
| The first value popped off of the stack must be non-zero. |
| |
| * `%`: |
| The top two values are popped off the stack, remaindered, and the result is |
| pushed onto the stack. |
| |
| Remaindering is equivalent to 1) Computing `a/b` to current `scale`, and 2) |
| Using the result of step 1 to calculate `a-(a/b)*b` to **scale** |
| `max(scale + scale(b), scale(a))`. |
| |
| The first value popped off of the stack must be non-zero. |
| |
| * `~`: |
| 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 `x y / x y %` except that `x` and `y` are only |
| evaluated once. |
| |
| The first value popped off of the stack must be non-zero. |
| |
| This is a **non-portable extension**. |
| |
| * `^`: |
| 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 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. |
| |
| * `v`: |
| The top value is popped off the stack, its square root is computed, and the |
| result is pushed onto the stack. The **scale** of the result is equal to |
| `scale`. |
| |
| The value popped off of the stack must be non-negative. |
| |
| * `_`: |
| If this command *immediately* precedes a number (i.e., no spaces or other |
| commands), then that number is input as a negative number. |
| |
| 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 |
| **non-portable extension**. |
| |
| * `b`: |
| 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. |
| |
| This is a **non-portable extension**. |
| |
| * `|`: |
| The top three values are popped off the stack, a modular exponentiation is |
| computed, and the result is pushed onto the stack. |
| |
| 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. |
| |
| This is a **non-portable extension**. |
| |
| * `$`: |
| The top value is popped off the stack and copied, and the copy is truncated |
| and pushed onto the stack. |
| |
| This is a **non-portable extension**. |
| |
| * `@`: |
| 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. |
| |
| The first value popped off of the stack must be an integer and non-negative. |
| |
| This is a **non-portable extension**. |
| |
| * `H`: |
| The top two values are popped off the stack, and the second is shifted left |
| (radix shifted right) to the value of the first. |
| |
| The first value popped off of the stack must be an integer and non-negative. |
| |
| This is a **non-portable extension**. |
| |
| * `h`: |
| The top two values are popped off the stack, and the second is shifted right |
| (radix shifted left) to the value of the first. |
| |
| The first value popped off of the stack must be an integer and non-negative. |
| |
| This is a **non-portable extension**. |
| |
| * `G`: |
| The top two values are popped off of the stack, they are compared, and a `1` |
| is pushed if they are equal, or `0` otherwise. |
| |
| This is a **non-portable extension**. |
| |
| * `N`: |
| The top value is popped off of the stack, and if it a `0`, a `1` is pushed; |
| otherwise, a `0` is pushed. |
| |
| This is a **non-portable extension**. |
| |
| * `(`: |
| The top two values are popped off of the stack, they are compared, and a `1` |
| is pushed if the first is less than the second, or `0` otherwise. |
| |
| This is a **non-portable extension**. |
| |
| * `{`: |
| The top two values are popped off of the stack, they are compared, and a `1` |
| is pushed if the first is less than or equal to the second, or `0` |
| otherwise. |
| |
| This is a **non-portable extension**. |
| |
| * `)`: |
| The top two values are popped off of the stack, they are compared, and a `1` |
| is pushed if the first is greater than the second, or `0` otherwise. |
| |
| This is a **non-portable extension**. |
| |
| * `}`: |
| The top two values are popped off of the stack, they are compared, and a `1` |
| is pushed if the first is greater than or equal to the second, or `0` |
| otherwise. |
| |
| This is a **non-portable extension**. |
| |
| * `M`: |
| The top two values are popped off of the stack. If they are both non-zero, a |
| `1` is pushed onto the stack. If either of them is zero, or both of them |
| are, then a `0` is pushed onto the stack. |
| |
| This is like the `&&` operator in bc(1), and it is not a short-circuit |
| operator. |
| |
| This is a **non-portable extension**. |
| |
| * `m`: |
| The top two values are popped off of the stack. If at least one of them is |
| non-zero, a `1` is pushed onto the stack. If both of them are zero, then a |
| `0` is pushed onto the stack. |
| |
| This is like the `||` operator in bc(1), and it is not a short-circuit |
| operator. |
| |
| This is a **non-portable extension**. |
| |
| ### Stack Control |
| |
| These commands control the stack. |
| |
| * `c`: |
| Removes all items from ("clears") the stack. |
| |
| * `d`: |
| Copies the item on top of the stack ("duplicates") and pushes the copy onto |
| the stack. |
| |
| * `r`: |
| Swaps ("reverses") the two top items on the stack. |
| |
| * `R`: |
| Pops ("removes") the top value from the stack. |
| |
| ### Register Control |
| |
| These commands control registers (see the REGISTERS section). |
| |
| * `s`*r*: |
| Pops the value off the top of the stack and stores it into register `r`. |
| |
| * `l`*r*: |
| Copies the value in register `r` and pushes it onto the stack. This does not |
| alter the contents of `r`. |
| |
| * `S`*r*: |
| Pops the value off the top of the (main) stack and pushes it onto the stack |
| of register `r`. The previous value of the register becomes inaccessible. |
| |
| * `L`*r*: |
| Pops the value off the top of the stack for register `r` and push it onto |
| the main stack. The previous value in the stack for register `r`, if any, is |
| now accessible via the `l`*r* command. |
| |
| ### Parameters |
| |
| These commands control the values of `ibase`, `obase`, and `scale` (see the |
| SYNTAX section). |
| |
| * `i`: |
| Pops the value off of the top of the stack and uses it to set `ibase`, which |
| must be between `2` and `16`, inclusive. |
| |
| If the value on top of the stack has any **scale**, the **scale** is |
| ignored. |
| |
| * `o`: |
| Pops the value off of the top of the stack and uses it to set `obase`, which |
| must be between `2` and `DC_BASE_MAX`, inclusive (see bc(1)). The value can |
| be either `0` or `1` if dc(1) was built with the extra math option. |
| |
| If the value on top of the stack has any **scale**, the **scale** is |
| ignored. |
| |
| * `k`: |
| Pops the value off of the top of the stack and uses it to set `scale`, which |
| must be non-negative. |
| |
| If the value on top of the stack has any **scale**, the **scale** is |
| ignored. |
| |
| * `I`: |
| Pushes the current value of `ibase` onto the main stack. |
| |
| * `O`: |
| Pushes the current value of `obase` onto the main stack. |
| |
| * `K`: |
| Pushes the current value of `scale` onto the main stack. |
| |
| * `T`: |
| Pushes the maximum allowable value of `ibase` onto the main stack. |
| |
| This is a **non-portable extension**. |
| |
| * `U`: |
| Pushes the maximum allowable value of `obase` onto the main stack. |
| |
| This is a **non-portable extension**. |
| |
| * `V`: |
| Pushes the maximum allowable value of `scale` onto the main stack. |
| |
| This is a **non-portable extension**. |
| |
| ### Strings |
| |
| The following commands control strings. |
| |
| dc(1) can work with both numbers and strings, and registers (see the REGISTERS |
| section) can hold both strings and numbers. dc(1) always knows whether the |
| contents of a register are a string or a number. |
| |
| While arithmetic operations have to have numbers, and will print an error if |
| given a string, other commands accept strings. |
| |
| Strings can also be executed as macros. For example, if the string `[1pR]` is |
| executed as a macro, then the code `1pR` is executed, meaning that the `1` will |
| be printed with a newline after and then popped from the stack. |
| |
| * `[`*characters*`]`: |
| Makes a string containing *characters* and pushes it onto the stack. |
| |
| If there are brackets (`[` and `]`) in the string, then they must be |
| balanced. Unbalanced brackets can be escaped using a backslash (`\`) |
| character. |
| |
| 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. |
| |
| * `a`: |
| The value on top of the stack is popped. |
| |
| If it is a number, it is truncated and its absolute value is taken. The |
| result mod `UCHAR_MAX + 1` is calculated. If that result is `0`, push an |
| empty string; otherwise, push a one-character string where the character is |
| the result of the mod interpreted as an ASCII character. |
| |
| 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. |
| |
| This is a **non-portable extension**. |
| |
| * `x`: |
| Pops a value off of the top of the stack. |
| |
| If it is a number, it is pushed onto the stack. |
| |
| If it is a string, it is executed as a macro. |
| |
| This behavior is the norm whenever a macro is executed, whether by this |
| command or by the conditional execution commands below. |
| |
| * `>`*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 |
| `r` are executed. |
| |
| For example, `0 1>a` will execute the contents of register `a`, and `1 0>a` |
| will not. |
| |
| * `>`*r*`e`*s*: |
| Like the above, but will execute register `s` if the comparison fails. |
| |
| This is a **non-portable extension**. |
| |
| * `!>`*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 `r` are executed. |
| |
| * `!>`*r*`e`*s*: |
| Like the above, but will execute register `s` if the comparison fails. |
| |
| This is a **non-portable extension**. |
| |
| * `<`*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 `r` |
| are executed. |
| |
| * `<`*r*`e`*s*: |
| Like the above, but will execute register `s` if the comparison fails. |
| |
| This is a **non-portable extension**. |
| |
| * `!<`*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 `r` are executed. |
| |
| * `!<`*r*`e`*s*: |
| Like the above, but will execute register `s` if the comparison fails. |
| |
| This is a **non-portable extension**. |
| |
| * `=`*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 `r` |
| are executed. |
| |
| * `=`*r*`e`*s*: |
| Like the above, but will execute register `s` if the comparison fails. |
| |
| This is a **non-portable extension**. |
| |
| * `!=`*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 |
| `r` are executed. |
| |
| * `!=`*r*`e`*s*: |
| Like the above, but will execute register `s` if the comparison fails. |
| |
| This is a **non-portable extension**. |
| |
| * `?`: |
| Reads a line from the `stdin` and executes it. This is to allow macros to |
| request input from users. |
| |
| * `q`: |
| 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. |
| |
| * `Q`: |
| 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. |
| |
| ### Status |
| |
| These commands query status of the stack or its top value. |
| |
| * `Z`: |
| Pops a value off of the stack. |
| |
| If it is a number, calculates the number of significant decimal digits it |
| has and pushes the result. |
| |
| If it is a string, pushes the number of characters the string has. |
| |
| * `X`: |
| Pops a value off of the stack. |
| |
| If it is a number, pushes the **scale** of the value onto the stack. |
| |
| If it is a string, pushes `0`. |
| |
| * `z`: |
| Pushes the current stack depth (before execution of this command). |
| |
| ### Arrays |
| |
| These commands manipulate arrays. |
| |
| * `:`*r*: |
| Pops the top two values off of the stack. The second value will be stored in |
| the array `r` (see the REGISTERS section), indexed by the first value. |
| |
| * `;`*r*: |
| Pops the value on top of the stack and uses it as an index into the array |
| `r`. The selected value is then pushed onto the stack. |
| |
| REGISTERS |
| --------- |
| |
| Registers are names that can store strings, numbers, and arrays. (Number/string |
| registers do not interfere with array registers.) |
| |
| 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 |
| (`0`) in their stack. |
| |
| In non-extended register mode, a register name is just the single character that |
| follows any command that needs a register name. The only exception is a newline |
| (`'\n'`); it is a parse error for a newline to be used as a register name. |
| |
| ### Extended Register Mode |
| |
| Unlike most other dc(1) implentations, this dc(1) provides nearly unlimited |
| amounts of registers, if extended register mode is enabled. |
| |
| If extended register mode is enabled (`-x` or `--extended-register` command-line |
| arguments are given), then normal single character registers are used |
| ***unless*** the character immediately following a command that needs a register |
| name is a space (according to `isspace()`) and not a newline (`'\n'`). |
| |
| In that case, the register name is found according to the regex |
| `[a-z][a-z0-9_]*` (like bc(1)), and it is a parse error if the next |
| non-space characters do not match that regex. |
| |
| RESET |
| ----- |
| |
| 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. |
| |
| 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 |
| functions returned) is skipped. |
| |
| 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 |
| EXIT STATUS section), it asks for more input; otherwise, it exits with the |
| appropriate return code. |
| |
| PERFORMANCE |
| ----------- |
| |
| Most dc(1) implementations use `char` types to calculate the value of `1` |
| decimal digit at a time, but that can be slow. This dc(1) does something |
| different. |
| |
| It uses large integers to calculate more than `1` decimal digit at a time. If |
| built in a environment where `DC_LONG_BIT` (see the LIMITS section) is `64`, |
| then each integer has `9` decimal digits. If built in an environment where |
| `DC_LONG_BIT` is `32` then each integer has `4` decimal digits. This value (the |
| number of decimal digits per large integer) is called `DC_BASE_DIGS`. |
| |
| In addition, this dc(1) uses an even larger integer for overflow checking. This |
| integer type depends on the value of `DC_LONG_BIT`, but is always at least twice |
| as large as the integer type used to store digits. |
| |
| LIMITS |
| ------ |
| |
| The following are the limits on dc(1): |
| |
| * `DC_LONG_BIT`: |
| The number of bits in the `long` 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 PERFORMANCE section). |
| |
| * `DC_BASE_DIGS`: |
| The number of decimal digits per large integer (see the PERFORMANCE |
| section). Depends on `DC_LONG_BIT`. |
| |
| * `DC_BASE_POW`: |
| The max decimal number that each large integer can store (see |
| `DC_BASE_DIGS`) plus `1`. Depends on `DC_BASE_DIGS`. |
| |
| * `DC_OVERFLOW_MAX`: |
| The max number that the overflow type (see the PERFORMANCE section) can |
| hold. Depends on `DC_LONG_BIT`. |
| |
| * `DC_BASE_DIGS`: |
| The number of decimal digits per large integer (see the PERFORMANCE |
| section). |
| |
| * `DC_BASE_MAX`: |
| The maximum output base. Set at `DC_BASE_POW`. |
| |
| * `DC_DIM_MAX`: |
| The maximum size of arrays. Set at `SIZE_MAX-1`. |
| |
| * `DC_SCALE_MAX`: |
| The maximum `scale`. Set at `DC_OVERFLOW_MAX-1`. |
| |
| * `DC_STRING_MAX`: |
| The maximum length of strings. Set at `DC_OVERFLOW_MAX-1`. |
| |
| * `DC_NAME_MAX`: |
| The maximum length of identifiers. Set at `DC_OVERFLOW_MAX-1`. |
| |
| * `DC_NUM_MAX`: |
| The maximum length of a number (in decimal digits), which includes digits |
| after the decimal point. Set at `DC_OVERFLOW_MAX-1`. |
| |
| * Exponent: |
| The maximum allowable exponent (positive or negative). Set at |
| `DC_OVERFLOW_MAX`. |
| |
| * Number of vars: |
| The maximum number of vars/arrays. Set at `SIZE_MAX-1`. |
| |
| 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. |
| |
| ENVIRONMENT VARIABLES |
| --------------------- |
| |
| dc(1) recognizes the following environment variables: |
| |
| * `DC_ENV_ARGS`: |
| 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 `DC_ENV_ARGS` will be processed |
| before files given on the command-line. This gives the user the ability to |
| set up "standard" 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 `-e` |
| option to set `scale` to a value other than `0`. |
| |
| * `DC_LINE_LENGTH`: |
| If this environment variable exists and contains an integer that is greater |
| than `1` and is less than `UINT16_MAX` (`2^16-1`), dc(1) will output lines |
| to that length, including the backslash newline combo. The default line |
| length is `70`. |
| |
| * `DC_EXPR_EXIT`: |
| If this variable exists (no matter the contents), dc(1) will exit |
| immediately after executing expressions and files given by the `-e` and/or |
| `-f` command-line options (and any equivalents). |
| |
| EXIT STATUS |
| ----------- |
| |
| dc(1) returns the following exit statuses: |
| |
| * `0`: |
| No error. |
| |
| * `1`: |
| A math error occurred. This follows standard practice of using `1` for |
| expected errors, since math errors will happen in the process of normal |
| execution. |
| |
| Math errors include divide by `0`, taking the square root of a negative |
| number, attempting to convert a negative number to a hardware integer, |
| overflow when converting a number to a hardware integer, and attempting to |
| use a non-integer where an integer is required. |
| |
| Converting to a hardware integer happens for the second operand of the power |
| (`^`), places (`@`), left shift (`H`), and right shift (`h`) operators. |
| |
| * `2`: |
| A parse error occurred. |
| |
| Parse errors include unexpected `EOF`, using an invalid character, failing |
| to find the end of a string or comment, and using a token where it is |
| invalid. |
| |
| * `3`: |
| A runtime error occurred. |
| |
| Runtime errors include assigning an invalid number to `ibase`, `obase`, or |
| `scale`; give a bad expression to a `read()` call, calling `read()` inside |
| of a `read()` call, type errors, and attempting an operation when the stack |
| has too few elements. |
| |
| * `4`: |
| A fatal error occurred. |
| |
| 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. |
| |
| The exit status `4` is special; when a fatal error occurs, dc(1) always exits |
| and returns `4`, no matter what mode dc(1) is in. |
| |
| The other statuses will only be returned when dc(1) is not in interactive mode, |
| since dc(1) resets its state (see the RESET 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 `-i` option. |
| |
| These exit statuses allow dc(1) to be used in shell scripting with error |
| checking, and its normal behavior can be forced by using `-i`. |
| |
| SIGNAL HANDLING |
| --------------- |
| |
| If dc(1) has been compiled with the signal handling, sending a `SIGINT` will |
| cause dc(1) to stop execution of the current input and reset (see the RESET |
| section), asking for more input. |
| |
| Otherwise, `SIGTERM` and `SIGQUIT` cause dc(1) to clean up and exit, and it uses |
| the default handler for all other signals. |
| |
| If dc(1) has not been compiled with signal handling, it uses the default signal |
| handlers for all signals. |
| |
| COMMAND LINE HISTORY |
| -------------------- |
| |
| dc(1) supports interactive command-line editing, if compiled with the history |
| option enabled. If `stdin` is hooked to a terminal, it is enabled. Previous |
| lines can be recalled and edited with the arrow keys. |
| |
| **Note**: when dc(1) is built with history support, tabs are converted to 8 |
| spaces. |
| |
| LOCALES |
| ------- |
| |
| This dc(1) ships with support for adding error messages for different locales. |
| |
| SEE ALSO |
| -------- |
| |
| bc(1) |
| |
| STANDARDS |
| --------- |
| |
| The dc(1) utility operators are compliant with the operators in the bc(1) |
| [IEEE Std 1003.1-2017 (“POSIX.1-2017”)][1] specification. |
| |
| AUTHOR |
| ------ |
| |
| This dc(1) was made from scratch by Gavin D. Howard. |
| |
| BUGS |
| ---- |
| |
| None are known. Report bugs at https://github.com/gavinhoward/bc. |
| |
| [1]: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html |