diff options
Diffstat (limited to 'contrib/bc/manuals/dc/E.1')
| -rw-r--r-- | contrib/bc/manuals/dc/E.1 | 366 |
1 files changed, 240 insertions, 126 deletions
diff --git a/contrib/bc/manuals/dc/E.1 b/contrib/bc/manuals/dc/E.1 index a677bcea0c0c..bc8d66eb3f97 100644 --- a/contrib/bc/manuals/dc/E.1 +++ b/contrib/bc/manuals/dc/E.1 @@ -1,7 +1,7 @@ .\" .\" SPDX-License-Identifier: BSD-2-Clause .\" -.\" Copyright (c) 2018-2021 Gavin D. Howard and contributors. +.\" Copyright (c) 2018-2023 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: @@ -25,21 +25,22 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" -.TH "DC" "1" "June 2021" "Gavin D. Howard" "General Commands Manual" +.TH "DC" "1" "February 2023" "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]-hiPRvVx\f[R]] [\f[B]--version\f[R]] -[\f[B]--help\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[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]\&...] .SH DESCRIPTION -.PP dc(1) is an arbitrary-precision calculator. It uses a stack (reverse Polish notation) to store numbers and results of computations. @@ -56,14 +57,105 @@ 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]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 quits. +Prints a usage message and exits. .TP -\f[B]-v\f[R], \f[B]-V\f[R], \f[B]--version\f[R] -Print the version information (copyright header) and exit. +\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. @@ -83,11 +175,23 @@ In other words, this option sets \f[B]BC_LINE_LENGTH\f[R] to \f[B]0\f[R] 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). +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 @@ -101,8 +205,9 @@ This is a \f[B]non-portable extension\f[R]. \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). +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 @@ -119,76 +224,42 @@ VARIABLES\f[R] section), but only for the read prompt. This is a \f[B]non-portable extension\f[R]. .RE .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. +\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 -This is a \f[B]non-portable extension\f[R]. -.RE -.TP -\f[B]-z\f[R], \f[B]--leading-zeroes\f[R] -Makes bc(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). +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. +\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 -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. +\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 -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 .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) read from \f[B]stdin\f[R]. +\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 @@ -198,7 +269,6 @@ 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 @@ -207,7 +277,7 @@ to \f[B]stdout\f[R]. \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. +\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 @@ -215,13 +285,12 @@ 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. +\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 @@ -229,7 +298,6 @@ 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. @@ -264,30 +332,57 @@ precision of any operations (with exceptions). 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. .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] + their position in the +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]). -If a digit or letter makes no sense with the current value of -\f[B]ibase\f[R], they are set to the value of the highest valid digit in -\f[B]ibase\f[R]. .PP -Single-character numbers (i.e., \f[B]A\f[R] alone) take the value that -they would have if they were valid digits, regardless of the value of -\f[B]ibase\f[R]. +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]F\f[R] alone always equals decimal \f[B]15\f[R]. +\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]. .SH COMMANDS -.PP The valid commands are listed below. .SS Printing -.PP These commands are used for printing. .TP \f[B]p\f[R] @@ -324,7 +419,6 @@ without altering anything. 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] @@ -514,7 +608,6 @@ a short-circuit operator. 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] @@ -530,7 +623,6 @@ Swaps (\[lq]reverses\[rq]) the two top items on the stack. \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] @@ -552,7 +644,6 @@ 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], and \f[B]scale\f[R]. Also see the \f[B]SYNTAX\f[R] section. @@ -619,7 +710,6 @@ stack. 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 @@ -831,8 +921,11 @@ 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 +.RS .PP +This is a \f[B]non-portable extension\f[R]. +.RE +.SS Status These commands query status of the stack or its top value. .TP \f[B]Z\f[R] @@ -857,6 +950,24 @@ stack. If it is a string, pushes \f[B]0\f[R]. .RE .TP +\f[B]u\f[R] +Pops one value off of the stack. +If the value is a number, this pushes \f[B]1\f[R] onto the stack. +Otherwise (if it is a string), it pushes \f[B]0\f[R]. +.RS +.PP +This is a \f[B]non-portable extension\f[R]. +.RE +.TP +\f[B]t\f[R] +Pops one value off of the stack. +If the value is a string, this pushes \f[B]1\f[R] onto the stack. +Otherwise (if it is a number), it pushes \f[B]0\f[R]. +.RS +.PP +This is a \f[B]non-portable extension\f[R]. +.RE +.TP \f[B]z\f[R] Pushes the current depth of the stack (before execution of this command) onto the stack. @@ -875,7 +986,6 @@ This means that this command will never push \f[B]0\f[R]. 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] @@ -895,7 +1005,6 @@ Pushes the length of the array \f[I]r\f[R] onto the stack. 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]. @@ -907,12 +1016,17 @@ section). 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]gx\f[R] +Pushes \f[B]1\f[R] onto the stack if extended register mode is on, +\f[B]0\f[R] otherwise. +See the \f[I]Extended Register Mode\f[R] subsection of the +\f[B]REGISTERS\f[R] section for more information. +.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 @@ -928,7 +1042,6 @@ 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 @@ -943,7 +1056,6 @@ 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. @@ -960,7 +1072,6 @@ 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. @@ -980,7 +1091,6 @@ 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] @@ -1042,8 +1152,8 @@ 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 -dc(1) recognizes the following environment variables: +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). @@ -1141,15 +1251,29 @@ 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 non-zero value makes dc(1) not -exit. +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 -.SH EXIT STATUS +.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 dc(1) returns the following exit statuses: .TP \f[B]0\f[R] @@ -1216,7 +1340,6 @@ 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 @@ -1229,7 +1352,6 @@ 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 @@ -1249,12 +1371,10 @@ 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 (https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html), -and interactive mode requires only \f[B]stdin\f[R] and \f[B]stdout\f[R] -to be connected to a terminal. +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 @@ -1262,7 +1382,6 @@ a TTY and the \f[B]DC_TTY_MODE\f[R] environment variable (see the 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] @@ -1283,7 +1402,6 @@ 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] @@ -1318,7 +1436,6 @@ 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), @@ -1333,23 +1450,20 @@ 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 are compliant with the operators in the -bc(1) IEEE Std 1003.1-2017 -(\[lq]POSIX.1-2017\[rq]) (https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html) -specification. +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. +Report bugs at https://git.gavinhoward.com/gavin/bc . .SH AUTHOR -.PP -Gavin D. -Howard <gavin@yzena.com> and contributors. +Gavin D. Howard \c +.MT gavin@gavinhoward.com +.ME \c +\ and contributors. |