diff options
Diffstat (limited to 'manuals/bc/H.1')
| -rw-r--r-- | manuals/bc/H.1 | 511 |
1 files changed, 398 insertions, 113 deletions
diff --git a/manuals/bc/H.1 b/manuals/bc/H.1 index 2fab932c..d477dc8a 100644 --- a/manuals/bc/H.1 +++ b/manuals/bc/H.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,26 +25,33 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" -.TH "BC" "1" "June 2021" "Gavin D. Howard" "General Commands Manual" +.TH "BC" "1" "February 2023" "Gavin D. Howard" "General Commands Manual" +.nh +.ad l .SH NAME .PP bc - arbitrary-precision decimal arithmetic language and calculator .SH SYNOPSIS .PP -\f[B]bc\f[R] [\f[B]-ghilPqRsvVw\f[R]] [\f[B]--global-stacks\f[R]] +\f[B]bc\f[R] [\f[B]-cCghilPqRsvVw\f[R]] [\f[B]--digit-clamp\f[R]] +[\f[B]--no-digit-clamp\f[R]] [\f[B]--global-stacks\f[R]] [\f[B]--help\f[R]] [\f[B]--interactive\f[R]] [\f[B]--mathlib\f[R]] [\f[B]--no-prompt\f[R]] [\f[B]--no-read-prompt\f[R]] [\f[B]--quiet\f[R]] [\f[B]--standard\f[R]] [\f[B]--warn\f[R]] [\f[B]--version\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]--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 bc(1) is an interactive processor for a language first standardized in 1991 by POSIX. -(The current standard is -here (https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html).) +(See the \f[B]STANDARDS\f[R] section.) The language provides unlimited precision decimal arithmetic and is somewhat C-like, but there are differences. Such differences will be noted in this document. @@ -73,6 +80,102 @@ See the \f[B]BUGS\f[R] section. .PP The following are the options that bc(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]BC_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]BC_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 the \f[B]-f\f[R] and \f[B]--file\f[R] +options), 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]BC_ENV_ARGS\f[R], see the \f[B]ENVIRONMENT VARIABLES\f[R] section), +then after processing all expressions and files, bc(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]BC_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, bc(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 the \f[B]-e\f[R] and +\f[B]--expression\f[R] options), 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]BC_ENV_ARGS\f[R], see the \f[B]ENVIRONMENT VARIABLES\f[R] section), +then after processing all expressions and files, bc(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, bc(1) will give a fatal error and +exit. +.PP +This is a \f[B]non-portable extension\f[R]. +.RE +.TP \f[B]-g\f[R], \f[B]--global-stacks\f[R] Turns the globals \f[B]ibase\f[R], \f[B]obase\f[R], \f[B]scale\f[R], and \f[B]seed\f[R] into stacks. @@ -166,7 +269,18 @@ 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]-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. @@ -176,6 +290,16 @@ Forces interactive mode. 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]-l\f[R], \f[B]--mathlib\f[R] Sets \f[B]scale\f[R] (see the \f[B]SYNTAX\f[R] section) to \f[B]20\f[R] and loads the included math library and the extended math library before @@ -186,11 +310,23 @@ command line. To learn what is in the libraries, see the \f[B]LIBRARY\f[R] section. .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 bc(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 bc(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). .RS @@ -201,11 +337,28 @@ environment variables (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). This is a \f[B]non-portable extension\f[R]. .RE .TP +\f[B]-q\f[R], \f[B]--quiet\f[R] +This option is for compatibility with the GNU bc(1) +(https://www.gnu.org/software/bc/); it is a no-op. +Without this option, GNU bc(1) prints a copyright header. +This bc(1) only prints the copyright header if one or more of the +\f[B]-v\f[R], \f[B]-V\f[R], or \f[B]--version\f[R] options are given +unless the \f[B]BC_BANNER\f[R] environment variable is set and contains +a non-zero integer or if this bc(1) was built with the header displayed +by default. +If \f[I]any\f[R] of that is the case, then this option \f[I]does\f[R] +prevent bc(1) from printing the header. +.RS +.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 bc(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 bc(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 bc(1) scripts that @@ -277,33 +430,33 @@ multiple times. Keywords are \f[I]not\f[R] redefined when parsing the builtin math library (see the \f[B]LIBRARY\f[R] section). .PP -It is a fatal error to redefine keywords mandated by the POSIX standard. +It is a fatal error to redefine keywords mandated by the POSIX standard +(see the \f[B]STANDARDS\f[R] section). It is a fatal error to attempt to redefine words that this bc(1) does not reserve as keywords. .RE .TP -\f[B]-q\f[R], \f[B]--quiet\f[R] -This option is for compatibility with the GNU -bc(1) (https://www.gnu.org/software/bc/); it is a no-op. -Without this option, GNU bc(1) prints a copyright header. -This bc(1) only prints the copyright header if one or more of the -\f[B]-v\f[R], \f[B]-V\f[R], or \f[B]--version\f[R] options are given. +\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]-s\f[R], \f[B]--standard\f[R] -Process exactly the language defined by the -standard (https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html) -and error if any extensions are used. +Process exactly the language defined by the standard (see the +\f[B]STANDARDS\f[R] section) and error if any extensions are used. .RS .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 exit. +Print the version information (copyright header) and exits. .RS .PP This is a \f[B]non-portable extension\f[R]. @@ -318,45 +471,14 @@ continues normally. 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]-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 -If this option is given on the command-line (i.e., not in -\f[B]BC_ENV_ARGS\f[R], see the \f[B]ENVIRONMENT VARIABLES\f[R] section), -then after processing all expressions and files, bc(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]BC_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, bc(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]BC_ENV_ARGS\f[R], see the \f[B]ENVIRONMENT VARIABLES\f[R] section), -then after processing all expressions and files, bc(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, bc(1) will give a fatal error and -exit. +This can be set for individual numbers with the \f[B]plz(x)\f[R], +\f[B]plznl(x)\f[R], \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 @@ -366,7 +488,7 @@ All long options are \f[B]non-portable extensions\f[R]. .PP If 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 -bc(1) read from \f[B]stdin\f[R]. +bc(1) reads from \f[B]stdin\f[R]. .PP However, there are a few caveats to this. .PP @@ -413,10 +535,9 @@ redirect \f[B]stderr\f[R] to \f[B]/dev/null\f[R]. .SH SYNTAX .PP The syntax for bc(1) programs is mostly C-like, with some differences. -This bc(1) follows the POSIX -standard (https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html), -which is a much more thorough resource for the language this bc(1) -accepts. +This bc(1) follows the POSIX standard (see the \f[B]STANDARDS\f[R] +section), which is a much more thorough resource for the language this +bc(1) accepts. This section is meant to be a summary and a listing of all the extensions to the standard. .PP @@ -590,6 +711,14 @@ This is a \f[B]non-portable extension\f[R]. \f[B]abs(E)\f[R]: The absolute value of \f[B]E\f[R]. This is a \f[B]non-portable extension\f[R]. .IP " 9." 4 +\f[B]is_number(E)\f[R]: \f[B]1\f[R] if the given argument is a number, +\f[B]0\f[R] if it is a string. +This is a \f[B]non-portable extension\f[R]. +.IP "10." 4 +\f[B]is_string(E)\f[R]: \f[B]1\f[R] if the given argument is a string, +\f[B]0\f[R] if it is a number. +This is a \f[B]non-portable extension\f[R]. +.IP "11." 4 \f[B]modexp(E, E, E)\f[R]: Modular exponentiation, where the first expression is the base, the second is the exponent, and the third is the modulus. @@ -597,7 +726,7 @@ All three values must be integers. The second argument must be non-negative. The third argument must be non-zero. This is a \f[B]non-portable extension\f[R]. -.IP "10." 4 +.IP "12." 4 \f[B]divmod(E, E, I[])\f[R]: Division and modulus in one operation. This is for optimization. The first expression is the dividend, and the second is the divisor, @@ -605,13 +734,19 @@ which must be non-zero. The return value is the quotient, and the modulus is stored in index \f[B]0\f[R] of the provided array (the last argument). This is a \f[B]non-portable extension\f[R]. -.IP "11." 4 +.IP "13." 4 \f[B]asciify(E)\f[R]: If \f[B]E\f[R] is a string, returns a string that is the first letter of its argument. If it is a number, calculates the number mod \f[B]256\f[R] and returns that number as a one-character string. This is a \f[B]non-portable extension\f[R]. -.IP "12." 4 +.IP "14." 4 +\f[B]asciify(I[])\f[R]: A string that is made up of the characters that +would result from running \f[B]asciify(E)\f[R] on each element of the +array identified by the argument. +This allows creating multi-character strings and storing them. +This is a \f[B]non-portable extension\f[R]. +.IP "15." 4 \f[B]I()\f[R], \f[B]I(E)\f[R], \f[B]I(E, E)\f[R], and so on, where \f[B]I\f[R] is an identifier for a non-\f[B]void\f[R] function (see the \f[I]Void Functions\f[R] subsection of the \f[B]FUNCTIONS\f[R] section). @@ -620,27 +755,44 @@ The \f[B]E\f[R] argument(s) may also be arrays of the form (see the \f[I]Array References\f[R] subsection of the \f[B]FUNCTIONS\f[R] section) if the corresponding parameter in the function definition is an array reference. -.IP "13." 4 +.IP "16." 4 \f[B]read()\f[R]: Reads a line from \f[B]stdin\f[R] and uses that as an expression. The result of that expression is the result of the \f[B]read()\f[R] operand. This is a \f[B]non-portable extension\f[R]. -.IP "14." 4 +.IP "17." 4 \f[B]maxibase()\f[R]: The max allowable \f[B]ibase\f[R]. This is a \f[B]non-portable extension\f[R]. -.IP "15." 4 +.IP "18." 4 \f[B]maxobase()\f[R]: The max allowable \f[B]obase\f[R]. This is a \f[B]non-portable extension\f[R]. -.IP "16." 4 +.IP "19." 4 \f[B]maxscale()\f[R]: The max allowable \f[B]scale\f[R]. This is a \f[B]non-portable extension\f[R]. -.IP "17." 4 +.IP "20." 4 +\f[B]line_length()\f[R]: The line length set with +\f[B]BC_LINE_LENGTH\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] +section). +This is a \f[B]non-portable extension\f[R]. +.IP "21." 4 +\f[B]global_stacks()\f[R]: \f[B]0\f[R] if global stacks are not enabled +with the \f[B]-g\f[R] or \f[B]--global-stacks\f[R] options, non-zero +otherwise. +See the \f[B]OPTIONS\f[R] section. +This is a \f[B]non-portable extension\f[R]. +.IP "22." 4 +\f[B]leading_zero()\f[R]: \f[B]0\f[R] if leading zeroes are not enabled +with the \f[B]-z\f[R] or \f[B]\[en]leading-zeroes\f[R] options, non-zero +otherwise. +See the \f[B]OPTIONS\f[R] section. +This is a \f[B]non-portable extension\f[R]. +.IP "23." 4 \f[B]rand()\f[R]: A pseudo-random integer between \f[B]0\f[R] (inclusive) and \f[B]BC_RAND_MAX\f[R] (inclusive). Using this operand will change the value of \f[B]seed\f[R]. This is a \f[B]non-portable extension\f[R]. -.IP "18." 4 +.IP "24." 4 \f[B]irand(E)\f[R]: A pseudo-random integer between \f[B]0\f[R] (inclusive) and the value of \f[B]E\f[R] (exclusive). If \f[B]E\f[R] is negative or is a non-integer (\f[B]E\f[R]\[cq]s @@ -658,7 +810,7 @@ value of \f[B]E\f[R] is \f[B]0\f[R] or \f[B]1\f[R]. In that case, \f[B]0\f[R] is returned, and \f[B]seed\f[R] is \f[I]not\f[R] changed. This is a \f[B]non-portable extension\f[R]. -.IP "19." 4 +.IP "25." 4 \f[B]maxrand()\f[R]: The max integer returned by \f[B]rand()\f[R]. This is a \f[B]non-portable extension\f[R]. .PP @@ -681,17 +833,49 @@ In any other case, use a non-seeded pseudo-random number generator. Numbers are strings made up of digits, uppercase letters, and at most \f[B]1\f[R] period for a radix. Numbers can have up to \f[B]BC_NUM_MAX\f[R] digits. -Uppercase letters are equal to \f[B]9\f[R] + 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]. +Uppercase letters are equal to \f[B]9\f[R] plus their position in the +alphabet, starting from \f[B]1\f[R] (i.e., \f[B]A\f[R] equals +\f[B]10\f[R], or \f[B]9+1\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]BC_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 (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, bc(1) accepts numbers in scientific notation. These have the form \f[B]<number>e<integer>\f[R]. @@ -981,8 +1165,7 @@ Note that unlike in C, these operators have a lower precedence than the \f[B]assignment\f[R] operators, which means that \f[B]a=b>c\f[R] is interpreted as \f[B](a=b)>c\f[R]. .PP -Also, unlike the -standard (https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html) +Also, unlike the standard (see the \f[B]STANDARDS\f[R] section) requires, these operators can appear anywhere any other expressions can be used. This allowance is a \f[B]non-portable extension\f[R]. @@ -1014,8 +1197,8 @@ The following items are statements: .IP " 1." 4 \f[B]E\f[R] .IP " 2." 4 -\f[B]{\f[R] \f[B]S\f[R] \f[B];\f[R] \&... \f[B];\f[R] \f[B]S\f[R] -\f[B]}\f[R] +\f[B]{\f[R] \f[B]S\f[R] \f[B];\f[R] \&... +\f[B];\f[R] \f[B]S\f[R] \f[B]}\f[R] .IP " 3." 4 \f[B]if\f[R] \f[B](\f[R] \f[B]E\f[R] \f[B])\f[R] \f[B]S\f[R] .IP " 4." 4 @@ -1041,9 +1224,11 @@ An empty statement .IP "13." 4 A string of characters, enclosed in double quotes .IP "14." 4 -\f[B]print\f[R] \f[B]E\f[R] \f[B],\f[R] \&... \f[B],\f[R] \f[B]E\f[R] +\f[B]print\f[R] \f[B]E\f[R] \f[B],\f[R] \&... +\f[B],\f[R] \f[B]E\f[R] .IP "15." 4 -\f[B]stream\f[R] \f[B]E\f[R] \f[B],\f[R] \&... \f[B],\f[R] \f[B]E\f[R] +\f[B]stream\f[R] \f[B]E\f[R] \f[B],\f[R] \&... +\f[B],\f[R] \f[B]E\f[R] .IP "16." 4 \f[B]I()\f[R], \f[B]I(E)\f[R], \f[B]I(E, E)\f[R], and so on, where \f[B]I\f[R] is an identifier for a \f[B]void\f[R] function (see the @@ -1076,6 +1261,25 @@ The \f[B]if\f[R] \f[B]else\f[R] statement does the same thing as in C. The \f[B]quit\f[R] statement causes bc(1) to quit, even if it is on a branch that will not be executed (it is a compile-time command). .PP +\f[B]Warning\f[R]: The behavior of this bc(1) on \f[B]quit\f[R] is +slightly different from other bc(1) implementations. +Other bc(1) implementations will exit as soon as they finish parsing the +line that a \f[B]quit\f[R] command is on. +This bc(1) will execute any completed and executable statements that +occur before the \f[B]quit\f[R] statement before exiting. +.PP +In other words, for the bc(1) code below: +.IP +.nf +\f[C] +for (i = 0; i < 3; ++i) i; quit +\f[R] +.fi +.PP +Other bc(1) implementations will print nothing, and this bc(1) will +print \f[B]0\f[R], \f[B]1\f[R], and \f[B]2\f[R] on successive lines +before exiting. +.PP The \f[B]halt\f[R] statement causes bc(1) to quit, if it is executed. (Unlike \f[B]quit\f[R] if it is on a branch of an \f[B]if\f[R] statement that is not executed, bc(1) does not quit.) @@ -1289,9 +1493,8 @@ when the \f[B]-s\f[R] option, the \f[B]-w\f[R] option, or equivalents are given. .SS Standard Library .PP -The -standard (https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html) -defines the following functions for the math library: +The standard (see the \f[B]STANDARDS\f[R] section) defines the following +functions for the math library: .TP \f[B]s(x)\f[R] Returns the sine of \f[B]x\f[R], which is assumed to be in radians. @@ -1346,7 +1549,7 @@ Functions\f[R] subsection below). The extended library is \f[I]not\f[R] loaded when the \f[B]-s\f[R]/\f[B]--standard\f[R] or \f[B]-w\f[R]/\f[B]--warn\f[R] options are given since they are not part of the library defined by the -standard (https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html). +standard (see the \f[B]STANDARDS\f[R] section). .PP The extended library is a \f[B]non-portable extension\f[R]. .TP @@ -1365,13 +1568,13 @@ Functions\f[R] subsection below). .TP \f[B]r(x, p)\f[R] Returns \f[B]x\f[R] rounded to \f[B]p\f[R] decimal places according to -the rounding mode round half away from -\f[B]0\f[R] (https://en.wikipedia.org/wiki/Rounding#Round_half_away_from_zero). +the rounding mode round half away from \f[B]0\f[R] +(https://en.wikipedia.org/wiki/Rounding#Round_half_away_from_zero). .TP \f[B]ceil(x, p)\f[R] Returns \f[B]x\f[R] rounded to \f[B]p\f[R] decimal places according to -the rounding mode round away from -\f[B]0\f[R] (https://en.wikipedia.org/wiki/Rounding#Rounding_away_from_zero). +the rounding mode round away from \f[B]0\f[R] +(https://en.wikipedia.org/wiki/Rounding#Rounding_away_from_zero). .TP \f[B]f(x)\f[R] Returns the factorial of the truncated absolute value of \f[B]x\f[R]. @@ -1937,6 +2140,46 @@ This function is used to implement other bitwise functions; it is not meant to be used by users, but it can be. .RE .TP +\f[B]plz(x)\f[R] +If \f[B]x\f[R] is not equal to \f[B]0\f[R] and greater that \f[B]-1\f[R] +and less than \f[B]1\f[R], it is printed with a leading zero, regardless +of the use of the \f[B]-z\f[R] option (see the \f[B]OPTIONS\f[R] +section) and without a trailing newline. +.RS +.PP +Otherwise, \f[B]x\f[R] is printed normally, without a trailing newline. +.RE +.TP +\f[B]plznl(x)\f[R] +If \f[B]x\f[R] is not equal to \f[B]0\f[R] and greater that \f[B]-1\f[R] +and less than \f[B]1\f[R], it is printed with a leading zero, regardless +of the use of the \f[B]-z\f[R] option (see the \f[B]OPTIONS\f[R] +section) and with a trailing newline. +.RS +.PP +Otherwise, \f[B]x\f[R] is printed normally, with a trailing newline. +.RE +.TP +\f[B]pnlz(x)\f[R] +If \f[B]x\f[R] is not equal to \f[B]0\f[R] and greater that \f[B]-1\f[R] +and less than \f[B]1\f[R], it is printed without a leading zero, +regardless of the use of the \f[B]-z\f[R] option (see the +\f[B]OPTIONS\f[R] section) and without a trailing newline. +.RS +.PP +Otherwise, \f[B]x\f[R] is printed normally, without a trailing newline. +.RE +.TP +\f[B]pnlznl(x)\f[R] +If \f[B]x\f[R] is not equal to \f[B]0\f[R] and greater that \f[B]-1\f[R] +and less than \f[B]1\f[R], it is printed without a leading zero, +regardless of the use of the \f[B]-z\f[R] option (see the +\f[B]OPTIONS\f[R] section) and with a trailing newline. +.RS +.PP +Otherwise, \f[B]x\f[R] is printed normally, with a trailing newline. +.RE +.TP \f[B]ubytes(x)\f[R] Returns the numbers of unsigned integer bytes required to hold the truncated absolute value of \f[B]x\f[R]. @@ -2196,11 +2439,11 @@ subsection of the \f[B]FUNCTIONS\f[R] section). .RE .SS Transcendental Functions .PP -All transcendental functions can return slightly inaccurate results (up -to 1 ULP (https://en.wikipedia.org/wiki/Unit_in_the_last_place)). -This is unavoidable, and this -article (https://people.eecs.berkeley.edu/~wkahan/LOG10HAF.TXT) explains -why it is impossible and unnecessary to calculate exact results for the +All transcendental functions can return slightly inaccurate results, up +to 1 ULP (https://en.wikipedia.org/wiki/Unit_in_the_last_place). +This is unavoidable, and the article at +https://people.eecs.berkeley.edu/\[ti]wkahan/LOG10HAF.TXT explains why +it is impossible and unnecessary to calculate exact results for the transcendental functions. .PP Because of the possible inaccuracy, I recommend that users call those @@ -2365,7 +2608,8 @@ at which they become a problem. In fact, memory should be exhausted before these limits should be hit. .SH ENVIRONMENT VARIABLES .PP -bc(1) recognizes the following environment variables: +As \f[B]non-portable extensions\f[R], bc(1) recognizes the following +environment variables: .TP \f[B]POSIXLY_CORRECT\f[R] If this variable exists (no matter the contents), bc(1) behaves as if @@ -2407,6 +2651,12 @@ 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]), bc(1) will output lines to that length, including the backslash (\f[B]\[rs]\f[R]). 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]BC_BANNER\f[R] If this environment variable exists and contains an integer, then a @@ -2467,6 +2717,34 @@ This environment variable and the \f[B]BC_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]BC_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 bc(1) exit after executing the +expressions and expression files, and a zero value makes bc(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]BC_DIGIT_CLAMP\f[R] +When parsing numbers and if this environment variable exists and +contains an integer, a non-zero value makes bc(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 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 bc(1) returns the following exit statuses: @@ -2548,9 +2826,8 @@ 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 -Per the -standard (https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html), -bc(1) has an interactive mode and a non-interactive mode. +Per the standard (see the \f[B]STANDARDS\f[R] section), bc(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. @@ -2582,8 +2859,7 @@ 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), +required in the bc(1) standard (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 Prompt @@ -2649,11 +2925,17 @@ dc(1) .SH STANDARDS .PP bc(1) is compliant with the IEEE Std 1003.1-2017 -(\[lq]POSIX.1-2017\[rq]) (https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html) -specification. +(\[lq]POSIX.1-2017\[rq]) specification at +https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html . The flags \f[B]-efghiqsvVw\f[R], all long options, and the extensions noted above are extensions to that specification. .PP +In addition, the behavior of the \f[B]quit\f[R] implements an +interpretation of that specification that is different from all known +implementations. +For more information see the \f[B]Statements\f[R] subsection of the +\f[B]SYNTAX\f[R] section. +.PP Note that the specification explicitly says that bc(1) only accepts numbers that use a period (\f[B].\f[R]) as a radix point, regardless of the value of \f[B]LC_NUMERIC\f[R]. @@ -2662,9 +2944,12 @@ This bc(1) supports error messages for different locales, and thus, it supports \f[B]LC_MESSAGES\f[R]. .SH BUGS .PP -None are known. -Report bugs at https://git.yzena.com/gavin/bc. +Before version \f[B]6.1.0\f[R], this bc(1) had incorrect behavior for +the \f[B]quit\f[R] statement. +.PP +No other bugs are known. +Report bugs at https://git.gavinhoward.com/gavin/bc . .SH AUTHORS .PP Gavin D. -Howard <gavin@yzena.com> and contributors. +Howard <gavin@gavinhoward.com> and contributors. |