diff options
Diffstat (limited to 'contrib/bc/manuals/dc/N.1')
| -rw-r--r-- | contrib/bc/manuals/dc/N.1 | 354 |
1 files changed, 217 insertions, 137 deletions
diff --git a/contrib/bc/manuals/dc/N.1 b/contrib/bc/manuals/dc/N.1 index 39782bf95e5e..5bb0dff18e0a 100644 --- a/contrib/bc/manuals/dc/N.1 +++ b/contrib/bc/manuals/dc/N.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,27 +25,26 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" -.TH "DC" "1" "June 2022" "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[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]] +\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. @@ -62,86 +61,56 @@ 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]-h\f[R], \f[B]--help\f[R] -Prints a usage message and quits. -.TP -\f[B]-v\f[R], \f[B]-V\f[R], \f[B]--version\f[R] -Print the version information (copyright header) and exit. -.TP -\f[B]-i\f[R], \f[B]--interactive\f[R] -Forces interactive mode. -(See the \f[B]INTERACTIVE MODE\f[R] section.) +\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 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 +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 -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 +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 -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). +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]-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. +\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 option does not disable the regular prompt because the read prompt -is only used when the \f[B]?\f[R] command is used. +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 -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. +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 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. -.RS +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]-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. +\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 -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 @@ -189,6 +158,9 @@ exit. 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. @@ -200,6 +172,24 @@ If multiple instances of this option are given, the last is used. 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. @@ -211,6 +201,44 @@ If multiple instances of this option are given, the last is used. 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. @@ -222,20 +250,28 @@ If multiple instances of this option are given, the last is used. 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. +\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 multiple instances of this option are given, the last is used. +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 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]. @@ -248,7 +284,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 @@ -257,7 +292,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 @@ -265,13 +300,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 @@ -279,7 +313,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. @@ -352,25 +385,54 @@ In any other case, use a non-seeded pseudo-random number generator. 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] + 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]. .PP In addition, dc(1) accepts numbers in scientific notation. These have the form \f[B]<number>e<integer>\f[R]. @@ -392,10 +454,8 @@ number string \f[B]FFeA\f[R], the resulting decimal number will be 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 @@ -443,7 +503,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] @@ -675,7 +734,6 @@ a short-circuit operator. 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 @@ -719,7 +777,6 @@ limitations of the pseudo-random number generator. 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] @@ -735,7 +792,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] @@ -757,7 +813,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], \f[B]scale\f[R], and \f[B]seed\f[R]. Also see the \f[B]SYNTAX\f[R] section. @@ -869,7 +924,6 @@ Pushes the maximum (inclusive) integer that can be generated with the 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 @@ -1081,8 +1135,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] @@ -1107,6 +1164,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. @@ -1125,7 +1200,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] @@ -1145,7 +1219,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]. @@ -1157,12 +1230,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 @@ -1178,7 +1256,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 @@ -1193,7 +1270,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. @@ -1210,7 +1286,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. @@ -1230,7 +1305,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] @@ -1297,8 +1371,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). @@ -1402,8 +1476,23 @@ expressions and expression files, and a zero value makes dc(1) not exit. 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] @@ -1472,7 +1561,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 @@ -1485,7 +1573,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 @@ -1505,12 +1592,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 at -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 @@ -1518,7 +1603,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] @@ -1539,7 +1623,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] @@ -1574,7 +1657,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), @@ -1589,19 +1671,17 @@ section). .PP \f[B]Note\f[R]: tabs are converted to 8 spaces. .SH SEE ALSO -.PP bc(1) .SH STANDARDS -.PP -The dc(1) utility operators are compliant with the operators in the IEEE -Std 1003.1-2017 (\[lq]POSIX.1-2017\[rq]) specification at -https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html for -bc(1). +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. |