d/freebsd-dev
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

contrib/bc: merge from vendor release 6.2.2

Browse Source 
This update fixes a few issues in history editing and the processing
of the "quit" function. The "quit" function will no longer cause bc
to exit when encountered in a script file (before any command from
the script has been executed).

New functions is_number(), is_string return 1 if the passed argument
is a number resp. a string. The asciify() function has been extended
to support the conversion of an array of numbers into a string.

Merge commit '1a63323d17fedb05b6962853e821c9d7c6b9853e'
This commit is contained in:
Stefan Eßer 2023-01-28 22:26:22 +01:00
commit d101cdd6ed
176 changed files with 14173 additions and 6492 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

152
contrib/bc/.clang-format
View File

@ -1,152 +0,0 @@
---
Language: Cpp
# BasedOnStyle: LLVM
AccessModifierOffset: 1
AlignAfterOpenBracket: Align
AlignConsecutiveAssignments: false
AlignConsecutiveBitFields: true
AlignConsecutiveDeclarations: false
AlignConsecutiveMacros: false
AlignEscapedNewlines: Left
AlignOperands: Align
AlignTrailingComments: true
AllowAllArgumentsOnNextLine: false
AllowAllConstructorInitializersOnNextLine: true
AllowAllParametersOfDeclarationOnNextLine: false
AllowShortBlocksOnASingleLine: Never
AllowShortCaseLabelsOnASingleLine: false
AllowShortEnumsOnASingleLine: false
AllowShortFunctionsOnASingleLine: None
AllowShortIfStatementsOnASingleLine: AllIfsAndElse
AllowShortLambdasOnASingleLine: Empty
AllowShortLoopsOnASingleLine: false
AlwaysBreakAfterReturnType: All
AlwaysBreakBeforeMultilineStrings: false
AlwaysBreakTemplateDeclarations: true
#AttributeMacros: []
BinPackArguments: true
BinPackParameters: true
#BitFieldColonSpacing: Both
BreakBeforeBraces: Custom
BraceWrapping:
AfterCaseLabel: true
AfterClass: true
AfterControlStatement: true
AfterEnum: true
AfterFunction: true
AfterNamespace: true
AfterObjCDeclaration: true
AfterStruct: true
AfterUnion: true
AfterExternBlock: true
BeforeCatch: true
BeforeElse: true
BeforeLambdaBody: false
BeforeWhile: true
IndentBraces: false
SplitEmptyFunction: false
SplitEmptyRecord: false
SplitEmptyNamespace: false
BreakAfterJavaFieldAnnotations: true
BreakBeforeBinaryOperators: None
#BreakBeforeConceptDeclarations: true
BreakBeforeInheritanceComma: false
BreakBeforeTernaryOperators: false
BreakConstructorInitializers: AfterColon
BreakInheritanceList: AfterColon
BreakStringLiterals: false
ColumnLimit: 80
CommentPragmas: '^ IWYU pragma:'
CompactNamespaces: false
ConstructorInitializerAllOnOneLineOrOnePerLine: false
ConstructorInitializerIndentWidth: 4
ContinuationIndentWidth: 4
Cpp11BracedListStyle: false
DeriveLineEnding: false
DerivePointerAlignment: false
DisableFormat: false
ExperimentalAutoDetectBinPacking: false
FixNamespaceComments: true
ForEachMacros:
- foreach
- Q_FOREACH
- BOOST_FOREACH
IncludeBlocks: Regroup
IncludeCategories:
- Regex: '^<(sys|arpa|net|netinet)/.*\.h>'
Priority: 2
- Regex: '^<(args|bc|bcl|dc|file|history|lang|lex|library|num|opt|parse|program|rand|read|status|vector|version|vm)\.h>'
Priority: 3
- Regex: '^<.*\.h>'
Priority: 0
- Regex: '^<.*>'
Priority: 1
IncludeIsMainRegex: '(Test)?$'
IncludeIsMainSourceRegex: ''
IndentCaseLabels: true
IndentExternBlock: NoIndent
IndentGotoLabels: false
IndentPPDirectives: None
#IndentPragmas: false
#IndentRequires: true
IndentWidth: 4
IndentWrappedFunctionNames: false
InsertTrailingCommas: None
JavaImportGroups: []
JavaScriptQuotes: Double
JavaScriptWrapImports: true
KeepEmptyLinesAtTheStartOfBlocks: false
Language: Cpp
MacroBlockBegin: ''
MacroBlockEnd: ''
MaxEmptyLinesToKeep: 1
NamespaceIndentation: None
NamespaceMacros: []
ObjCBinPackProtocolList: Always
ObjCBlockIndentWidth: 4
ObjCBreakBeforeNestedBlockParam: true
ObjCSpaceAfterProperty: true
ObjCSpaceBeforeProtocolList: true
PenaltyBreakAssignment: 1000
PenaltyBreakBeforeFirstCallParameter: 429496720
PenaltyBreakComment: 300
PenaltyBreakFirstLessLess: 42949672
PenaltyBreakString: 10000
PenaltyBreakTemplateDeclaration: 10
PenaltyExcessCharacter: 42949672
PenaltyIndentedWhitespace: 1
PenaltyReturnTypeOnItsOwnLine: 60
PointerAlignment: Left
#RawStringFormats:
# This is used to get spaces around a bitwise and operator.
ReferenceAlignment: Middle
ReflowComments: true
SortIncludes: false
SortUsingDeclarations: true
SpaceAfterCStyleCast: true
SpaceAfterLogicalNot: false
SpaceAfterTemplateKeyword: true
#SpaceAroundPointerQualifiers: Default
SpaceBeforeAssignmentOperators: true
SpaceBeforeCpp11BracedList: true
SpaceBeforeCtorInitializerColon: true
SpaceBeforeInheritanceColon: true
SpaceBeforeParens: ControlStatements
SpaceBeforeRangeBasedForLoopColon: true
SpaceBeforeSquareBrackets: false
SpaceInEmptyBlock: false
SpaceInEmptyParentheses: false
SpacesBeforeTrailingComments: 1
SpacesInAngles: false
SpacesInContainerLiterals: true
SpacesInCStyleCastParentheses: false
SpacesInConditionalStatement: false
SpacesInParentheses: false
SpacesInSquareBrackets: false
Standard: Latest
TabWidth: 4
TypenameMacros: []
UseCRLF: false
UseTab: ForIndentation
WhitespaceSensitiveMacros: []
...

43
contrib/bc/.clang-tidy
View File

@ -1,43 +0,0 @@
Checks: 'clang-diagnostic-*,clang-analyzer-*'
WarningsAsErrors: 'clang-diagnostic-*,clang-analyzer-*'
HeaderFilterRegex: ''
AnalyzeTemporaryDtors: false
FormatStyle: file
CheckOptions:
- key: llvm-else-after-return.WarnOnConditionVariables
value: 'false'
- key: modernize-loop-convert.MinConfidence
value: reasonable
- key: modernize-replace-auto-ptr.IncludeStyle
value: llvm
- key: cert-str34-c.DiagnoseSignedUnsignedCharComparisons
value: 'false'
- key: google-readability-namespace-comments.ShortNamespaceLines
value: '10'
- key: cert-oop54-cpp.WarnOnlyIfThisHasSuspiciousField
value: 'false'
- key: cppcoreguidelines-non-private-member-variables-in-classes.IgnoreClassesWithAllMemberVariablesBeingPublic
value: 'true'
- key: cert-dcl16-c.NewSuffixes
value: 'L;LL;LU;LLU'
- key: google-readability-braces-around-statements.ShortStatementLines
value: '1'
- key: modernize-pass-by-value.IncludeStyle
value: llvm
- key: google-readability-namespace-comments.SpacesBeforeComments
value: '2'
- key: modernize-loop-convert.MaxCopySize
value: '16'
- key: cppcoreguidelines-explicit-virtual-functions.IgnoreDestructors
value: 'true'
- key: modernize-use-nullptr.NullMacros
value: 'NULL'
- key: llvm-qualified-auto.AddConstToQualified
value: 'false'
- key: modernize-loop-convert.NamingStyle
value: CamelCase
- key: llvm-else-after-return.WarnOnUnfixable
value: 'false'
- key: google-readability-function-size.StatementThreshold
value: '800'
...

86
contrib/bc/.gitignore vendored
View File

@ -1,86 +0,0 @@
*.config
*.creator
*.files
*.includes
*.creator.user*
*.cflags
*.cxxflags
bin/*bc
bin/*bc.exe
bin/*dc
bin/*dc.exe
bin/bcl
bc.old
*.o
*.a
.log_*.txt
.test.txt
.math.txt
.results.txt
.ops.txt
manuals/bc.1
manuals/bc.1.ronn
manuals/bc.1.md
manuals/dc.1
manuals/dc.1.ronn
manuals/dc.1.md
gen/strgen
lib.c
lib2.c
lib3.c
bc_help.c
dc_help.c
config.mak
timeconst.bc
Makefile
bcl.pc
build/*
tests/fuzzing/bc_outputs1/*
tests/fuzzing/bc_outputs2/*
tests/fuzzing/bc_outputs3/*
tests/fuzzing/dc_outputs/*
tests/bc_outputs/*
tests/dc_outputs/*
.gdb_history
# Ignore the generated test files
parse.txt
parse_results.txt
print.txt
print_results.txt
bessel.txt
bessel_results.txt
prime.txt
strings2.txt
strings2_results.txt
tests/bc/scripts/add.txt
tests/bc/scripts/divide.txt
tests/bc/scripts/multiply.txt
tests/bc/scripts/subtract.txt
tests/bc/scripts/strings2.txt
benchmarks/bc/*.txt
benchmarks/dc/*.txt
scripts/ministat
scripts/bitfuncgen
perf.data
perf.data.old
*.gcda
*.gcno
*.gcov
*.html
*.profraw
core.*
cscope*.out
tags
*.vcxproj.user
vs/.vs/*
vs/bin/*
vs/lib/*
vs/src2/*
vs/tests/*.txt
vs/tests/*.exe

6
contrib/bc/LICENSE.md
View File

@ -1,6 +1,6 @@
# License
Copyright (c) 2018-2021 Gavin D. Howard <yzena.tech@gmail.com>
Copyright (c) 2018-2023 Gavin D. Howard <gavin@yzena.com>
Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:
@ -31,7 +31,7 @@ copyrights and license:
Copyright (c) 2010-2014, Salvatore Sanfilippo <antirez at gmail dot com><br>
Copyright (c) 2010-2013, Pieter Noordhuis <pcnoordhuis at gmail dot com><br>
Copyright (c) 2018 rain-1 <rain1@openmailbox.org><br>
Copyright (c) 2018-2021, Gavin D. Howard <yzena.tech@gmail.com>
Copyright (c) 2018-2023, Gavin D. Howard <gavin@yzena.com>
Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:
@ -60,7 +60,7 @@ The files `src/rand.c` and `include/rand.h` are under the following copyrights
and license:
Copyright (c) 2014-2017 Melissa O'Neill and PCG Project contributors
Copyright (c) 2018-2021 Gavin D. Howard <yzena.tech@gmail.com>
Copyright (c) 2018-2023 Gavin D. Howard <gavin@yzena.com>
Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in

53
contrib/bc/MEMORY_BUGS.md Normal file
View File

@ -0,0 +1,53 @@
# Memory Bugs
This is a list of all of the memory bugs that were found in *released* versions
of `bc`, `dc`, or `bcl`. (Non-released commits with memory bugs do not count.)
I made this list for two reasons: first, so users can know what versions of
`bc`, `dc`, and `bcl` have vulnerabilities, and two, I once had a perfect record
and then found a couple, but forgot and claimed I still had a perfect record
right after, which was embarrassing.
This list is sorted by the first version a bug exists in, not the last it
existed in.
* In versions `1.1.0` until `6.2.0` (inclusive) of `bc` and `dc`, there is a
out of bounds read and write in history when pressing ctrl+r (or any other
unused letter) then inserting two characters.
The first version without this bug is `6.2.1`.
* In versions `3.0.0` until `6.0.1` (inclusive) of `bc` and `dc`, there is a
double-free on `SIGINT` when using command-line expressions with `-e` and
`-f`. This was caused by not properly ending a jump series.
The first version without this bug is `6.0.2`.
* In versions `5.0.0` until `6.0.4` (inclusive) of `bc`, there is an
out-of-bounds access if a non-local (non-`auto`) variable is set to a string
with `asciify()`, then the function is redefined with a use of the same
non-local variable.
This happened because strings were stored per-function, and the non-local
variable now had a reference to the string in the old function, which could be
at a higher index than exists in the new function. Strings are stored globally
now, and they are *not* freed once not used.
The first version without this bug is `6.1.0`.
* In versions `5.0.0` until `6.0.4` (inclusive) of `bc`, there is another
out-of-bounds access if an array is passed to the `asciify()` built-in
function as the only argument. This happened because arrays are allowed as
function arguments, which allowed them to be used as arguments to `asciify()`,
but they should not have been allowed. However, since they were, the
`asciify()` code tried to access an argument that was not there.
The first version without this bug is `6.1.0`.
* In version `6.0.0` of `bcl`, there are several uses of initialized data that
have the same root cause: I forgot to call `memset()` on the per-thread global
data. This is because the data used to be *actually* global, which meant that
it was initialized to zero by the system. This happened because I thought I
had properly hooked Valgrind into my `bcl` tests, but I had not.
The first version without this bug is `6.0.1`.

26
contrib/bc/Makefile.in
View File

@ -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:
@ -55,7 +55,7 @@ HISTORY_HEADERS = $(INCDIR)/history.h
EXTRA_MATH_HEADERS = $(INCDIR)/rand.h
LIBRARY_HEADERS = $(INCDIR)/bcl.h $(INCDIR)/library.h
GEN_DIR = gen
GEN_DIR = %%GEN_DIR%%
GEN = %%GEN%%
GEN_EXEC = $(GEN_DIR)/$(GEN)
GEN_C = $(GENDIR)/$(GEN).c
@ -146,7 +146,6 @@ BC_ENABLE_HISTORY = %%HISTORY%%
BC_ENABLE_EXTRA_MATH_NAME = BC_ENABLE_EXTRA_MATH
BC_ENABLE_EXTRA_MATH = %%EXTRA_MATH%%
BC_ENABLE_NLS = %%NLS%%
BC_LONG_BIT = %%LONG_BIT%%
BC_EXCLUDE_EXTRA_MATH = %%EXCLUDE_EXTRA_MATH%%
BC_ENABLE_AFL = %%FUZZ%%
@ -161,6 +160,8 @@ BC_DEFAULT_PROMPT = %%BC_DEFAULT_PROMPT%%
DC_DEFAULT_PROMPT = %%DC_DEFAULT_PROMPT%%
BC_DEFAULT_EXPR_EXIT = %%BC_DEFAULT_EXPR_EXIT%%
DC_DEFAULT_EXPR_EXIT = %%DC_DEFAULT_EXPR_EXIT%%
BC_DEFAULT_DIGIT_CLAMP = %%BC_DEFAULT_DIGIT_CLAMP%%
DC_DEFAULT_DIGIT_CLAMP = %%DC_DEFAULT_DIGIT_CLAMP%%
RM = rm
MKDIR = mkdir
@ -192,12 +193,14 @@ BC_DEFS1 = -DBC_DEFAULT_SIGINT_RESET=$(BC_DEFAULT_SIGINT_RESET)
BC_DEFS2 = -DBC_DEFAULT_TTY_MODE=$(BC_DEFAULT_TTY_MODE)
BC_DEFS3 = -DBC_DEFAULT_PROMPT=$(BC_DEFAULT_PROMPT)
BC_DEFS4 = -DBC_DEFAULT_EXPR_EXIT=$(BC_DEFAULT_EXPR_EXIT)
BC_DEFS = $(BC_DEFS0) $(BC_DEFS1) $(BC_DEFS2) $(BC_DEFS3) $(BC_DEFS4)
BC_DEFS5 = -DBC_DEFAULT_DIGIT_CLAMP=$(BC_DEFAULT_DIGIT_CLAMP)
BC_DEFS = $(BC_DEFS0) $(BC_DEFS1) $(BC_DEFS2) $(BC_DEFS3) $(BC_DEFS4) $(BC_DEFS5)
DC_DEFS1 = -DDC_DEFAULT_SIGINT_RESET=$(DC_DEFAULT_SIGINT_RESET)
DC_DEFS2 = -DDC_DEFAULT_TTY_MODE=$(DC_DEFAULT_TTY_MODE)
DC_DEFS3 = -DDC_DEFAULT_PROMPT=$(DC_DEFAULT_PROMPT)
DC_DEFS4 = -DDC_DEFAULT_EXPR_EXIT=$(DC_DEFAULT_EXPR_EXIT)
DC_DEFS = $(DC_DEFS1) $(DC_DEFS2) $(DC_DEFS3) $(DC_DEFS4)
DC_DEFS5 = -DDC_DEFAULT_DIGIT_CLAMP=$(DC_DEFAULT_DIGIT_CLAMP)
DC_DEFS = $(DC_DEFS1) $(DC_DEFS2) $(DC_DEFS3) $(DC_DEFS4) $(DC_DEFS5)
CPPFLAGS1 = -D$(BC_ENABLED_NAME)=$(BC_ENABLED) -D$(DC_ENABLED_NAME)=$(DC_ENABLED)
CPPFLAGS2 = $(CPPFLAGS1) -I$(INCDIR)/ -DBUILD_TYPE=$(BC_BUILD_TYPE) %%LONG_BIT_DEFINE%%
@ -208,8 +211,8 @@ CPPFLAGS6 = $(CPPFLAGS5) -DBC_ENABLE_NLS=$(BC_ENABLE_NLS)
CPPFLAGS7 = $(CPPFLAGS6) -D$(BC_ENABLE_EXTRA_MATH_NAME)=$(BC_ENABLE_EXTRA_MATH)
CPPFLAGS8 = $(CPPFLAGS7) -DBC_ENABLE_HISTORY=$(BC_ENABLE_HISTORY) -DBC_ENABLE_LIBRARY=$(BC_ENABLE_LIBRARY)
CPPFLAGS = $(CPPFLAGS8) -DBC_ENABLE_MEMCHECK=$(BC_ENABLE_MEMCHECK) -DBC_ENABLE_AFL=$(BC_ENABLE_AFL)
CFLAGS = $(CPPFLAGS) $(BC_DEFS) $(DC_DEFS) %%CPPFLAGS%% %%CFLAGS%% -I$(INCLUDEDIR)
LDFLAGS = %%LDFLAGS%% -L$(LIBDIR)
CFLAGS = $(CPPFLAGS) $(BC_DEFS) $(DC_DEFS) %%CPPFLAGS%% %%CFLAGS%%
LDFLAGS = %%LDFLAGS%%
HOSTCFLAGS = %%HOSTCFLAGS%%
@ -299,11 +302,6 @@ help:
@printf ' time_test_dc runs the dc test suite, displaying times for some things\n'
@printf ' timeconst runs the test on the Linux timeconst.bc script,\n'
@printf ' if it exists and bc has been built\n'
@printf ' valgrind runs the test suite through valgrind\n'
@printf ' valgrind_bc runs the bc test suite, if bc has been built,\n'
@printf ' through valgrind\n'
@printf ' valgrind_dc runs the dc test suite, if dc has been built,\n'
@printf ' through valgrind\n'
run_all_tests: bc_all_tests timeconst_all_tests dc_all_tests
@ -502,10 +500,10 @@ test_history_header:
@printf '$(TEST_STARS)\n\nRunning history tests...\n\n'
library_test: $(LIBBC)
$(CC) $(CFLAGS) $(BCL_TEST_C) $(LIBBC) -o $(BCL_TEST)
$(CC) $(CFLAGS) -lpthread $(BCL_TEST_C) $(LIBBC) -o $(BCL_TEST)
test_library: library_test
$(BCL_TEST)
%%BCL_TEST_EXEC%%
karatsuba:
%%KARATSUBA%%

136
contrib/bc/NEWS.md
View File

@ -1,5 +1,141 @@
# News
## 6.2.2
This is a production release that fixes a bug.
The bug was that if an array element was used as a parameter, and then a later
parameter had the same name as the array whose element was used, `bc` would grab
the element from the new array parameter, not the actual element from before the
function call.
## 6.2.1
This is a production release with one bug fix for a memory bug in history.
## 6.2.0
This is a production release with a new feature and a few bug fixes.
The bug fixes include:
* A crash when `bc` and `dc` are built using editline, but history is not
activated.
* A missing local in the `uint*()` family of functions in the extended math
library.
* A failure to clear the tail call list in `dc` on error.
* A crash when attempting to swap characters in command-line history when no
characters exist.
* `SIGWINCH` was activated even when history was not.
The new feature is that stack traces are now given for runtime errors. In debug
mode, the C source file and line of errors are given as well.
## 6.1.1
This is a production release that fixes a build issue with predefined builds and
generated tests.
## 6.1.0
This is a production release that fixes a discrepancy from the `bc` standard,
a couple of memory bugs, and adds new features.
The discrepancy from the `bc` standard was with regards to the behavior of the
`quit` command. This `bc` used to quit whenever it encountered `quit` during
parsing, even if it was parsing a full file. Now, `bc` only quits when
encountering `quit` *after* it has executed all executable statements up to that
point.
This behavior is slightly different from GNU `bc`, but users will only notice
the difference if they put `quit` on the same line as other statements.
The first memory bug could be reproduced by assigning a string to a non-local
variable in a function, then redefining the function with use of the same
non-local variable, which would still refer to a string in the previous version
of the function.
The second memory bug was caused by passing an array argument to the `asciify()`
built-in function. In certain cases, that was wrongly allowed, and the
interpreter just assumed everything was correct and accessed memory. Now that
arrays are allowed as arguments (see below), this is not an issue.
The first feature was the addition of the `is_number()` built-in function (`u`
in `dc`) that returns 1 if the runtime argument is a number and 0 otherwise.
The second feature was the addition of the `is_string()` built-in function (`t`
in `dc`) that returns 1 if the runtime argument is a string and 0 otherwise.
These features were added because I realized that type-checking is necessary now
that strings can be assigned to variables in `bc` and because they've always
been assignable to variables in `dc`.
The last added feature is the ability of the `asciify()` built-in function in
`bc` to convert a full array of numbers into a string. This means that
character-by-character printing will not be necessary, and more strings than
just single-character ones will be able to be created.
## 6.0.4
This is a production release that most users will not need to upgrade to.
This fixes a build bug for `bcl` only on OpenBSD. Users that do not need `bcl`
or have not run into build errors with `bcl` do ***NOT*** need to upgrade.
## 6.0.3
This is a production release that fixes a build bug for cross-compilation.
Users that do not need cross-compilation do ***NOT*** need to upgrade.
## 6.0.2
This is a production release that fixes two bugs:
* The `-l` option overrode the `-S` option.
* A double-free and crash when sending a `SIGINT` while executing expressions
given on the command-line.
## 6.0.1
This is a production release that fixes memory bugs and memory leaks in `bcl`.
Users that do not use `bcl` (use only `bc` and/or `dc`) do ***NOT*** need to
upgrade.
These happened because I was unaware that the `bcl` test was not hooked into the
Valgrind test infrastructure. Then, when I ran the release script, which tests
everything under Valgrind (or so I thought), it caught nothing, and I thought it
was safe.
But it was not.
Nevertheless, I have now run it under Valgrind and fixed all of the memory bugs
(caused by not using `memset()` where I should have but previously didn't have
to) and memory leaks.
## 6.0.0
This is a production release that fixes an oversight in the `bc` parser (that
sometimes caused the wrong error message) and adds a feature for compatibility
with the BSD `bc` and `dc`: turning off digit clamping when parsing numbers.
The default for clamping can be set during the build (see the [build
manual][13]), it can be set with the `BC_DIGIT_CLAMP` and `DC_DIGIT_CLAMP`
environment variables, and it can be set with the `-c` and `-C` command-line
options.
Turning off clamping was also added to the `bcl` library.
In addition, signal handling was removed from the `bcl` library in order to add
the capability for multi-threading. This required a major version bump. I
apologize to all library users (I don't know of any), but signals and threads do
not play well together.
To help with building, a convenience option (`-p`) to `configure.sh` was added
to build a `bc` and `dc` that is by default compatible with either the BSD `bc`
and `dc` or the GNU `bc` and `dc`.
## 5.3.3
This is a production release that fixes a build problem in the FreeBSD base

2
contrib/bc/NOTICE.md
View File

@ -1,6 +1,6 @@
# Notice
Copyright 2018-2021 Gavin D. Howard and contributors.
Copyright 2018-2023 Gavin D. Howard and contributors.
## Contributors

61
contrib/bc/README.md
View File

@ -171,8 +171,8 @@ other locations, use the `PREFIX` environment variable when running
#### Library
This `bc` does provide a way to build a math library with C bindings. This is
done by the `-a` or `--library` options to `configure.sh`:
To build the math library, pass the `-a` or `--library` options to
`configure.sh`:
```
./configure.sh -a
@ -318,7 +318,8 @@ may prove useful to any serious users.
This `bc` compares favorably to GNU `bc`.
* This `bc` builds natively on Windows.
* It has more extensions, which make this `bc` more useful for scripting.
* It has more extensions, which make this `bc` more useful for scripting. (See
[Extensions](#extensions).)
* This `bc` is a bit more POSIX compliant.
* It has a much less buggy parser. The GNU `bc` will give parse errors for what
is actually valid `bc` code, or should be. For example, putting an `else` on
@ -341,6 +342,58 @@ There is one instance where this `bc` is slower: if scripts are light on math.
This is because this `bc`'s intepreter is slightly slower than GNU `bc`, but
that is because it is more robust. See the [benchmarks][19].
### Extensions
Below is a non-comprehensive list of extensions that this `bc` and `dc` have
that all others do not.
* An extended math library. (See [here][30] for more information.)
* A command-line prompt.
* Turning on and off digit clamping. (Digit clamping is about how to treat
"invalid" digits for a particular base. GNU `bc` uses it, and the BSD `bc`
does not. Mine does both.)
* A pseudo-random number generator. This includes the ability to set the seed
and get reproducible streams of random numbers.
* The ability to use stacks for the globals `scale`, `ibase`, and `obase`
instead of needing to restore them in *every* function.
* The ability to *not* use non-standard keywords. For example, `abs` is a
keyword (a built-in function), but if some script actually defines a function
called that, it's possible to tell my `bc` to not treat it as a keyword, which
will make the script parses correctly.
* The ability to turn on and off printing leading zeroes on numbers greater than
`-1` and less than `1`.
* Outputting in scientific and engineering notation.
* Accepting input in scientific and engineering notation.
* Passing strings and arrays to the `length()` built-in function. (In `dc`, the
`Y` command will do this for arrays, and the `Z` command will do this for both
numbers and strings.)
* The `abs()` built-in function. (This is the `b` command in `dc`.)
* The `is_number()` and `is_string()` built-in functions. (These tell whether a
variable is holding a string or a number, for runtime type checking. The
commands are `u` and `t` in `dc`.)
* For `bc` only, the `divmod()` built-in function for computing a quotient and
remainder at the same time.
* For `bc` only, the `asciify()` built-in function for converting an array to a
string.
* The `$` truncation operator. (It's the same in `bc` and `dc`.)
* The `@` "set scale" operator. (It's the same in `bc` and `dc`.)
* The decimal shift operators. (`<<` and `>>` in `bc`, `H` and `h` in `dc`.)
* Built-in functions or commands to get the max of `scale`, `ibase`, and
`obase`.
* The ability to put strings into variables in `bc`. (This always existed in
`dc`.)
* The `'` command in `dc` for the depth of the execution stack.
* The `y` command in `dc` for the depth of register stacks.
* Built-in functions or commands to get the value of certain environment
variables that might affect execution.
* The `stream` keyword to do the same thing as the `P` command in `dc`.
* Defined order of evaluation.
* Defined exit statuses.
* All environment variables other than `POSIXLY_CORRECT`, `BC_ENV_ARGS`, and
`BC_LINE_LENGTH`.
* The ability for users to define their own defaults for various options during
build. (See [here][31] for more information.)
## Algorithms
To see what algorithms this `bc` uses, see the [algorithms manual][7].
@ -441,3 +494,5 @@ Folders:
[27]: https://en.wikipedia.org/wiki/Bus_factor
[28]: ./manuals/development.md
[29]: https://github.com/gavinhoward/bc
[30]: ./manuals/bc/A.1.md#extended-library
[31]: ./manuals/build.md#settings

370
contrib/bc/configure.sh
View File

@ -2,7 +2,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:
@ -43,7 +43,7 @@ usage() {
_usage_val=1
printf "%s\n\n" "$1"
printf '%s\n\n' "$1"
else
_usage_val=0
@ -52,18 +52,25 @@ usage() {
printf 'usage:\n'
printf ' %s -h\n' "$script"
printf ' %s --help\n' "$script"
printf ' %s [-a|-bD|-dB|-c] [-CeEfgGHlmMNrtTvz] [-O OPT_LEVEL] [-k KARATSUBA_LEN]\\\n' "$script"
printf ' [-s SETTING] [-S SETTING]\n'
printf ' %s [-a|-bD|-dB|-c] [-CeEfgGHilmMNPrtTvz] [-O OPT_LEVEL] [-k KARATSUBA_LEN]\\\n' "$script"
printf ' [-s SETTING] [-S SETTING] [-p TYPE]\n'
printf ' %s \\\n' "$script"
printf ' [--library|--bc-only --disable-dc|--dc-only --disable-bc|--coverage] \\\n'
printf ' [--force --debug --disable-extra-math --disable-generated-tests] \\\n'
printf ' [--disable-history --disable-man-pages --disable-nls --disable-strip] \\\n'
printf ' [--enable-editline] [--enable-readline] \\\n'
printf ' [--install-all-locales] [--opt=OPT_LEVEL] \\\n'
printf ' [--karatsuba-len=KARATSUBA_LEN] \\\n'
printf ' [--enable-editline] [--enable-readline] [--enable-internal-history] \\\n'
printf ' [--disable-problematic-tests] [--install-all-locales] \\\n'
printf ' [--opt=OPT_LEVEL] [--karatsuba-len=KARATSUBA_LEN] \\\n'
printf ' [--set-default-on=SETTING] [--set-default-off=SETTING] \\\n'
printf ' [--predefined-build-type=TYPE] \\\n'
printf ' [--prefix=PREFIX] [--bindir=BINDIR] [--datarootdir=DATAROOTDIR] \\\n'
printf ' [--datadir=DATADIR] [--mandir=MANDIR] [--man1dir=MAN1DIR] \\\n'
printf ' [--man3dir=MAN3DIR]\n'
if [ "$_usage_val" -ne 0 ]; then
exit
fi
printf '\n'
printf ' -a, --library\n'
printf ' Build the libbcl instead of the programs. This is meant to be used with\n'
@ -90,9 +97,9 @@ usage() {
printf ' are specified too.\n'
printf ' -e, --enable-editline\n'
printf ' Enable the use of libedit/editline. This is meant for those users that\n'
printf ' want vi-like or Emacs-like behavior in history.This option is ignored if\n'
printf ' history is disabled. It is an error if this option is enabled when the\n'
printf ' -r/--enable-readline option is enabled.\n'
printf ' want vi-like or Emacs-like behavior in history. This option is ignored\n'
printf ' if history is disabled. If the -r or -i options are given with this\n'
printf ' option, the last occurrence of all of the three is used.\n'
printf ' -E, --disable-extra-math\n'
printf ' Disable extra math. This includes: "$" operator (truncate to integer),\n'
printf ' "@" operator (set number of decimal places), and r(x, p) (rounding\n'
@ -114,6 +121,11 @@ usage() {
printf ' Print this help message and exit.\n'
printf ' -H, --disable-history\n'
printf ' Disable history.\n'
printf ' -i, --enable-internal-history\n'
printf ' Enable the internal history implementation and do not depend on either\n'
printf ' editline or readline. This option is ignored if history is disabled.\n'
printf ' If this option is given along with -e and -r, the last occurrence of\n'
printf ' all of the three is used.\n'
printf ' -k KARATSUBA_LEN, --karatsuba-len KARATSUBA_LEN\n'
printf ' Set the karatsuba length to KARATSUBA_LEN (default is 64).\n'
printf ' It is an error if KARATSUBA_LEN is not a number or is less than 16.\n'
@ -127,15 +139,31 @@ usage() {
printf ' Disable installing manpages.\n'
printf ' -N, --disable-nls\n'
printf ' Disable POSIX locale (NLS) support.\n'
printf ' ***WARNING***: Locales ignore the prefix because they *must* be\n'
printf ' installed at a fixed location to work at all. If you do not want that\n'
printf ' to happen, you must disable locales (NLS) completely.\n'
printf ' -O OPT_LEVEL, --opt OPT_LEVEL\n'
printf ' Set the optimization level. This can also be included in the CFLAGS,\n'
printf ' but it is provided, so maintainers can build optimized debug builds.\n'
printf ' This is passed through to the compiler, so it must be supported.\n'
printf ' -p TYPE, --predefined-build-type=TYPE\n'
printf ' Sets a given predefined build type with specific defaults. This is for\n'
printf ' easy setting of predefined builds. For example, to get a build that\n'
printf ' acts like the GNU bc by default, TYPE should be "GNU" (without the\n'
printf ' quotes) This option *must* come before any others that might change the\n'
printf ' build options. Currently supported values for TYPE include: "BSD" (for\n'
printf ' matching the BSD bc and BSD dc), "GNU" (for matching the GNU bc and\n'
printf ' dc), "GDH" (for the preferred build of the author, Gavin D. Howard),\n'
printf ' and "DBG" (for the preferred debug build of the author). This will\n'
printf ' also automatically enable a release build (except for "DBG").\n'
printf ' -P, --disable-problematic-tests\n'
printf ' Disables problematic tests. These tests usually include tests that\n'
printf ' can cause a SIGKILL because of too much memory usage.\n'
printf ' -r, --enable-readline\n'
printf ' Enable the use of libreadline/readline. This is meant for those users\n'
printf ' that want vi-like or Emacs-like behavior in history.This option is\n'
printf ' ignored if history is disabled. It is an error if this option is\n'
printf ' enabled when the -e/--enable-editline option is enabled.\n'
printf ' that want vi-like or Emacs-like behavior in history. This option is\n'
printf ' ignored if history is disabled. If this option is given along with -e\n'
printf ' and -r, the last occurrence of all of the three is used.\n'
printf ' -s SETTING, --set-default-on SETTING\n'
printf ' Set the default named by SETTING to on. See below for possible values\n'
printf ' for SETTING. For multiple instances of the -s or -S for the the same\n'
@ -157,6 +185,9 @@ usage() {
printf ' The prefix to install to. Overrides "$PREFIX" if it exists.\n'
printf ' If PREFIX is "/usr", install path will be "/usr/bin".\n'
printf ' Default is "/usr/local".\n'
printf ' ***WARNING***: Locales ignore the prefix because they *must* be\n'
printf ' installed at a fixed location to work at all. If you do not want that to\n'
printf ' happen, you must disable locales (NLS) completely.\n'
printf ' --bindir BINDIR\n'
printf ' The directory to install binaries in. Overrides "$BINDIR" if it exists.\n'
printf ' Default is "$PREFIX/bin".\n'
@ -202,6 +233,9 @@ usage() {
printf ' LDFLAGS Linker flags. Default is "".\n'
printf ' PREFIX The prefix to install to. Default is "/usr/local".\n'
printf ' If PREFIX is "/usr", install path will be "/usr/bin".\n'
printf ' ***WARNING***: Locales ignore the prefix because they *must* be\n'
printf ' installed at a fixed location to work at all. If you do not\n'
printf ' want that to happen, you must disable locales (NLS) completely.\n'
printf ' BINDIR The directory to install binaries in. Default is "$PREFIX/bin".\n'
printf ' INCLUDEDIR The directory to install header files in. Default is\n'
printf ' "$PREFIX/include".\n'
@ -317,6 +351,20 @@ usage() {
printf '| | given with the -e or | | |\n'
printf '| | -f options. | | |\n'
printf '| --------------- | -------------------- | ------------ | -------------------- |\n'
printf '| bc.digit_clamp | Whether to have bc | 0 | BC_DIGIT_CLAMP |\n'
printf '| | clamp digits that | | |\n'
printf '| | are greater than or | | |\n'
printf '| | equal to the current | | |\n'
printf '| | ibase when parsing | | |\n'
printf '| | numbers. | | |\n'
printf '| --------------- | -------------------- | ------------ | -------------------- |\n'
printf '| dc.digit_clamp | Whether to have dc | 0 | DC_DIGIT_CLAMP |\n'
printf '| | clamp digits that | | |\n'
printf '| | are greater than or | | |\n'
printf '| | equal to the current | | |\n'
printf '| | ibase when parsing | | |\n'
printf '| | numbers. | | |\n'
printf '| --------------- | -------------------- | ------------ | -------------------- |\n'
printf '\n'
printf 'These settings are not meant to be changed on a whim. They are meant to ensure\n'
printf 'that this bc and dc will conform to the expectations of the user on each\n'
@ -413,7 +461,7 @@ find_src_files() {
fi
_find_src_files_files=$(find "$scriptdir/src/" -depth -name "*.c" -print)
_find_src_files_files=$(find "$scriptdir/src/" -depth -name "*.c" -print | LC_ALL=C sort)
_find_src_files_result=""
@ -515,7 +563,7 @@ gen_std_tests() {
fi
printf 'test_%s_%s:\n\t@export BC_TEST_OUTPUT_DIR="%s/tests"; sh \$(TESTSDIR)/test.sh %s %s %s %s %s\n\n' \
printf 'test_%s_%s:\n\t@export BC_TEST_OUTPUT_DIR="%s/tests"; sh $(TESTSDIR)/test.sh %s %s %s %s %s\n\n' \
"$_gen_std_tests_name" "$_gen_std_tests_t" "$builddir" "$_gen_std_tests_name" \
"$_gen_std_tests_t" "$generate_tests" "$time_tests" \
"$*" >> "Makefile"
@ -555,9 +603,9 @@ gen_err_tests() {
for _gen_err_tests_t in $_gen_err_tests_fs; do
printf 'test_%s_error_%s:\n\t@export BC_TEST_OUTPUT_DIR="%s/tests"; sh \$(TESTSDIR)/error.sh %s %s %s\n\n' \
printf 'test_%s_error_%s:\n\t@export BC_TEST_OUTPUT_DIR="%s/tests"; sh $(TESTSDIR)/error.sh %s %s %s %s\n\n' \
"$_gen_err_tests_name" "$_gen_err_tests_t" "$builddir" "$_gen_err_tests_name" \
"$_gen_err_tests_t" "$*" >> "Makefile"
"$_gen_err_tests_t" "$problematic_tests" "$*" >> "Makefile"
done
@ -609,7 +657,7 @@ gen_script_tests() {
_gen_script_tests_b=$(basename "$_gen_script_tests_f" ".${_gen_script_tests_name}")
printf 'test_%s_script_%s:\n\t@export BC_TEST_OUTPUT_DIR="%s/tests"; sh \$(TESTSDIR)/script.sh %s %s %s 1 %s %s %s\n\n' \
printf 'test_%s_script_%s:\n\t@export BC_TEST_OUTPUT_DIR="%s/tests"; sh $(TESTSDIR)/script.sh %s %s %s 1 %s %s %s\n\n' \
"$_gen_script_tests_name" "$_gen_script_tests_b" "$builddir" "$_gen_script_tests_name" \
"$_gen_script_tests_f" "$_gen_script_tests_extra_math" "$_gen_script_tests_generate" \
"$_gen_script_tests_time" "$*" >> "Makefile"
@ -639,11 +687,163 @@ set_default() {
dc.prompt) dc_default_prompt="$_set_default_on" ;;
bc.expr_exit) bc_default_expr_exit="$_set_default_on";;
dc.expr_exit) dc_default_expr_exit="$_set_default_on";;
bc.digit_clamp) bc_default_digit_clamp="$_set_default_on";;
dc.digit_clamp) dc_default_digit_clamp="$_set_default_on";;
?) usage "Invalid setting: $_set_default_name" ;;
esac
}
predefined_build() {
_predefined_build_type="$1"
shift
# The reason that the variables that are being set do not have the same
# non-collision avoidance that the other variables do is that we *do* want
# the settings of these variables to leak out of the function. They adjust
# the settings outside of the function.
case "$_predefined_build_type" in
BSD)
bc_only=0
dc_only=0
coverage=0
debug=0
optimization="3"
hist=1
hist_impl="editline"
extra_math=1
generate_tests=$generate_tests
install_manpages=0
nls=1
force=0
strip_bin=1
all_locales=0
library=0
fuzz=0
time_tests=0
vg=0
memcheck=0
clean=1
bc_default_banner=0
bc_default_sigint_reset=1
dc_default_sigint_reset=1
bc_default_tty_mode=1
dc_default_tty_mode=0
bc_default_prompt=""
dc_default_prompt=""
bc_default_expr_exit=1
dc_default_expr_exit=1
bc_default_digit_clamp=0
dc_default_digit_clamp=0;;
GNU)
bc_only=0
dc_only=0
coverage=0
debug=0
optimization="3"
hist=1
hist_impl="internal"
extra_math=1
generate_tests=$generate_tests
install_manpages=1
nls=1
force=0
strip_bin=1
all_locales=0
library=0
fuzz=0
time_tests=0
vg=0
memcheck=0
clean=1
bc_default_banner=1
bc_default_sigint_reset=1
dc_default_sigint_reset=0
bc_default_tty_mode=1
dc_default_tty_mode=0
bc_default_prompt=""
dc_default_prompt=""
bc_default_expr_exit=1
dc_default_expr_exit=1
bc_default_digit_clamp=1
dc_default_digit_clamp=0;;
GDH)
CFLAGS="-flto -Weverything -Wno-padded -Werror -pedantic -std=c11"
bc_only=0
dc_only=0
coverage=0
debug=0
optimization="3"
hist=1
hist_impl="internal"
extra_math=1
generate_tests=1
install_manpages=1
nls=0
force=0
strip_bin=1
all_locales=0
library=0
fuzz=0
time_tests=0
vg=0
memcheck=0
clean=1
bc_default_banner=1
bc_default_sigint_reset=1
dc_default_sigint_reset=1
bc_default_tty_mode=1
dc_default_tty_mode=1
bc_default_prompt=""
dc_default_prompt=""
bc_default_expr_exit=0
dc_default_expr_exit=0
bc_default_digit_clamp=1
dc_default_digit_clamp=1;;
DBG)
CFLAGS="-Weverything -Wno-padded -Werror -pedantic -std=c11"
bc_only=0
dc_only=0
coverage=0
debug=1
optimization="0"
hist=1
hist_impl="internal"
extra_math=1
generate_tests=1
install_manpages=1
nls=1
force=0
strip_bin=1
all_locales=0
library=0
fuzz=0
time_tests=0
vg=0
memcheck=1
clean=1
bc_default_banner=1
bc_default_sigint_reset=1
dc_default_sigint_reset=1
bc_default_tty_mode=1
dc_default_tty_mode=1
bc_default_prompt=""
dc_default_prompt=""
bc_default_expr_exit=0
dc_default_expr_exit=0
bc_default_digit_clamp=1
dc_default_digit_clamp=1;;
?|'') usage "Invalid user build: \"$_predefined_build_type\". Accepted types are BSD, GNU, GDH, DBG.";;
esac
}
# Generates a list of script test targets that will be used as prerequisites for
# other targets.
#
@ -677,8 +877,7 @@ coverage=0
karatsuba_len=32
debug=0
hist=1
editline=0
readline=0
hist_impl="internal"
extra_math=1
optimization=""
generate_tests=1
@ -693,6 +892,7 @@ time_tests=0
vg=0
memcheck=0
clean=1
problematic_tests=1
# The empty strings are because they depend on TTY mode. If they are directly
# set, though, they will be integers. We test for empty strings later.
@ -705,11 +905,13 @@ bc_default_prompt=""
dc_default_prompt=""
bc_default_expr_exit=1
dc_default_expr_exit=1
bc_default_digit_clamp=0
dc_default_digit_clamp=0
# getopts is a POSIX utility, but it cannot handle long options. Thus, the
# handling of long options is done by hand, and that's the reason that short and
# long options cannot be mixed.
while getopts "abBcdDeEfgGhHk:lMmNO:rS:s:tTvz-" opt; do
while getopts "abBcdDeEfgGhHik:lMmNO:p:PrS:s:tTvz-" opt; do
case "$opt" in
a) library=1 ;;
@ -719,20 +921,23 @@ while getopts "abBcdDeEfgGhHk:lMmNO:rS:s:tTvz-" opt; do
C) clean=0 ;;
d) dc_only=1 ;;
D) bc_only=1 ;;
e) editline=1 ;;
e) hist_impl="editline" ;;
E) extra_math=0 ;;
f) force=1 ;;
g) debug=1 ;;
G) generate_tests=0 ;;
h) usage ;;
H) hist=0 ;;
i) hist_impl="internal" ;;
k) karatsuba_len="$OPTARG" ;;
l) all_locales=1 ;;
m) memcheck=1 ;;
M) install_manpages=0 ;;
N) nls=0 ;;
O) optimization="$OPTARG" ;;
r) readline=1 ;;
p) predefined_build "$OPTARG" ;;
P) problematic_tests=0 ;;
r) hist_impl="readline" ;;
S) set_default 0 "$OPTARG" ;;
s) set_default 1 "$OPTARG" ;;
t) time_tests=1 ;;
@ -814,13 +1019,6 @@ while getopts "abBcdDeEfgGhHk:lMmNO:rS:s:tTvz-" opt; do
fi
MAN3DIR="$2"
shift ;;
localedir=?*) LOCALEDIR="$LONG_OPTARG" ;;
localedir)
if [ "$#" -lt 2 ]; then
usage "No argument given for '--$arg' option"
fi
LOCALEDIR="$2"
shift ;;
karatsuba-len=?*) karatsuba_len="$LONG_OPTARG" ;;
karatsuba-len)
if [ "$#" -lt 2 ]; then
@ -849,6 +1047,13 @@ while getopts "abBcdDeEfgGhHk:lMmNO:rS:s:tTvz-" opt; do
fi
set_default 0 "$1"
shift ;;
predefined-build-type=?*) predefined_build "$LONG_OPTARG" ;;
predefined-build-type)
if [ "$#" -lt 2 ]; then
usage "No argument given for '--$arg' option"
fi
predefined_build "$1"
shift ;;
disable-bc) dc_only=1 ;;
disable-dc) bc_only=1 ;;
disable-clean) clean=0 ;;
@ -858,8 +1063,10 @@ while getopts "abBcdDeEfgGhHk:lMmNO:rS:s:tTvz-" opt; do
disable-man-pages) install_manpages=0 ;;
disable-nls) nls=0 ;;
disable-strip) strip_bin=0 ;;
enable-editline) editline=1 ;;
enable-readline) readline=1 ;;
disable-problematic-tests) problematic_tests=0 ;;
enable-editline) hist_impl="editline" ;;
enable-readline) hist_impl="readline" ;;
enable-internal-history) hist_impl="internal" ;;
enable-test-timing) time_tests=1 ;;
enable-valgrind) vg=1 ;;
enable-fuzz-mode) fuzz=1 ;;
@ -875,12 +1082,16 @@ while getopts "abBcdDeEfgGhHk:lMmNO:rS:s:tTvz-" opt; do
usage "No arg allowed for --$arg option" ;;
disable-man-pages* | disable-nls* | disable-strip*)
usage "No arg allowed for --$arg option" ;;
disable-problematic-tests*)
usage "No arg allowed for --$arg option" ;;
enable-fuzz-mode* | enable-test-timing* | enable-valgrind*)
usage "No arg allowed for --$arg option" ;;
enable-memcheck* | install-all-locales*)
usage "No arg allowed for --$arg option" ;;
enable-editline* | enable-readline*)
usage "No arg allowed for --$arg option" ;;
enable-internal-history*)
usage "No arg allowed for --$arg option" ;;
'') break ;; # "--" terminates argument processing
* ) usage "Invalid option $LONG_OPTARG" ;;
esac
@ -929,7 +1140,7 @@ if [ -z "${LONG_BIT+set}" ]; then
elif [ "$LONG_BIT" -lt 32 ]; then
usage "LONG_BIT is less than 32"
else
LONG_BIT_DEFINE="-DBC_LONG_BIT=\$(BC_LONG_BIT)"
LONG_BIT_DEFINE="-DBC_LONG_BIT=$LONG_BIT"
fi
if [ -z "$CC" ]; then
@ -1001,10 +1212,10 @@ executable="BC_EXEC"
tests="test_bc timeconst test_dc"
bc_test="@export BC_TEST_OUTPUT_DIR=\"$builddir/tests\"; \$(TESTSDIR)/all.sh bc $extra_math 1 $generate_tests $time_tests \$(BC_EXEC)"
bc_test_np="@export BC_TEST_OUTPUT_DIR=\"$builddir/tests\"; \$(TESTSDIR)/all.sh -n bc $extra_math 1 $generate_tests $time_tests \$(BC_EXEC)"
dc_test="@export BC_TEST_OUTPUT_DIR=\"$builddir/tests\"; \$(TESTSDIR)/all.sh dc $extra_math 1 $generate_tests $time_tests \$(DC_EXEC)"
dc_test_np="@export BC_TEST_OUTPUT_DIR=\"$builddir/tests\"; \$(TESTSDIR)/all.sh -n dc $extra_math 1 $generate_tests $time_tests \$(DC_EXEC)"
bc_test="@export BC_TEST_OUTPUT_DIR=\"$builddir/tests\"; \$(TESTSDIR)/all.sh bc $extra_math 1 $generate_tests $problematic_tests $time_tests \$(BC_EXEC)"
bc_test_np="@export BC_TEST_OUTPUT_DIR=\"$builddir/tests\"; \$(TESTSDIR)/all.sh -n bc $extra_math 1 $generate_tests $problematic_tests $time_tests \$(BC_EXEC)"
dc_test="@export BC_TEST_OUTPUT_DIR=\"$builddir/tests\"; \$(TESTSDIR)/all.sh dc $extra_math 1 $generate_tests $problematic_tests $time_tests \$(DC_EXEC)"
dc_test_np="@export BC_TEST_OUTPUT_DIR=\"$builddir/tests\"; \$(TESTSDIR)/all.sh -n dc $extra_math 1 $generate_tests $problematic_tests $time_tests \$(DC_EXEC)"
timeconst="@export BC_TEST_OUTPUT_DIR=\"$builddir/tests\"; \$(TESTSDIR)/bc/timeconst.sh \$(TESTSDIR)/bc/scripts/timeconst.bc \$(BC_EXEC)"
@ -1014,9 +1225,11 @@ if [ "$vg" -ne 0 ]; then
debug=1
bc_test_exec='valgrind $(VALGRIND_ARGS) $(BC_EXEC)'
dc_test_exec='valgrind $(VALGRIND_ARGS) $(DC_EXEC)'
bcl_test_exec='valgrind $(VALGRIND_ARGS) $(BCL_TEST)'
else
bc_test_exec='$(BC_EXEC)'
dc_test_exec='$(DC_EXEC)'
bcl_test_exec='$(BCL_TEST)'
fi
test_bc_history_prereqs="test_bc_history_all"
@ -1151,7 +1364,13 @@ if [ "$debug" -eq 1 ]; then
CFLAGS="-O0"
fi
CFLAGS="-g $CFLAGS"
ccbase=$(basename "$CC")
if [ "$ccbase" = "clang" ]; then
CFLAGS="-gdwarf-4 $CFLAGS"
else
CFLAGS="-g $CFLAGS"
fi
else
@ -1195,8 +1414,12 @@ else
destdir="DESTDIR = $DESTDIR"
fi
# defprefix is for a warning about locales later.
if [ -z "${PREFIX+set}" ]; then
PREFIX="/usr/local"
defprefix=1
else
defprefix=0
fi
if [ -z "${BINDIR+set}" ]; then
@ -1230,7 +1453,7 @@ if [ -z "${PC_PATH+set}" ]; then
fi
# Set a default for the DATAROOTDIR. This is done if either manpages will be
# installed, or locales are enabled because that's probably where NLS_PATH
# installed, or locales are enabled because that's probably where NLSPATH
# points.
if [ "$install_manpages" -ne 0 ] || [ "$nls" -ne 0 ]; then
if [ -z "${DATAROOTDIR+set}" ]; then
@ -1276,6 +1499,12 @@ if [ "$nls" -ne 0 ]; then
flags="$flags -DBC_ENABLE_EXTRA_MATH=$extra_math -I$scriptdir/include/"
flags="$flags -D_POSIX_C_SOURCE=200809L -D_XOPEN_SOURCE=700"
ccbase=$(basename "$CC")
if [ "$ccbase" = "clang" ]; then
flags="$flags -Wno-unreachable-code"
fi
"$CC" $CPPFLAGS $CFLAGS $flags -c "$scriptdir/src/vm.c" -o "./vm.o" > /dev/null 2>&1
err="$?"
@ -1351,8 +1580,15 @@ fi
# Like the above tested locale support, this tests history.
if [ "$hist" -eq 1 ]; then
if [ "$editline" -ne 0 ] && [ "$readline" -ne 0 ]; then
usage "Must only enable one of readline or editline"
if [ "$hist_impl" = "editline" ]; then
editline=1
readline=0
elif [ "$hist_impl" = "readline" ]; then
editline=0
readline=1
else
editline=0
readline=0
fi
set +e
@ -1387,6 +1623,11 @@ if [ "$hist" -eq 1 ]; then
set -e
else
editline=0
readline=0
fi
# We have to disable the history tests if it is disabled or valgrind is on. Or
@ -1430,7 +1671,7 @@ set +e
printf 'Testing for FreeBSD...\n'
flags="-DBC_TEST_FREEBSD -DBC_ENABLE_AFL=0"
"$CC" $CPPFLAGS $CFLAGS $flags "-I$scriptdir/include" -E "$scriptdir/include/status.h" > /dev/null 2>&1
"$CC" $CPPFLAGS $CFLAGS $flags "-I$scriptdir/include" -E "$scriptdir/src/vm.c" > /dev/null 2>&1
err="$?"
@ -1453,13 +1694,20 @@ set +e
printf 'Testing for OpenBSD...\n'
flags="-DBC_TEST_OPENBSD -DBC_ENABLE_AFL=0"
"$CC" $CPPFLAGS $CFLAGS $flags "-I$scriptdir/include" -E "$scriptdir/include/status.h" > /dev/null 2>&1
"$CC" $CPPFLAGS $CFLAGS $flags "-I$scriptdir/include" -E "$scriptdir/src/vm.c" > /dev/null 2>&1
err="$?"
if [ "$err" -ne 0 ]; then
printf 'On OpenBSD. Using _BSD_SOURCE.\n\n'
bsd="-D_BSD_SOURCE"
# Readline errors on OpenBSD, for some weird reason.
if [ "$readline" -ne 0 ]; then
usage "Cannot use readline on OpenBSD"
fi
else
printf 'Not on OpenBSD.\n\n'
bsd=""
@ -1475,10 +1723,12 @@ else
BC_LIB2_O=""
fi
GEN_DIR="$scriptdir/gen"
# These lines set the appropriate targets based on whether `gen/strgen.c` or
# `gen/strgen.sh` is used.
GEN="strgen"
GEN_EXEC_TARGET="\$(HOSTCC) \$(HOSTCFLAGS) -o \$(GEN_EXEC) \$(GEN_C)"
GEN_EXEC_TARGET="\$(HOSTCC) -DBC_ENABLE_AFL=0 -I$scriptdir/include/ \$(HOSTCFLAGS) -o \$(GEN_EXEC) \$(GEN_C)"
CLEAN_PREREQS=" clean_gen clean_coverage"
if [ -z "${GEN_HOST+set}" ]; then
@ -1620,7 +1870,7 @@ printf '\n'
printf 'BC_ENABLE_LIBRARY=%s\n\n' "$library"
printf 'BC_ENABLE_HISTORY=%s\n' "$hist"
printf 'BC_ENABLE_EXTRA_MATH=%s\n' "$extra_math"
printf 'BC_ENABLE_NLS=%s\n' "$nls"
printf 'BC_ENABLE_NLS=%s\n\n' "$nls"
printf 'BC_ENABLE_AFL=%s\n' "$fuzz"
printf '\n'
printf 'BC_NUM_KARATSUBA_LEN=%s\n' "$karatsuba_len"
@ -1660,6 +1910,30 @@ printf 'bc.prompt=%s\n' "$bc_default_prompt"
printf 'dc.prompt=%s\n' "$dc_default_prompt"
printf 'bc.expr_exit=%s\n' "$bc_default_expr_exit"
printf 'dc.expr_exit=%s\n' "$dc_default_expr_exit"
printf 'bc.digit_clamp=%s\n' "$bc_default_digit_clamp"
printf 'dc.digit_clamp=%s\n' "$dc_default_digit_clamp"
# This code outputs a warning. The warning is to not surprise users when locales
# are installed outside of the prefix. This warning is suppressed when the
# default prefix is used, as well, so as not to panic users just installing by
# hand. I believe this will be okay because NLSPATH is usually in /usr and the
# default prefix is /usr/local, so they'll be close that way.
if [ "$nls" -ne 0 ] && [ "${NLSPATH#$PREFIX}" = "${NLSPATH}" ] && [ "$defprefix" -eq 0 ]; then
printf '\n********************************************************************************\n\n'
printf 'WARNING: Locales will *NOT* be installed in $PREFIX (%s).\n' "$PREFIX"
printf '\n'
printf ' This is because they *MUST* be installed at a fixed location to even\n'
printf ' work, and that fixed location is $NLSPATH (%s).\n' "$NLSPATH"
printf '\n'
printf ' This location is *outside* of $PREFIX. If you do not wish to install\n'
printf ' locales outside of $PREFIX, you must disable NLS with the -N or the\n'
printf ' --disable-nls options.\n'
printf '\n'
printf ' The author apologizes for the inconvenience, but the need to install\n'
printf ' the locales at a fixed location is mandated by POSIX, and it is not\n'
printf ' possible for the author to change that requirement.\n'
printf '\n********************************************************************************\n'
fi
# This is where the real work begins. This is the point at which the Makefile.in
# template is edited and output to the Makefile.
@ -1712,6 +1986,8 @@ contents=$(replace "$contents" "DC_SCRIPT_TESTS" "$dc_script_tests")
contents=$(replace "$contents" "DC_ERROR_TESTS" "$dc_err_tests")
contents=$(replace "$contents" "DC_TEST_EXEC" "$dc_test_exec")
contents=$(replace "$contents" "BCL_TEST_EXEC" "$bcl_test_exec")
contents=$(replace "$contents" "BUILD_TYPE" "$manpage_args")
contents=$(replace "$contents" "EXCLUDE_EXTRA_MATH" "$exclude_extra_math")
@ -1787,9 +2063,9 @@ contents=$(replace "$contents" "TIMECONST" "$timeconst")
contents=$(replace "$contents" "KARATSUBA" "$karatsuba")
contents=$(replace "$contents" "KARATSUBA_TEST" "$karatsuba_test")
contents=$(replace "$contents" "LONG_BIT" "$LONG_BIT")
contents=$(replace "$contents" "LONG_BIT_DEFINE" "$LONG_BIT_DEFINE")
contents=$(replace "$contents" "GEN_DIR" "$GEN_DIR")
contents=$(replace "$contents" "GEN" "$GEN")
contents=$(replace "$contents" "GEN_EXEC_TARGET" "$GEN_EXEC_TARGET")
contents=$(replace "$contents" "CLEAN_PREREQS" "$CLEAN_PREREQS")
@ -1806,6 +2082,8 @@ contents=$(replace "$contents" "BC_DEFAULT_PROMPT" "$bc_default_prompt")
contents=$(replace "$contents" "DC_DEFAULT_PROMPT" "$dc_default_prompt")
contents=$(replace "$contents" "BC_DEFAULT_EXPR_EXIT" "$bc_default_expr_exit")
contents=$(replace "$contents" "DC_DEFAULT_EXPR_EXIT" "$dc_default_expr_exit")
contents=$(replace "$contents" "BC_DEFAULT_DIGIT_CLAMP" "$bc_default_digit_clamp")
contents=$(replace "$contents" "DC_DEFAULT_DIGIT_CLAMP" "$dc_default_digit_clamp")
# Do the first print to the Makefile.
printf '%s\n%s\n\n' "$contents" "$SRC_TARGETS" > "Makefile"

40
contrib/bc/gen/bc_help.txt
View File

@ -3,7 +3,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:
@ -62,6 +62,29 @@ This bc has three differences to the GNU bc:
This bc also implements the dot (.) extension of the BSD bc.
Options:
-C --no-digit-clamp
Disables clamping of digits that are larger than or equal to the current
ibase when parsing numbers.
This means that the value added to a number from a digit is always that
digit's value multiplied by the value of ibase raised to the power of the
digit's position, which starts from 0 at the least significant digit.
If multiple of this option and the -c option are given, the last is used.
-c --digit-clamp
Enables clamping of digits that are larger than or equal to the current
ibase when parsing numbers.
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's
position, which starts from 0 at the least significant digit.
If multiple of this option and the -C option are given, the last is used.
{{ A H N HN }}
-E seed --seed=seed
@ -189,6 +212,8 @@ Environment variables:
If an integer and non-zero, display the copyright banner in interactive
mode.
If zero, disable the banner.
Overrides the default, which is %s print the banner.
BC_SIGINT_RESET
@ -196,18 +221,24 @@ Environment variables:
If an integer and non-zero, reset on SIGINT, rather than exit, when in
interactive mode.
If zero, do not reset on SIGINT in all cases, but exit instead.
Overrides the default, which is %s.
BC_TTY_MODE
If an integer and non-zero, enable TTY mode when it is available.
If zero, disable TTY mode in all cases.
Overrides the default, which is TTY mode %s.
BC_PROMPT
If an integer and non-zero, enable prompt when TTY mode is possible.
If zero, disable prompt in all cases.
Overrides the default, which is prompt %s.
BC_EXPR_EXIT
@ -216,3 +247,10 @@ Environment variables:
given on the command-line, and does not exit when an integer and zero.
Overrides the default, which is %s.
BC_DIGIT_CLAMP
If an integer and non-zero, clamp digits larger than or equal to the
current ibase when parsing numbers.
Overrides the default, which is %s.

38
contrib/bc/gen/dc_help.txt
View File

@ -3,7 +3,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:
@ -71,6 +71,29 @@ This dc has a few differences from the two above:
that requires a register name is taken as the register name.
Options:
-C --no-digit-clamp
Disables clamping of digits that are larger than or equal to the current
ibase when parsing numbers.
This means that the value added to a number from a digit is always that
digit's value multiplied by the value of ibase raised to the power of the
digit's position, which starts from 0 at the least significant digit.
If multiple of this option and the -c option are given, the last is used.
-c --digit-clamp
Enables clamping of digits that are larger than or equal to the current
ibase when parsing numbers.
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's
position, which starts from 0 at the least significant digit.
If multiple of this option and the -C option are given, the last is used.
{{ A H N HN }}
-E seed --seed=seed
@ -155,18 +178,24 @@ Environment variables:
If an integer and non-zero, reset on SIGINT, rather than exit, when in
interactive mode.
If zero, do not reset on SIGINT in all cases, but exit instead.
Overrides the default, which is %s.
DC_TTY_MODE
If an integer and non-zero, enable TTY mode when it is available.
If zero, disable TTY mode in all cases.
Overrides the default, which is TTY mode %s.
DC_PROMPT
If an integer and non-zero, enable prompt when TTY mode is possible.
If zero, disable prompt in all cases.
Overrides the default, which is prompt %s.
DC_EXPR_EXIT
@ -175,3 +204,10 @@ Environment variables:
given on the command-line, and does not exit when an integer and zero.
Overrides the default, which is %s.
DC_DIGIT_CLAMP
If an integer and non-zero, clamp digits larger than or equal to the
current ibase when parsing numbers.
Overrides the default, which is %s.

3
contrib/bc/gen/lib.bc
View File

@ -3,7 +3,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:
@ -33,7 +33,6 @@
*
*/
scale=2*A
define e(x){
auto b,s,n,r,d,i,p,f,v
b=ibase

15
contrib/bc/gen/lib2.bc
View File

@ -3,7 +3,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:
@ -250,8 +250,7 @@ define ubytes(x){
define sbytes(x){
auto p,n,z
z=(x<0)
x=abs(x)
x=x$
x=abs(x)$
n=ubytes(x)
p=2^(n*8-1)
if(x>p||(!z&&x==p))n*=2
@ -311,21 +310,19 @@ define void pnlznl(x){
print"\n"
}
define void output_byte(x,i){
auto j,p,y,b
j=ibase
ibase=A
auto j,p,y,b,s
s=scale
scale=0
x=abs(x)$
b=x/(2^(i*8))
b%=256
y=log(256,obase)
j=2^8
b%=j
y=log(j,obase)
if(b>1)p=log(b,obase)+1
else p=b
for(i=y-p;i>0;--i)print 0
if(b)print b
scale=s
ibase=j
}
define void output_uint(x,n){
auto i

8
contrib/bc/gen/strgen.c
View File

@ -3,7 +3,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:
@ -54,9 +54,7 @@
#endif // _WIN32
// This pulls in cross-platform stuff.
#include "../include/bcl.h"
#define BC_ERR(v) (v)
#include <status.h>
// clang-format off
@ -70,7 +68,7 @@ static const char* const bc_gen_ex_end = "{{ end }}";
// This is exactly what it looks like. It just slaps a simple license header on
// the generated C source file.
static const char* const bc_gen_header =
"// Copyright (c) 2018-2021 Gavin D. Howard and contributors.\n"
"// Copyright (c) 2018-2023 Gavin D. Howard and contributors.\n"
"// Licensed under the 2-clause BSD license.\n"
"// *** AUTOMATICALLY GENERATED FROM %s. DO NOT MODIFY. ***\n\n";
// clang-format on

6
contrib/bc/gen/strgen.sh
View File

@ -2,7 +2,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:
@ -52,7 +52,7 @@ label="$5"
define="$6"
remove_tabs="$7"
tmpinput=$(mktemp -t "${input##*/}")
tmpinput=$(mktemp -t "${input##*/}_XXXXXX")
if [ "$exclude" -ne 0 ]; then
filter_text "$input" "$tmpinput" "E"
@ -82,7 +82,7 @@ if [ -n "$remove_tabs" ]; then
fi
cat<<EOF
// Copyright (c) 2018-2021 Gavin D. Howard and contributors.
// Copyright (c) 2018-2023 Gavin D. Howard and contributors.
// Licensed under the 2-clause BSD license.
// *** AUTOMATICALLY GENERATED FROM ${input}. DO NOT MODIFY. ***

33
contrib/bc/include/args.h
View File

@ -3,7 +3,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:
@ -46,10 +46,37 @@
* @param argv The array of arguments.
* @param exit_exprs True if bc/dc should exit when there are expressions,
* false otherwise.
* @param scale The current scale.
* @param scale A pointer to return the scale that the arguments set, if
* any.
* @param ibase A pointer to return the ibase that the arguments set, if
* any.
* @param obase A pointer to return the obase that the arguments set, if
* any.
*/
void
bc_args(int argc, char* argv[], bool exit_exprs, BcBigDig scale);
bc_args(int argc, char* argv[], bool exit_exprs, BcBigDig* scale,
BcBigDig* ibase, BcBigDig* obase);
#if BC_ENABLED
#if DC_ENABLED
/// Returns true if the banner should be quieted.
#define BC_ARGS_SHOULD_BE_QUIET (BC_IS_DC || vm->exprs.len > 1)
#else // DC_ENABLED
/// Returns true if the banner should be quieted.
#define BC_ARGS_SHOULD_BE_QUIET (vm->exprs.len > 1)
#endif // DC_ENABLED
#else // BC_ENABLED
/// Returns true if the banner should be quieted.
#define BC_ARGS_SHOULD_BE_QUIET (BC_IS_DC)
#endif // BC_ENABLED
// A reference to the list of long options.
extern const BcOptLong bc_args_lopt[];

6
contrib/bc/include/bc.h
View File

@ -3,7 +3,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:
@ -97,13 +97,13 @@ typedef struct BcLexKeyword
/// A macro for the number of keywords bc has. This has to be updated if any are
/// added. This is for the redefined_kws field of the BcVm struct.
#define BC_LEX_NKWS (35)
#define BC_LEX_NKWS (37)
#else // BC_ENABLE_EXTRA_MATH
/// A macro for the number of keywords bc has. This has to be updated if any are
/// added. This is for the redefined_kws field of the BcVm struct.
#define BC_LEX_NKWS (31)
#define BC_LEX_NKWS (33)
#endif // BC_ENABLE_EXTRA_MATH

57
contrib/bc/include/bcl.h
View File

@ -3,7 +3,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:
@ -36,6 +36,11 @@
#ifndef BC_BCL_H
#define BC_BCL_H
#include <stdbool.h>
#include <stdlib.h>
#include <limits.h>
#include <stdint.h>
#ifdef _WIN32
#include <Windows.h>
#include <BaseTsd.h>
@ -43,44 +48,8 @@
#include <io.h>
#endif // _WIN32
#include <stdbool.h>
#include <stdlib.h>
#include <limits.h>
#include <stdint.h>
#include <sys/types.h>
// Windows has deprecated isatty() and the rest of these. Or doesn't have them.
// So these are just fixes for Windows.
#ifdef _WIN32
// This one is special. Windows did not like me defining an
// inline function that was not given a definition in a header
// file. This suppresses that by making inline functions non-inline.
#define inline
#define restrict __restrict
#define strdup _strdup
#define write(f, b, s) _write((f), (b), (unsigned int) (s))
#define read(f, b, s) _read((f), (b), (unsigned int) (s))
#define close _close
#define open(f, n, m) \
_sopen_s((f), (n), (m) | _O_BINARY, _SH_DENYNO, _S_IREAD | _S_IWRITE)
#define sigjmp_buf jmp_buf
#define sigsetjmp(j, s) setjmp(j)
#define siglongjmp longjmp
#define isatty _isatty
#define STDIN_FILENO _fileno(stdin)
#define STDOUT_FILENO _fileno(stdout)
#define STDERR_FILENO _fileno(stderr)
#define ssize_t SSIZE_T
#define S_ISDIR(m) ((m) & (_S_IFDIR))
#define O_RDONLY _O_RDONLY
#define stat _stat
#define fstat _fstat
#define BC_FILE_SEP '\\'
#else // _WIN32
#define BC_FILE_SEP '/'
#endif // _WIN32
#define BCL_SEED_ULONGS (4)
@ -161,11 +130,11 @@ struct BclCtxt;
typedef struct BclCtxt* BclContext;
void
bcl_handleSignal(void);
BclError
bcl_start(void);
bool
bcl_running(void);
void
bcl_end(void);
BclError
bcl_init(void);
@ -185,6 +154,12 @@ bcl_leadingZeroes(void);
void
bcl_setLeadingZeroes(bool leadingZeroes);
bool
bcl_digitClamp(void);
void
bcl_setDigitClamp(bool digitClamp);
void
bcl_gc(void);

2
contrib/bc/include/dc.h
View File

@ -3,7 +3,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:

20
contrib/bc/include/file.h
View File

@ -3,7 +3,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:
@ -98,16 +98,24 @@ typedef enum BcFlushType
} BcFlushType;
// These are here to satisfy a clang warning about recursive macros.
#define bc_file_putchar(f, t, c) bc_file_putchar_impl(f, t, c)
#define bc_file_flushErr(f, t) bc_file_flushErr_impl(f, t)
#define bc_file_flush(f, t) bc_file_flush_impl(f, t)
#define bc_file_write(f, t, b, n) bc_file_write_impl(f, t, b, n)
#define bc_file_puts(f, t, s) bc_file_puts_impl(f, t, s)
#else // BC_ENABLE_HISTORY && !BC_ENABLE_LINE_LIB
// These make sure that the BcFlushType parameter disappears if history is not
// used, editline is used, or readline is used.
#define bc_file_putchar(f, t, c) bc_file_putchar(f, c)
#define bc_file_flushErr(f, t) bc_file_flushErr(f)
#define bc_file_flush(f, t) bc_file_flush(f)
#define bc_file_write(f, t, b, n) bc_file_write(f, b, n)
#define bc_file_puts(f, t, s) bc_file_puts(f, s)
#define bc_file_putchar(f, t, c) bc_file_putchar_impl(f, c)
#define bc_file_flushErr(f, t) bc_file_flushErr_impl(f)
#define bc_file_flush(f, t) bc_file_flush_impl(f)
#define bc_file_write(f, t, b, n) bc_file_write_impl(f, b, n)
#define bc_file_puts(f, t, s) bc_file_puts_impl(f, s)
#endif // BC_ENABLE_HISTORY && !BC_ENABLE_LINE_LIB

30
contrib/bc/include/history.h
View File

@ -3,7 +3,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:
@ -79,27 +79,10 @@
#ifndef BC_HISTORY_H
#define BC_HISTORY_H
#ifndef BC_ENABLE_HISTORY
#define BC_ENABLE_HISTORY (1)
#endif // BC_ENABLE_HISTORY
#ifndef BC_ENABLE_EDITLINE
#define BC_ENABLE_EDITLINE (0)
#endif // BC_ENABLE_EDITLINE
#ifndef BC_ENABLE_READLINE
#define BC_ENABLE_READLINE (0)
#endif // BC_ENABLE_READLINE
#if BC_ENABLE_EDITLINE && BC_ENABLE_READLINE
#error Must enable only one of editline or readline, not both.
#endif // BC_ENABLE_EDITLINE && BC_ENABLE_READLINE
#if BC_ENABLE_EDITLINE || BC_ENABLE_READLINE
#define BC_ENABLE_LINE_LIB (1)
#else // BC_ENABLE_EDITLINE || BC_ENABLE_READLINE
#define BC_ENABLE_LINE_LIB (0)
#endif // BC_ENABLE_EDITLINE || BC_ENABLE_READLINE
// These must come before the #if BC_ENABLE_LINE_LIB below because status.h
// defines it.
#include <status.h>
#include <vector.h>
#if BC_ENABLE_LINE_LIB
@ -107,9 +90,6 @@
#include <setjmp.h>
#include <signal.h>
#include <status.h>
#include <vector.h>
extern sigjmp_buf bc_history_jmpbuf;
extern volatile sig_atomic_t bc_history_inlinelib;

39
contrib/bc/include/lang.h
View File

@ -3,7 +3,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:
@ -38,19 +38,19 @@
#include <stdbool.h>
#if BC_C11
#include <assert.h>
#endif // BC_C11
// These have to come first to silence a warning on BC_C11 below.
#include <status.h>
#include <vector.h>
#include <num.h>
#if BC_C11
#include <assert.h>
#endif // BC_C11
/// The instructions for bytecode.
typedef enum BcInst
{
#if BC_ENABLED
/// Postfix increment and decrement. Prefix are translated into
/// BC_INST_ONE with either BC_INST_ASSIGN_PLUS or BC_INST_ASSIGN_MINUS.
BC_INST_INC = 0,
@ -62,6 +62,7 @@ typedef enum BcInst
/// Boolean not.
BC_INST_BOOL_NOT,
#if BC_ENABLE_EXTRA_MATH
/// Truncation operator.
BC_INST_TRUNC,
@ -76,7 +77,6 @@ typedef enum BcInst
BC_INST_MINUS,
#if BC_ENABLE_EXTRA_MATH
/// Places operator.
BC_INST_PLACES,
@ -178,6 +178,8 @@ typedef enum BcInst
BC_INST_SCALE_FUNC,
BC_INST_SQRT,
BC_INST_ABS,
BC_INST_IS_NUMBER,
BC_INST_IS_STRING,
#if BC_ENABLE_EXTRA_MATH
/// Another builtin function.
@ -350,6 +352,12 @@ typedef struct BcLoc
/// The index of the var or array.
size_t loc;
/// The index of the array or variable in the array stack. This is to
/// prevent a bug with getting the wrong array element or variable after a
/// function call. See the tests/bc/scripts/array.bc test for the array
/// case; the variable case is in various variable tests.
size_t stack_idx;
/// The index of the array element. Only used for array elements.
size_t idx;
@ -392,12 +400,6 @@ typedef struct BcFunc
#endif // BC_ENABLED
/// The strings encountered in the function.
BcVec strs;
/// The constants encountered in the function.
BcVec consts;
/// The function's name.
const char* name;
@ -660,17 +662,6 @@ bc_result_free(void* result);
void
bc_array_expand(BcVec* a, size_t len);
/**
* Compare two BcId's and return the result. Since they are just comparing the
* names in the BcId, I return the result from strcmp() exactly. This is used by
* maps in their binary search.
* @param e1 The first id.
* @param e2 The second id.
* @return The result of strcmp() on the BcId's names.
*/
int
bc_id_cmp(const BcId* e1, const BcId* e2);
#if BC_ENABLED
/**

59
contrib/bc/include/lex.h
View File

@ -3,7 +3,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:
@ -43,10 +43,30 @@
#include <vector.h>
#include <lang.h>
// Two convencience macros for throwing errors in lex code. They take care of
// plumbing like passing in the current line the lexer is on.
/**
* A convenience macro for throwing errors in lex code. This takes care of
* plumbing like passing in the current line the lexer is on.
* @param l The lexer.
* @param e The error.
*/
#ifndef NDEBUG
#define bc_lex_err(l, e) (bc_vm_handleError((e), __FILE__, __LINE__, (l)->line))
#else // NDEBUG
#define bc_lex_err(l, e) (bc_vm_handleError((e), (l)->line))
#endif // NDEBUG
/**
* A convenience macro for throwing errors in lex code. This takes care of
* plumbing like passing in the current line the lexer is on.
* @param l The lexer.
* @param e The error.
*/
#ifndef NDEBUG
#define bc_lex_verr(l, e, ...) \
(bc_vm_handleError((e), __FILE__, __LINE__, (l)->line, __VA_ARGS__))
#else // NDEBUG
#define bc_lex_verr(l, e, ...) (bc_vm_handleError((e), (l)->line, __VA_ARGS__))
#endif // NDEBUG
// BC_LEX_NEG_CHAR returns the char that corresponds to negative for the
// current calculator.
@ -136,6 +156,7 @@ typedef enum BcLexType
BC_LEX_OP_MINUS,
#if BC_ENABLE_EXTRA_MATH
/// Places (truncate or extend) operator.
BC_LEX_OP_PLACES,
@ -144,6 +165,7 @@ typedef enum BcLexType
/// Right (decimal) shift operator.
BC_LEX_OP_RSHIFT,
#endif // BC_ENABLE_EXTRA_MATH
/// Equal operator.
@ -171,6 +193,7 @@ typedef enum BcLexType
BC_LEX_OP_BOOL_AND,
#if BC_ENABLED
/// Power assignment operator.
BC_LEX_OP_ASSIGN_POWER,
@ -314,6 +337,12 @@ typedef enum BcLexType
/// bc abs keyword.
BC_LEX_KW_ABS,
/// bc is_number keyword.
BC_LEX_KW_IS_NUMBER,
/// bc is_string keyword.
BC_LEX_KW_IS_STRING,
#if BC_ENABLE_EXTRA_MATH
/// bc irand keyword.
@ -353,8 +382,10 @@ typedef enum BcLexType
BC_LEX_KW_MAXSCALE,
#if BC_ENABLE_EXTRA_MATH
/// bc maxrand keyword.
BC_LEX_KW_MAXRAND,
#endif // BC_ENABLE_EXTRA_MATH
/// bc line_length keyword.
@ -418,8 +449,10 @@ typedef enum BcLexType
BC_LEX_STORE_SCALE,
#if BC_ENABLE_EXTRA_MATH
/// Store seed command.
BC_LEX_STORE_SEED,
#endif // BC_ENABLE_EXTRA_MATH
/// Load variable onto stack command.
@ -487,14 +520,8 @@ typedef struct BcLex
/// string.
BcVec str;
/// If this is true, the lexer is processing stdin and can ask for more data
/// if a string or comment are not properly terminated.
bool is_stdin;
/// If this is true, the lexer is processing expressions from the
/// command-line and can ask for more data if a string or comment are not
/// properly terminated.
bool is_exprs;
/// The mode the lexer is in.
BcMode mode;
} BcLex;
@ -524,14 +551,12 @@ bc_lex_file(BcLex* l, const char* file);
/**
* Sets the text the lexer will lex.
* @param l The lexer.
* @param text The text to lex.
* @param is_stdin True if the text is from stdin, false otherwise.
* @param is_exprs True if the text is from command-line expressions, false
* otherwise.
* @param l The lexer.
* @param text The text to lex.
* @param mode The mode to lex in.
*/
void
bc_lex_text(BcLex* l, const char* text, bool is_stdin, bool is_exprs);
bc_lex_text(BcLex* l, const char* text, BcMode mode);
/**
* Generic next function for the parser to call. It takes care of calling the

144
contrib/bc/include/library.h
View File

@ -3,7 +3,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:
@ -36,94 +36,51 @@
#ifndef LIBBC_PRIVATE_H
#define LIBBC_PRIVATE_H
#ifndef _WIN32
#include <pthread.h>
#endif // _WIN32
#include <bcl.h>
#include <num.h>
#include <vm.h>
/**
* A header for functions that need to lock and setjmp(). It also sets the
* variable that tells bcl that it is running.
* @param l The label to jump to on error.
* A header that sets a jump.
* @param vm The thread data.
* @param l The label to jump to on error.
*/
#define BC_FUNC_HEADER_LOCK(l) \
do \
{ \
BC_SIG_LOCK; \
BC_SETJMP_LOCKED(l); \
vm.err = BCL_ERROR_NONE; \
vm.running = 1; \
} \
#define BC_FUNC_HEADER(vm, l) \
do \
{ \
BC_SETJMP(vm, l); \
vm->err = BCL_ERROR_NONE; \
} \
while (0)
/**
* A footer to unlock and stop the jumping if an error happened. It also sets
* the variable that tells bcl that it is running.
* @param e The error variable to set.
* A footer for functions that do not return an error code.
*/
#define BC_FUNC_FOOTER_UNLOCK(e) \
do \
{ \
BC_SIG_ASSERT_LOCKED; \
e = vm.err; \
vm.running = 0; \
BC_UNSETJMP; \
BC_LONGJMP_STOP; \
vm.sig_lock = 0; \
} \
#define BC_FUNC_FOOTER_NO_ERR(vm) \
do \
{ \
BC_UNSETJMP(vm); \
} \
while (0)
/**
* A header that sets a jump and sets running.
* @param l The label to jump to on error.
* A footer for functions that *do* return an error code.
* @param vm The thread data.
* @param e The error variable to set.
*/
#define BC_FUNC_HEADER(l) \
do \
{ \
BC_SETJMP(l); \
vm.err = BCL_ERROR_NONE; \
vm.running = 1; \
} \
while (0)
/**
* A header that assumes that signals are already locked. It sets a jump and
* running.
* @param l The label to jump to on error.
*/
#define BC_FUNC_HEADER_INIT(l) \
do \
{ \
BC_SETJMP_LOCKED(l); \
vm.err = BCL_ERROR_NONE; \
vm.running = 1; \
} \
while (0)
/**
* A footer for functions that do not return an error code. It clears running
* and unlocks the signals. It also stops the jumping.
*/
#define BC_FUNC_FOOTER_NO_ERR \
do \
{ \
vm.running = 0; \
BC_UNSETJMP; \
BC_LONGJMP_STOP; \
vm.sig_lock = 0; \
} \
while (0)
/**
* A footer for functions that *do* return an error code. It clears running and
* unlocks the signals. It also stops the jumping.
* @param e The error variable to set.
*/
#define BC_FUNC_FOOTER(e) \
do \
{ \
e = vm.err; \
BC_FUNC_FOOTER_NO_ERR; \
} \
#define BC_FUNC_FOOTER(vm, e) \
do \
{ \
e = vm->err; \
BC_FUNC_FOOTER_NO_ERR(vm); \
} \
while (0)
/**
@ -151,10 +108,10 @@
* is bad.
* @param c The context.
*/
#define BC_CHECK_CTXT(c) \
#define BC_CHECK_CTXT(vm, c) \
do \
{ \
c = bcl_context(); \
c = bcl_contextHelper(vm); \
if (BC_ERR(c == NULL)) \
{ \
BclNumber n_num; \
@ -168,10 +125,10 @@
* A header to check the context and return an error directly if it is bad.
* @param c The context.
*/
#define BC_CHECK_CTXT_ERR(c) \
#define BC_CHECK_CTXT_ERR(vm, c) \
do \
{ \
c = bcl_context(); \
c = bcl_contextHelper(vm); \
if (BC_ERR(c == NULL)) \
{ \
return BCL_ERROR_INVALID_CONTEXT; \
@ -183,12 +140,12 @@
* A header to check the context and abort if it is bad.
* @param c The context.
*/
#define BC_CHECK_CTXT_ASSERT(c) \
do \
{ \
c = bcl_context(); \
assert(c != NULL); \
} \
#define BC_CHECK_CTXT_ASSERT(vm, c) \
do \
{ \
c = bcl_contextHelper(vm); \
assert(c != NULL); \
} \
while (0)
/**
@ -272,4 +229,21 @@ typedef struct BclCtxt
} BclCtxt;
/**
* Returns the @a BcVm for the current thread.
* @return The vm for the current thread.
*/
BcVm*
bcl_getspecific(void);
#ifndef _WIN32
typedef pthread_key_t BclTls;
#else // _WIN32
typedef DWORD BclTls;
#endif // _WIN32
#endif // LIBBC_PRIVATE_H

14
contrib/bc/include/num.h
View File

@ -3,7 +3,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:
@ -47,10 +47,6 @@
#include <vector.h>
#include <bcl.h>
#ifndef BC_ENABLE_EXTRA_MATH
#define BC_ENABLE_EXTRA_MATH (1)
#endif // BC_ENABLE_EXTRA_MATH
/// Everything in bc is base 10..
#define BC_BASE (10)
@ -829,6 +825,14 @@ bc_num_parse(BcNum* restrict n, const char* restrict val, BcBigDig base);
void
bc_num_print(BcNum* restrict n, BcBigDig base, bool newline);
/**
* Invert @a into @a b at the current scale.
* @param a The number to invert.
* @param b The return parameter. This must be preallocated.
* @param scale The current scale.
*/
#define bc_num_inv(a, b, scale) bc_num_div(&vm->one, (a), (b), (scale))
#if !BC_ENABLE_LIBRARY
/**

2
contrib/bc/include/opt.h
View File

@ -3,7 +3,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:

40
contrib/bc/include/parse.h
View File

@ -3,7 +3,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:
@ -80,18 +80,6 @@
*/
#define BC_PARSE_IS_INITED(p, prg) ((p)->prog == (prg))
#if BC_ENABLED
/**
* Returns true if the current parser state allows parsing, false otherwise.
* @param p The parser.
* @return True if parsing can proceed, false otherwise.
*/
#define BC_PARSE_CAN_PARSE(p) \
((p).l.t != BC_LEX_EOF && (p).l.t != BC_LEX_KW_DEFINE)
#else // BC_ENABLED
/**
* Returns true if the current parser state allows parsing, false otherwise.
* @param p The parser.
@ -99,8 +87,6 @@
*/
#define BC_PARSE_CAN_PARSE(p) ((p).l.t != BC_LEX_EOF)
#endif // BC_ENABLED
/**
* Pushes the instruction @a i onto the bytecode vector for the current
* function.
@ -119,22 +105,32 @@
#define bc_parse_pushIndex(p, idx) (bc_vec_pushIndex(&(p)->func->code, (idx)))
/**
* A convenience macro for throwing errors in parse code. They take care of
* A convenience macro for throwing errors in parse code. This takes care of
* plumbing like passing in the current line the lexer is on.
* @param p The parser.
* @param e The error.
*/
#ifndef NDEBUG
#define bc_parse_err(p, e) \
(bc_vm_handleError((e), __FILE__, __LINE__, (p)->l.line))
#else // NDEBUG
#define bc_parse_err(p, e) (bc_vm_handleError((e), (p)->l.line))
#endif // NDEBUG
/**
* A convenience macro for throwing errors in parse code. They take care of
* A convenience macro for throwing errors in parse code. This takes care of
* plumbing like passing in the current line the lexer is on.
* @param p The parser.
* @param e The error.
* @param ... The varags that are needed.
*/
#ifndef NDEBUG
#define bc_parse_verr(p, e, ...) \
(bc_vm_handleError((e), __FILE__, __LINE__, (p)->l.line, __VA_ARGS__))
#else // NDEBUG
#define bc_parse_verr(p, e, ...) \
(bc_vm_handleError((e), (p)->l.line, __VA_ARGS__))
#endif // NDEBUG
// Forward declarations.
struct BcParse;
@ -268,14 +264,12 @@ bc_parse_pushName(const BcParse* p, char* name, bool var);
/**
* Sets the text that the parser will parse.
* @param p The parser.
* @param text The text to lex.
* @param is_stdin True if the text is from stdin, false otherwise.
* @param is_exprs True if the text is from command-line expressions, false
* otherwise.
* @param p The parser.
* @param text The text to lex.
* @param mode The mode to parse in.
*/
void
bc_parse_text(BcParse* p, const char* text, bool is_stdin, bool is_exprs);
bc_parse_text(BcParse* p, const char* text, BcMode mode);
// References to const 0 and 1 strings for special cases. bc and dc have
// specific instructions for 0 and 1 because they pop up so often and (in the

104
contrib/bc/include/program.h
View File

@ -3,7 +3,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:
@ -69,8 +69,10 @@ typedef struct BcProgram
/// The array of globals values.
BcBigDig globals[BC_PROG_GLOBALS_LEN];
#if BC_ENABLED
/// The array of globals stacks.
BcVec globals_v[BC_PROG_GLOBALS_LEN];
#endif // BC_ENABLED
#if BC_ENABLE_EXTRA_MATH
@ -85,11 +87,21 @@ typedef struct BcProgram
/// The execution stack.
BcVec stack;
/// A pointer to the current function's constants.
BcVec* consts;
/// The constants encountered in the program. They are global to the program
/// to prevent bad accesses when functions that used non-auto variables are
/// replaced.
BcVec consts;
/// A pointer to the current function's strings.
BcVec* strs;
/// The map of constants to go with consts.
BcVec const_map;
/// The strings encountered in the program. They are global to the program
/// to prevent bad accesses when functions that used non-auto variables are
/// replaced.
BcVec strs;
/// The map of strings to go with strs.
BcVec str_map;
/// The array of functions.
BcVec fns;
@ -122,6 +134,10 @@ typedef struct BcProgram
/// A BcNum that has the proper base for asciify.
BcNum strmb;
// A BcNum to run asciify. This is to prevent GCC longjmp() clobbering
// warnings.
BcNum asciify;
#if BC_ENABLED
/// The last printed value for bc.
@ -204,18 +220,29 @@ typedef struct BcProgram
#if !BC_ENABLED
/// This define disappears the parameter last because for dc only, last is
/// always true.
#define bc_program_copyToVar(p, name, t, last) bc_program_copyToVar(p, name, t)
/// Returns true if the calculator should pop after printing.
#define BC_PROGRAM_POP(pop) (pop)
#else // !BC_ENABLED
/// Returns true if the calculator should pop after printing.
#define BC_PROGRAM_POP(pop) (BC_IS_BC || (pop))
#endif // !BC_ENABLED
// This is here to satisfy a clang warning about recursive macros.
#define bc_program_pushVar(p, code, bgn, pop, copy) \
bc_program_pushVar_impl(p, code, bgn, pop, copy)
#else // DC_ENABLED
/// This define disappears pop and copy because for bc, 'pop' and 'copy' are
/// always false.
// This define disappears pop and copy because for bc, 'pop' and 'copy' are
// always false.
#define bc_program_pushVar(p, code, bgn, pop, copy) \
bc_program_pushVar(p, code, bgn)
bc_program_pushVar_impl(p, code, bgn)
/// Returns true if the calculator should pop after printing.
#define BC_PROGRAM_POP(pop) (BC_IS_BC)
// In debug mode, we want bc to check the stack, but otherwise, we don't because
// the bc language implicitly mandates that the stack should always have enough
@ -284,6 +311,13 @@ bc_program_free(BcProgram* p);
#endif // NDEBUG
/**
* Prints a stack trace of the bc functions or dc strings currently executing.
* @param p The program.
*/
void
bc_program_printStackTrace(BcProgram* p);
#if BC_DEBUG_CODE
#if BC_ENABLED && DC_ENABLED
@ -317,22 +351,22 @@ bc_program_printStackDebug(BcProgram* p);
/**
* Returns the index of the variable or array in their respective arrays.
* @param p The program.
* @param id The BcId of the variable or array.
* @param var True if the search should be for a variable, false for an array.
* @return The index of the variable or array in the correct array.
* @param p The program.
* @param name The name of the variable or array.
* @param var True if the search should be for a variable, false for an array.
* @return The index of the variable or array in the correct array.
*/
size_t
bc_program_search(BcProgram* p, const char* id, bool var);
bc_program_search(BcProgram* p, const char* name, bool var);
/**
* Adds a string to a function and returns the string's index in the function.
* @param p The program.
* @param str The string to add.
* @param fidx The index of the function to add to.
* Adds a string to the program and returns the string's index in the program.
* @param p The program.
* @param str The string to add.
* @return The string's index in the program.
*/
size_t
bc_program_addString(BcProgram* p, const char* str, size_t fidx);
bc_program_addString(BcProgram* p, const char* str);
/**
* Inserts a function into the program and returns the index of the function in
@ -438,14 +472,14 @@ extern const char bc_program_esc_seqs[];
#if BC_DEBUG_CODE
// clang-format off
#define BC_PROG_JUMP(inst, code, ip) \
do \
{ \
inst = (uchar) (code)[(ip)->idx++]; \
bc_file_printf(&vm.ferr, "inst: %s\n", bc_inst_names[inst]); \
bc_file_flush(&vm.ferr, bc_flush_none); \
goto *bc_program_inst_lbls[inst]; \
} \
#define BC_PROG_JUMP(inst, code, ip) \
do \
{ \
inst = (uchar) (code)[(ip)->idx++]; \
bc_file_printf(&vm->ferr, "inst: %s\n", bc_inst_names[inst]); \
bc_file_flush(&vm->ferr, bc_flush_none); \
goto *bc_program_inst_lbls[inst]; \
} \
while (0)
// clang-format on
@ -545,6 +579,8 @@ extern const char bc_program_esc_seqs[];
&&lbl_BC_INST_SCALE_FUNC, \
&&lbl_BC_INST_SQRT, \
&&lbl_BC_INST_ABS, \
&&lbl_BC_INST_IS_NUMBER, \
&&lbl_BC_INST_IS_STRING, \
&&lbl_BC_INST_IRAND, \
&&lbl_BC_INST_ASCIIFY, \
&&lbl_BC_INST_READ, \
@ -639,6 +675,8 @@ extern const char bc_program_esc_seqs[];
&&lbl_BC_INST_SCALE_FUNC, \
&&lbl_BC_INST_SQRT, \
&&lbl_BC_INST_ABS, \
&&lbl_BC_INST_IS_NUMBER, \
&&lbl_BC_INST_IS_STRING, \
&&lbl_BC_INST_ASCIIFY, \
&&lbl_BC_INST_READ, \
&&lbl_BC_INST_MAXIBASE, \
@ -745,6 +783,8 @@ extern const char bc_program_esc_seqs[];
&&lbl_BC_INST_SCALE_FUNC, \
&&lbl_BC_INST_SQRT, \
&&lbl_BC_INST_ABS, \
&&lbl_BC_INST_IS_NUMBER, \
&&lbl_BC_INST_IS_STRING, \
&&lbl_BC_INST_IRAND, \
&&lbl_BC_INST_ASCIIFY, \
&&lbl_BC_INST_READ, \
@ -825,6 +865,8 @@ extern const char bc_program_esc_seqs[];
&&lbl_BC_INST_SCALE_FUNC, \
&&lbl_BC_INST_SQRT, \
&&lbl_BC_INST_ABS, \
&&lbl_BC_INST_IS_NUMBER, \
&&lbl_BC_INST_IS_STRING, \
&&lbl_BC_INST_ASCIIFY, \
&&lbl_BC_INST_READ, \
&&lbl_BC_INST_MAXIBASE, \
@ -897,6 +939,8 @@ extern const char bc_program_esc_seqs[];
&&lbl_BC_INST_SCALE_FUNC, \
&&lbl_BC_INST_SQRT, \
&&lbl_BC_INST_ABS, \
&&lbl_BC_INST_IS_NUMBER, \
&&lbl_BC_INST_IS_STRING, \
&&lbl_BC_INST_IRAND, \
&&lbl_BC_INST_ASCIIFY, \
&&lbl_BC_INST_READ, \
@ -966,6 +1010,8 @@ extern const char bc_program_esc_seqs[];
&&lbl_BC_INST_SCALE_FUNC, \
&&lbl_BC_INST_SQRT, \
&&lbl_BC_INST_ABS, \
&&lbl_BC_INST_IS_NUMBER, \
&&lbl_BC_INST_IS_STRING, \
&&lbl_BC_INST_ASCIIFY, \
&&lbl_BC_INST_READ, \
&&lbl_BC_INST_MAXIBASE, \

2
contrib/bc/include/rand.h
View File

@ -13,7 +13,7 @@
* This code is under the following license:
*
* Copyright (c) 2014-2017 Melissa O'Neill and PCG Project contributors
* Copyright (c) 2018-2021 Gavin D. Howard and contributors.
* Copyright (c) 2018-2023 Gavin D. Howard and contributors.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal

2
contrib/bc/include/read.h
View File

@ -3,7 +3,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:

465
contrib/bc/include/status.h
View File

@ -3,7 +3,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:
@ -36,7 +36,15 @@
#ifndef BC_STATUS_H
#define BC_STATUS_H
#ifdef _WIN32
#include <Windows.h>
#include <BaseTsd.h>
#include <stdio.h>
#include <io.h>
#endif // _WIN32
#include <stdint.h>
#include <sys/types.h>
// This is used by configure.sh to test for OpenBSD.
#ifdef BC_TEST_OPENBSD
@ -52,6 +60,39 @@
#endif // __FreeBSD__
#endif // BC_TEST_FREEBSD
// Windows has deprecated isatty() and the rest of these. Or doesn't have them.
// So these are just fixes for Windows.
#ifdef _WIN32
// This one is special. Windows did not like me defining an
// inline function that was not given a definition in a header
// file. This suppresses that by making inline functions non-inline.
#define inline
#define restrict __restrict
#define strdup _strdup
#define write(f, b, s) _write((f), (b), (unsigned int) (s))
#define read(f, b, s) _read((f), (b), (unsigned int) (s))
#define close _close
#define open(f, n, m) \
_sopen_s((f), (n), (m) | _O_BINARY, _SH_DENYNO, _S_IREAD | _S_IWRITE)
#define sigjmp_buf jmp_buf
#define sigsetjmp(j, s) setjmp(j)
#define siglongjmp longjmp
#define isatty _isatty
#define STDIN_FILENO _fileno(stdin)
#define STDOUT_FILENO _fileno(stdout)
#define STDERR_FILENO _fileno(stderr)
#define S_ISDIR(m) ((m) & (_S_IFDIR))
#define O_RDONLY _O_RDONLY
#define stat _stat
#define fstat _fstat
#define BC_FILE_SEP '\\'
#else // _WIN32
#define BC_FILE_SEP '/'
#endif // _WIN32
#ifndef BC_ENABLED
#define BC_ENABLED (1)
#endif // BC_ENABLED
@ -60,10 +101,46 @@
#define DC_ENABLED (1)
#endif // DC_ENABLED
#ifndef BC_ENABLE_EXTRA_MATH
#define BC_ENABLE_EXTRA_MATH (1)
#endif // BC_ENABLE_EXTRA_MATH
#ifndef BC_ENABLE_LIBRARY
#define BC_ENABLE_LIBRARY (0)
#endif // BC_ENABLE_LIBRARY
#ifndef BC_ENABLE_HISTORY
#define BC_ENABLE_HISTORY (1)
#endif // BC_ENABLE_HISTORY
#ifndef BC_ENABLE_EDITLINE
#define BC_ENABLE_EDITLINE (0)
#endif // BC_ENABLE_EDITLINE
#ifndef BC_ENABLE_READLINE
#define BC_ENABLE_READLINE (0)
#endif // BC_ENABLE_READLINE
#ifndef BC_ENABLE_NLS
#define BC_ENABLE_NLS (0)
#endif // BC_ENABLE_NLS
#ifdef __OpenBSD__
#if BC_ENABLE_READLINE
#error Cannot use readline on OpenBSD
#endif // BC_ENABLE_READLINE
#endif // __OpenBSD__
#if BC_ENABLE_EDITLINE && BC_ENABLE_READLINE
#error Must enable only one of editline or readline, not both.
#endif // BC_ENABLE_EDITLINE && BC_ENABLE_READLINE
#if BC_ENABLE_EDITLINE || BC_ENABLE_READLINE
#define BC_ENABLE_LINE_LIB (1)
#else // BC_ENABLE_EDITLINE || BC_ENABLE_READLINE
#define BC_ENABLE_LINE_LIB (0)
#endif // BC_ENABLE_EDITLINE || BC_ENABLE_READLINE
// This is error checking for fuzz builds.
#if BC_ENABLE_AFL
#ifndef __AFL_HAVE_MANUAL_CONTROL
@ -122,6 +199,18 @@
#define BC_DEBUG_CODE (0)
#endif // BC_DEBUG_CODE
#if defined(__clang__)
#define BC_CLANG (1)
#else // defined(__clang__)
#define BC_CLANG (0)
#endif // defined(__clang__)
#if defined(__GNUC__) && !BC_CLANG
#define BC_GCC (1)
#else // defined(__GNUC__) && !BC_CLANG
#define BC_GCC (0)
#endif // defined(__GNUC__) && !BC_CLANG
// We want to be able to use _Noreturn on C11 compilers.
#if __STDC_VERSION__ >= 201112L
@ -131,7 +220,19 @@
#else // __STDC_VERSION__
#if BC_CLANG
#if __has_attribute(noreturn)
#define BC_NORETURN __attribute((noreturn))
#else // __has_attribute(noreturn)
#define BC_NORETURN
#endif // __has_attribute(noreturn)
#else // BC_CLANG
#define BC_NORETURN
#endif // BC_CLANG
#define BC_MUST_RETURN
#define BC_C11 (0)
@ -143,7 +244,7 @@
// GCC and Clang complain if fallthroughs are not marked with their special
// attribute. Jerks. This creates a define for marking the fallthroughs that is
// nothing on other compilers.
#if defined(__clang__) || defined(__GNUC__)
#if BC_CLANG || BC_GCC
#if defined(__has_attribute)
@ -153,28 +254,28 @@
#define BC_FALLTHROUGH
#endif // __has_attribute(fallthrough)
#ifdef __GNUC__
#if BC_GCC
#if __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 5)
#undef BC_HAS_UNREACHABLE
#define BC_HAS_UNREACHABLE (1)
#endif // __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 5)
#else // __GNUC__
#else // BC_GCC
#if __clang_major__ >= 4
#undef BC_HAS_UNREACHABLE
#define BC_HAS_UNREACHABLE (1)
#endif // __clang_major__ >= 4
#endif // __GNUC__
#endif // BC_GCC
#else // defined(__has_attribute)
#define BC_FALLTHROUGH
#endif // defined(__has_attribute)
#else // defined(__clang__) || defined(__GNUC__)
#else // BC_CLANG || BC_GCC
#define BC_FALLTHROUGH
#endif // defined(__clang__) || defined(__GNUC__)
#endif // BC_CLANG || BC_GCC
#if BC_HAS_UNREACHABLE
@ -194,7 +295,7 @@
#endif // BC_HAS_UNREACHABLE
#ifdef __GNUC__
#if BC_GCC
#if __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 5)
@ -203,9 +304,9 @@
#endif // __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 5)
#endif // __GNUC__
#endif // BC_GCC
#ifdef __clang__
#if BC_CLANG
#if __clang_major__ >= 4
@ -214,7 +315,7 @@
#endif // __clang_major__ >= 4
#endif // __GNUC__
#endif // BC_CLANG
#ifdef BC_NO_COMPUTED_GOTO
@ -223,12 +324,12 @@
#endif // BC_NO_COMPUTED_GOTO
#ifdef __GNUC__
#if BC_GCC
#ifdef __OpenBSD__
// The OpenBSD GCC doesn't like inline.
#define inline
#endif // __OpenBSD__
#endif // __GNUC__
#endif // BC_GCC
// Workarounds for AIX's POSIX incompatibility.
#ifndef SIZE_MAX
@ -279,6 +380,10 @@
#define BC_DEFAULT_EXPR_EXIT (1)
#endif // BC_DEFAULT_EXPR_EXIT
#ifndef BC_DEFAULT_DIGIT_CLAMP
#define BC_DEFAULT_DIGIT_CLAMP (0)
#endif // BC_DEFAULT_DIGIT_CLAMP
// All of these set defaults for settings.
#ifndef DC_DEFAULT_SIGINT_RESET
#define DC_DEFAULT_SIGINT_RESET (1)
@ -300,6 +405,10 @@
#define DC_DEFAULT_EXPR_EXIT (1)
#endif // DC_DEFAULT_EXPR_EXIT
#ifndef DC_DEFAULT_DIGIT_CLAMP
#define DC_DEFAULT_DIGIT_CLAMP (0)
#endif // DC_DEFAULT_DIGIT_CLAMP
/// Statuses, which mark either which category of error happened, or some other
/// status that matters.
typedef enum BcStatus
@ -549,6 +658,22 @@ typedef enum BcErr
#endif // BC_ENABLED
/**
* The mode bc is in. This is basically what input it is processing.
*/
typedef enum BcMode
{
/// Expressions mode.
BC_MODE_EXPRS,
/// File mode.
BC_MODE_FILE,
/// stdin mode.
BC_MODE_STDIN,
} BcMode;
/// Do a longjmp(). This is what to use when activating an "exception", i.e., a
/// longjmp(). With debug code, it will print the name of the function it jumped
/// from.
@ -558,13 +683,22 @@ typedef enum BcErr
#define BC_JMP bc_vm_jmp()
#endif // BC_DEBUG_CODE
#if !BC_ENABLE_LIBRARY
/// Returns true if an exception is in flight, false otherwise.
#define BC_SIG_EXC \
BC_UNLIKELY(vm.status != (sig_atomic_t) BC_STATUS_SUCCESS || vm.sig)
#define BC_SIG_EXC(vm) \
BC_UNLIKELY((vm)->status != (sig_atomic_t) BC_STATUS_SUCCESS || (vm)->sig)
/// Returns true if there is *no* exception in flight, false otherwise.
#define BC_NO_SIG_EXC \
BC_LIKELY(vm.status == (sig_atomic_t) BC_STATUS_SUCCESS && !vm.sig)
#define BC_NO_SIG_EXC(vm) \
BC_LIKELY((vm)->status == (sig_atomic_t) BC_STATUS_SUCCESS && !(vm)->sig)
#ifndef _WIN32
#define BC_SIG_INTERRUPT(vm) \
BC_UNLIKELY((vm)->sig != 0 && (vm)->sig != SIGWINCH)
#else // _WIN32
#define BC_SIG_INTERRUPT(vm) BC_UNLIKELY((vm)->sig != 0)
#endif // _WIN32
#ifndef NDEBUG
@ -572,22 +706,22 @@ typedef enum BcErr
/// bc, and they *must* have signals locked. Other functions are expected to
/// *not* have signals locked, for reasons. So this is a pre-built assert
/// (no-op in non-debug mode) that check that signals are locked.
#define BC_SIG_ASSERT_LOCKED \
do \
{ \
assert(vm.sig_lock); \
} \
#define BC_SIG_ASSERT_LOCKED \
do \
{ \
assert(vm->sig_lock); \
} \
while (0)
/// Assert that signals are unlocked. There are non-async-signal-safe functions
/// in bc, and they *must* have signals locked. Other functions are expected to
/// *not* have signals locked, for reasons. So this is a pre-built assert
/// (no-op in non-debug mode) that check that signals are unlocked.
#define BC_SIG_ASSERT_NOT_LOCKED \
do \
{ \
assert(vm.sig_lock == 0); \
} \
#define BC_SIG_ASSERT_NOT_LOCKED \
do \
{ \
assert(vm->sig_lock == 0); \
} \
while (0)
#else // NDEBUG
@ -611,7 +745,7 @@ typedef enum BcErr
do \
{ \
BC_SIG_ASSERT_NOT_LOCKED; \
vm.sig_lock = 1; \
vm->sig_lock = 1; \
} \
while (0)
@ -620,8 +754,8 @@ typedef enum BcErr
do \
{ \
BC_SIG_ASSERT_LOCKED; \
vm.sig_lock = 0; \
if (vm.sig) BC_JMP; \
vm->sig_lock = 0; \
if (vm->sig) BC_JMP; \
} \
while (0)
@ -629,24 +763,24 @@ typedef enum BcErr
/// used after labels that longjmp() goes to after the jump because the cleanup
/// code must have signals locked, and BC_LONGJMP_CONT will unlock signals if it
/// doesn't jump.
#define BC_SIG_MAYLOCK \
do \
{ \
vm.sig_lock = 1; \
} \
#define BC_SIG_MAYLOCK \
do \
{ \
vm->sig_lock = 1; \
} \
while (0)
/// Unlocks signals, regardless of if they were already unlocked. If a signal
/// happened, then this will cause a jump.
#define BC_SIG_MAYUNLOCK \
do \
{ \
vm.sig_lock = 0; \
if (vm.sig) BC_JMP; \
} \
#define BC_SIG_MAYUNLOCK \
do \
{ \
vm->sig_lock = 0; \
if (vm->sig) BC_JMP; \
} \
while (0)
/*
/**
* Locks signals, but stores the old lock state, to be restored later by
* BC_SIG_TRYUNLOCK.
* @param v The variable to store the old lock state to.
@ -654,23 +788,101 @@ typedef enum BcErr
#define BC_SIG_TRYLOCK(v) \
do \
{ \
v = vm.sig_lock; \
vm.sig_lock = 1; \
v = vm->sig_lock; \
vm->sig_lock = 1; \
} \
while (0)
/* Restores the previous state of a signal lock, and if it is now unlocked,
/**
* Restores the previous state of a signal lock, and if it is now unlocked,
* initiates an exception/jump.
* @param v The old lock state.
*/
#define BC_SIG_TRYUNLOCK(v) \
#define BC_SIG_TRYUNLOCK(v) \
do \
{ \
vm->sig_lock = (v); \
if (!(v) && vm->sig) BC_JMP; \
} \
while (0)
/// Stops a stack unwinding. Technically, a stack unwinding needs to be done
/// manually, but it will always be done unless certain flags are cleared. This
/// clears the flags.
#define BC_LONGJMP_STOP \
do \
{ \
vm->sig_pop = 0; \
vm->sig = 0; \
} \
while (0)
/**
* Sets a jump like BC_SETJMP, but unlike BC_SETJMP, it assumes signals are
* locked and will just set the jump. This does *not* have a call to
* bc_vec_grow() because it is assumed that BC_SETJMP_LOCKED(l) is used *after*
* the initializations that need the setjmp().
* param l The label to jump to on a longjmp().
*/
#define BC_SETJMP_LOCKED(vm, l) \
do \
{ \
sigjmp_buf sjb; \
BC_SIG_ASSERT_LOCKED; \
if (sigsetjmp(sjb, 0)) \
{ \
assert(BC_SIG_EXC(vm)); \
goto l; \
} \
bc_vec_push(&vm->jmp_bufs, &sjb); \
} \
while (0)
/// Used after cleanup labels set by BC_SETJMP and BC_SETJMP_LOCKED to jump to
/// the next place. This is what continues the stack unwinding. This basically
/// copies BC_SIG_UNLOCK into itself, but that is because its condition for
/// jumping is BC_SIG_EXC, not just that a signal happened.
#define BC_LONGJMP_CONT(vm) \
do \
{ \
BC_SIG_ASSERT_LOCKED; \
if (!vm->sig_pop) bc_vec_pop(&vm->jmp_bufs); \
vm->sig_lock = 0; \
if (BC_SIG_EXC(vm)) BC_JMP; \
} \
while (0)
#else // !BC_ENABLE_LIBRARY
#define BC_SIG_LOCK
#define BC_SIG_UNLOCK
#define BC_SIG_MAYLOCK
#define BC_SIG_TRYLOCK(lock)
#define BC_SIG_TRYUNLOCK(lock)
#define BC_SIG_ASSERT_LOCKED
/// Returns true if an exception is in flight, false otherwise.
#define BC_SIG_EXC(vm) \
BC_UNLIKELY(vm->status != (sig_atomic_t) BC_STATUS_SUCCESS)
/// Returns true if there is *no* exception in flight, false otherwise.
#define BC_NO_SIG_EXC(vm) \
BC_LIKELY(vm->status == (sig_atomic_t) BC_STATUS_SUCCESS)
/// Used after cleanup labels set by BC_SETJMP and BC_SETJMP_LOCKED to jump to
/// the next place. This is what continues the stack unwinding. This basically
/// copies BC_SIG_UNLOCK into itself, but that is because its condition for
/// jumping is BC_SIG_EXC, not just that a signal happened.
#define BC_LONGJMP_CONT(vm) \
do \
{ \
vm.sig_lock = (v); \
if (!(v) && vm.sig) BC_JMP; \
bc_vec_pop(&vm->jmp_bufs); \
if (BC_SIG_EXC(vm)) BC_JMP; \
} \
while (0)
#endif // !BC_ENABLE_LIBRARY
/**
* Sets a jump, and sets it up as well so that if a longjmp() happens, bc will
* immediately goto a label where some cleanup code is. This one assumes that
@ -681,82 +893,39 @@ typedef enum BcErr
* *before* the actual initialization calls that need the setjmp().
* param l The label to jump to on a longjmp().
*/
#define BC_SETJMP(l) \
do \
{ \
sigjmp_buf sjb; \
BC_SIG_LOCK; \
bc_vec_grow(&vm.jmp_bufs, 1); \
if (sigsetjmp(sjb, 0)) \
{ \
assert(BC_SIG_EXC); \
goto l; \
} \
bc_vec_push(&vm.jmp_bufs, &sjb); \
BC_SIG_UNLOCK; \
} \
while (0)
/**
* Sets a jump like BC_SETJMP, but unlike BC_SETJMP, it assumes signals are
* locked and will just set the jump. This does *not* have a call to
* bc_vec_grow() because it is assumed that BC_SETJMP_LOCKED(l) is used *after*
* the initializations that need the setjmp().
* param l The label to jump to on a longjmp().
*/
#define BC_SETJMP_LOCKED(l) \
do \
{ \
sigjmp_buf sjb; \
BC_SIG_ASSERT_LOCKED; \
if (sigsetjmp(sjb, 0)) \
{ \
assert(BC_SIG_EXC); \
goto l; \
} \
bc_vec_push(&vm.jmp_bufs, &sjb); \
} \
while (0)
/// Used after cleanup labels set by BC_SETJMP and BC_SETJMP_LOCKED to jump to
/// the next place. This is what continues the stack unwinding. This basically
/// copies BC_SIG_UNLOCK into itself, but that is because its condition for
/// jumping is BC_SIG_EXC, not just that a signal happened.
#define BC_LONGJMP_CONT \
do \
{ \
BC_SIG_ASSERT_LOCKED; \
if (!vm.sig_pop) bc_vec_pop(&vm.jmp_bufs); \
vm.sig_lock = 0; \
if (BC_SIG_EXC) BC_JMP; \
} \
#define BC_SETJMP(vm, l) \
do \
{ \
sigjmp_buf sjb; \
BC_SIG_LOCK; \
bc_vec_grow(&vm->jmp_bufs, 1); \
if (sigsetjmp(sjb, 0)) \
{ \
assert(BC_SIG_EXC(vm)); \
goto l; \
} \
bc_vec_push(&vm->jmp_bufs, &sjb); \
BC_SIG_UNLOCK; \
} \
while (0)
/// Unsets a jump. It always assumes signals are locked. This basically just
/// pops a jmp_buf off of the stack of jmp_bufs, and since the jump mechanism
/// always jumps to the location at the top of the stack, this effectively
/// undoes a setjmp().
#define BC_UNSETJMP \
do \
{ \
BC_SIG_ASSERT_LOCKED; \
bc_vec_pop(&vm.jmp_bufs); \
} \
#define BC_UNSETJMP(vm) \
do \
{ \
BC_SIG_ASSERT_LOCKED; \
bc_vec_pop(&vm->jmp_bufs); \
} \
while (0)
/// Stops a stack unwinding. Technically, a stack unwinding needs to be done
/// manually, but it will always be done unless certain flags are cleared. This
/// clears the flags.
#define BC_LONGJMP_STOP \
do \
{ \
vm.sig_pop = 0; \
vm.sig = 0; \
} \
while (0)
#if BC_ENABLE_LIBRARY
#define BC_SETJMP_LOCKED(vm, l) BC_SETJMP(vm, l)
// Various convenience macros for calling the bc's error handling routine.
#if BC_ENABLE_LIBRARY
/**
* Call bc's error handling routine.
@ -780,25 +949,41 @@ typedef enum BcErr
#else // BC_ENABLE_LIBRARY
// Various convenience macros for calling the bc's error handling routine.
/**
* Call bc's error handling routine.
* @param e The error.
* @param l The line of the script that the error happened.
* @param ... Extra arguments for error messages as necessary.
*/
#ifndef NDEBUG
#define bc_error(e, l, ...) \
(bc_vm_handleError((e), __FILE__, __LINE__, (l), __VA_ARGS__))
#else // NDEBUG
#define bc_error(e, l, ...) (bc_vm_handleError((e), (l), __VA_ARGS__))
#endif // NDEBUG
/**
* Call bc's error handling routine.
* @param e The error.
*/
#ifndef NDEBUG
#define bc_err(e) (bc_vm_handleError((e), __FILE__, __LINE__, 0))
#else // NDEBUG
#define bc_err(e) (bc_vm_handleError((e), 0))
#endif // NDEBUG
/**
* Call bc's error handling routine.
* @param e The error.
*/
#ifndef NDEBUG
#define bc_verr(e, ...) \
(bc_vm_handleError((e), __FILE__, __LINE__, 0, __VA_ARGS__))
#else // NDEBUG
#define bc_verr(e, ...) (bc_vm_handleError((e), 0, __VA_ARGS__))
#endif // NDEBUG
#endif // BC_ENABLE_LIBRARY
@ -813,34 +998,34 @@ typedef enum BcErr
// Convenience macros that can be placed at the beginning and exits of functions
// for easy marking of where functions are entered and exited.
#if BC_DEBUG_CODE
#define BC_FUNC_ENTER \
do \
{ \
size_t bc_func_enter_i; \
for (bc_func_enter_i = 0; bc_func_enter_i < vm.func_depth; \
++bc_func_enter_i) \
{ \
bc_file_puts(&vm.ferr, bc_flush_none, " "); \
} \
vm.func_depth += 1; \
bc_file_printf(&vm.ferr, "Entering %s\n", __func__); \
bc_file_flush(&vm.ferr, bc_flush_none); \
} \
#define BC_FUNC_ENTER \
do \
{ \
size_t bc_func_enter_i; \
for (bc_func_enter_i = 0; bc_func_enter_i < vm->func_depth; \
++bc_func_enter_i) \
{ \
bc_file_puts(&vm->ferr, bc_flush_none, " "); \
} \
vm->func_depth += 1; \
bc_file_printf(&vm->ferr, "Entering %s\n", __func__); \
bc_file_flush(&vm->ferr, bc_flush_none); \
} \
while (0);
#define BC_FUNC_EXIT \
do \
{ \
size_t bc_func_enter_i; \
vm.func_depth -= 1; \
for (bc_func_enter_i = 0; bc_func_enter_i < vm.func_depth; \
++bc_func_enter_i) \
{ \
bc_file_puts(&vm.ferr, bc_flush_none, " "); \
} \
bc_file_printf(&vm.ferr, "Leaving %s\n", __func__); \
bc_file_flush(&vm.ferr, bc_flush_none); \
} \
#define BC_FUNC_EXIT \
do \
{ \
size_t bc_func_enter_i; \
vm->func_depth -= 1; \
for (bc_func_enter_i = 0; bc_func_enter_i < vm->func_depth; \
++bc_func_enter_i) \
{ \
bc_file_puts(&vm->ferr, bc_flush_none, " "); \
} \
bc_file_printf(&vm->ferr, "Leaving %s\n", __func__); \
bc_file_flush(&vm->ferr, bc_flush_none); \
} \
while (0);
#else // BC_DEBUG_CODE
#define BC_FUNC_ENTER

18
contrib/bc/include/vector.h
View File

@ -3,7 +3,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:
@ -59,9 +59,6 @@ typedef unsigned char uchar;
*/
typedef void (*BcVecFree)(void* ptr);
// Forward declaration.
struct BcId;
#if BC_LONG_BIT >= 64
/// An integer to shrink the size of a vector by using these instead of size_t.
@ -322,7 +319,7 @@ void
bc_vec_free(void* vec);
/**
* Attempts to insert an item into a map and returns true if it succeeded, false
* Attempts to insert an ID into a map and returns true if it succeeded, false
* if the item already exists.
* @param v The map vector to insert into.
* @param name The name of the item to insert. This name is assumed to be owned
@ -427,17 +424,6 @@ bc_slabvec_init(BcVec* restrict v);
char*
bc_slabvec_strdup(BcVec* restrict v, const char* str);
#if BC_ENABLED
/**
* Undoes the last allocation on the slab vector. This allows bc to have a
* heap-based stacks for strings. This is used by the bc parser.
*/
void
bc_slabvec_undo(BcVec* restrict v, size_t len);
#endif // BC_ENABLED
/**
* Clears a slab vector. This deallocates all but the first slab and clears the
* first slab.

4
contrib/bc/include/version.h
View File

@ -3,7 +3,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:
@ -37,6 +37,6 @@
#define BC_VERSION_H
/// The current version.
#define VERSION 5.3.3
#define VERSION 6.2.2
#endif // BC_VERSION_H

294
contrib/bc/include/vm.h
View File

@ -3,7 +3,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:
@ -78,10 +78,6 @@
#endif
// Set defaults.
//
#ifndef BC_ENABLE_NLS
#define BC_ENABLE_NLS (0)
#endif // BC_ENABLE_NLS
#ifndef MAINEXEC
#define MAINEXEC bc
@ -179,52 +175,58 @@
/// The flag for exiting with expressions.
#define BC_FLAG_EXPR_EXIT (UINTMAX_C(1) << 13)
/// The flag for digit clamping.
#define BC_FLAG_DIGIT_CLAMP (UINTMAX_C(1) << 14)
/// A convenience macro for getting the TTYIN flag.
#define BC_TTYIN (vm.flags & BC_FLAG_TTYIN)
#define BC_TTYIN (vm->flags & BC_FLAG_TTYIN)
/// A convenience macro for getting the TTY flag.
#define BC_TTY (vm.flags & BC_FLAG_TTY)
#define BC_TTY (vm->flags & BC_FLAG_TTY)
/// A convenience macro for getting the SIGINT flag.
#define BC_SIGINT (vm.flags & BC_FLAG_SIGINT)
#define BC_SIGINT (vm->flags & BC_FLAG_SIGINT)
#if BC_ENABLED
/// A convenience macro for getting the POSIX error flag.
#define BC_S (vm.flags & BC_FLAG_S)
#define BC_S (vm->flags & BC_FLAG_S)
/// A convenience macro for getting the POSIX warning flag.
#define BC_W (vm.flags & BC_FLAG_W)
#define BC_W (vm->flags & BC_FLAG_W)
/// A convenience macro for getting the math library flag.
#define BC_L (vm.flags & BC_FLAG_L)
#define BC_L (vm->flags & BC_FLAG_L)
/// A convenience macro for getting the global stacks flag.
#define BC_G (vm.flags & BC_FLAG_G)
#define BC_G (vm->flags & BC_FLAG_G)
#endif // BC_ENABLED
#if DC_ENABLED
/// A convenience macro for getting the extended register flag.
#define DC_X (vm.flags & DC_FLAG_X)
#define DC_X (vm->flags & DC_FLAG_X)
#endif // DC_ENABLED
/// A convenience macro for getting the interactive flag.
#define BC_I (vm.flags & BC_FLAG_I)
#define BC_I (vm->flags & BC_FLAG_I)
/// A convenience macro for getting the prompt flag.
#define BC_P (vm.flags & BC_FLAG_P)
#define BC_P (vm->flags & BC_FLAG_P)
/// A convenience macro for getting the read prompt flag.
#define BC_R (vm.flags & BC_FLAG_R)
#define BC_R (vm->flags & BC_FLAG_R)
/// A convenience macro for getting the leading zero flag.
#define BC_Z (vm.flags & BC_FLAG_Z)
#define BC_Z (vm->flags & BC_FLAG_Z)
/// A convenience macro for getting the expression exit flag.
#define BC_EXPR_EXIT (vm.flags & BC_FLAG_EXPR_EXIT)
#define BC_EXPR_EXIT (vm->flags & BC_FLAG_EXPR_EXIT)
/// A convenience macro for getting the digit clamp flag.
#define BC_DIGIT_CLAMP (vm->flags & BC_FLAG_DIGIT_CLAMP)
#if BC_ENABLED
@ -234,10 +236,57 @@
#if DC_ENABLED
/// Returns true if bc is running.
#define BC_IS_BC (vm.name[0] != 'd')
#define BC_IS_BC (vm->name[0] != 'd')
/// Returns true if dc is running.
#define BC_IS_DC (vm.name[0] == 'd')
#define BC_IS_DC (vm->name[0] == 'd')
/// Returns the correct read prompt.
#define BC_VM_READ_PROMPT (BC_IS_BC ? "read> " : "?> ")
/// Returns the string for the line length environment variable.
#define BC_VM_LINE_LENGTH_STR (BC_IS_BC ? "BC_LINE_LENGTH" : "DC_LINE_LENGTH")
/// Returns the string for the environment args environment variable.
#define BC_VM_ENV_ARGS_STR (BC_IS_BC ? "BC_ENV_ARGS" : "DC_ENV_ARGS")
/// Returns the string for the expression exit environment variable.
#define BC_VM_EXPR_EXIT_STR (BC_IS_BC ? "BC_EXPR_EXIT" : "DC_EXPR_EXIT")
/// Returns the default for the expression exit environment variable.
#define BC_VM_EXPR_EXIT_DEF \
(BC_IS_BC ? BC_DEFAULT_EXPR_EXIT : DC_DEFAULT_EXPR_EXIT)
/// Returns the string for the digit clamp environment variable.
#define BC_VM_DIGIT_CLAMP_STR (BC_IS_BC ? "BC_DIGIT_CLAMP" : "DC_DIGIT_CLAMP")
/// Returns the default for the digit clamp environment variable.
#define BC_VM_DIGIT_CLAMP_DEF \
(BC_IS_BC ? BC_DEFAULT_DIGIT_CLAMP : DC_DEFAULT_DIGIT_CLAMP)
/// Returns the string for the TTY mode environment variable.
#define BC_VM_TTY_MODE_STR (BC_IS_BC ? "BC_TTY_MODE" : "DC_TTY_MODE")
/// Returns the default for the TTY mode environment variable.
#define BC_VM_TTY_MODE_DEF \
(BC_IS_BC ? BC_DEFAULT_TTY_MODE : DC_DEFAULT_TTY_MODE)
/// Returns the string for the prompt environment variable.
#define BC_VM_PROMPT_STR (BC_IS_BC ? "BC_PROMPT" : "DC_PROMPT")
/// Returns the default for the prompt environment variable.
#define BC_VM_PROMPT_DEF (BC_IS_BC ? BC_DEFAULT_PROMPT : DC_DEFAULT_PROMPT)
/// Returns the string for the SIGINT reset environment variable.
#define BC_VM_SIGINT_RESET_STR \
(BC_IS_BC ? "BC_SIGINT_RESET" : "DC_SIGINT_RESET")
/// Returns the string for the SIGINT reset environment variable.
#define BC_VM_SIGINT_RESET_DEF \
(BC_IS_BC ? BC_DEFAULT_SIGINT_RESET : DC_DEFAULT_SIGINT_RESET)
/// Returns true if the calculator should run stdin.
#define BC_VM_RUN_STDIN(has_file) (BC_IS_BC || !(has_file))
#else // DC_ENABLED
@ -247,6 +296,48 @@
/// Returns true if dc is running.
#define BC_IS_DC (0)
/// Returns the correct read prompt.
#define BC_VM_READ_PROMPT ("read> ")
/// Returns the string for the line length environment variable.
#define BC_VM_LINE_LENGTH_STR ("BC_LINE_LENGTH")
/// Returns the string for the environment args environment variable.
#define BC_VM_ENV_ARGS_STR ("BC_ENV_ARGS")
/// Returns the string for the expression exit environment variable.
#define BC_VM_EXPR_EXIT_STR ("BC_EXPR_EXIT")
/// Returns the default for the expression exit environment variable.
#define BC_VM_EXPR_EXIT_DEF (BC_DEFAULT_EXPR_EXIT)
/// Returns the string for the digit clamp environment variable.
#define BC_VM_DIGIT_CLAMP_STR ("BC_DIGIT_CLAMP")
/// Returns the default for the digit clamp environment variable.
#define BC_VM_DIGIT_CLAMP_DEF (BC_DEFAULT_DIGIT_CLAMP)
/// Returns the string for the TTY mode environment variable.
#define BC_VM_TTY_MODE_STR ("BC_TTY_MODE")
/// Returns the default for the TTY mode environment variable.
#define BC_VM_TTY_MODE_DEF (BC_DEFAULT_TTY_MODE)
/// Returns the string for the prompt environment variable.
#define BC_VM_PROMPT_STR ("BC_PROMPT")
/// Returns the default for the SIGINT reset environment variable.
#define BC_VM_PROMPT_DEF (BC_DEFAULT_PROMPT)
/// Returns the string for the SIGINT reset environment variable.
#define BC_VM_SIGINT_RESET_STR ("BC_SIGINT_RESET")
/// Returns the string for the SIGINT reset environment variable.
#define BC_VM_SIGINT_RESET_DEF (BC_DEFAULT_SIGINT_RESET)
/// Returns true if the calculator should run stdin.
#define BC_VM_RUN_STDIN(has_file) (BC_IS_BC)
#endif // DC_ENABLED
#else // BC_ENABLED
@ -260,6 +351,48 @@
/// Returns true if dc is running.
#define BC_IS_DC (1)
/// Returns the correct read prompt.
#define BC_VM_READ_PROMPT ("?> ")
/// Returns the string for the line length environment variable.
#define BC_VM_LINE_LENGTH_STR ("DC_LINE_LENGTH")
/// Returns the string for the environment args environment variable.
#define BC_VM_ENV_ARGS_STR ("DC_ENV_ARGS")
/// Returns the string for the expression exit environment variable.
#define BC_VM_EXPR_EXIT_STR ("DC_EXPR_EXIT")
/// Returns the default for the expression exit environment variable.
#define BC_VM_EXPR_EXIT_DEF (DC_DEFAULT_EXPR_EXIT)
/// Returns the string for the digit clamp environment variable.
#define BC_VM_DIGIT_CLAMP_STR ("DC_DIGIT_CLAMP")
/// Returns the default for the digit clamp environment variable.
#define BC_VM_DIGIT_CLAMP_DEF (DC_DEFAULT_DIGIT_CLAMP)
/// Returns the string for the TTY mode environment variable.
#define BC_VM_TTY_MODE_STR ("DC_TTY_MODE")
/// Returns the default for the TTY mode environment variable.
#define BC_VM_TTY_MODE_DEF (DC_DEFAULT_TTY_MODE)
/// Returns the string for the prompt environment variable.
#define BC_VM_PROMPT_STR ("DC_PROMPT")
/// Returns the default for the SIGINT reset environment variable.
#define BC_VM_PROMPT_DEF (DC_DEFAULT_PROMPT)
/// Returns the string for the SIGINT reset environment variable.
#define BC_VM_SIGINT_RESET_STR ("DC_SIGINT_RESET")
/// Returns the string for the SIGINT reset environment variable.
#define BC_VM_SIGINT_RESET_DEF (DC_DEFAULT_SIGINT_RESET)
/// Returns true if the calculator should run stdin.
#define BC_VM_RUN_STDIN(has_file) (!(has_file))
#endif // BC_ENABLED
/// A convenience macro for checking if the prompt is enabled.
@ -267,7 +400,9 @@
#else // !BC_ENABLE_LIBRARY
#define BC_Z (vm.leading_zeroes)
#define BC_Z (vm->leading_zeroes)
#define BC_DIGIT_CLAMP (vm->digit_clamp)
#endif // !BC_ENABLE_LIBRARY
@ -437,18 +572,14 @@ typedef struct BcVm
/// Whether or not to print leading zeros.
bool leading_zeroes;
/// Whether or not to clamp digits that are greater than or equal to the
/// current ibase.
bool digit_clamp;
/// The number of "references," or times that the library was initialized.
unsigned int refs;
/// Non-zero if bcl is running. This is volatile sig_atomic_t because it is
/// also used in the signal handler. See the development manual
/// (manuals/development.md#async-signal-safe-signal-handling) for more
/// information.
volatile sig_atomic_t running;
#endif // BC_ENABLE_LIBRARY
#if !BC_ENABLE_LIBRARY
#else // BC_ENABLE_LIBRARY
/// A pointer to the filename of the current file. This is not owned by the
/// BcVm struct.
@ -457,8 +588,6 @@ typedef struct BcVm
/// The message printed when SIGINT happens.
const char* sigmsg;
#endif // !BC_ENABLE_LIBRARY
/// Non-zero when signals are "locked." This is volatile sig_atomic_t
/// because it is also used in the signal handler. See the development
/// manual (manuals/development.md#async-signal-safe-signal-handling) for
@ -472,8 +601,6 @@ typedef struct BcVm
/// information.
volatile sig_atomic_t sig;
#if !BC_ENABLE_LIBRARY
/// The length of sigmsg.
uchar siglen;
@ -501,8 +628,8 @@ typedef struct BcVm
/// True if EOF was encountered.
bool eof;
/// True if bc is currently reading from stdin.
bool is_stdin;
/// The mode that the program is in.
uchar mode;
#if BC_ENABLED
@ -512,13 +639,6 @@ typedef struct BcVm
#endif // BC_ENABLED
#endif // !BC_ENABLE_LIBRARY
/// An array of maxes for the globals.
BcBigDig maxes[BC_PROG_GLOBALS_LEN + BC_ENABLE_EXTRA_MATH];
#if !BC_ENABLE_LIBRARY
/// A vector of filenames to process.
BcVec files;
@ -548,9 +668,6 @@ typedef struct BcVm
/// The function to call to parse expressions.
BcParseExpr expr;
/// The text to display to label functions in error messages.
const char* func_header;
/// The names of the categories of errors.
const char* err_ids[BC_ERR_IDX_NELEMS + BC_ENABLED];
@ -562,7 +679,10 @@ typedef struct BcVm
const char* locale;
#endif // BC_ENABLE_NLS
#endif // !BC_ENABLE_LIBRARY
#endif // BC_ENABLE_LIBRARY
/// An array of maxes for the globals.
BcBigDig maxes[BC_PROG_GLOBALS_LEN + BC_ENABLE_EXTRA_MATH];
/// The last base used to parse.
BcBigDig last_base;
@ -632,16 +752,9 @@ typedef struct BcVm
/// The number of items in the input buffer.
size_t buf_len;
/// The slab for constants in the main function. This is separate for
/// garbage collection reasons.
BcVec main_const_slab;
//// The slab for all other strings for the main function.
BcVec main_slabs;
/// The slab for function names, strings in other functions, and constants
/// in other functions.
BcVec other_slabs;
/// The slabs vector for constants, strings, function names, and other
/// string-like things.
BcVec slabs;
#if BC_ENABLED
@ -652,6 +765,8 @@ typedef struct BcVm
#endif // BC_ENABLED
#endif // !BC_ENABLE_LIBRARY
BcDig* temps_buf[BC_VM_MAX_TEMPS];
#if BC_DEBUG_CODE
/// The depth for BC_FUNC_ENTER and BC_FUNC_EXIT.
@ -697,27 +812,40 @@ void
bc_vm_addTemp(BcDig* num);
/**
* Dish out a temp, or NULL if there are none.
* Return the temp on the top of the temp stack, or NULL if there are none.
* @return A temp, or NULL if none exist.
*/
BcDig*
bc_vm_takeTemp(void);
/**
* Gets the top temp of the temp stack. This is separate from bc_vm_takeTemp()
* to quiet a GCC warning about longjmp() clobbering in bc_num_init().
* @return A temp, or NULL if none exist.
*/
BcDig*
bc_vm_getTemp(void);
/**
* Frees all temporaries.
*/
void
bc_vm_freeTemps(void);
#if !BC_ENABLE_HISTORY || BC_ENABLE_LINE_LIB
#if !BC_ENABLE_HISTORY || BC_ENABLE_LINE_LIB || BC_ENABLE_LIBRARY
/**
* Erases the flush argument if history does not exist because it does not
* matter if history does not exist.
*/
#define bc_vm_putchar(c, t) bc_vm_putchar(c)
#define bc_vm_putchar(c, t) bc_vm_putchar_impl(c)
#endif // !BC_ENABLE_HISTORY || BC_ENABLE_LINE_LIB
#else // !BC_ENABLE_HISTORY || BC_ENABLE_LINE_LIB || BC_ENABLE_LIBRARY
// This is here to satisfy a clang warning about recursive macros.
#define bc_vm_putchar(c, t) bc_vm_putchar_impl(c, t)
#endif // !BC_ENABLE_HISTORY || BC_ENABLE_LINE_LIB || BC_ENABLE_LIBRARY
/**
* Print to stdout with limited formating.
@ -826,6 +954,7 @@ bc_vm_getenvFree(char* val);
*/
void
bc_vm_jmp(const char* f);
#else // BC_DEBUG_CODE
/**
@ -862,16 +991,42 @@ bc_vm_atexit(void);
#else // BC_ENABLE_LIBRARY
/**
* Calculates the number of decimal digits in the argument.
* @param val The value to calculate the number of decimal digits in.
* @return The number of decimal digits in @a val.
*/
size_t
bc_vm_numDigits(size_t val);
#ifndef NDEBUG
/**
* Handle an error. This is the true error handler. It will start a jump series
* if an error occurred. POSIX errors will not cause jumps when warnings are on
* or no POSIX errors are enabled.
* @param e The error.
* @param file The source file where the error occurred.
* @param fline The line in the source file where the error occurred.
* @param line The bc source line where the error occurred.
*/
void
bc_vm_handleError(BcErr e, const char* file, int fline, size_t line, ...);
#else // NDEBUG
/**
* Handle an error. This is the true error handler. It will start a jump series
* if an error occurred. POSIX errors will not cause jumps when warnings are on
* or no POSIX errors are enabled.
* @param e The error.
* @param line The source line where the error occurred.
* @param line The bc source line where the error occurred.
*/
void
bc_vm_handleError(BcErr e, size_t line, ...);
#endif // NDEBUG
/**
* Handle a fatal error.
* @param e The error.
@ -893,12 +1048,6 @@ bc_vm_atexit(int status);
/// A reference to the copyright header.
extern const char bc_copyright[];
/// A reference to the format string for source code line printing.
extern const char* const bc_err_line;
/// A reference to the format string for source code function printing.
extern const char* const bc_err_func_header;
/// A reference to the array of default error category names.
extern const char* bc_errs[];
@ -921,10 +1070,17 @@ extern const char bc_pledge_end_history[];
/// A reference to the end pledge() promises when *not* using history.
extern const char bc_pledge_end[];
#if !BC_ENABLE_LIBRARY
/// A reference to the global data.
extern BcVm vm;
extern BcVm* vm;
/// The global data.
extern BcVm vm_data;
/// A reference to the global output buffers.
extern char output_bufs[BC_VM_BUF_SIZE];
#endif // !BC_ENABLE_LIBRARY
#endif // BC_VM_H

17
contrib/bc/locales/de_DE.ISO8859-1.msg
View File

@ -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:
@ -28,13 +28,8 @@ $ $
$quote "
$ Headers for printing errors/warnings.
$set 1
1 "Funktion:"
$ Error types.
$set 2
$set 1
1 "Rechenfehler:"
2 "Analysefehler:"
@ -43,7 +38,7 @@ $set 2
5 "Warnung:"
$ Math errors.
$set 3
$set 2
1 "negative Zahl"
2 "Nicht-Ganzzahl-Wert"
@ -51,7 +46,7 @@ $set 3
4 "Division durch 0"
$ Parse errors.
$set 4
$set 3
1 "Ende der Datei"
2 "ungültiges Zeichen: '%c'"
@ -85,7 +80,7 @@ $set 4
30 "POSIX erlaubt keine Zuweisung von Strings an Variablen oder Arrays"
$ Runtime errors.
$set 5
$set 4
1 "ungültige \"ibase\": muss im Intervall [%lu, %lu] liegen"
2 "ungültige \"obase\": muss im Intervall [%lu, %lu] liegen"
@ -100,7 +95,7 @@ $set 5
11 "kann keinen ungültigen Wert in einem Ausdruck verwenden"
$ Fatal errors.
$set 6
$set 5
1 "Speicherzuweisung fehlgeschlagen"
2 "Ein-Ausgabe-Fehler"

17
contrib/bc/locales/de_DE.UTF-8.msg
View File

@ -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:
@ -28,13 +28,8 @@ $ $
$quote "
$ Headers for printing errors/warnings.
$set 1
1 "Funktion:"
$ Error types.
$set 2
$set 1
1 "Rechenfehler:"
2 "Analysefehler:"
@ -43,7 +38,7 @@ $set 2
5 "Warnung:"
$ Math errors.
$set 3
$set 2
1 "negative Zahl"
2 "Nicht-Ganzzahl-Wert"
@ -51,7 +46,7 @@ $set 3
4 "Division durch 0"
$ Parse errors.
$set 4
$set 3
1 "Ende der Datei"
2 "ungültiges Zeichen: '%c'"
@ -85,7 +80,7 @@ $set 4
30 "POSIX erlaubt keine Zuweisung von Strings an Variablen oder Arrays"
$ Runtime errors.
$set 5
$set 4
1 "ungültige \"ibase\": muss im Intervall [%lu, %lu] liegen"
2 "ungültige \"obase\": muss im Intervall [%lu, %lu] liegen"
@ -100,7 +95,7 @@ $set 5
11 "kann keinen ungültigen Wert in einem Ausdruck verwenden"
$ Fatal errors.
$set 6
$set 5
1 "Speicherzuweisung fehlgeschlagen"
2 "Ein-Ausgabe-Fehler"

17
contrib/bc/locales/en_US.msg
View File

@ -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:
@ -28,13 +28,8 @@ $ $
$quote "
$ Miscellaneous messages.
$set 1
1 "Function:"
$ Error types.
$set 2
$set 1
1 "Math error:"
2 "Parse error:"
@ -43,7 +38,7 @@ $set 2
5 "Warning:"
$ Math errors.
$set 3
$set 2
1 "negative number"
2 "non-integer number"
@ -51,7 +46,7 @@ $set 3
4 "divide by 0"
$ Parse errors.
$set 4
$set 3
1 "end of file"
2 "invalid character '%c'"
@ -85,7 +80,7 @@ $set 4
30 "POSIX does not allow strings to be assigned to variables or arrays"
$ Runtime errors.
$set 5
$set 4
1 "invalid ibase: must be [%lu, %lu]"
2 "invalid obase: must be [%lu, %lu]"
@ -100,7 +95,7 @@ $set 5
11 "cannot use a void value in an expression"
$ Fatal errors.
$set 6
$set 5
1 "memory allocation failed"
2 "I/O error"

17
contrib/bc/locales/es_ES.ISO8859-1.msg
View File

@ -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:
@ -28,13 +28,8 @@ $ $
$quote "
$ Miscellaneous messages.
$set 1
1 "Función:"
$ Error types.
$set 2
$set 1
1 "Error de matemática:"
2 "Error de syntaxis:"
@ -43,7 +38,7 @@ $set 2
5 "Advertencia:"
$ Math errors.
$set 3
$set 2
1 "número negativo"
2 "número no es entero"
@ -51,7 +46,7 @@ $set 3
4 "división por cero"
$ Parse errors.
$set 4
$set 3
1 "fin de archivo"
2 "no válido '%c'"
@ -85,7 +80,7 @@ $set 4
30 "POSIX no permite asignar cadenas a variables o matrices"
$ Runtime errors.
$set 5
$set 4
1 "\"ibase\" no es válido: debe ser [%lu, %lu]"
2 "\"obase\" no es válido: debe ser [%lu, %lu]"
@ -100,7 +95,7 @@ $set 5
11 "no puede utilizar un valor vacío en una expresión"
$ Fatal errors.
$set 6
$set 5
1 "error en la asignación de memoria"
2 "error de I/O"

17
contrib/bc/locales/es_ES.UTF-8.msg
View File

@ -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:
@ -28,13 +28,8 @@ $ $
$quote "
$ Miscellaneous messages.
$set 1
1 "Función:"
$ Error types.
$set 2
$set 1
1 "Error de matemática:"
2 "Error de syntaxis:"
@ -43,7 +38,7 @@ $set 2
5 "Advertencia:"
$ Math errors.
$set 3
$set 2
1 "número negativo"
2 "número no es entero"
@ -51,7 +46,7 @@ $set 3
4 "división por cero"
$ Parse errors.
$set 4
$set 3
1 "fin de archivo"
2 "no válido '%c'"
@ -85,7 +80,7 @@ $set 4
30 "POSIX no permite asignar cadenas a variables o matrices"
$ Runtime errors.
$set 5
$set 4
1 "\"ibase\" no es válido: debe ser [%lu, %lu]"
2 "\"obase\" no es válido: debe ser [%lu, %lu]"
@ -100,7 +95,7 @@ $set 5
11 "no puede utilizar un valor vacío en una expresión"
$ Fatal errors.
$set 6
$set 5
1 "error en la asignación de memoria"
2 "error de I/O"

17
contrib/bc/locales/fr_FR.ISO8859-1.msg
View File

@ -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:
@ -28,13 +28,8 @@ $ $
$quote "
$ Miscellaneous messages.
$set 1
1 "Fonction :"
$ Error types.
$set 2
$set 1
1 "Erreur de calcul :"
2 "Erreur d'analyse syntaxique :"
@ -43,7 +38,7 @@ $set 2
5 "Avertissement :"
$ Math errors.
$set 3
$set 2
1 "nombre strictement négatif"
2 "nombre non entier"
@ -51,7 +46,7 @@ $set 3
4 "division par 0"
$ Parse errors.
$set 4
$set 3
1 "fin de fichier"
2 "caractère invalide '%c'"
@ -85,7 +80,7 @@ $set 4
30 "POSIX interdit pas d'assigner des chaînes de caractères à des variables ou à des tableaux"
$ Runtime errors.
$set 5
$set 4
1 "ibase invalide : doit être [%lu, %lu]"
2 "obase invalide : doit être [%lu, %lu]"
@ -100,7 +95,7 @@ $set 5
11 "une valeur 'void' est inutilisable dans une expression"
$ Fatal errors.
$set 6
$set 5
1 "échec d'allocation mémoire"
2 "erreur d'entrée-sortie"

17
contrib/bc/locales/fr_FR.UTF-8.msg
View File

@ -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:
@ -28,13 +28,8 @@ $ $
$quote "
$ Miscellaneous messages.
$set 1
1 "Fonction :"
$ Error types.
$set 2
$set 1
1 "Erreur de calcul :"
2 "Erreur d'analyse syntaxique :"
@ -43,7 +38,7 @@ $set 2
5 "Avertissement :"
$ Math errors.
$set 3
$set 2
1 "nombre strictement négatif"
2 "nombre non entier"
@ -51,7 +46,7 @@ $set 3
4 "division par 0"
$ Parse errors.
$set 4
$set 3
1 "fin de fichier"
2 "caractère invalide '%c'"
@ -85,7 +80,7 @@ $set 4
30 "POSIX interdit pas d'assigner des chaînes de caractères à des variables ou à des tableaux"
$ Runtime errors.
$set 5
$set 4
1 "ibase invalide : doit être [%lu, %lu]"
2 "obase invalide : doit être [%lu, %lu]"
@ -100,7 +95,7 @@ $set 5
11 "une valeur 'void' est inutilisable dans une expression"
$ Fatal errors.
$set 6
$set 5
1 "échec d'allocation mémoire"
2 "erreur d'entrée-sortie"

17
contrib/bc/locales/ja_JP.UTF-8.msg
View File

@ -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:
@ -28,13 +28,8 @@ $ $
$quote "
$ その他のメッセージ。
$set 1
1 "関数："
$ エラーの種類。
$set 2
$set 1
1 "数学のエラー："
2 "パースエラー："
@ -43,7 +38,7 @@ $set 2
5 "警告："
$ 数学のエラーです。
$set 3
$set 2
1 "負の数"
2 "非整数"
@ -51,7 +46,7 @@ $set 3
4 "0で割る"
$ 構文解析のエラー。
$set 4
$set 3
1 "ファイルの終了"
2 "無効な文字 '%c'"
@ -85,7 +80,7 @@ $set 4
30 "POSIXでは、変数や配列に文字列を割り当てることはできません。"
$ ランタイムエラー。
$set 5
$set 4
1 "無効なibase：は[%lu、%lu]でなければなりません"
2 "無効なobase：は[%lu、%lu]でなければなりません"
@ -100,7 +95,7 @@ $set 5
11 "式では void 値を使用できません"
$ 致命的なエラーが発生しました。
$set 6
$set 5
1 "メモリの割り当てに失敗しました"
2 "I/Oエラー"

17
contrib/bc/locales/ja_JP.eucJP.msg
View File

@ -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:
@ -28,13 +28,8 @@ $ $
$quote "
$ その他のメッセージ。
$set 1
1 "関数："
$ エラーの種類。
$set 2
$set 1
1 "数学のエラー："
2 "パースエラー："
@ -43,7 +38,7 @@ $set 2
5 "警告："
$ 数学のエラーです。
$set 3
$set 2
1 "負の数"
2 "非整数"
@ -51,7 +46,7 @@ $set 3
4 "0で割る"
$ 構文解析のエラー。
$set 4
$set 3
1 "ファイルの終了"
2 "無効な文字 '%c'"
@ -85,7 +80,7 @@ $set 4
30 "POSIXでは、変数や配列に文字列を割り当てることはできません。"
$ ランタイムエラー。
$set 5
$set 4
1 "無効なibase：は[%lu、%lu]でなければなりません"
2 "無効なobase：は[%lu、%lu]でなければなりません"
@ -100,7 +95,7 @@ $set 5
11 "式では void 値を使用できません"
$ 致命的なエラーが発生しました。
$set 6
$set 5
1 "メモリの割り当てに失敗しました"
2 "I/Oエラー"

17
contrib/bc/locales/nl_NL.ISO8859-1.msg
View File

@ -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:
@ -28,13 +28,8 @@ $ $
$quote "
$ Diversen berichten.
$set 1
1 "Functie:"
$ Fouttypes.
$set 2
$set 1
1 "Rekenfout:"
2 "Parse error:"
@ -43,7 +38,7 @@ $set 2
5 "Waarschuwing:"
$ Math error.
$set 3
$set 2
1 "negatief getal"
2 "niet-integraal getal"
@ -51,7 +46,7 @@ $set 3
4 "delen door 0"
$ Parsefouten.
$set 4
$set 3
1 "einde van het file"
2 "ongeldig teken '%c'"
@ -85,7 +80,7 @@ $set 4
30 "POSIX staat niet toe dat strings worden toegewezen aan variabelen of arrays"
$ Runtime fouten.
$set 5
$set 4
1 "ongeldige ibase: moet [%lu, %lu] zijn"
2 "ongeldige obase: moet [%lu, %lu] zijn"
@ -100,7 +95,7 @@ $set 5
11 "kan geen nietige waarde in een uitdrukking gebruiken"
$ Fatale fouten.
$set 6
$set 5
1 "geheugentoewijzing mislukt"
2 "I/O-fout"

17
contrib/bc/locales/nl_NL.UTF-8.msg
View File

@ -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:
@ -28,13 +28,8 @@ $ $
$quote "
$ Diversen berichten.
$set 1
1 "Functie:"
$ Fouttypes.
$set 2
$set 1
1 "Rekenfout:"
2 "Parse error:"
@ -43,7 +38,7 @@ $set 2
5 "Waarschuwing:"
$ Math error.
$set 3
$set 2
1 "negatief getal"
2 "niet-integraal getal"
@ -51,7 +46,7 @@ $set 3
4 "delen door 0"
$ Parsefouten.
$set 4
$set 3
1 "einde van het file"
2 "ongeldig teken '%c'"
@ -85,7 +80,7 @@ $set 4
30 "POSIX staat niet toe dat strings worden toegewezen aan variabelen of arrays"
$ Runtime fouten.
$set 5
$set 4
1 "ongeldige ibase: moet [%lu, %lu] zijn"
2 "ongeldige obase: moet [%lu, %lu] zijn"
@ -100,7 +95,7 @@ $set 5
11 "kan geen nietige waarde in een uitdrukking gebruiken"
$ Fatale fouten.
$set 6
$set 5
1 "geheugentoewijzing mislukt"
2 "I/O-fout"

17
contrib/bc/locales/pl_PL.ISO8859-2.msg
View File

@ -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:
@ -28,13 +28,8 @@ $ $
$quote "
$ Ró¿ne wiadomo¶ci.
$set 1
1 "Funkcja:"
$ Typy błędów.
$set 2
$set 1
1 "Błąd matematyczny:"
2 "Błąd parse'a:"
@ -43,7 +38,7 @@ $set 2
5 "Ostrzeżenie:"
$ Błędy matematyczne.
$set 3
$set 2
1 "liczba ujemna"
2 "numer nieintegracyjny"
@ -51,7 +46,7 @@ $set 3
4 "dzielenie przez 0"
$ Błędy Parse'a.
$set 4
$set 3
1 "koniec akt"
2 "nieważny znak '%c'"
@ -85,7 +80,7 @@ $set 4
30 "POSIX nie pozwala na przypisywanie ciągów znaków do zmiennych lub tablic"
$ Błędy Runtime'u.
$set 5
$set 4
1 "nieprawidłowa ibase: musi być [%lu, %lu]"
2 "nieprawidłowa obase: musi być [%lu, %lu]"
@ -100,7 +95,7 @@ $set 5
11 "nie może użyć wartości pustej w wyrażeniu"
$ Fatalne błędy.
$set 6
$set 5
1 "Alokacja pamięci nie powiodła się"
2 "Błąd we/wy"

17
contrib/bc/locales/pl_PL.UTF-8.msg
View File

@ -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:
@ -28,13 +28,8 @@ $ $
$quote "
$ Różne wiadomości.
$set 1
1 "Funkcja:"
$ Typy błędów.
$set 2
$set 1
1 "Błąd matematyczny:"
2 "Błąd parse'a:"
@ -43,7 +38,7 @@ $set 2
5 "Ostrzeżenie:"
$ Błędy matematyczne.
$set 3
$set 2
1 "liczba ujemna"
2 "numer nieintegracyjny"
@ -51,7 +46,7 @@ $set 3
4 "dzielenie przez 0"
$ Błędy Parse'a.
$set 4
$set 3
1 "koniec akt"
2 "nieważny znak '%c'"
@ -85,7 +80,7 @@ $set 4
30 "POSIX nie pozwala na przypisywanie ciągów znaków do zmiennych lub tablic"
$ Błędy Runtime'u.
$set 5
$set 4
1 "nieprawidłowa ibase: musi być [%lu, %lu]"
2 "nieprawidłowa obase: musi być [%lu, %lu]"
@ -100,7 +95,7 @@ $set 5
11 "nie może użyć wartości pustej w wyrażeniu"
$ Fatalne błędy.
$set 6
$set 5
1 "Alokacja pamięci nie powiodła się"
2 "Błąd we/wy"

17
contrib/bc/locales/pt_PT.ISO8859-1.msg
View File

@ -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:
@ -28,13 +28,8 @@ $ $
$quote "
$ Miscellaneous messages.
$set 1
1 "Função:"
$ Error types.
$set 2
$set 1
1 "Erro de cálculo:"
2 "Erro de análise de sintaxe:"
@ -43,7 +38,7 @@ $set 2
5 "Aviso:"
$ Math errors.
$set 3
$set 2
1 "número negativo"
2 "número não inteiro"
@ -51,7 +46,7 @@ $set 3
4 "dividir por 0"
$ Parse errors.
$set 4
$set 3
1 "fim do arquivo"
2 "caractere inválido '%c'"
@ -85,7 +80,7 @@ $set 4
30 "POSIX não permite a atribuição de cadeias de caracteres a variáveis ou matrizes"
$ Runtime errors.
$set 5
$set 4
1 "ibase inválido: deve ser [%lu, %lu]"
2 "obase inválido: deve ser [%lu, %lu]"
@ -100,7 +95,7 @@ $set 5
11 "um valor 'void' não pode ser usado em uma expressão"
$ Fatal errors.
$set 6
$set 5
1 "falha na alocação de memória"
2 "erro de entrada-saída"

17
contrib/bc/locales/pt_PT.UTF-8.msg
View File

@ -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:
@ -28,13 +28,8 @@ $ $
$quote "
$ Miscellaneous messages.
$set 1
1 "Função:"
$ Error types.
$set 2
$set 1
1 "Erro de cálculo:"
2 "Erro de análise de sintaxe:"
@ -43,7 +38,7 @@ $set 2
5 "Aviso:"
$ Math errors.
$set 3
$set 2
1 "número negativo"
2 "número não inteiro"
@ -51,7 +46,7 @@ $set 3
4 "dividir por 0"
$ Parse errors.
$set 4
$set 3
1 "fim do arquivo"
2 "caractere inválido '%c'"
@ -85,7 +80,7 @@ $set 4
30 "POSIX não permite a atribuição de cadeias de caracteres a variáveis ou matrizes"
$ Runtime errors.
$set 5
$set 4
1 "ibase inválido: deve ser [%lu, %lu]"
2 "obase inválido: deve ser [%lu, %lu]"
@ -100,7 +95,7 @@ $set 5
11 "um valor 'void' não pode ser usado em uma expressão"
$ Fatal errors.
$set 6
$set 5
1 "falha na alocação de memória"
2 "erro de entrada-saída"

17
contrib/bc/locales/ru_RU.CP1251.msg
View File

@ -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:
@ -28,13 +28,8 @@ $ $
$quote "
$ Ðàçíûå ñîîáùåíèÿ.
$set 1
1 "Ôóíêöèÿ:"
$ Типы ошибок.
$set 2
$set 1
1 "Математическая ошибка:"
2 "Ошибка при разборе:"
@ -43,7 +38,7 @@ $set 2
5 "Предупреждение:"
$ Математические ошибки.
$set 3
$set 2
1 "отрицательное число"
2 "неинтегрированное число"
@ -51,7 +46,7 @@ $set 3
4 "делить на 0"
$ Ошибки при разборе.
$set 4
$set 3
1 "конец файла"
2 "недопустимый символ '%c'"
@ -85,7 +80,7 @@ $set 4
30 "POSIX не позволяет присваивать строки переменным или массивам"
$ Ошибки выполнения.
$set 5
$set 4
1 "Недействительный ibase: должен быть [%lu, %lu]"
2 "Недействительный obase: должен быть [%lu, %lu]"
@ -100,7 +95,7 @@ $set 5
11 "не может использовать пустое значение в выражении"
$ Фатальные ошибки.
$set 6
$set 5
1 "Не удалось выделить память"
2 "Ошибка ввода/вывода"

17
contrib/bc/locales/ru_RU.CP866.msg
View File

@ -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:
@ -28,13 +28,8 @@ $ $
$quote "
$ <20> §­ë¥ á®®¡é¥­¨ï.
$set 1
1 "”ã­ªæ¨ï:"
$ ’¨¯ë ®è¨¡®ª.
$set 2
$set 1
1 "Œ â¥¬ â¨ç¥áª ï ®è¨¡ª :"
2 "Žè¨¡ª  ¯à¨ à §¡®à¥:"
@ -43,7 +38,7 @@ $set 2
5 "<22>।ã¯à¥¦¤¥­¨¥:"
$ Œ â¥¬ â¨ç¥áª¨¥ ®è¨¡ª¨.
$set 3
$set 2
1 "®âà¨æ â¥«ì­®¥ ç¨á«®"
2 "­¥¨­â¥£à¨à®¢ ­­®¥ ç¨á«®"
@ -51,7 +46,7 @@ $set 3
4 "¤¥«¨âì ­  0"
$ Žè¨¡ª¨ ¯à¨ à §¡®à¥.
$set 4
$set 3
1 "ª®­¥æ ä ©« "
2 "­¥¤®¯ãáâ¨¬ë© á¨¬¢®« '%c'"
@ -85,7 +80,7 @@ $set 4
30 "POSIX ­¥ ¯®§¢®«ï¥â ¯à¨á¢ ¨¢ âì áâப¨ ¯¥à¥¬¥­­ë¬ ¨«¨ ¬ áᨢ ¬"
$ Žè¨¡ª¨ ¢ë¯®«­¥­¨ï.
$set 5
$set 4
1 "<22>¥¤¥©á⢨⥫ì­ë© ibase: ¤®«¦¥­ ¡ëâì [%lu, %lu]"
2 "<22>¥¤¥©á⢨⥫ì­ë© obase: ¤®«¦¥­ ¡ëâì [%lu, %lu]"
@ -100,7 +95,7 @@ $set 5
11 "­¥ ¬®¦¥â ¨á¯®«ì§®¢ âì ¯ãá⮥ §­ ç¥­¨¥ ¢ ¢ëà ¦¥­¨¨"
$ ” â «ì­ë¥ ®è¨¡ª¨.
$set 6
$set 5
1 "<22>¥ 㤠«®áì ¢ë¤¥«¨âì ¯ ¬ïâì"
2 "Žè¨¡ª  ¢¢®¤ /¢ë¢®¤ "

17
contrib/bc/locales/ru_RU.ISO8859-5.msg
View File

@ -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:
@ -28,13 +28,8 @@ $ $
$quote "
$ ÀÐ×ÝëÕ áÞÞÑéÕÝØï.
$set 1
1 "ÄãÝÚæØï:"
$ Типы ошибок.
$set 2
$set 1
1 "Математическая ошибка:"
2 "Ошибка при разборе:"
@ -43,7 +38,7 @@ $set 2
5 "Предупреждение:"
$ Математические ошибки.
$set 3
$set 2
1 "отрицательное число"
2 "неинтегрированное число"
@ -51,7 +46,7 @@ $set 3
4 "делить на 0"
$ Ошибки при разборе.
$set 4
$set 3
1 "конец файла"
2 "недопустимый символ '%c'"
@ -85,7 +80,7 @@ $set 4
30 "POSIX не позволяет присваивать строки переменным или массивам"
$ Ошибки выполнения.
$set 5
$set 4
1 "Недействительный ibase: должен быть [%lu, %lu]"
2 "Недействительный obase: должен быть [%lu, %lu]"
@ -100,7 +95,7 @@ $set 5
11 "не может использовать пустое значение в выражении"
$ Фатальные ошибки.
$set 6
$set 5
1 "Не удалось выделить память"
2 "Ошибка ввода/вывода"

17
contrib/bc/locales/ru_RU.KOI8-R.msg
View File

@ -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:
@ -28,13 +28,8 @@ $ $
$quote "
$ òÁÚÎÙÅ ÓÏÏÂÝÅÎÉÑ.
$set 1
1 "æÕÎËÃÉÑ:"
$ Типы ошибок.
$set 2
$set 1
1 "Математическая ошибка:"
2 "Ошибка при разборе:"
@ -43,7 +38,7 @@ $set 2
5 "Предупреждение:"
$ Математические ошибки.
$set 3
$set 2
1 "отрицательное число"
2 "неинтегрированное число"
@ -51,7 +46,7 @@ $set 3
4 "делить на 0"
$ Ошибки при разборе.
$set 4
$set 3
1 "конец файла"
2 "недопустимый символ '%c'"
@ -85,7 +80,7 @@ $set 4
30 "POSIX не позволяет присваивать строки переменным или массивам"
$ Ошибки выполнения.
$set 5
$set 4
1 "Недействительный ibase: должен быть [%lu, %lu]"
2 "Недействительный obase: должен быть [%lu, %lu]"
@ -99,7 +94,7 @@ $set 5
10 "не может использовать пустое значение в выражении"
$ Фатальные ошибки.
$set 6
$set 5
1 "Не удалось выделить память"
2 "Ошибка ввода/вывода"

17
contrib/bc/locales/ru_RU.UTF-8.msg
View File

@ -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:
@ -28,13 +28,8 @@ $ $
$quote "
$ Разные сообщения.
$set 1
1 "Функция:"
$ Типы ошибок.
$set 2
$set 1
1 "Математическая ошибка:"
2 "Ошибка при разборе:"
@ -43,7 +38,7 @@ $set 2
5 "Предупреждение:"
$ Математические ошибки.
$set 3
$set 2
1 "отрицательное число"
2 "неинтегрированное число"
@ -51,7 +46,7 @@ $set 3
4 "делить на 0"
$ Ошибки при разборе.
$set 4
$set 3
1 "конец файла"
2 "недопустимый символ '%c'"
@ -85,7 +80,7 @@ $set 4
30 "POSIX не позволяет присваивать строки переменным или массивам"
$ Ошибки выполнения.
$set 5
$set 4
1 "Недействительный ibase: должен быть [%lu, %lu]"
2 "Недействительный obase: должен быть [%lu, %lu]"
@ -100,7 +95,7 @@ $set 5
11 "не может использовать пустое значение в выражении"
$ Фатальные ошибки.
$set 6
$set 5
1 "Не удалось выделить память"
2 "Ошибка ввода/вывода"

17
contrib/bc/locales/zh_CN.GB18030.msg
View File

@ -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:
@ -28,13 +28,8 @@ $ $
$quote "
$ 杂项信息。
$set 1
1 "函数："
$ 错误类型。
$set 2
$set 1
1 "数学错误："
2 "解析错误："
@ -43,7 +38,7 @@ $set 2
5 "警告："
$ 数学错误。
$set 3
$set 2
1 "负数"
2 "非整数"
@ -51,7 +46,7 @@ $set 3
4 "除以0"
$ 解析错误。
$set 4
$set 3
1 "文件结束"
2 "无效字符'%c'"
@ -85,7 +80,7 @@ $set 4
30 "POSIX不允许将字符串分配给变量或数组"
$ 运行时错误。
$set 5
$set 4
1 "无效的ibase: 必须是[%lu, %lu]"
2 "无效的obase：必须是[%lu，%lu]"
@ -100,7 +95,7 @@ $set 5
11 “不能在表达式中使用空值”
$ 致命错误。
$set 6
$set 5
1 "内存分配失败"
2 "I/O错误"

17
contrib/bc/locales/zh_CN.GB2312.msg
View File

@ -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:
@ -28,13 +28,8 @@ $ $
$quote "
$ 杂项信息。
$set 1
1 "函数："
$ 错误类型。
$set 2
$set 1
1 "数学错误："
2 "解析错误："
@ -43,7 +38,7 @@ $set 2
5 "警告："
$ 数学错误。
$set 3
$set 2
1 "负数"
2 "非整数"
@ -51,7 +46,7 @@ $set 3
4 "除以0"
$ 解析错误。
$set 4
$set 3
1 "文件结束"
2 "无效字符'%c'"
@ -85,7 +80,7 @@ $set 4
30 "POSIX不允许将字符串分配给变量或数组"
$ 运行时错误。
$set 5
$set 4
1 "无效的ibase: 必须是[%lu, %lu]"
2 "无效的obase：必须是[%lu，%lu]"
@ -100,7 +95,7 @@ $set 5
11 “不能在表达式中使用空值”
$ 致命错误。
$set 6
$set 5
1 "内存分配失败"
2 "I/O错误"

17
contrib/bc/locales/zh_CN.GBK.msg
View File

@ -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:
@ -28,13 +28,8 @@ $ $
$quote "
$ 杂项信息。
$set 1
1 "函数："
$ 错误类型。
$set 2
$set 1
1 "数学错误："
2 "解析错误："
@ -43,7 +38,7 @@ $set 2
5 "警告："
$ 数学错误。
$set 3
$set 2
1 "负数"
2 "非整数"
@ -51,7 +46,7 @@ $set 3
4 "除以0"
$ 解析错误。
$set 4
$set 3
1 "文件结束"
2 "无效字符'%c'"
@ -85,7 +80,7 @@ $set 4
30 "POSIX不允许将字符串分配给变量或数组"
$ 运行时错误。
$set 5
$set 4
1 "无效的ibase: 必须是[%lu, %lu]"
2 "无效的obase：必须是[%lu，%lu]"
@ -100,7 +95,7 @@ $set 5
11 “不能在表达式中使用空值”
$ 致命错误。
$set 6
$set 5
1 "内存分配失败"
2 "I/O错误"

17
contrib/bc/locales/zh_CN.UTF-8.msg
View File

@ -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:
@ -28,13 +28,8 @@ $ $
$quote "
$ 杂项信息。
$set 1
1 "函数："
$ 错误类型。
$set 2
$set 1
1 "数学错误："
2 "解析错误："
@ -43,7 +38,7 @@ $set 2
5 "警告："
$ 数学错误。
$set 3
$set 2
1 "负数"
2 "非整数"
@ -51,7 +46,7 @@ $set 3
4 "除以0"
$ 解析错误。
$set 4
$set 3
1 "文件结束"
2 "无效字符'%c'"
@ -85,7 +80,7 @@ $set 4
30 "POSIX不允许将字符串分配给变量或数组"
$ 运行时错误。
$set 5
$set 4
1 "无效的ibase: 必须是[%lu, %lu]"
2 "无效的obase：必须是[%lu，%lu]"
@ -100,7 +95,7 @@ $set 5
11 “不能在表达式中使用空值”
$ 致命错误。
$set 6
$set 5
1 "内存分配失败"
2 "I/O错误"

17
contrib/bc/locales/zh_CN.eucCN.msg
View File

@ -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:
@ -28,13 +28,8 @@ $ $
$quote "
$ 杂项信息。
$set 1
1 "函数："
$ 错误类型。
$set 2
$set 1
1 "数学错误："
2 "解析错误："
@ -43,7 +38,7 @@ $set 2
5 "警告："
$ 数学错误。
$set 3
$set 2
1 "负数"
2 "非整数"
@ -51,7 +46,7 @@ $set 3
4 "除以0"
$ 解析错误。
$set 4
$set 3
1 "文件结束"
2 "无效字符'%c'"
@ -85,7 +80,7 @@ $set 4
30 "POSIX不允许将字符串分配给变量或数组"
$ 运行时错误。
$set 5
$set 4
1 "无效的ibase: 必须是[%lu, %lu]"
2 "无效的obase：必须是[%lu，%lu]"
@ -100,7 +95,7 @@ $set 5
11 “不能在表达式中使用空值”
$ 致命错误。
$set 6
$set 5
1 "内存分配失败"
2 "I/O错误"

2
contrib/bc/manuals/algorithms.md
View File

@ -178,7 +178,7 @@ to calculate the bessel when `x < 0`, It has a complexity of `O(n^3)`.
their calculations with the precision (`scale`) set to at least 1 greater than
is needed.
### Modular Exponentiation (`dc` Only)
### Modular Exponentiation
This `dc` uses the [Memory-efficient method][8] to compute modular
exponentiation. The complexity is `O(e*n^2)`, which may initially seem

459
contrib/bc/manuals/bc/A.1
View File

@ -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,7 +25,7 @@
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.TH "BC" "1" "June 2022" "Gavin D. Howard" "General Commands Manual"
.TH "BC" "1" "October 2022" "Gavin D. Howard" "General Commands Manual"
.nh
.ad l
.SH NAME
@ -33,24 +33,25 @@
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[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]--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 at
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.
@ -79,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.
@ -172,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.
@ -202,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
@ -217,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
@ -294,38 +431,32 @@ 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
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html).
(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
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.
\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].
@ -351,93 +482,6 @@ extended math library (see the \f[B]LIBRARY\f[R] section).
.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]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.
.PP
This is a \f[B]non-portable extension\f[R].
.RE
.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]-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]-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]-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
.PP
All long options are \f[B]non-portable extensions\f[R].
.SH STDIN
@ -491,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
@ -668,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.
@ -675,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,
@ -683,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).
@ -698,44 +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 "18." 4
.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 "19." 4
.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 "20." 4
.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 "21." 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
@ -753,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 "22." 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
@ -776,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].
@ -1076,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].
@ -1109,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
@ -1136,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
@ -1171,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.)
@ -1384,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.
@ -1441,8 +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
@ -2501,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
@ -2621,6 +2729,22 @@ expressions and expression files, and a zero value makes bc(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
.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:
@ -2702,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.
@ -2736,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) standard
(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 Command-Line History
@ -2837,6 +2959,12 @@ 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].
@ -2845,8 +2973,11 @@ 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.yzena.com/gavin/bc .
.SH AUTHORS
.PP
Gavin D.

370
contrib/bc/manuals/bc/A.1.md
View File

@ -2,7 +2,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:
@ -34,15 +34,14 @@ bc - arbitrary-precision decimal arithmetic language and calculator
# SYNOPSIS
**bc** [**-ghilPqRsvVw**] [**-\-global-stacks**] [**-\-help**] [**-\-interactive**] [**-\-mathlib**] [**-\-no-prompt**] [**-\-no-read-prompt**] [**-\-quiet**] [**-\-standard**] [**-\-warn**] [**-\-version**] [**-e** *expr*] [**-\-expression**=*expr*...] [**-f** *file*...] [**-\-file**=*file*...] [*file*...] [**-I** *ibase*] [**-\-ibase**=*ibase*] [**-O** *obase*] [**-\-obase**=*obase*] [**-S** *scale*] [**-\-scale**=*scale*] [**-E** *seed*] [**-\-seed**=*seed*]
**bc** [**-cCghilPqRsvVw**] [**-\-digit-clamp**] [**-\-no-digit-clamp**] [**-\-global-stacks**] [**-\-help**] [**-\-interactive**] [**-\-mathlib**] [**-\-no-prompt**] [**-\-no-read-prompt**] [**-\-quiet**] [**-\-standard**] [**-\-warn**] [**-\-version**] [**-e** *expr*] [**-\-expression**=*expr*...] [**-f** *file*...] [**-\-file**=*file*...] [*file*...] [**-I** *ibase*] [**-\-ibase**=*ibase*] [**-O** *obase*] [**-\-obase**=*obase*] [**-S** *scale*] [**-\-scale**=*scale*] [**-E** *seed*] [**-\-seed**=*seed*]
# DESCRIPTION
bc(1) is an interactive processor for a language first standardized in 1991 by
POSIX. (The current standard is at
https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html .) The
language provides unlimited precision decimal arithmetic and is somewhat C-like,
but there are differences. Such differences will be noted in this document.
POSIX. (See the **STANDARDS** 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.
After parsing and handling options, this bc(1) reads any files given on the
command line and executes them before reading from **stdin**.
@ -64,6 +63,86 @@ that is a bug and should be reported. See the **BUGS** section.
The following are the options that bc(1) accepts.
**-C**, **-\-no-digit-clamp**
: Disables clamping of digits greater than or equal to the current **ibase**
when parsing numbers.
This means that the value added to a number from a digit is always that
digit's value multiplied by the value of ibase raised to the power of the
digit's position, which starts from 0 at the least significant digit.
If this and/or the **-c** or **-\-digit-clamp** options are given multiple
times, the last one given is used.
This option overrides the **BC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section) and the default, which can be queried
with the **-h** or **-\-help** options.
This is a **non-portable extension**.
**-c**, **-\-digit-clamp**
: Enables clamping of digits greater than or equal to the current **ibase**
when parsing numbers.
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's
position, which starts from 0 at the least significant digit.
If this and/or the **-C** or **-\-no-digit-clamp** options are given
multiple times, the last one given is used.
This option overrides the **BC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section) and the default, which can be queried
with the **-h** or **-\-help** options.
This is a **non-portable extension**.
**-E** *seed*, **-\-seed**=*seed*
: Sets the builtin variable **seed** to the value *seed* assuming that *seed*
is in base 10. It is a fatal error if *seed* is not a valid number.
If multiple instances of this option are given, the last is used.
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 the **-f** and **-\-file** 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.
If this option is given on the command-line (i.e., not in **BC_ENV_ARGS**,
see the **ENVIRONMENT VARIABLES** section), then after processing all
expressions and files, bc(1) will exit, unless **-** (**stdin**) was given
as an argument at least once to **-f** or **-\-file**, whether on the
command-line or in **BC_ENV_ARGS**. However, if any other **-e**,
**-\-expression**, **-f**, or **-\-file** arguments are given after **-f-**
or equivalent is given, bc(1) will give a fatal error and exit.
This is a **non-portable extension**.
**-f** *file*, **-\-file**=*file*
: Reads in *file* and evaluates it, line by line, as though it were read
through **stdin**. If expressions are also given (see the **-e** and
**-\-expression** options), the expressions are evaluated in the order
given.
If this option is given on the command-line (i.e., not in **BC_ENV_ARGS**,
see the **ENVIRONMENT VARIABLES** section), then after processing all
expressions and files, bc(1) will exit, unless **-** (**stdin**) was given
as an argument at least once to **-f** or **-\-file**. However, if any other
**-e**, **-\-expression**, **-f**, or **-\-file** arguments are given after
**-f-** or equivalent is given, bc(1) will give a fatal error and exit.
This is a **non-portable extension**.
**-g**, **-\-global-stacks**
: Turns the globals **ibase**, **obase**, **scale**, and **seed** into stacks.
@ -134,7 +213,16 @@ The following are the options that bc(1) accepts.
**-h**, **-\-help**
: Prints a usage message and quits.
: Prints a usage message and exits.
**-I** *ibase*, **-\-ibase**=*ibase*
: Sets the builtin variable **ibase** to the value *ibase* assuming that
*ibase* is in base 10. It is a fatal error if *ibase* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-i**, **-\-interactive**
@ -158,6 +246,15 @@ The following are the options that bc(1) accepts.
To learn what is in the libraries, see the **LIBRARY** section.
**-O** *obase*, **-\-obase**=*obase*
: Sets the builtin variable **obase** to the value *obase* assuming that
*obase* is in base 10. It is a fatal error if *obase* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-P**, **-\-no-prompt**
: Disables the prompt in TTY mode. (The prompt is only enabled in TTY mode.
@ -171,6 +268,19 @@ The following are the options that bc(1) accepts.
This is a **non-portable extension**.
**-q**, **-\-quiet**
: 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 **-v**, **-V**, or **-\-version** options are given
unless the **BC_BANNER** environment variable is set and contains a non-zero
integer or if this bc(1) was built with the header displayed by default. If
*any* of that is the case, then this option *does* prevent bc(1) from
printing the header.
This is a **non-portable extension**.
**-R**, **-\-no-read-prompt**
: Disables the read prompt in TTY mode. (The read prompt is only enabled in
@ -224,35 +334,29 @@ The following are the options that bc(1) accepts.
Keywords are *not* redefined when parsing the builtin math library (see the
**LIBRARY** section).
It is a fatal error to redefine keywords mandated by the POSIX standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html). It is
a fatal error to attempt to redefine words that this bc(1) does not reserve
as keywords.
It is a fatal error to redefine keywords mandated by the POSIX standard (see
the **STANDARDS** section). It is a fatal error to attempt to redefine words
that this bc(1) does not reserve as keywords.
**-q**, **-\-quiet**
**-S** *scale*, **-\-scale**=*scale*
: 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 **-v**, **-V**, or **-\-version** options are given
unless the **BC_BANNER** environment variable is set and contains a non-zero
integer or if this bc(1) was built with the header displayed by default. If
*any* of that is the case, then this option *does* prevent bc(1) from
printing the header.
: Sets the builtin variable **scale** to the value *scale* assuming that
*scale* is in base 10. It is a fatal error if *scale* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-s**, **-\-standard**
: 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 **STANDARDS**
section) and error if any extensions are used.
This is a **non-portable extension**.
**-v**, **-V**, **-\-version**
: Print the version information (copyright header) and exit.
: Print the version information (copyright header) and exits.
This is a **non-portable extension**.
@ -274,74 +378,6 @@ The following are the options that bc(1) accepts.
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.
If this option is given on the command-line (i.e., not in **BC_ENV_ARGS**,
see the **ENVIRONMENT VARIABLES** section), then after processing all
expressions and files, bc(1) will exit, unless **-** (**stdin**) was given
as an argument at least once to **-f** or **-\-file**, whether on the
command-line or in **BC_ENV_ARGS**. However, if any other **-e**,
**-\-expression**, **-f**, or **-\-file** arguments are given after **-f-**
or equivalent is given, bc(1) will give a fatal error and exit.
This is a **non-portable extension**.
**-f** *file*, **-\-file**=*file*
: Reads in *file* and evaluates it, line by line, as though it were read
through **stdin**. If expressions are also given (see above), the
expressions are evaluated in the order given.
If this option is given on the command-line (i.e., not in **BC_ENV_ARGS**,
see the **ENVIRONMENT VARIABLES** section), then after processing all
expressions and files, bc(1) will exit, unless **-** (**stdin**) was given
as an argument at least once to **-f** or **-\-file**. However, if any other
**-e**, **-\-expression**, **-f**, or **-\-file** arguments are given after
**-f-** or equivalent is given, bc(1) will give a fatal error and exit.
This is a **non-portable extension**.
**-I** *ibase*, **-\-ibase**=*ibase*
: Sets the builtin variable **ibase** to the value *ibase* assuming that
*ibase* is in base 10. It is a fatal error if *ibase* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-O** *obase*, **-\-obase**=*obase*
: Sets the builtin variable **obase** to the value *obase* assuming that
*obase* is in base 10. It is a fatal error if *obase* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-S** *scale*, **-\-scale**=*scale*
: Sets the builtin variable **scale** to the value *scale* assuming that
*scale* is in base 10. It is a fatal error if *scale* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-E** *seed*, **-\-seed**=*seed*
: Sets the builtin variable **seed** to the value *seed* assuming that *seed*
is in base 10. It is a fatal error if *seed* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
All long options are **non-portable extensions**.
# STDIN
@ -393,8 +429,7 @@ it is recommended that those scripts be changed to redirect **stderr** to
# SYNTAX
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
bc(1) follows the POSIX standard (see the **STANDARDS** 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.
@ -523,46 +558,54 @@ The following are valid operands in bc(1):
7. **scale(E)**: The *scale* of **E**.
8. **abs(E)**: The absolute value of **E**. This is a **non-portable
extension**.
9. **modexp(E, E, E)**: Modular exponentiation, where the first expression is
9. **is_number(E)**: **1** if the given argument is a number, **0** if it is a
string. This is a **non-portable extension**.
10. **is_string(E)**: **1** if the given argument is a string, **0** if it is a
number. This is a **non-portable extension**.
11. **modexp(E, E, E)**: Modular exponentiation, where the first expression is
the base, the second is the exponent, and the third is the modulus. All
three values must be integers. The second argument must be non-negative. The
third argument must be non-zero. This is a **non-portable extension**.
10. **divmod(E, E, I[])**: Division and modulus in one operation. This is for
11. **divmod(E, E, I[])**: Division and modulus in one operation. This is for
optimization. The first expression is the dividend, and the second is the
divisor, which must be non-zero. The return value is the quotient, and the
modulus is stored in index **0** of the provided array (the last argument).
This is a **non-portable extension**.
11. **asciify(E)**: If **E** is a string, returns a string that is the first
12. **asciify(E)**: If **E** is a string, returns a string that is the first
letter of its argument. If it is a number, calculates the number mod **256**
and returns that number as a one-character string. This is a **non-portable
extension**.
12. **I()**, **I(E)**, **I(E, E)**, and so on, where **I** is an identifier for
13. **asciify(I[])**: A string that is made up of the characters that would
result from running **asciify(E)** on each element of the array identified
by the argument. This allows creating multi-character strings and storing
them. This is a **non-portable extension**.
14. **I()**, **I(E)**, **I(E, E)**, and so on, where **I** is an identifier for
a non-**void** function (see the *Void Functions* subsection of the
**FUNCTIONS** section). The **E** argument(s) may also be arrays of the form
**I[]**, which will automatically be turned into array references (see the
*Array References* subsection of the **FUNCTIONS** section) if the
corresponding parameter in the function definition is an array reference.
13. **read()**: Reads a line from **stdin** and uses that as an expression. The
15. **read()**: Reads a line from **stdin** and uses that as an expression. The
result of that expression is the result of the **read()** operand. This is a
**non-portable extension**.
14. **maxibase()**: The max allowable **ibase**. This is a **non-portable
16. **maxibase()**: The max allowable **ibase**. This is a **non-portable
extension**.
15. **maxobase()**: The max allowable **obase**. This is a **non-portable
17. **maxobase()**: The max allowable **obase**. This is a **non-portable
extension**.
16. **maxscale()**: The max allowable **scale**. This is a **non-portable
18. **maxscale()**: The max allowable **scale**. This is a **non-portable
extension**.
17. **line_length()**: The line length set with **BC_LINE_LENGTH** (see the
19. **line_length()**: The line length set with **BC_LINE_LENGTH** (see the
**ENVIRONMENT VARIABLES** section). This is a **non-portable extension**.
18. **global_stacks()**: **0** if global stacks are not enabled with the **-g**
20. **global_stacks()**: **0** if global stacks are not enabled with the **-g**
or **-\-global-stacks** options, non-zero otherwise. See the **OPTIONS**
section. This is a **non-portable extension**.
19. **leading_zero()**: **0** if leading zeroes are not enabled with the **-z**
21. **leading_zero()**: **0** if leading zeroes are not enabled with the **-z**
or **--leading-zeroes** options, non-zero otherwise. See the **OPTIONS**
section. This is a **non-portable extension**.
20. **rand()**: A pseudo-random integer between **0** (inclusive) and
22. **rand()**: A pseudo-random integer between **0** (inclusive) and
**BC_RAND_MAX** (inclusive). Using this operand will change the value of
**seed**. This is a **non-portable extension**.
21. **irand(E)**: A pseudo-random integer between **0** (inclusive) and the
23. **irand(E)**: A pseudo-random integer between **0** (inclusive) and the
value of **E** (exclusive). If **E** is negative or is a non-integer
(**E**'s *scale* is not **0**), an error is raised, and bc(1) resets (see
the **RESET** section) while **seed** remains unchanged. If **E** is larger
@ -573,7 +616,7 @@ The following are valid operands in bc(1):
change the value of **seed**, unless the value of **E** is **0** or **1**.
In that case, **0** is returned, and **seed** is *not* changed. This is a
**non-portable extension**.
22. **maxrand()**: The max integer returned by **rand()**. This is a
24. **maxrand()**: The max integer returned by **rand()**. This is a
**non-portable extension**.
The integers generated by **rand()** and **irand(E)** are guaranteed to be as
@ -592,14 +635,40 @@ use a non-seeded pseudo-random number generator.
Numbers are strings made up of digits, uppercase letters, and at most **1**
period for a radix. Numbers can have up to **BC_NUM_MAX** digits. Uppercase
letters are equal to **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**.
letters are equal to **9** plus their position in the alphabet, starting from
**1** (i.e., **A** equals **10**, or **9+1**).
Single-character numbers (i.e., **A** alone) take the value that they would have
if they were valid digits, regardless of the value of **ibase**. This means that
**A** alone always equals decimal **10** and **Z** alone always equals decimal
**35**.
If a digit or letter makes no sense with the current value of **ibase** (i.e.,
they are greater than or equal to the current value of **ibase**), then the
behavior depends on the existence of the **-c**/**-\-digit-clamp** or
**-C**/**-\-no-digit-clamp** options (see the **OPTIONS** section), the
existence and setting of the **BC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section), or the default, which can be queried with
the **-h**/**-\-help** option.
If clamping is off, then digits or letters that are greater than or equal to the
current value of **ibase** are not changed. Instead, their given value is
multiplied by the appropriate power of **ibase** and added into the number. This
means that, with an **ibase** of **3**, the number **AB** is equal to
**3\^1\*A+3\^0\*B**, which is **3** times **10** plus **11**, or **41**.
If clamping is on, then digits or letters that are greater than or equal to the
current value of **ibase** are set to the value of the highest valid digit in
**ibase** before being multiplied by the appropriate power of **ibase** and
added into the number. This means that, with an **ibase** of **3**, the number
**AB** is equal to **3\^1\*2+3\^0\*2**, which is **3** times **2** plus **2**,
or **8**.
There is one exception to clamping: single-character numbers (i.e., **A**
alone). Such numbers are never clamped and always take the value they would have
in the highest possible **ibase**. This means that **A** alone always equals
decimal **10** and **Z** alone always equals decimal **35**. This behavior is
mandated by the standard (see the STANDARDS section) and is meant to provide an
easy way to set the current **ibase** (with the **i** command) regardless of the
current value of **ibase**.
If clamping is on, and the clamped value of a character is needed, use a leading
zero, i.e., for **A**, use **0A**.
In addition, bc(1) accepts numbers in scientific notation. These have the form
**\<number\>e\<integer\>**. The exponent (the portion after the **e**) must be
@ -849,10 +918,9 @@ The operators will be described in more detail below.
**assignment** operators, which means that **a=b\>c** is interpreted as
**(a=b)\>c**.
Also, unlike the standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html)
requires, these operators can appear anywhere any other expressions can be
used. This allowance is a **non-portable extension**.
Also, unlike the standard (see the **STANDARDS** section) requires, these
operators can appear anywhere any other expressions can be used. This
allowance is a **non-portable extension**.
**&&**
@ -916,6 +984,19 @@ The **if** **else** statement does the same thing as in C.
The **quit** statement causes bc(1) to quit, even if it is on a branch that will
not be executed (it is a compile-time command).
**Warning**: The behavior of this bc(1) on **quit** is slightly different from
other bc(1) implementations. Other bc(1) implementations will exit as soon as
they finish parsing the line that a **quit** command is on. This bc(1) will
execute any completed and executable statements that occur before the **quit**
statement before exiting.
In other words, for the bc(1) code below:
for (i = 0; i < 3; ++i) i; quit
Other bc(1) implementations will print nothing, and this bc(1) will print **0**,
**1**, and **2** on successive lines before exiting.
The **halt** statement causes bc(1) to quit, if it is executed. (Unlike **quit**
if it is on a branch of an **if** statement that is not executed, bc(1) does not
quit.)
@ -1099,9 +1180,8 @@ equivalents are given.
## Standard Library
The standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html) defines the
following functions for the math library:
The standard (see the **STANDARDS** section) defines the following functions for
the math library:
**s(x)**
@ -1149,8 +1229,7 @@ following functions for the math library:
The extended library is *not* loaded when the **-s**/**-\-standard** or
**-w**/**-\-warn** options are given since they are not part of the library
defined by the standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html).
defined by the standard (see the **STANDARDS** section).
The extended library is a **non-portable extension**.
@ -2085,7 +2164,8 @@ be hit.
# ENVIRONMENT VARIABLES
bc(1) recognizes the following environment variables:
As **non-portable extensions**, bc(1) recognizes the following environment
variables:
**POSIXLY_CORRECT**
@ -2191,6 +2271,21 @@ bc(1) recognizes the following environment variables:
This environment variable overrides the default, which can be queried with
the **-h** or **-\-help** options.
**BC_DIGIT_CLAMP**
: 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 **ibase** so that all such digits are considered equal
to the **ibase** 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 **ibase**.
This never applies to single-digit numbers, as per the standard (see the
**STANDARDS** section).
This environment variable overrides the default, which can be queried with
the **-h** or **-\-help** options.
# EXIT STATUS
bc(1) returns the following exit statuses:
@ -2266,12 +2361,10 @@ checking, and its normal behavior can be forced by using the **-i** flag or
# INTERACTIVE MODE
Per the standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html), bc(1) has
an interactive mode and a non-interactive mode. Interactive mode is turned on
automatically when both **stdin** and **stdout** are hooked to a terminal, but
the **-i** flag and **-\-interactive** option can turn it on in other
situations.
Per the standard (see the **STANDARDS** section), bc(1) has an interactive mode
and a non-interactive mode. Interactive mode is turned on automatically when
both **stdin** and **stdout** are hooked to a terminal, but the **-i** flag and
**-\-interactive** option can turn it on in other situations.
In interactive mode, bc(1) attempts to recover from errors (see the **RESET**
section), and in normal execution, flushes **stdout** as soon as execution is
@ -2297,10 +2390,8 @@ setting is used. The default setting can be queried with the **-h** or
**-\-help** options.
TTY mode is different from interactive mode because interactive mode is required
in the bc(1) standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html), and
interactive mode requires only **stdin** and **stdout** to be connected to a
terminal.
in the bc(1) standard (see the **STANDARDS** section), and interactive mode
requires only **stdin** and **stdout** to be connected to a terminal.
## Command-Line History
@ -2391,6 +2482,10 @@ at https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html . The
flags **-efghiqsvVw**, all long options, and the extensions noted above are
extensions to that specification.
In addition, the behavior of the **quit** implements an interpretation of that
specification that is different from all known implementations. For more
information see the **Statements** subsection of the **SYNTAX** section.
Note that the specification explicitly says that bc(1) only accepts numbers that
use a period (**.**) as a radix point, regardless of the value of
**LC_NUMERIC**.
@ -2400,7 +2495,10 @@ This bc(1) supports error messages for different locales, and thus, it supports
# BUGS
None are known. Report bugs at https://git.yzena.com/gavin/bc.
Before version **6.1.0**, this bc(1) had incorrect behavior for the **quit**
statement.
No other bugs are known. Report bugs at https://git.yzena.com/gavin/bc .
# AUTHORS

420
contrib/bc/manuals/bc/E.1
View File

@ -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,7 +25,7 @@
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.TH "BC" "1" "June 2022" "Gavin D. Howard" "General Commands Manual"
.TH "BC" "1" "October 2022" "Gavin D. Howard" "General Commands Manual"
.nh
.ad l
.SH NAME
@ -33,20 +33,21 @@
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]\&...]
.SH DESCRIPTION
.PP
bc(1) is an interactive processor for a language first standardized in
1991 by POSIX.
(The current standard is at
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.
@ -56,6 +57,8 @@ the command line and executes them before reading from \f[B]stdin\f[R].
.PP
This bc(1) is a drop-in replacement for \f[I]any\f[R] bc(1), including
(and especially) the GNU bc(1).
It also has many extensions and extra features beyond other
implementations.
.PP
\f[B]Note\f[R]: If running this bc(1) on \f[I]any\f[R] script meant for
another bc(1) gives a parse error, it is probably because a word this
@ -73,6 +76,91 @@ 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]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], and \f[B]scale\f[R]
into stacks.
@ -146,7 +234,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.
@ -175,11 +274,23 @@ any expressions or files specified on the command line.
To learn what is in the library, 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
@ -190,11 +301,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
@ -259,38 +387,32 @@ 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
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html).
(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
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.
\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].
@ -316,82 +438,6 @@ extended math library (see the \f[B]LIBRARY\f[R] section).
.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]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.
.PP
This is a \f[B]non-portable extension\f[R].
.RE
.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]-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]-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
.PP
All long options are \f[B]non-portable extensions\f[R].
.SH STDIN
@ -445,10 +491,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
@ -588,6 +633,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.
@ -595,7 +648,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,
@ -603,13 +656,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).
@ -618,33 +677,33 @@ 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 "18." 4
.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 "19." 4
.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.
@ -655,17 +714,49 @@ This is a \f[B]non-portable extension\f[R].
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].
.SS Operators
.PP
The following arithmetic and logical operators can be used.
@ -853,8 +944,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].
@ -886,8 +976,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
@ -913,9 +1003,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
@ -948,6 +1040,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.)
@ -1143,9 +1254,8 @@ All of the functions below are available when the \f[B]-l\f[R] or
\f[B]--mathlib\f[R] command-line flags 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.
@ -1333,7 +1443,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
@ -1453,6 +1564,22 @@ expressions and expression files, and a zero value makes bc(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
.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:
@ -1532,9 +1659,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.
@ -1566,8 +1692,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) standard
(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 Command-Line History
@ -1667,6 +1792,12 @@ 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].
@ -1675,8 +1806,11 @@ 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.yzena.com/gavin/bc .
.SH AUTHORS
.PP
Gavin D.

348
contrib/bc/manuals/bc/E.1.md
View File

@ -2,7 +2,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:
@ -34,21 +34,21 @@ bc - arbitrary-precision decimal arithmetic language and calculator
# SYNOPSIS
**bc** [**-ghilPqRsvVw**] [**-\-global-stacks**] [**-\-help**] [**-\-interactive**] [**-\-mathlib**] [**-\-no-prompt**] [**-\-no-read-prompt**] [**-\-quiet**] [**-\-standard**] [**-\-warn**] [**-\-version**] [**-e** *expr*] [**-\-expression**=*expr*...] [**-f** *file*...] [**-\-file**=*file*...] [*file*...]
**bc** [**-cCghilPqRsvVw**] [**-\-digit-clamp**] [**-\-no-digit-clamp**] [**-\-global-stacks**] [**-\-help**] [**-\-interactive**] [**-\-mathlib**] [**-\-no-prompt**] [**-\-no-read-prompt**] [**-\-quiet**] [**-\-standard**] [**-\-warn**] [**-\-version**] [**-e** *expr*] [**-\-expression**=*expr*...] [**-f** *file*...] [**-\-file**=*file*...] [*file*...]
# DESCRIPTION
bc(1) is an interactive processor for a language first standardized in 1991 by
POSIX. (The current standard is at
https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html .) The
language provides unlimited precision decimal arithmetic and is somewhat C-like,
but there are differences. Such differences will be noted in this document.
POSIX. (See the **STANDARDS** 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.
After parsing and handling options, this bc(1) reads any files given on the
command line and executes them before reading from **stdin**.
This bc(1) is a drop-in replacement for *any* bc(1), including (and especially)
the GNU bc(1).
This bc(1) is a drop-in replacement for *any* bc(1), including (and
especially) the GNU bc(1). It also has many extensions and extra features beyond
other implementations.
**Note**: If running this bc(1) on *any* script meant for another bc(1) gives a
parse error, it is probably because a word this bc(1) reserves as a keyword is
@ -63,6 +63,77 @@ that is a bug and should be reported. See the **BUGS** section.
The following are the options that bc(1) accepts.
**-C**, **-\-no-digit-clamp**
: Disables clamping of digits greater than or equal to the current **ibase**
when parsing numbers.
This means that the value added to a number from a digit is always that
digit's value multiplied by the value of ibase raised to the power of the
digit's position, which starts from 0 at the least significant digit.
If this and/or the **-c** or **-\-digit-clamp** options are given multiple
times, the last one given is used.
This option overrides the **BC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section) and the default, which can be queried
with the **-h** or **-\-help** options.
This is a **non-portable extension**.
**-c**, **-\-digit-clamp**
: Enables clamping of digits greater than or equal to the current **ibase**
when parsing numbers.
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's
position, which starts from 0 at the least significant digit.
If this and/or the **-C** or **-\-no-digit-clamp** options are given
multiple times, the last one given is used.
This option overrides the **BC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section) and the default, which can be queried
with the **-h** or **-\-help** options.
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 the **-f** and **-\-file** 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.
If this option is given on the command-line (i.e., not in **BC_ENV_ARGS**,
see the **ENVIRONMENT VARIABLES** section), then after processing all
expressions and files, bc(1) will exit, unless **-** (**stdin**) was given
as an argument at least once to **-f** or **-\-file**, whether on the
command-line or in **BC_ENV_ARGS**. However, if any other **-e**,
**-\-expression**, **-f**, or **-\-file** arguments are given after **-f-**
or equivalent is given, bc(1) will give a fatal error and exit.
This is a **non-portable extension**.
**-f** *file*, **-\-file**=*file*
: Reads in *file* and evaluates it, line by line, as though it were read
through **stdin**. If expressions are also given (see the **-e** and
**-\-expression** options), the expressions are evaluated in the order
given.
If this option is given on the command-line (i.e., not in **BC_ENV_ARGS**,
see the **ENVIRONMENT VARIABLES** section), then after processing all
expressions and files, bc(1) will exit, unless **-** (**stdin**) was given
as an argument at least once to **-f** or **-\-file**. However, if any other
**-e**, **-\-expression**, **-f**, or **-\-file** arguments are given after
**-f-** or equivalent is given, bc(1) will give a fatal error and exit.
This is a **non-portable extension**.
**-g**, **-\-global-stacks**
: Turns the globals **ibase**, **obase**, and **scale** into stacks.
@ -118,7 +189,16 @@ The following are the options that bc(1) accepts.
**-h**, **-\-help**
: Prints a usage message and quits.
: Prints a usage message and exits.
**-I** *ibase*, **-\-ibase**=*ibase*
: Sets the builtin variable **ibase** to the value *ibase* assuming that
*ibase* is in base 10. It is a fatal error if *ibase* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-i**, **-\-interactive**
@ -142,6 +222,15 @@ The following are the options that bc(1) accepts.
To learn what is in the library, see the **LIBRARY** section.
**-O** *obase*, **-\-obase**=*obase*
: Sets the builtin variable **obase** to the value *obase* assuming that
*obase* is in base 10. It is a fatal error if *obase* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-P**, **-\-no-prompt**
: Disables the prompt in TTY mode. (The prompt is only enabled in TTY mode.
@ -155,6 +244,19 @@ The following are the options that bc(1) accepts.
This is a **non-portable extension**.
**-q**, **-\-quiet**
: 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 **-v**, **-V**, or **-\-version** options are given
unless the **BC_BANNER** environment variable is set and contains a non-zero
integer or if this bc(1) was built with the header displayed by default. If
*any* of that is the case, then this option *does* prevent bc(1) from
printing the header.
This is a **non-portable extension**.
**-R**, **-\-no-read-prompt**
: Disables the read prompt in TTY mode. (The read prompt is only enabled in
@ -204,35 +306,29 @@ The following are the options that bc(1) accepts.
Keywords are *not* redefined when parsing the builtin math library (see the
**LIBRARY** section).
It is a fatal error to redefine keywords mandated by the POSIX standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html). It is
a fatal error to attempt to redefine words that this bc(1) does not reserve
as keywords.
It is a fatal error to redefine keywords mandated by the POSIX standard (see
the **STANDARDS** section). It is a fatal error to attempt to redefine words
that this bc(1) does not reserve as keywords.
**-q**, **-\-quiet**
**-S** *scale*, **-\-scale**=*scale*
: 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 **-v**, **-V**, or **-\-version** options are given
unless the **BC_BANNER** environment variable is set and contains a non-zero
integer or if this bc(1) was built with the header displayed by default. If
*any* of that is the case, then this option *does* prevent bc(1) from
printing the header.
: Sets the builtin variable **scale** to the value *scale* assuming that
*scale* is in base 10. It is a fatal error if *scale* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-s**, **-\-standard**
: 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 **STANDARDS**
section) and error if any extensions are used.
This is a **non-portable extension**.
**-v**, **-V**, **-\-version**
: Print the version information (copyright header) and exit.
: Print the version information (copyright header) and exits.
This is a **non-portable extension**.
@ -254,65 +350,6 @@ The following are the options that bc(1) accepts.
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.
If this option is given on the command-line (i.e., not in **BC_ENV_ARGS**,
see the **ENVIRONMENT VARIABLES** section), then after processing all
expressions and files, bc(1) will exit, unless **-** (**stdin**) was given
as an argument at least once to **-f** or **-\-file**, whether on the
command-line or in **BC_ENV_ARGS**. However, if any other **-e**,
**-\-expression**, **-f**, or **-\-file** arguments are given after **-f-**
or equivalent is given, bc(1) will give a fatal error and exit.
This is a **non-portable extension**.
**-f** *file*, **-\-file**=*file*
: Reads in *file* and evaluates it, line by line, as though it were read
through **stdin**. If expressions are also given (see above), the
expressions are evaluated in the order given.
If this option is given on the command-line (i.e., not in **BC_ENV_ARGS**,
see the **ENVIRONMENT VARIABLES** section), then after processing all
expressions and files, bc(1) will exit, unless **-** (**stdin**) was given
as an argument at least once to **-f** or **-\-file**. However, if any other
**-e**, **-\-expression**, **-f**, or **-\-file** arguments are given after
**-f-** or equivalent is given, bc(1) will give a fatal error and exit.
This is a **non-portable extension**.
**-I** *ibase*, **-\-ibase**=*ibase*
: Sets the builtin variable **ibase** to the value *ibase* assuming that
*ibase* is in base 10. It is a fatal error if *ibase* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-O** *obase*, **-\-obase**=*obase*
: Sets the builtin variable **obase** to the value *obase* assuming that
*obase* is in base 10. It is a fatal error if *obase* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-S** *scale*, **-\-scale**=*scale*
: Sets the builtin variable **scale** to the value *scale* assuming that
*scale* is in base 10. It is a fatal error if *scale* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
All long options are **non-portable extensions**.
# STDIN
@ -364,8 +401,7 @@ it is recommended that those scripts be changed to redirect **stderr** to
# SYNTAX
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
bc(1) follows the POSIX standard (see the **STANDARDS** 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.
@ -468,40 +504,48 @@ The following are valid operands in bc(1):
7. **scale(E)**: The *scale* of **E**.
8. **abs(E)**: The absolute value of **E**. This is a **non-portable
extension**.
9. **modexp(E, E, E)**: Modular exponentiation, where the first expression is
9. **is_number(E)**: **1** if the given argument is a number, **0** if it is a
string. This is a **non-portable extension**.
10. **is_string(E)**: **1** if the given argument is a string, **0** if it is a
number. This is a **non-portable extension**.
11. **modexp(E, E, E)**: Modular exponentiation, where the first expression is
the base, the second is the exponent, and the third is the modulus. All
three values must be integers. The second argument must be non-negative. The
third argument must be non-zero. This is a **non-portable extension**.
10. **divmod(E, E, I[])**: Division and modulus in one operation. This is for
11. **divmod(E, E, I[])**: Division and modulus in one operation. This is for
optimization. The first expression is the dividend, and the second is the
divisor, which must be non-zero. The return value is the quotient, and the
modulus is stored in index **0** of the provided array (the last argument).
This is a **non-portable extension**.
11. **asciify(E)**: If **E** is a string, returns a string that is the first
12. **asciify(E)**: If **E** is a string, returns a string that is the first
letter of its argument. If it is a number, calculates the number mod **256**
and returns that number as a one-character string. This is a **non-portable
extension**.
12. **I()**, **I(E)**, **I(E, E)**, and so on, where **I** is an identifier for
13. **asciify(I[])**: A string that is made up of the characters that would
result from running **asciify(E)** on each element of the array identified
by the argument. This allows creating multi-character strings and storing
them. This is a **non-portable extension**.
14. **I()**, **I(E)**, **I(E, E)**, and so on, where **I** is an identifier for
a non-**void** function (see the *Void Functions* subsection of the
**FUNCTIONS** section). The **E** argument(s) may also be arrays of the form
**I[]**, which will automatically be turned into array references (see the
*Array References* subsection of the **FUNCTIONS** section) if the
corresponding parameter in the function definition is an array reference.
13. **read()**: Reads a line from **stdin** and uses that as an expression. The
15. **read()**: Reads a line from **stdin** and uses that as an expression. The
result of that expression is the result of the **read()** operand. This is a
**non-portable extension**.
14. **maxibase()**: The max allowable **ibase**. This is a **non-portable
16. **maxibase()**: The max allowable **ibase**. This is a **non-portable
extension**.
15. **maxobase()**: The max allowable **obase**. This is a **non-portable
17. **maxobase()**: The max allowable **obase**. This is a **non-portable
extension**.
16. **maxscale()**: The max allowable **scale**. This is a **non-portable
18. **maxscale()**: The max allowable **scale**. This is a **non-portable
extension**.
17. **line_length()**: The line length set with **BC_LINE_LENGTH** (see the
19. **line_length()**: The line length set with **BC_LINE_LENGTH** (see the
**ENVIRONMENT VARIABLES** section). This is a **non-portable extension**.
18. **global_stacks()**: **0** if global stacks are not enabled with the **-g**
20. **global_stacks()**: **0** if global stacks are not enabled with the **-g**
or **-\-global-stacks** options, non-zero otherwise. See the **OPTIONS**
section. This is a **non-portable extension**.
19. **leading_zero()**: **0** if leading zeroes are not enabled with the **-z**
21. **leading_zero()**: **0** if leading zeroes are not enabled with the **-z**
or **--leading-zeroes** options, non-zero otherwise. See the **OPTIONS**
section. This is a **non-portable extension**.
@ -509,14 +553,40 @@ The following are valid operands in bc(1):
Numbers are strings made up of digits, uppercase letters, and at most **1**
period for a radix. Numbers can have up to **BC_NUM_MAX** digits. Uppercase
letters are equal to **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**.
letters are equal to **9** plus their position in the alphabet, starting from
**1** (i.e., **A** equals **10**, or **9+1**).
Single-character numbers (i.e., **A** alone) take the value that they would have
if they were valid digits, regardless of the value of **ibase**. This means that
**A** alone always equals decimal **10** and **Z** alone always equals decimal
**35**.
If a digit or letter makes no sense with the current value of **ibase** (i.e.,
they are greater than or equal to the current value of **ibase**), then the
behavior depends on the existence of the **-c**/**-\-digit-clamp** or
**-C**/**-\-no-digit-clamp** options (see the **OPTIONS** section), the
existence and setting of the **BC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section), or the default, which can be queried with
the **-h**/**-\-help** option.
If clamping is off, then digits or letters that are greater than or equal to the
current value of **ibase** are not changed. Instead, their given value is
multiplied by the appropriate power of **ibase** and added into the number. This
means that, with an **ibase** of **3**, the number **AB** is equal to
**3\^1\*A+3\^0\*B**, which is **3** times **10** plus **11**, or **41**.
If clamping is on, then digits or letters that are greater than or equal to the
current value of **ibase** are set to the value of the highest valid digit in
**ibase** before being multiplied by the appropriate power of **ibase** and
added into the number. This means that, with an **ibase** of **3**, the number
**AB** is equal to **3\^1\*2+3\^0\*2**, which is **3** times **2** plus **2**,
or **8**.
There is one exception to clamping: single-character numbers (i.e., **A**
alone). Such numbers are never clamped and always take the value they would have
in the highest possible **ibase**. This means that **A** alone always equals
decimal **10** and **Z** alone always equals decimal **35**. This behavior is
mandated by the standard (see the STANDARDS section) and is meant to provide an
easy way to set the current **ibase** (with the **i** command) regardless of the
current value of **ibase**.
If clamping is on, and the clamped value of a character is needed, use a leading
zero, i.e., for **A**, use **0A**.
## Operators
@ -683,10 +753,9 @@ The operators will be described in more detail below.
**assignment** operators, which means that **a=b\>c** is interpreted as
**(a=b)\>c**.
Also, unlike the standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html)
requires, these operators can appear anywhere any other expressions can be
used. This allowance is a **non-portable extension**.
Also, unlike the standard (see the **STANDARDS** section) requires, these
operators can appear anywhere any other expressions can be used. This
allowance is a **non-portable extension**.
**&&**
@ -750,6 +819,19 @@ The **if** **else** statement does the same thing as in C.
The **quit** statement causes bc(1) to quit, even if it is on a branch that will
not be executed (it is a compile-time command).
**Warning**: The behavior of this bc(1) on **quit** is slightly different from
other bc(1) implementations. Other bc(1) implementations will exit as soon as
they finish parsing the line that a **quit** command is on. This bc(1) will
execute any completed and executable statements that occur before the **quit**
statement before exiting.
In other words, for the bc(1) code below:
for (i = 0; i < 3; ++i) i; quit
Other bc(1) implementations will print nothing, and this bc(1) will print **0**,
**1**, and **2** on successive lines before exiting.
The **halt** statement causes bc(1) to quit, if it is executed. (Unlike **quit**
if it is on a branch of an **if** statement that is not executed, bc(1) does not
quit.)
@ -919,9 +1001,8 @@ command-line flags are given.
## Standard Library
The standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html) defines the
following functions for the math library:
The standard (see the **STANDARDS** section) defines the following functions for
the math library:
**s(x)**
@ -1093,7 +1174,8 @@ be hit.
# ENVIRONMENT VARIABLES
bc(1) recognizes the following environment variables:
As **non-portable extensions**, bc(1) recognizes the following environment
variables:
**POSIXLY_CORRECT**
@ -1199,6 +1281,21 @@ bc(1) recognizes the following environment variables:
This environment variable overrides the default, which can be queried with
the **-h** or **-\-help** options.
**BC_DIGIT_CLAMP**
: 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 **ibase** so that all such digits are considered equal
to the **ibase** 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 **ibase**.
This never applies to single-digit numbers, as per the standard (see the
**STANDARDS** section).
This environment variable overrides the default, which can be queried with
the **-h** or **-\-help** options.
# EXIT STATUS
bc(1) returns the following exit statuses:
@ -1272,12 +1369,10 @@ checking, and its normal behavior can be forced by using the **-i** flag or
# INTERACTIVE MODE
Per the standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html), bc(1) has
an interactive mode and a non-interactive mode. Interactive mode is turned on
automatically when both **stdin** and **stdout** are hooked to a terminal, but
the **-i** flag and **-\-interactive** option can turn it on in other
situations.
Per the standard (see the **STANDARDS** section), bc(1) has an interactive mode
and a non-interactive mode. Interactive mode is turned on automatically when
both **stdin** and **stdout** are hooked to a terminal, but the **-i** flag and
**-\-interactive** option can turn it on in other situations.
In interactive mode, bc(1) attempts to recover from errors (see the **RESET**
section), and in normal execution, flushes **stdout** as soon as execution is
@ -1303,10 +1398,8 @@ setting is used. The default setting can be queried with the **-h** or
**-\-help** options.
TTY mode is different from interactive mode because interactive mode is required
in the bc(1) standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html), and
interactive mode requires only **stdin** and **stdout** to be connected to a
terminal.
in the bc(1) standard (see the **STANDARDS** section), and interactive mode
requires only **stdin** and **stdout** to be connected to a terminal.
## Command-Line History
@ -1397,6 +1490,10 @@ at https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html . The
flags **-efghiqsvVw**, all long options, and the extensions noted above are
extensions to that specification.
In addition, the behavior of the **quit** implements an interpretation of that
specification that is different from all known implementations. For more
information see the **Statements** subsection of the **SYNTAX** section.
Note that the specification explicitly says that bc(1) only accepts numbers that
use a period (**.**) as a radix point, regardless of the value of
**LC_NUMERIC**.
@ -1406,7 +1503,10 @@ This bc(1) supports error messages for different locales, and thus, it supports
# BUGS
None are known. Report bugs at https://git.yzena.com/gavin/bc.
Before version **6.1.0**, this bc(1) had incorrect behavior for the **quit**
statement.
No other bugs are known. Report bugs at https://git.yzena.com/gavin/bc .
# AUTHORS

420
contrib/bc/manuals/bc/EH.1
View File

@ -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,7 +25,7 @@
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.TH "BC" "1" "June 2022" "Gavin D. Howard" "General Commands Manual"
.TH "BC" "1" "October 2022" "Gavin D. Howard" "General Commands Manual"
.nh
.ad l
.SH NAME
@ -33,20 +33,21 @@
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]\&...]
.SH DESCRIPTION
.PP
bc(1) is an interactive processor for a language first standardized in
1991 by POSIX.
(The current standard is at
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.
@ -56,6 +57,8 @@ the command line and executes them before reading from \f[B]stdin\f[R].
.PP
This bc(1) is a drop-in replacement for \f[I]any\f[R] bc(1), including
(and especially) the GNU bc(1).
It also has many extensions and extra features beyond other
implementations.
.PP
\f[B]Note\f[R]: If running this bc(1) on \f[I]any\f[R] script meant for
another bc(1) gives a parse error, it is probably because a word this
@ -73,6 +76,91 @@ 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]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], and \f[B]scale\f[R]
into stacks.
@ -146,7 +234,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.
@ -175,11 +274,23 @@ any expressions or files specified on the command line.
To learn what is in the library, 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
@ -190,11 +301,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
@ -259,38 +387,32 @@ 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
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html).
(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
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.
\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].
@ -316,82 +438,6 @@ extended math library (see the \f[B]LIBRARY\f[R] section).
.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]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.
.PP
This is a \f[B]non-portable extension\f[R].
.RE
.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]-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]-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
.PP
All long options are \f[B]non-portable extensions\f[R].
.SH STDIN
@ -445,10 +491,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
@ -588,6 +633,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.
@ -595,7 +648,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,
@ -603,13 +656,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).
@ -618,33 +677,33 @@ 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 "18." 4
.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 "19." 4
.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.
@ -655,17 +714,49 @@ This is a \f[B]non-portable extension\f[R].
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].
.SS Operators
.PP
The following arithmetic and logical operators can be used.
@ -853,8 +944,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].
@ -886,8 +976,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
@ -913,9 +1003,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
@ -948,6 +1040,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.)
@ -1143,9 +1254,8 @@ All of the functions below are available when the \f[B]-l\f[R] or
\f[B]--mathlib\f[R] command-line flags 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.
@ -1333,7 +1443,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
@ -1453,6 +1564,22 @@ expressions and expression files, and a zero value makes bc(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
.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:
@ -1532,9 +1659,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.
@ -1566,8 +1692,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) standard
(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
@ -1638,6 +1763,12 @@ 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].
@ -1646,8 +1777,11 @@ 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.yzena.com/gavin/bc .
.SH AUTHORS
.PP
Gavin D.

348
contrib/bc/manuals/bc/EH.1.md
View File

@ -2,7 +2,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:
@ -34,21 +34,21 @@ bc - arbitrary-precision decimal arithmetic language and calculator
# SYNOPSIS
**bc** [**-ghilPqRsvVw**] [**-\-global-stacks**] [**-\-help**] [**-\-interactive**] [**-\-mathlib**] [**-\-no-prompt**] [**-\-no-read-prompt**] [**-\-quiet**] [**-\-standard**] [**-\-warn**] [**-\-version**] [**-e** *expr*] [**-\-expression**=*expr*...] [**-f** *file*...] [**-\-file**=*file*...] [*file*...]
**bc** [**-cCghilPqRsvVw**] [**-\-digit-clamp**] [**-\-no-digit-clamp**] [**-\-global-stacks**] [**-\-help**] [**-\-interactive**] [**-\-mathlib**] [**-\-no-prompt**] [**-\-no-read-prompt**] [**-\-quiet**] [**-\-standard**] [**-\-warn**] [**-\-version**] [**-e** *expr*] [**-\-expression**=*expr*...] [**-f** *file*...] [**-\-file**=*file*...] [*file*...]
# DESCRIPTION
bc(1) is an interactive processor for a language first standardized in 1991 by
POSIX. (The current standard is at
https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html .) The
language provides unlimited precision decimal arithmetic and is somewhat C-like,
but there are differences. Such differences will be noted in this document.
POSIX. (See the **STANDARDS** 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.
After parsing and handling options, this bc(1) reads any files given on the
command line and executes them before reading from **stdin**.
This bc(1) is a drop-in replacement for *any* bc(1), including (and especially)
the GNU bc(1).
This bc(1) is a drop-in replacement for *any* bc(1), including (and
especially) the GNU bc(1). It also has many extensions and extra features beyond
other implementations.
**Note**: If running this bc(1) on *any* script meant for another bc(1) gives a
parse error, it is probably because a word this bc(1) reserves as a keyword is
@ -63,6 +63,77 @@ that is a bug and should be reported. See the **BUGS** section.
The following are the options that bc(1) accepts.
**-C**, **-\-no-digit-clamp**
: Disables clamping of digits greater than or equal to the current **ibase**
when parsing numbers.
This means that the value added to a number from a digit is always that
digit's value multiplied by the value of ibase raised to the power of the
digit's position, which starts from 0 at the least significant digit.
If this and/or the **-c** or **-\-digit-clamp** options are given multiple
times, the last one given is used.
This option overrides the **BC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section) and the default, which can be queried
with the **-h** or **-\-help** options.
This is a **non-portable extension**.
**-c**, **-\-digit-clamp**
: Enables clamping of digits greater than or equal to the current **ibase**
when parsing numbers.
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's
position, which starts from 0 at the least significant digit.
If this and/or the **-C** or **-\-no-digit-clamp** options are given
multiple times, the last one given is used.
This option overrides the **BC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section) and the default, which can be queried
with the **-h** or **-\-help** options.
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 the **-f** and **-\-file** 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.
If this option is given on the command-line (i.e., not in **BC_ENV_ARGS**,
see the **ENVIRONMENT VARIABLES** section), then after processing all
expressions and files, bc(1) will exit, unless **-** (**stdin**) was given
as an argument at least once to **-f** or **-\-file**, whether on the
command-line or in **BC_ENV_ARGS**. However, if any other **-e**,
**-\-expression**, **-f**, or **-\-file** arguments are given after **-f-**
or equivalent is given, bc(1) will give a fatal error and exit.
This is a **non-portable extension**.
**-f** *file*, **-\-file**=*file*
: Reads in *file* and evaluates it, line by line, as though it were read
through **stdin**. If expressions are also given (see the **-e** and
**-\-expression** options), the expressions are evaluated in the order
given.
If this option is given on the command-line (i.e., not in **BC_ENV_ARGS**,
see the **ENVIRONMENT VARIABLES** section), then after processing all
expressions and files, bc(1) will exit, unless **-** (**stdin**) was given
as an argument at least once to **-f** or **-\-file**. However, if any other
**-e**, **-\-expression**, **-f**, or **-\-file** arguments are given after
**-f-** or equivalent is given, bc(1) will give a fatal error and exit.
This is a **non-portable extension**.
**-g**, **-\-global-stacks**
: Turns the globals **ibase**, **obase**, and **scale** into stacks.
@ -118,7 +189,16 @@ The following are the options that bc(1) accepts.
**-h**, **-\-help**
: Prints a usage message and quits.
: Prints a usage message and exits.
**-I** *ibase*, **-\-ibase**=*ibase*
: Sets the builtin variable **ibase** to the value *ibase* assuming that
*ibase* is in base 10. It is a fatal error if *ibase* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-i**, **-\-interactive**
@ -142,6 +222,15 @@ The following are the options that bc(1) accepts.
To learn what is in the library, see the **LIBRARY** section.
**-O** *obase*, **-\-obase**=*obase*
: Sets the builtin variable **obase** to the value *obase* assuming that
*obase* is in base 10. It is a fatal error if *obase* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-P**, **-\-no-prompt**
: Disables the prompt in TTY mode. (The prompt is only enabled in TTY mode.
@ -155,6 +244,19 @@ The following are the options that bc(1) accepts.
This is a **non-portable extension**.
**-q**, **-\-quiet**
: 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 **-v**, **-V**, or **-\-version** options are given
unless the **BC_BANNER** environment variable is set and contains a non-zero
integer or if this bc(1) was built with the header displayed by default. If
*any* of that is the case, then this option *does* prevent bc(1) from
printing the header.
This is a **non-portable extension**.
**-R**, **-\-no-read-prompt**
: Disables the read prompt in TTY mode. (The read prompt is only enabled in
@ -204,35 +306,29 @@ The following are the options that bc(1) accepts.
Keywords are *not* redefined when parsing the builtin math library (see the
**LIBRARY** section).
It is a fatal error to redefine keywords mandated by the POSIX standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html). It is
a fatal error to attempt to redefine words that this bc(1) does not reserve
as keywords.
It is a fatal error to redefine keywords mandated by the POSIX standard (see
the **STANDARDS** section). It is a fatal error to attempt to redefine words
that this bc(1) does not reserve as keywords.
**-q**, **-\-quiet**
**-S** *scale*, **-\-scale**=*scale*
: 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 **-v**, **-V**, or **-\-version** options are given
unless the **BC_BANNER** environment variable is set and contains a non-zero
integer or if this bc(1) was built with the header displayed by default. If
*any* of that is the case, then this option *does* prevent bc(1) from
printing the header.
: Sets the builtin variable **scale** to the value *scale* assuming that
*scale* is in base 10. It is a fatal error if *scale* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-s**, **-\-standard**
: 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 **STANDARDS**
section) and error if any extensions are used.
This is a **non-portable extension**.
**-v**, **-V**, **-\-version**
: Print the version information (copyright header) and exit.
: Print the version information (copyright header) and exits.
This is a **non-portable extension**.
@ -254,65 +350,6 @@ The following are the options that bc(1) accepts.
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.
If this option is given on the command-line (i.e., not in **BC_ENV_ARGS**,
see the **ENVIRONMENT VARIABLES** section), then after processing all
expressions and files, bc(1) will exit, unless **-** (**stdin**) was given
as an argument at least once to **-f** or **-\-file**, whether on the
command-line or in **BC_ENV_ARGS**. However, if any other **-e**,
**-\-expression**, **-f**, or **-\-file** arguments are given after **-f-**
or equivalent is given, bc(1) will give a fatal error and exit.
This is a **non-portable extension**.
**-f** *file*, **-\-file**=*file*
: Reads in *file* and evaluates it, line by line, as though it were read
through **stdin**. If expressions are also given (see above), the
expressions are evaluated in the order given.
If this option is given on the command-line (i.e., not in **BC_ENV_ARGS**,
see the **ENVIRONMENT VARIABLES** section), then after processing all
expressions and files, bc(1) will exit, unless **-** (**stdin**) was given
as an argument at least once to **-f** or **-\-file**. However, if any other
**-e**, **-\-expression**, **-f**, or **-\-file** arguments are given after
**-f-** or equivalent is given, bc(1) will give a fatal error and exit.
This is a **non-portable extension**.
**-I** *ibase*, **-\-ibase**=*ibase*
: Sets the builtin variable **ibase** to the value *ibase* assuming that
*ibase* is in base 10. It is a fatal error if *ibase* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-O** *obase*, **-\-obase**=*obase*
: Sets the builtin variable **obase** to the value *obase* assuming that
*obase* is in base 10. It is a fatal error if *obase* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-S** *scale*, **-\-scale**=*scale*
: Sets the builtin variable **scale** to the value *scale* assuming that
*scale* is in base 10. It is a fatal error if *scale* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
All long options are **non-portable extensions**.
# STDIN
@ -364,8 +401,7 @@ it is recommended that those scripts be changed to redirect **stderr** to
# SYNTAX
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
bc(1) follows the POSIX standard (see the **STANDARDS** 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.
@ -468,40 +504,48 @@ The following are valid operands in bc(1):
7. **scale(E)**: The *scale* of **E**.
8. **abs(E)**: The absolute value of **E**. This is a **non-portable
extension**.
9. **modexp(E, E, E)**: Modular exponentiation, where the first expression is
9. **is_number(E)**: **1** if the given argument is a number, **0** if it is a
string. This is a **non-portable extension**.
10. **is_string(E)**: **1** if the given argument is a string, **0** if it is a
number. This is a **non-portable extension**.
11. **modexp(E, E, E)**: Modular exponentiation, where the first expression is
the base, the second is the exponent, and the third is the modulus. All
three values must be integers. The second argument must be non-negative. The
third argument must be non-zero. This is a **non-portable extension**.
10. **divmod(E, E, I[])**: Division and modulus in one operation. This is for
11. **divmod(E, E, I[])**: Division and modulus in one operation. This is for
optimization. The first expression is the dividend, and the second is the
divisor, which must be non-zero. The return value is the quotient, and the
modulus is stored in index **0** of the provided array (the last argument).
This is a **non-portable extension**.
11. **asciify(E)**: If **E** is a string, returns a string that is the first
12. **asciify(E)**: If **E** is a string, returns a string that is the first
letter of its argument. If it is a number, calculates the number mod **256**
and returns that number as a one-character string. This is a **non-portable
extension**.
12. **I()**, **I(E)**, **I(E, E)**, and so on, where **I** is an identifier for
13. **asciify(I[])**: A string that is made up of the characters that would
result from running **asciify(E)** on each element of the array identified
by the argument. This allows creating multi-character strings and storing
them. This is a **non-portable extension**.
14. **I()**, **I(E)**, **I(E, E)**, and so on, where **I** is an identifier for
a non-**void** function (see the *Void Functions* subsection of the
**FUNCTIONS** section). The **E** argument(s) may also be arrays of the form
**I[]**, which will automatically be turned into array references (see the
*Array References* subsection of the **FUNCTIONS** section) if the
corresponding parameter in the function definition is an array reference.
13. **read()**: Reads a line from **stdin** and uses that as an expression. The
15. **read()**: Reads a line from **stdin** and uses that as an expression. The
result of that expression is the result of the **read()** operand. This is a
**non-portable extension**.
14. **maxibase()**: The max allowable **ibase**. This is a **non-portable
16. **maxibase()**: The max allowable **ibase**. This is a **non-portable
extension**.
15. **maxobase()**: The max allowable **obase**. This is a **non-portable
17. **maxobase()**: The max allowable **obase**. This is a **non-portable
extension**.
16. **maxscale()**: The max allowable **scale**. This is a **non-portable
18. **maxscale()**: The max allowable **scale**. This is a **non-portable
extension**.
17. **line_length()**: The line length set with **BC_LINE_LENGTH** (see the
19. **line_length()**: The line length set with **BC_LINE_LENGTH** (see the
**ENVIRONMENT VARIABLES** section). This is a **non-portable extension**.
18. **global_stacks()**: **0** if global stacks are not enabled with the **-g**
20. **global_stacks()**: **0** if global stacks are not enabled with the **-g**
or **-\-global-stacks** options, non-zero otherwise. See the **OPTIONS**
section. This is a **non-portable extension**.
19. **leading_zero()**: **0** if leading zeroes are not enabled with the **-z**
21. **leading_zero()**: **0** if leading zeroes are not enabled with the **-z**
or **--leading-zeroes** options, non-zero otherwise. See the **OPTIONS**
section. This is a **non-portable extension**.
@ -509,14 +553,40 @@ The following are valid operands in bc(1):
Numbers are strings made up of digits, uppercase letters, and at most **1**
period for a radix. Numbers can have up to **BC_NUM_MAX** digits. Uppercase
letters are equal to **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**.
letters are equal to **9** plus their position in the alphabet, starting from
**1** (i.e., **A** equals **10**, or **9+1**).
Single-character numbers (i.e., **A** alone) take the value that they would have
if they were valid digits, regardless of the value of **ibase**. This means that
**A** alone always equals decimal **10** and **Z** alone always equals decimal
**35**.
If a digit or letter makes no sense with the current value of **ibase** (i.e.,
they are greater than or equal to the current value of **ibase**), then the
behavior depends on the existence of the **-c**/**-\-digit-clamp** or
**-C**/**-\-no-digit-clamp** options (see the **OPTIONS** section), the
existence and setting of the **BC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section), or the default, which can be queried with
the **-h**/**-\-help** option.
If clamping is off, then digits or letters that are greater than or equal to the
current value of **ibase** are not changed. Instead, their given value is
multiplied by the appropriate power of **ibase** and added into the number. This
means that, with an **ibase** of **3**, the number **AB** is equal to
**3\^1\*A+3\^0\*B**, which is **3** times **10** plus **11**, or **41**.
If clamping is on, then digits or letters that are greater than or equal to the
current value of **ibase** are set to the value of the highest valid digit in
**ibase** before being multiplied by the appropriate power of **ibase** and
added into the number. This means that, with an **ibase** of **3**, the number
**AB** is equal to **3\^1\*2+3\^0\*2**, which is **3** times **2** plus **2**,
or **8**.
There is one exception to clamping: single-character numbers (i.e., **A**
alone). Such numbers are never clamped and always take the value they would have
in the highest possible **ibase**. This means that **A** alone always equals
decimal **10** and **Z** alone always equals decimal **35**. This behavior is
mandated by the standard (see the STANDARDS section) and is meant to provide an
easy way to set the current **ibase** (with the **i** command) regardless of the
current value of **ibase**.
If clamping is on, and the clamped value of a character is needed, use a leading
zero, i.e., for **A**, use **0A**.
## Operators
@ -683,10 +753,9 @@ The operators will be described in more detail below.
**assignment** operators, which means that **a=b\>c** is interpreted as
**(a=b)\>c**.
Also, unlike the standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html)
requires, these operators can appear anywhere any other expressions can be
used. This allowance is a **non-portable extension**.
Also, unlike the standard (see the **STANDARDS** section) requires, these
operators can appear anywhere any other expressions can be used. This
allowance is a **non-portable extension**.
**&&**
@ -750,6 +819,19 @@ The **if** **else** statement does the same thing as in C.
The **quit** statement causes bc(1) to quit, even if it is on a branch that will
not be executed (it is a compile-time command).
**Warning**: The behavior of this bc(1) on **quit** is slightly different from
other bc(1) implementations. Other bc(1) implementations will exit as soon as
they finish parsing the line that a **quit** command is on. This bc(1) will
execute any completed and executable statements that occur before the **quit**
statement before exiting.
In other words, for the bc(1) code below:
for (i = 0; i < 3; ++i) i; quit
Other bc(1) implementations will print nothing, and this bc(1) will print **0**,
**1**, and **2** on successive lines before exiting.
The **halt** statement causes bc(1) to quit, if it is executed. (Unlike **quit**
if it is on a branch of an **if** statement that is not executed, bc(1) does not
quit.)
@ -919,9 +1001,8 @@ command-line flags are given.
## Standard Library
The standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html) defines the
following functions for the math library:
The standard (see the **STANDARDS** section) defines the following functions for
the math library:
**s(x)**
@ -1093,7 +1174,8 @@ be hit.
# ENVIRONMENT VARIABLES
bc(1) recognizes the following environment variables:
As **non-portable extensions**, bc(1) recognizes the following environment
variables:
**POSIXLY_CORRECT**
@ -1199,6 +1281,21 @@ bc(1) recognizes the following environment variables:
This environment variable overrides the default, which can be queried with
the **-h** or **-\-help** options.
**BC_DIGIT_CLAMP**
: 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 **ibase** so that all such digits are considered equal
to the **ibase** 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 **ibase**.
This never applies to single-digit numbers, as per the standard (see the
**STANDARDS** section).
This environment variable overrides the default, which can be queried with
the **-h** or **-\-help** options.
# EXIT STATUS
bc(1) returns the following exit statuses:
@ -1272,12 +1369,10 @@ checking, and its normal behavior can be forced by using the **-i** flag or
# INTERACTIVE MODE
Per the standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html), bc(1) has
an interactive mode and a non-interactive mode. Interactive mode is turned on
automatically when both **stdin** and **stdout** are hooked to a terminal, but
the **-i** flag and **-\-interactive** option can turn it on in other
situations.
Per the standard (see the **STANDARDS** section), bc(1) has an interactive mode
and a non-interactive mode. Interactive mode is turned on automatically when
both **stdin** and **stdout** are hooked to a terminal, but the **-i** flag and
**-\-interactive** option can turn it on in other situations.
In interactive mode, bc(1) attempts to recover from errors (see the **RESET**
section), and in normal execution, flushes **stdout** as soon as execution is
@ -1303,10 +1398,8 @@ setting is used. The default setting can be queried with the **-h** or
**-\-help** options.
TTY mode is different from interactive mode because interactive mode is required
in the bc(1) standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html), and
interactive mode requires only **stdin** and **stdout** to be connected to a
terminal.
in the bc(1) standard (see the **STANDARDS** section), and interactive mode
requires only **stdin** and **stdout** to be connected to a terminal.
## Prompt
@ -1371,6 +1464,10 @@ at https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html . The
flags **-efghiqsvVw**, all long options, and the extensions noted above are
extensions to that specification.
In addition, the behavior of the **quit** implements an interpretation of that
specification that is different from all known implementations. For more
information see the **Statements** subsection of the **SYNTAX** section.
Note that the specification explicitly says that bc(1) only accepts numbers that
use a period (**.**) as a radix point, regardless of the value of
**LC_NUMERIC**.
@ -1380,7 +1477,10 @@ This bc(1) supports error messages for different locales, and thus, it supports
# BUGS
None are known. Report bugs at https://git.yzena.com/gavin/bc.
Before version **6.1.0**, this bc(1) had incorrect behavior for the **quit**
statement.
No other bugs are known. Report bugs at https://git.yzena.com/gavin/bc .
# AUTHORS

420
contrib/bc/manuals/bc/EHN.1
View File

@ -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,7 +25,7 @@
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.TH "BC" "1" "June 2022" "Gavin D. Howard" "General Commands Manual"
.TH "BC" "1" "October 2022" "Gavin D. Howard" "General Commands Manual"
.nh
.ad l
.SH NAME
@ -33,20 +33,21 @@
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]\&...]
.SH DESCRIPTION
.PP
bc(1) is an interactive processor for a language first standardized in
1991 by POSIX.
(The current standard is at
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.
@ -56,6 +57,8 @@ the command line and executes them before reading from \f[B]stdin\f[R].
.PP
This bc(1) is a drop-in replacement for \f[I]any\f[R] bc(1), including
(and especially) the GNU bc(1).
It also has many extensions and extra features beyond other
implementations.
.PP
\f[B]Note\f[R]: If running this bc(1) on \f[I]any\f[R] script meant for
another bc(1) gives a parse error, it is probably because a word this
@ -73,6 +76,91 @@ 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]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], and \f[B]scale\f[R]
into stacks.
@ -146,7 +234,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.
@ -175,11 +274,23 @@ any expressions or files specified on the command line.
To learn what is in the library, 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
@ -190,11 +301,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
@ -259,38 +387,32 @@ 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
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html).
(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
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.
\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].
@ -316,82 +438,6 @@ extended math library (see the \f[B]LIBRARY\f[R] section).
.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]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.
.PP
This is a \f[B]non-portable extension\f[R].
.RE
.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]-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]-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
.PP
All long options are \f[B]non-portable extensions\f[R].
.SH STDIN
@ -445,10 +491,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
@ -588,6 +633,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.
@ -595,7 +648,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,
@ -603,13 +656,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).
@ -618,33 +677,33 @@ 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 "18." 4
.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 "19." 4
.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.
@ -655,17 +714,49 @@ This is a \f[B]non-portable extension\f[R].
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].
.SS Operators
.PP
The following arithmetic and logical operators can be used.
@ -853,8 +944,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].
@ -886,8 +976,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
@ -913,9 +1003,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
@ -948,6 +1040,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.)
@ -1143,9 +1254,8 @@ All of the functions below are available when the \f[B]-l\f[R] or
\f[B]--mathlib\f[R] command-line flags 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.
@ -1333,7 +1443,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
@ -1453,6 +1564,22 @@ expressions and expression files, and a zero value makes bc(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
.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:
@ -1532,9 +1659,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.
@ -1566,8 +1692,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) standard
(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
@ -1634,13 +1759,22 @@ 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].
.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.yzena.com/gavin/bc .
.SH AUTHORS
.PP
Gavin D.

348
contrib/bc/manuals/bc/EHN.1.md
View File

@ -2,7 +2,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:
@ -34,21 +34,21 @@ bc - arbitrary-precision decimal arithmetic language and calculator
# SYNOPSIS
**bc** [**-ghilPqRsvVw**] [**-\-global-stacks**] [**-\-help**] [**-\-interactive**] [**-\-mathlib**] [**-\-no-prompt**] [**-\-no-read-prompt**] [**-\-quiet**] [**-\-standard**] [**-\-warn**] [**-\-version**] [**-e** *expr*] [**-\-expression**=*expr*...] [**-f** *file*...] [**-\-file**=*file*...] [*file*...]
**bc** [**-cCghilPqRsvVw**] [**-\-digit-clamp**] [**-\-no-digit-clamp**] [**-\-global-stacks**] [**-\-help**] [**-\-interactive**] [**-\-mathlib**] [**-\-no-prompt**] [**-\-no-read-prompt**] [**-\-quiet**] [**-\-standard**] [**-\-warn**] [**-\-version**] [**-e** *expr*] [**-\-expression**=*expr*...] [**-f** *file*...] [**-\-file**=*file*...] [*file*...]
# DESCRIPTION
bc(1) is an interactive processor for a language first standardized in 1991 by
POSIX. (The current standard is at
https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html .) The
language provides unlimited precision decimal arithmetic and is somewhat C-like,
but there are differences. Such differences will be noted in this document.
POSIX. (See the **STANDARDS** 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.
After parsing and handling options, this bc(1) reads any files given on the
command line and executes them before reading from **stdin**.
This bc(1) is a drop-in replacement for *any* bc(1), including (and especially)
the GNU bc(1).
This bc(1) is a drop-in replacement for *any* bc(1), including (and
especially) the GNU bc(1). It also has many extensions and extra features beyond
other implementations.
**Note**: If running this bc(1) on *any* script meant for another bc(1) gives a
parse error, it is probably because a word this bc(1) reserves as a keyword is
@ -63,6 +63,77 @@ that is a bug and should be reported. See the **BUGS** section.
The following are the options that bc(1) accepts.
**-C**, **-\-no-digit-clamp**
: Disables clamping of digits greater than or equal to the current **ibase**
when parsing numbers.
This means that the value added to a number from a digit is always that
digit's value multiplied by the value of ibase raised to the power of the
digit's position, which starts from 0 at the least significant digit.
If this and/or the **-c** or **-\-digit-clamp** options are given multiple
times, the last one given is used.
This option overrides the **BC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section) and the default, which can be queried
with the **-h** or **-\-help** options.
This is a **non-portable extension**.
**-c**, **-\-digit-clamp**
: Enables clamping of digits greater than or equal to the current **ibase**
when parsing numbers.
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's
position, which starts from 0 at the least significant digit.
If this and/or the **-C** or **-\-no-digit-clamp** options are given
multiple times, the last one given is used.
This option overrides the **BC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section) and the default, which can be queried
with the **-h** or **-\-help** options.
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 the **-f** and **-\-file** 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.
If this option is given on the command-line (i.e., not in **BC_ENV_ARGS**,
see the **ENVIRONMENT VARIABLES** section), then after processing all
expressions and files, bc(1) will exit, unless **-** (**stdin**) was given
as an argument at least once to **-f** or **-\-file**, whether on the
command-line or in **BC_ENV_ARGS**. However, if any other **-e**,
**-\-expression**, **-f**, or **-\-file** arguments are given after **-f-**
or equivalent is given, bc(1) will give a fatal error and exit.
This is a **non-portable extension**.
**-f** *file*, **-\-file**=*file*
: Reads in *file* and evaluates it, line by line, as though it were read
through **stdin**. If expressions are also given (see the **-e** and
**-\-expression** options), the expressions are evaluated in the order
given.
If this option is given on the command-line (i.e., not in **BC_ENV_ARGS**,
see the **ENVIRONMENT VARIABLES** section), then after processing all
expressions and files, bc(1) will exit, unless **-** (**stdin**) was given
as an argument at least once to **-f** or **-\-file**. However, if any other
**-e**, **-\-expression**, **-f**, or **-\-file** arguments are given after
**-f-** or equivalent is given, bc(1) will give a fatal error and exit.
This is a **non-portable extension**.
**-g**, **-\-global-stacks**
: Turns the globals **ibase**, **obase**, and **scale** into stacks.
@ -118,7 +189,16 @@ The following are the options that bc(1) accepts.
**-h**, **-\-help**
: Prints a usage message and quits.
: Prints a usage message and exits.
**-I** *ibase*, **-\-ibase**=*ibase*
: Sets the builtin variable **ibase** to the value *ibase* assuming that
*ibase* is in base 10. It is a fatal error if *ibase* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-i**, **-\-interactive**
@ -142,6 +222,15 @@ The following are the options that bc(1) accepts.
To learn what is in the library, see the **LIBRARY** section.
**-O** *obase*, **-\-obase**=*obase*
: Sets the builtin variable **obase** to the value *obase* assuming that
*obase* is in base 10. It is a fatal error if *obase* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-P**, **-\-no-prompt**
: Disables the prompt in TTY mode. (The prompt is only enabled in TTY mode.
@ -155,6 +244,19 @@ The following are the options that bc(1) accepts.
This is a **non-portable extension**.
**-q**, **-\-quiet**
: 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 **-v**, **-V**, or **-\-version** options are given
unless the **BC_BANNER** environment variable is set and contains a non-zero
integer or if this bc(1) was built with the header displayed by default. If
*any* of that is the case, then this option *does* prevent bc(1) from
printing the header.
This is a **non-portable extension**.
**-R**, **-\-no-read-prompt**
: Disables the read prompt in TTY mode. (The read prompt is only enabled in
@ -204,35 +306,29 @@ The following are the options that bc(1) accepts.
Keywords are *not* redefined when parsing the builtin math library (see the
**LIBRARY** section).
It is a fatal error to redefine keywords mandated by the POSIX standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html). It is
a fatal error to attempt to redefine words that this bc(1) does not reserve
as keywords.
It is a fatal error to redefine keywords mandated by the POSIX standard (see
the **STANDARDS** section). It is a fatal error to attempt to redefine words
that this bc(1) does not reserve as keywords.
**-q**, **-\-quiet**
**-S** *scale*, **-\-scale**=*scale*
: 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 **-v**, **-V**, or **-\-version** options are given
unless the **BC_BANNER** environment variable is set and contains a non-zero
integer or if this bc(1) was built with the header displayed by default. If
*any* of that is the case, then this option *does* prevent bc(1) from
printing the header.
: Sets the builtin variable **scale** to the value *scale* assuming that
*scale* is in base 10. It is a fatal error if *scale* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-s**, **-\-standard**
: 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 **STANDARDS**
section) and error if any extensions are used.
This is a **non-portable extension**.
**-v**, **-V**, **-\-version**
: Print the version information (copyright header) and exit.
: Print the version information (copyright header) and exits.
This is a **non-portable extension**.
@ -254,65 +350,6 @@ The following are the options that bc(1) accepts.
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.
If this option is given on the command-line (i.e., not in **BC_ENV_ARGS**,
see the **ENVIRONMENT VARIABLES** section), then after processing all
expressions and files, bc(1) will exit, unless **-** (**stdin**) was given
as an argument at least once to **-f** or **-\-file**, whether on the
command-line or in **BC_ENV_ARGS**. However, if any other **-e**,
**-\-expression**, **-f**, or **-\-file** arguments are given after **-f-**
or equivalent is given, bc(1) will give a fatal error and exit.
This is a **non-portable extension**.
**-f** *file*, **-\-file**=*file*
: Reads in *file* and evaluates it, line by line, as though it were read
through **stdin**. If expressions are also given (see above), the
expressions are evaluated in the order given.
If this option is given on the command-line (i.e., not in **BC_ENV_ARGS**,
see the **ENVIRONMENT VARIABLES** section), then after processing all
expressions and files, bc(1) will exit, unless **-** (**stdin**) was given
as an argument at least once to **-f** or **-\-file**. However, if any other
**-e**, **-\-expression**, **-f**, or **-\-file** arguments are given after
**-f-** or equivalent is given, bc(1) will give a fatal error and exit.
This is a **non-portable extension**.
**-I** *ibase*, **-\-ibase**=*ibase*
: Sets the builtin variable **ibase** to the value *ibase* assuming that
*ibase* is in base 10. It is a fatal error if *ibase* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-O** *obase*, **-\-obase**=*obase*
: Sets the builtin variable **obase** to the value *obase* assuming that
*obase* is in base 10. It is a fatal error if *obase* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-S** *scale*, **-\-scale**=*scale*
: Sets the builtin variable **scale** to the value *scale* assuming that
*scale* is in base 10. It is a fatal error if *scale* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
All long options are **non-portable extensions**.
# STDIN
@ -364,8 +401,7 @@ it is recommended that those scripts be changed to redirect **stderr** to
# SYNTAX
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
bc(1) follows the POSIX standard (see the **STANDARDS** 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.
@ -468,40 +504,48 @@ The following are valid operands in bc(1):
7. **scale(E)**: The *scale* of **E**.
8. **abs(E)**: The absolute value of **E**. This is a **non-portable
extension**.
9. **modexp(E, E, E)**: Modular exponentiation, where the first expression is
9. **is_number(E)**: **1** if the given argument is a number, **0** if it is a
string. This is a **non-portable extension**.
10. **is_string(E)**: **1** if the given argument is a string, **0** if it is a
number. This is a **non-portable extension**.
11. **modexp(E, E, E)**: Modular exponentiation, where the first expression is
the base, the second is the exponent, and the third is the modulus. All
three values must be integers. The second argument must be non-negative. The
third argument must be non-zero. This is a **non-portable extension**.
10. **divmod(E, E, I[])**: Division and modulus in one operation. This is for
11. **divmod(E, E, I[])**: Division and modulus in one operation. This is for
optimization. The first expression is the dividend, and the second is the
divisor, which must be non-zero. The return value is the quotient, and the
modulus is stored in index **0** of the provided array (the last argument).
This is a **non-portable extension**.
11. **asciify(E)**: If **E** is a string, returns a string that is the first
12. **asciify(E)**: If **E** is a string, returns a string that is the first
letter of its argument. If it is a number, calculates the number mod **256**
and returns that number as a one-character string. This is a **non-portable
extension**.
12. **I()**, **I(E)**, **I(E, E)**, and so on, where **I** is an identifier for
13. **asciify(I[])**: A string that is made up of the characters that would
result from running **asciify(E)** on each element of the array identified
by the argument. This allows creating multi-character strings and storing
them. This is a **non-portable extension**.
14. **I()**, **I(E)**, **I(E, E)**, and so on, where **I** is an identifier for
a non-**void** function (see the *Void Functions* subsection of the
**FUNCTIONS** section). The **E** argument(s) may also be arrays of the form
**I[]**, which will automatically be turned into array references (see the
*Array References* subsection of the **FUNCTIONS** section) if the
corresponding parameter in the function definition is an array reference.
13. **read()**: Reads a line from **stdin** and uses that as an expression. The
15. **read()**: Reads a line from **stdin** and uses that as an expression. The
result of that expression is the result of the **read()** operand. This is a
**non-portable extension**.
14. **maxibase()**: The max allowable **ibase**. This is a **non-portable
16. **maxibase()**: The max allowable **ibase**. This is a **non-portable
extension**.
15. **maxobase()**: The max allowable **obase**. This is a **non-portable
17. **maxobase()**: The max allowable **obase**. This is a **non-portable
extension**.
16. **maxscale()**: The max allowable **scale**. This is a **non-portable
18. **maxscale()**: The max allowable **scale**. This is a **non-portable
extension**.
17. **line_length()**: The line length set with **BC_LINE_LENGTH** (see the
19. **line_length()**: The line length set with **BC_LINE_LENGTH** (see the
**ENVIRONMENT VARIABLES** section). This is a **non-portable extension**.
18. **global_stacks()**: **0** if global stacks are not enabled with the **-g**
20. **global_stacks()**: **0** if global stacks are not enabled with the **-g**
or **-\-global-stacks** options, non-zero otherwise. See the **OPTIONS**
section. This is a **non-portable extension**.
19. **leading_zero()**: **0** if leading zeroes are not enabled with the **-z**
21. **leading_zero()**: **0** if leading zeroes are not enabled with the **-z**
or **--leading-zeroes** options, non-zero otherwise. See the **OPTIONS**
section. This is a **non-portable extension**.
@ -509,14 +553,40 @@ The following are valid operands in bc(1):
Numbers are strings made up of digits, uppercase letters, and at most **1**
period for a radix. Numbers can have up to **BC_NUM_MAX** digits. Uppercase
letters are equal to **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**.
letters are equal to **9** plus their position in the alphabet, starting from
**1** (i.e., **A** equals **10**, or **9+1**).
Single-character numbers (i.e., **A** alone) take the value that they would have
if they were valid digits, regardless of the value of **ibase**. This means that
**A** alone always equals decimal **10** and **Z** alone always equals decimal
**35**.
If a digit or letter makes no sense with the current value of **ibase** (i.e.,
they are greater than or equal to the current value of **ibase**), then the
behavior depends on the existence of the **-c**/**-\-digit-clamp** or
**-C**/**-\-no-digit-clamp** options (see the **OPTIONS** section), the
existence and setting of the **BC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section), or the default, which can be queried with
the **-h**/**-\-help** option.
If clamping is off, then digits or letters that are greater than or equal to the
current value of **ibase** are not changed. Instead, their given value is
multiplied by the appropriate power of **ibase** and added into the number. This
means that, with an **ibase** of **3**, the number **AB** is equal to
**3\^1\*A+3\^0\*B**, which is **3** times **10** plus **11**, or **41**.
If clamping is on, then digits or letters that are greater than or equal to the
current value of **ibase** are set to the value of the highest valid digit in
**ibase** before being multiplied by the appropriate power of **ibase** and
added into the number. This means that, with an **ibase** of **3**, the number
**AB** is equal to **3\^1\*2+3\^0\*2**, which is **3** times **2** plus **2**,
or **8**.
There is one exception to clamping: single-character numbers (i.e., **A**
alone). Such numbers are never clamped and always take the value they would have
in the highest possible **ibase**. This means that **A** alone always equals
decimal **10** and **Z** alone always equals decimal **35**. This behavior is
mandated by the standard (see the STANDARDS section) and is meant to provide an
easy way to set the current **ibase** (with the **i** command) regardless of the
current value of **ibase**.
If clamping is on, and the clamped value of a character is needed, use a leading
zero, i.e., for **A**, use **0A**.
## Operators
@ -683,10 +753,9 @@ The operators will be described in more detail below.
**assignment** operators, which means that **a=b\>c** is interpreted as
**(a=b)\>c**.
Also, unlike the standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html)
requires, these operators can appear anywhere any other expressions can be
used. This allowance is a **non-portable extension**.
Also, unlike the standard (see the **STANDARDS** section) requires, these
operators can appear anywhere any other expressions can be used. This
allowance is a **non-portable extension**.
**&&**
@ -750,6 +819,19 @@ The **if** **else** statement does the same thing as in C.
The **quit** statement causes bc(1) to quit, even if it is on a branch that will
not be executed (it is a compile-time command).
**Warning**: The behavior of this bc(1) on **quit** is slightly different from
other bc(1) implementations. Other bc(1) implementations will exit as soon as
they finish parsing the line that a **quit** command is on. This bc(1) will
execute any completed and executable statements that occur before the **quit**
statement before exiting.
In other words, for the bc(1) code below:
for (i = 0; i < 3; ++i) i; quit
Other bc(1) implementations will print nothing, and this bc(1) will print **0**,
**1**, and **2** on successive lines before exiting.
The **halt** statement causes bc(1) to quit, if it is executed. (Unlike **quit**
if it is on a branch of an **if** statement that is not executed, bc(1) does not
quit.)
@ -919,9 +1001,8 @@ command-line flags are given.
## Standard Library
The standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html) defines the
following functions for the math library:
The standard (see the **STANDARDS** section) defines the following functions for
the math library:
**s(x)**
@ -1093,7 +1174,8 @@ be hit.
# ENVIRONMENT VARIABLES
bc(1) recognizes the following environment variables:
As **non-portable extensions**, bc(1) recognizes the following environment
variables:
**POSIXLY_CORRECT**
@ -1199,6 +1281,21 @@ bc(1) recognizes the following environment variables:
This environment variable overrides the default, which can be queried with
the **-h** or **-\-help** options.
**BC_DIGIT_CLAMP**
: 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 **ibase** so that all such digits are considered equal
to the **ibase** 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 **ibase**.
This never applies to single-digit numbers, as per the standard (see the
**STANDARDS** section).
This environment variable overrides the default, which can be queried with
the **-h** or **-\-help** options.
# EXIT STATUS
bc(1) returns the following exit statuses:
@ -1272,12 +1369,10 @@ checking, and its normal behavior can be forced by using the **-i** flag or
# INTERACTIVE MODE
Per the standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html), bc(1) has
an interactive mode and a non-interactive mode. Interactive mode is turned on
automatically when both **stdin** and **stdout** are hooked to a terminal, but
the **-i** flag and **-\-interactive** option can turn it on in other
situations.
Per the standard (see the **STANDARDS** section), bc(1) has an interactive mode
and a non-interactive mode. Interactive mode is turned on automatically when
both **stdin** and **stdout** are hooked to a terminal, but the **-i** flag and
**-\-interactive** option can turn it on in other situations.
In interactive mode, bc(1) attempts to recover from errors (see the **RESET**
section), and in normal execution, flushes **stdout** as soon as execution is
@ -1303,10 +1398,8 @@ setting is used. The default setting can be queried with the **-h** or
**-\-help** options.
TTY mode is different from interactive mode because interactive mode is required
in the bc(1) standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html), and
interactive mode requires only **stdin** and **stdout** to be connected to a
terminal.
in the bc(1) standard (see the **STANDARDS** section), and interactive mode
requires only **stdin** and **stdout** to be connected to a terminal.
## Prompt
@ -1366,13 +1459,20 @@ at https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html . The
flags **-efghiqsvVw**, all long options, and the extensions noted above are
extensions to that specification.
In addition, the behavior of the **quit** implements an interpretation of that
specification that is different from all known implementations. For more
information see the **Statements** subsection of the **SYNTAX** section.
Note that the specification explicitly says that bc(1) only accepts numbers that
use a period (**.**) as a radix point, regardless of the value of
**LC_NUMERIC**.
# BUGS
None are known. Report bugs at https://git.yzena.com/gavin/bc.
Before version **6.1.0**, this bc(1) had incorrect behavior for the **quit**
statement.
No other bugs are known. Report bugs at https://git.yzena.com/gavin/bc .
# AUTHORS

420
contrib/bc/manuals/bc/EN.1
View File

@ -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,7 +25,7 @@
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.TH "BC" "1" "June 2022" "Gavin D. Howard" "General Commands Manual"
.TH "BC" "1" "October 2022" "Gavin D. Howard" "General Commands Manual"
.nh
.ad l
.SH NAME
@ -33,20 +33,21 @@
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]\&...]
.SH DESCRIPTION
.PP
bc(1) is an interactive processor for a language first standardized in
1991 by POSIX.
(The current standard is at
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.
@ -56,6 +57,8 @@ the command line and executes them before reading from \f[B]stdin\f[R].
.PP
This bc(1) is a drop-in replacement for \f[I]any\f[R] bc(1), including
(and especially) the GNU bc(1).
It also has many extensions and extra features beyond other
implementations.
.PP
\f[B]Note\f[R]: If running this bc(1) on \f[I]any\f[R] script meant for
another bc(1) gives a parse error, it is probably because a word this
@ -73,6 +76,91 @@ 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]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], and \f[B]scale\f[R]
into stacks.
@ -146,7 +234,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.
@ -175,11 +274,23 @@ any expressions or files specified on the command line.
To learn what is in the library, 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
@ -190,11 +301,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
@ -259,38 +387,32 @@ 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
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html).
(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
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.
\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].
@ -316,82 +438,6 @@ extended math library (see the \f[B]LIBRARY\f[R] section).
.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]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.
.PP
This is a \f[B]non-portable extension\f[R].
.RE
.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]-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]-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
.PP
All long options are \f[B]non-portable extensions\f[R].
.SH STDIN
@ -445,10 +491,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
@ -588,6 +633,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.
@ -595,7 +648,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,
@ -603,13 +656,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).
@ -618,33 +677,33 @@ 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 "18." 4
.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 "19." 4
.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.
@ -655,17 +714,49 @@ This is a \f[B]non-portable extension\f[R].
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].
.SS Operators
.PP
The following arithmetic and logical operators can be used.
@ -853,8 +944,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].
@ -886,8 +976,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
@ -913,9 +1003,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
@ -948,6 +1040,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.)
@ -1143,9 +1254,8 @@ All of the functions below are available when the \f[B]-l\f[R] or
\f[B]--mathlib\f[R] command-line flags 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.
@ -1333,7 +1443,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
@ -1453,6 +1564,22 @@ expressions and expression files, and a zero value makes bc(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
.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:
@ -1532,9 +1659,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.
@ -1566,8 +1692,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) standard
(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 Command-Line History
@ -1663,13 +1788,22 @@ 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].
.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.yzena.com/gavin/bc .
.SH AUTHORS
.PP
Gavin D.

348
contrib/bc/manuals/bc/EN.1.md
View File

@ -2,7 +2,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:
@ -34,21 +34,21 @@ bc - arbitrary-precision decimal arithmetic language and calculator
# SYNOPSIS
**bc** [**-ghilPqRsvVw**] [**-\-global-stacks**] [**-\-help**] [**-\-interactive**] [**-\-mathlib**] [**-\-no-prompt**] [**-\-no-read-prompt**] [**-\-quiet**] [**-\-standard**] [**-\-warn**] [**-\-version**] [**-e** *expr*] [**-\-expression**=*expr*...] [**-f** *file*...] [**-\-file**=*file*...] [*file*...]
**bc** [**-cCghilPqRsvVw**] [**-\-digit-clamp**] [**-\-no-digit-clamp**] [**-\-global-stacks**] [**-\-help**] [**-\-interactive**] [**-\-mathlib**] [**-\-no-prompt**] [**-\-no-read-prompt**] [**-\-quiet**] [**-\-standard**] [**-\-warn**] [**-\-version**] [**-e** *expr*] [**-\-expression**=*expr*...] [**-f** *file*...] [**-\-file**=*file*...] [*file*...]
# DESCRIPTION
bc(1) is an interactive processor for a language first standardized in 1991 by
POSIX. (The current standard is at
https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html .) The
language provides unlimited precision decimal arithmetic and is somewhat C-like,
but there are differences. Such differences will be noted in this document.
POSIX. (See the **STANDARDS** 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.
After parsing and handling options, this bc(1) reads any files given on the
command line and executes them before reading from **stdin**.
This bc(1) is a drop-in replacement for *any* bc(1), including (and especially)
the GNU bc(1).
This bc(1) is a drop-in replacement for *any* bc(1), including (and
especially) the GNU bc(1). It also has many extensions and extra features beyond
other implementations.
**Note**: If running this bc(1) on *any* script meant for another bc(1) gives a
parse error, it is probably because a word this bc(1) reserves as a keyword is
@ -63,6 +63,77 @@ that is a bug and should be reported. See the **BUGS** section.
The following are the options that bc(1) accepts.
**-C**, **-\-no-digit-clamp**
: Disables clamping of digits greater than or equal to the current **ibase**
when parsing numbers.
This means that the value added to a number from a digit is always that
digit's value multiplied by the value of ibase raised to the power of the
digit's position, which starts from 0 at the least significant digit.
If this and/or the **-c** or **-\-digit-clamp** options are given multiple
times, the last one given is used.
This option overrides the **BC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section) and the default, which can be queried
with the **-h** or **-\-help** options.
This is a **non-portable extension**.
**-c**, **-\-digit-clamp**
: Enables clamping of digits greater than or equal to the current **ibase**
when parsing numbers.
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's
position, which starts from 0 at the least significant digit.
If this and/or the **-C** or **-\-no-digit-clamp** options are given
multiple times, the last one given is used.
This option overrides the **BC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section) and the default, which can be queried
with the **-h** or **-\-help** options.
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 the **-f** and **-\-file** 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.
If this option is given on the command-line (i.e., not in **BC_ENV_ARGS**,
see the **ENVIRONMENT VARIABLES** section), then after processing all
expressions and files, bc(1) will exit, unless **-** (**stdin**) was given
as an argument at least once to **-f** or **-\-file**, whether on the
command-line or in **BC_ENV_ARGS**. However, if any other **-e**,
**-\-expression**, **-f**, or **-\-file** arguments are given after **-f-**
or equivalent is given, bc(1) will give a fatal error and exit.
This is a **non-portable extension**.
**-f** *file*, **-\-file**=*file*
: Reads in *file* and evaluates it, line by line, as though it were read
through **stdin**. If expressions are also given (see the **-e** and
**-\-expression** options), the expressions are evaluated in the order
given.
If this option is given on the command-line (i.e., not in **BC_ENV_ARGS**,
see the **ENVIRONMENT VARIABLES** section), then after processing all
expressions and files, bc(1) will exit, unless **-** (**stdin**) was given
as an argument at least once to **-f** or **-\-file**. However, if any other
**-e**, **-\-expression**, **-f**, or **-\-file** arguments are given after
**-f-** or equivalent is given, bc(1) will give a fatal error and exit.
This is a **non-portable extension**.
**-g**, **-\-global-stacks**
: Turns the globals **ibase**, **obase**, and **scale** into stacks.
@ -118,7 +189,16 @@ The following are the options that bc(1) accepts.
**-h**, **-\-help**
: Prints a usage message and quits.
: Prints a usage message and exits.
**-I** *ibase*, **-\-ibase**=*ibase*
: Sets the builtin variable **ibase** to the value *ibase* assuming that
*ibase* is in base 10. It is a fatal error if *ibase* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-i**, **-\-interactive**
@ -142,6 +222,15 @@ The following are the options that bc(1) accepts.
To learn what is in the library, see the **LIBRARY** section.
**-O** *obase*, **-\-obase**=*obase*
: Sets the builtin variable **obase** to the value *obase* assuming that
*obase* is in base 10. It is a fatal error if *obase* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-P**, **-\-no-prompt**
: Disables the prompt in TTY mode. (The prompt is only enabled in TTY mode.
@ -155,6 +244,19 @@ The following are the options that bc(1) accepts.
This is a **non-portable extension**.
**-q**, **-\-quiet**
: 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 **-v**, **-V**, or **-\-version** options are given
unless the **BC_BANNER** environment variable is set and contains a non-zero
integer or if this bc(1) was built with the header displayed by default. If
*any* of that is the case, then this option *does* prevent bc(1) from
printing the header.
This is a **non-portable extension**.
**-R**, **-\-no-read-prompt**
: Disables the read prompt in TTY mode. (The read prompt is only enabled in
@ -204,35 +306,29 @@ The following are the options that bc(1) accepts.
Keywords are *not* redefined when parsing the builtin math library (see the
**LIBRARY** section).
It is a fatal error to redefine keywords mandated by the POSIX standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html). It is
a fatal error to attempt to redefine words that this bc(1) does not reserve
as keywords.
It is a fatal error to redefine keywords mandated by the POSIX standard (see
the **STANDARDS** section). It is a fatal error to attempt to redefine words
that this bc(1) does not reserve as keywords.
**-q**, **-\-quiet**
**-S** *scale*, **-\-scale**=*scale*
: 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 **-v**, **-V**, or **-\-version** options are given
unless the **BC_BANNER** environment variable is set and contains a non-zero
integer or if this bc(1) was built with the header displayed by default. If
*any* of that is the case, then this option *does* prevent bc(1) from
printing the header.
: Sets the builtin variable **scale** to the value *scale* assuming that
*scale* is in base 10. It is a fatal error if *scale* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-s**, **-\-standard**
: 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 **STANDARDS**
section) and error if any extensions are used.
This is a **non-portable extension**.
**-v**, **-V**, **-\-version**
: Print the version information (copyright header) and exit.
: Print the version information (copyright header) and exits.
This is a **non-portable extension**.
@ -254,65 +350,6 @@ The following are the options that bc(1) accepts.
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.
If this option is given on the command-line (i.e., not in **BC_ENV_ARGS**,
see the **ENVIRONMENT VARIABLES** section), then after processing all
expressions and files, bc(1) will exit, unless **-** (**stdin**) was given
as an argument at least once to **-f** or **-\-file**, whether on the
command-line or in **BC_ENV_ARGS**. However, if any other **-e**,
**-\-expression**, **-f**, or **-\-file** arguments are given after **-f-**
or equivalent is given, bc(1) will give a fatal error and exit.
This is a **non-portable extension**.
**-f** *file*, **-\-file**=*file*
: Reads in *file* and evaluates it, line by line, as though it were read
through **stdin**. If expressions are also given (see above), the
expressions are evaluated in the order given.
If this option is given on the command-line (i.e., not in **BC_ENV_ARGS**,
see the **ENVIRONMENT VARIABLES** section), then after processing all
expressions and files, bc(1) will exit, unless **-** (**stdin**) was given
as an argument at least once to **-f** or **-\-file**. However, if any other
**-e**, **-\-expression**, **-f**, or **-\-file** arguments are given after
**-f-** or equivalent is given, bc(1) will give a fatal error and exit.
This is a **non-portable extension**.
**-I** *ibase*, **-\-ibase**=*ibase*
: Sets the builtin variable **ibase** to the value *ibase* assuming that
*ibase* is in base 10. It is a fatal error if *ibase* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-O** *obase*, **-\-obase**=*obase*
: Sets the builtin variable **obase** to the value *obase* assuming that
*obase* is in base 10. It is a fatal error if *obase* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-S** *scale*, **-\-scale**=*scale*
: Sets the builtin variable **scale** to the value *scale* assuming that
*scale* is in base 10. It is a fatal error if *scale* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
All long options are **non-portable extensions**.
# STDIN
@ -364,8 +401,7 @@ it is recommended that those scripts be changed to redirect **stderr** to
# SYNTAX
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
bc(1) follows the POSIX standard (see the **STANDARDS** 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.
@ -468,40 +504,48 @@ The following are valid operands in bc(1):
7. **scale(E)**: The *scale* of **E**.
8. **abs(E)**: The absolute value of **E**. This is a **non-portable
extension**.
9. **modexp(E, E, E)**: Modular exponentiation, where the first expression is
9. **is_number(E)**: **1** if the given argument is a number, **0** if it is a
string. This is a **non-portable extension**.
10. **is_string(E)**: **1** if the given argument is a string, **0** if it is a
number. This is a **non-portable extension**.
11. **modexp(E, E, E)**: Modular exponentiation, where the first expression is
the base, the second is the exponent, and the third is the modulus. All
three values must be integers. The second argument must be non-negative. The
third argument must be non-zero. This is a **non-portable extension**.
10. **divmod(E, E, I[])**: Division and modulus in one operation. This is for
11. **divmod(E, E, I[])**: Division and modulus in one operation. This is for
optimization. The first expression is the dividend, and the second is the
divisor, which must be non-zero. The return value is the quotient, and the
modulus is stored in index **0** of the provided array (the last argument).
This is a **non-portable extension**.
11. **asciify(E)**: If **E** is a string, returns a string that is the first
12. **asciify(E)**: If **E** is a string, returns a string that is the first
letter of its argument. If it is a number, calculates the number mod **256**
and returns that number as a one-character string. This is a **non-portable
extension**.
12. **I()**, **I(E)**, **I(E, E)**, and so on, where **I** is an identifier for
13. **asciify(I[])**: A string that is made up of the characters that would
result from running **asciify(E)** on each element of the array identified
by the argument. This allows creating multi-character strings and storing
them. This is a **non-portable extension**.
14. **I()**, **I(E)**, **I(E, E)**, and so on, where **I** is an identifier for
a non-**void** function (see the *Void Functions* subsection of the
**FUNCTIONS** section). The **E** argument(s) may also be arrays of the form
**I[]**, which will automatically be turned into array references (see the
*Array References* subsection of the **FUNCTIONS** section) if the
corresponding parameter in the function definition is an array reference.
13. **read()**: Reads a line from **stdin** and uses that as an expression. The
15. **read()**: Reads a line from **stdin** and uses that as an expression. The
result of that expression is the result of the **read()** operand. This is a
**non-portable extension**.
14. **maxibase()**: The max allowable **ibase**. This is a **non-portable
16. **maxibase()**: The max allowable **ibase**. This is a **non-portable
extension**.
15. **maxobase()**: The max allowable **obase**. This is a **non-portable
17. **maxobase()**: The max allowable **obase**. This is a **non-portable
extension**.
16. **maxscale()**: The max allowable **scale**. This is a **non-portable
18. **maxscale()**: The max allowable **scale**. This is a **non-portable
extension**.
17. **line_length()**: The line length set with **BC_LINE_LENGTH** (see the
19. **line_length()**: The line length set with **BC_LINE_LENGTH** (see the
**ENVIRONMENT VARIABLES** section). This is a **non-portable extension**.
18. **global_stacks()**: **0** if global stacks are not enabled with the **-g**
20. **global_stacks()**: **0** if global stacks are not enabled with the **-g**
or **-\-global-stacks** options, non-zero otherwise. See the **OPTIONS**
section. This is a **non-portable extension**.
19. **leading_zero()**: **0** if leading zeroes are not enabled with the **-z**
21. **leading_zero()**: **0** if leading zeroes are not enabled with the **-z**
or **--leading-zeroes** options, non-zero otherwise. See the **OPTIONS**
section. This is a **non-portable extension**.
@ -509,14 +553,40 @@ The following are valid operands in bc(1):
Numbers are strings made up of digits, uppercase letters, and at most **1**
period for a radix. Numbers can have up to **BC_NUM_MAX** digits. Uppercase
letters are equal to **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**.
letters are equal to **9** plus their position in the alphabet, starting from
**1** (i.e., **A** equals **10**, or **9+1**).
Single-character numbers (i.e., **A** alone) take the value that they would have
if they were valid digits, regardless of the value of **ibase**. This means that
**A** alone always equals decimal **10** and **Z** alone always equals decimal
**35**.
If a digit or letter makes no sense with the current value of **ibase** (i.e.,
they are greater than or equal to the current value of **ibase**), then the
behavior depends on the existence of the **-c**/**-\-digit-clamp** or
**-C**/**-\-no-digit-clamp** options (see the **OPTIONS** section), the
existence and setting of the **BC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section), or the default, which can be queried with
the **-h**/**-\-help** option.
If clamping is off, then digits or letters that are greater than or equal to the
current value of **ibase** are not changed. Instead, their given value is
multiplied by the appropriate power of **ibase** and added into the number. This
means that, with an **ibase** of **3**, the number **AB** is equal to
**3\^1\*A+3\^0\*B**, which is **3** times **10** plus **11**, or **41**.
If clamping is on, then digits or letters that are greater than or equal to the
current value of **ibase** are set to the value of the highest valid digit in
**ibase** before being multiplied by the appropriate power of **ibase** and
added into the number. This means that, with an **ibase** of **3**, the number
**AB** is equal to **3\^1\*2+3\^0\*2**, which is **3** times **2** plus **2**,
or **8**.
There is one exception to clamping: single-character numbers (i.e., **A**
alone). Such numbers are never clamped and always take the value they would have
in the highest possible **ibase**. This means that **A** alone always equals
decimal **10** and **Z** alone always equals decimal **35**. This behavior is
mandated by the standard (see the STANDARDS section) and is meant to provide an
easy way to set the current **ibase** (with the **i** command) regardless of the
current value of **ibase**.
If clamping is on, and the clamped value of a character is needed, use a leading
zero, i.e., for **A**, use **0A**.
## Operators
@ -683,10 +753,9 @@ The operators will be described in more detail below.
**assignment** operators, which means that **a=b\>c** is interpreted as
**(a=b)\>c**.
Also, unlike the standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html)
requires, these operators can appear anywhere any other expressions can be
used. This allowance is a **non-portable extension**.
Also, unlike the standard (see the **STANDARDS** section) requires, these
operators can appear anywhere any other expressions can be used. This
allowance is a **non-portable extension**.
**&&**
@ -750,6 +819,19 @@ The **if** **else** statement does the same thing as in C.
The **quit** statement causes bc(1) to quit, even if it is on a branch that will
not be executed (it is a compile-time command).
**Warning**: The behavior of this bc(1) on **quit** is slightly different from
other bc(1) implementations. Other bc(1) implementations will exit as soon as
they finish parsing the line that a **quit** command is on. This bc(1) will
execute any completed and executable statements that occur before the **quit**
statement before exiting.
In other words, for the bc(1) code below:
for (i = 0; i < 3; ++i) i; quit
Other bc(1) implementations will print nothing, and this bc(1) will print **0**,
**1**, and **2** on successive lines before exiting.
The **halt** statement causes bc(1) to quit, if it is executed. (Unlike **quit**
if it is on a branch of an **if** statement that is not executed, bc(1) does not
quit.)
@ -919,9 +1001,8 @@ command-line flags are given.
## Standard Library
The standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html) defines the
following functions for the math library:
The standard (see the **STANDARDS** section) defines the following functions for
the math library:
**s(x)**
@ -1093,7 +1174,8 @@ be hit.
# ENVIRONMENT VARIABLES
bc(1) recognizes the following environment variables:
As **non-portable extensions**, bc(1) recognizes the following environment
variables:
**POSIXLY_CORRECT**
@ -1199,6 +1281,21 @@ bc(1) recognizes the following environment variables:
This environment variable overrides the default, which can be queried with
the **-h** or **-\-help** options.
**BC_DIGIT_CLAMP**
: 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 **ibase** so that all such digits are considered equal
to the **ibase** 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 **ibase**.
This never applies to single-digit numbers, as per the standard (see the
**STANDARDS** section).
This environment variable overrides the default, which can be queried with
the **-h** or **-\-help** options.
# EXIT STATUS
bc(1) returns the following exit statuses:
@ -1272,12 +1369,10 @@ checking, and its normal behavior can be forced by using the **-i** flag or
# INTERACTIVE MODE
Per the standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html), bc(1) has
an interactive mode and a non-interactive mode. Interactive mode is turned on
automatically when both **stdin** and **stdout** are hooked to a terminal, but
the **-i** flag and **-\-interactive** option can turn it on in other
situations.
Per the standard (see the **STANDARDS** section), bc(1) has an interactive mode
and a non-interactive mode. Interactive mode is turned on automatically when
both **stdin** and **stdout** are hooked to a terminal, but the **-i** flag and
**-\-interactive** option can turn it on in other situations.
In interactive mode, bc(1) attempts to recover from errors (see the **RESET**
section), and in normal execution, flushes **stdout** as soon as execution is
@ -1303,10 +1398,8 @@ setting is used. The default setting can be queried with the **-h** or
**-\-help** options.
TTY mode is different from interactive mode because interactive mode is required
in the bc(1) standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html), and
interactive mode requires only **stdin** and **stdout** to be connected to a
terminal.
in the bc(1) standard (see the **STANDARDS** section), and interactive mode
requires only **stdin** and **stdout** to be connected to a terminal.
## Command-Line History
@ -1392,13 +1485,20 @@ at https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html . The
flags **-efghiqsvVw**, all long options, and the extensions noted above are
extensions to that specification.
In addition, the behavior of the **quit** implements an interpretation of that
specification that is different from all known implementations. For more
information see the **Statements** subsection of the **SYNTAX** section.
Note that the specification explicitly says that bc(1) only accepts numbers that
use a period (**.**) as a radix point, regardless of the value of
**LC_NUMERIC**.
# BUGS
None are known. Report bugs at https://git.yzena.com/gavin/bc.
Before version **6.1.0**, this bc(1) had incorrect behavior for the **quit**
statement.
No other bugs are known. Report bugs at https://git.yzena.com/gavin/bc .
# AUTHORS

459
contrib/bc/manuals/bc/H.1
View File

@ -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,7 +25,7 @@
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.TH "BC" "1" "June 2022" "Gavin D. Howard" "General Commands Manual"
.TH "BC" "1" "October 2022" "Gavin D. Howard" "General Commands Manual"
.nh
.ad l
.SH NAME
@ -33,24 +33,25 @@
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[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]--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 at
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.
@ -79,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.
@ -172,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.
@ -202,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
@ -217,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
@ -294,38 +431,32 @@ 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
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html).
(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
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.
\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].
@ -351,93 +482,6 @@ extended math library (see the \f[B]LIBRARY\f[R] section).
.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]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.
.PP
This is a \f[B]non-portable extension\f[R].
.RE
.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]-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]-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]-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
.PP
All long options are \f[B]non-portable extensions\f[R].
.SH STDIN
@ -491,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
@ -668,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.
@ -675,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,
@ -683,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).
@ -698,44 +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 "18." 4
.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 "19." 4
.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 "20." 4
.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 "21." 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
@ -753,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 "22." 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
@ -776,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].
@ -1076,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].
@ -1109,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
@ -1136,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
@ -1171,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.)
@ -1384,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.
@ -1441,8 +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
@ -2501,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
@ -2621,6 +2729,22 @@ expressions and expression files, and a zero value makes bc(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
.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:
@ -2702,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.
@ -2736,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) standard
(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
@ -2808,6 +2930,12 @@ 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].
@ -2816,8 +2944,11 @@ 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.yzena.com/gavin/bc .
.SH AUTHORS
.PP
Gavin D.

370
contrib/bc/manuals/bc/H.1.md
View File

@ -2,7 +2,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:
@ -34,15 +34,14 @@ bc - arbitrary-precision decimal arithmetic language and calculator
# SYNOPSIS
**bc** [**-ghilPqRsvVw**] [**-\-global-stacks**] [**-\-help**] [**-\-interactive**] [**-\-mathlib**] [**-\-no-prompt**] [**-\-no-read-prompt**] [**-\-quiet**] [**-\-standard**] [**-\-warn**] [**-\-version**] [**-e** *expr*] [**-\-expression**=*expr*...] [**-f** *file*...] [**-\-file**=*file*...] [*file*...] [**-I** *ibase*] [**-\-ibase**=*ibase*] [**-O** *obase*] [**-\-obase**=*obase*] [**-S** *scale*] [**-\-scale**=*scale*] [**-E** *seed*] [**-\-seed**=*seed*]
**bc** [**-cCghilPqRsvVw**] [**-\-digit-clamp**] [**-\-no-digit-clamp**] [**-\-global-stacks**] [**-\-help**] [**-\-interactive**] [**-\-mathlib**] [**-\-no-prompt**] [**-\-no-read-prompt**] [**-\-quiet**] [**-\-standard**] [**-\-warn**] [**-\-version**] [**-e** *expr*] [**-\-expression**=*expr*...] [**-f** *file*...] [**-\-file**=*file*...] [*file*...] [**-I** *ibase*] [**-\-ibase**=*ibase*] [**-O** *obase*] [**-\-obase**=*obase*] [**-S** *scale*] [**-\-scale**=*scale*] [**-E** *seed*] [**-\-seed**=*seed*]
# DESCRIPTION
bc(1) is an interactive processor for a language first standardized in 1991 by
POSIX. (The current standard is at
https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html .) The
language provides unlimited precision decimal arithmetic and is somewhat C-like,
but there are differences. Such differences will be noted in this document.
POSIX. (See the **STANDARDS** 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.
After parsing and handling options, this bc(1) reads any files given on the
command line and executes them before reading from **stdin**.
@ -64,6 +63,86 @@ that is a bug and should be reported. See the **BUGS** section.
The following are the options that bc(1) accepts.
**-C**, **-\-no-digit-clamp**
: Disables clamping of digits greater than or equal to the current **ibase**
when parsing numbers.
This means that the value added to a number from a digit is always that
digit's value multiplied by the value of ibase raised to the power of the
digit's position, which starts from 0 at the least significant digit.
If this and/or the **-c** or **-\-digit-clamp** options are given multiple
times, the last one given is used.
This option overrides the **BC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section) and the default, which can be queried
with the **-h** or **-\-help** options.
This is a **non-portable extension**.
**-c**, **-\-digit-clamp**
: Enables clamping of digits greater than or equal to the current **ibase**
when parsing numbers.
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's
position, which starts from 0 at the least significant digit.
If this and/or the **-C** or **-\-no-digit-clamp** options are given
multiple times, the last one given is used.
This option overrides the **BC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section) and the default, which can be queried
with the **-h** or **-\-help** options.
This is a **non-portable extension**.
**-E** *seed*, **-\-seed**=*seed*
: Sets the builtin variable **seed** to the value *seed* assuming that *seed*
is in base 10. It is a fatal error if *seed* is not a valid number.
If multiple instances of this option are given, the last is used.
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 the **-f** and **-\-file** 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.
If this option is given on the command-line (i.e., not in **BC_ENV_ARGS**,
see the **ENVIRONMENT VARIABLES** section), then after processing all
expressions and files, bc(1) will exit, unless **-** (**stdin**) was given
as an argument at least once to **-f** or **-\-file**, whether on the
command-line or in **BC_ENV_ARGS**. However, if any other **-e**,
**-\-expression**, **-f**, or **-\-file** arguments are given after **-f-**
or equivalent is given, bc(1) will give a fatal error and exit.
This is a **non-portable extension**.
**-f** *file*, **-\-file**=*file*
: Reads in *file* and evaluates it, line by line, as though it were read
through **stdin**. If expressions are also given (see the **-e** and
**-\-expression** options), the expressions are evaluated in the order
given.
If this option is given on the command-line (i.e., not in **BC_ENV_ARGS**,
see the **ENVIRONMENT VARIABLES** section), then after processing all
expressions and files, bc(1) will exit, unless **-** (**stdin**) was given
as an argument at least once to **-f** or **-\-file**. However, if any other
**-e**, **-\-expression**, **-f**, or **-\-file** arguments are given after
**-f-** or equivalent is given, bc(1) will give a fatal error and exit.
This is a **non-portable extension**.
**-g**, **-\-global-stacks**
: Turns the globals **ibase**, **obase**, **scale**, and **seed** into stacks.
@ -134,7 +213,16 @@ The following are the options that bc(1) accepts.
**-h**, **-\-help**
: Prints a usage message and quits.
: Prints a usage message and exits.
**-I** *ibase*, **-\-ibase**=*ibase*
: Sets the builtin variable **ibase** to the value *ibase* assuming that
*ibase* is in base 10. It is a fatal error if *ibase* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-i**, **-\-interactive**
@ -158,6 +246,15 @@ The following are the options that bc(1) accepts.
To learn what is in the libraries, see the **LIBRARY** section.
**-O** *obase*, **-\-obase**=*obase*
: Sets the builtin variable **obase** to the value *obase* assuming that
*obase* is in base 10. It is a fatal error if *obase* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-P**, **-\-no-prompt**
: Disables the prompt in TTY mode. (The prompt is only enabled in TTY mode.
@ -171,6 +268,19 @@ The following are the options that bc(1) accepts.
This is a **non-portable extension**.
**-q**, **-\-quiet**
: 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 **-v**, **-V**, or **-\-version** options are given
unless the **BC_BANNER** environment variable is set and contains a non-zero
integer or if this bc(1) was built with the header displayed by default. If
*any* of that is the case, then this option *does* prevent bc(1) from
printing the header.
This is a **non-portable extension**.
**-R**, **-\-no-read-prompt**
: Disables the read prompt in TTY mode. (The read prompt is only enabled in
@ -224,35 +334,29 @@ The following are the options that bc(1) accepts.
Keywords are *not* redefined when parsing the builtin math library (see the
**LIBRARY** section).
It is a fatal error to redefine keywords mandated by the POSIX standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html). It is
a fatal error to attempt to redefine words that this bc(1) does not reserve
as keywords.
It is a fatal error to redefine keywords mandated by the POSIX standard (see
the **STANDARDS** section). It is a fatal error to attempt to redefine words
that this bc(1) does not reserve as keywords.
**-q**, **-\-quiet**
**-S** *scale*, **-\-scale**=*scale*
: 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 **-v**, **-V**, or **-\-version** options are given
unless the **BC_BANNER** environment variable is set and contains a non-zero
integer or if this bc(1) was built with the header displayed by default. If
*any* of that is the case, then this option *does* prevent bc(1) from
printing the header.
: Sets the builtin variable **scale** to the value *scale* assuming that
*scale* is in base 10. It is a fatal error if *scale* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-s**, **-\-standard**
: 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 **STANDARDS**
section) and error if any extensions are used.
This is a **non-portable extension**.
**-v**, **-V**, **-\-version**
: Print the version information (copyright header) and exit.
: Print the version information (copyright header) and exits.
This is a **non-portable extension**.
@ -274,74 +378,6 @@ The following are the options that bc(1) accepts.
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.
If this option is given on the command-line (i.e., not in **BC_ENV_ARGS**,
see the **ENVIRONMENT VARIABLES** section), then after processing all
expressions and files, bc(1) will exit, unless **-** (**stdin**) was given
as an argument at least once to **-f** or **-\-file**, whether on the
command-line or in **BC_ENV_ARGS**. However, if any other **-e**,
**-\-expression**, **-f**, or **-\-file** arguments are given after **-f-**
or equivalent is given, bc(1) will give a fatal error and exit.
This is a **non-portable extension**.
**-f** *file*, **-\-file**=*file*
: Reads in *file* and evaluates it, line by line, as though it were read
through **stdin**. If expressions are also given (see above), the
expressions are evaluated in the order given.
If this option is given on the command-line (i.e., not in **BC_ENV_ARGS**,
see the **ENVIRONMENT VARIABLES** section), then after processing all
expressions and files, bc(1) will exit, unless **-** (**stdin**) was given
as an argument at least once to **-f** or **-\-file**. However, if any other
**-e**, **-\-expression**, **-f**, or **-\-file** arguments are given after
**-f-** or equivalent is given, bc(1) will give a fatal error and exit.
This is a **non-portable extension**.
**-I** *ibase*, **-\-ibase**=*ibase*
: Sets the builtin variable **ibase** to the value *ibase* assuming that
*ibase* is in base 10. It is a fatal error if *ibase* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-O** *obase*, **-\-obase**=*obase*
: Sets the builtin variable **obase** to the value *obase* assuming that
*obase* is in base 10. It is a fatal error if *obase* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-S** *scale*, **-\-scale**=*scale*
: Sets the builtin variable **scale** to the value *scale* assuming that
*scale* is in base 10. It is a fatal error if *scale* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-E** *seed*, **-\-seed**=*seed*
: Sets the builtin variable **seed** to the value *seed* assuming that *seed*
is in base 10. It is a fatal error if *seed* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
All long options are **non-portable extensions**.
# STDIN
@ -393,8 +429,7 @@ it is recommended that those scripts be changed to redirect **stderr** to
# SYNTAX
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
bc(1) follows the POSIX standard (see the **STANDARDS** 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.
@ -523,46 +558,54 @@ The following are valid operands in bc(1):
7. **scale(E)**: The *scale* of **E**.
8. **abs(E)**: The absolute value of **E**. This is a **non-portable
extension**.
9. **modexp(E, E, E)**: Modular exponentiation, where the first expression is
9. **is_number(E)**: **1** if the given argument is a number, **0** if it is a
string. This is a **non-portable extension**.
10. **is_string(E)**: **1** if the given argument is a string, **0** if it is a
number. This is a **non-portable extension**.
11. **modexp(E, E, E)**: Modular exponentiation, where the first expression is
the base, the second is the exponent, and the third is the modulus. All
three values must be integers. The second argument must be non-negative. The
third argument must be non-zero. This is a **non-portable extension**.
10. **divmod(E, E, I[])**: Division and modulus in one operation. This is for
11. **divmod(E, E, I[])**: Division and modulus in one operation. This is for
optimization. The first expression is the dividend, and the second is the
divisor, which must be non-zero. The return value is the quotient, and the
modulus is stored in index **0** of the provided array (the last argument).
This is a **non-portable extension**.
11. **asciify(E)**: If **E** is a string, returns a string that is the first
12. **asciify(E)**: If **E** is a string, returns a string that is the first
letter of its argument. If it is a number, calculates the number mod **256**
and returns that number as a one-character string. This is a **non-portable
extension**.
12. **I()**, **I(E)**, **I(E, E)**, and so on, where **I** is an identifier for
13. **asciify(I[])**: A string that is made up of the characters that would
result from running **asciify(E)** on each element of the array identified
by the argument. This allows creating multi-character strings and storing
them. This is a **non-portable extension**.
14. **I()**, **I(E)**, **I(E, E)**, and so on, where **I** is an identifier for
a non-**void** function (see the *Void Functions* subsection of the
**FUNCTIONS** section). The **E** argument(s) may also be arrays of the form
**I[]**, which will automatically be turned into array references (see the
*Array References* subsection of the **FUNCTIONS** section) if the
corresponding parameter in the function definition is an array reference.
13. **read()**: Reads a line from **stdin** and uses that as an expression. The
15. **read()**: Reads a line from **stdin** and uses that as an expression. The
result of that expression is the result of the **read()** operand. This is a
**non-portable extension**.
14. **maxibase()**: The max allowable **ibase**. This is a **non-portable
16. **maxibase()**: The max allowable **ibase**. This is a **non-portable
extension**.
15. **maxobase()**: The max allowable **obase**. This is a **non-portable
17. **maxobase()**: The max allowable **obase**. This is a **non-portable
extension**.
16. **maxscale()**: The max allowable **scale**. This is a **non-portable
18. **maxscale()**: The max allowable **scale**. This is a **non-portable
extension**.
17. **line_length()**: The line length set with **BC_LINE_LENGTH** (see the
19. **line_length()**: The line length set with **BC_LINE_LENGTH** (see the
**ENVIRONMENT VARIABLES** section). This is a **non-portable extension**.
18. **global_stacks()**: **0** if global stacks are not enabled with the **-g**
20. **global_stacks()**: **0** if global stacks are not enabled with the **-g**
or **-\-global-stacks** options, non-zero otherwise. See the **OPTIONS**
section. This is a **non-portable extension**.
19. **leading_zero()**: **0** if leading zeroes are not enabled with the **-z**
21. **leading_zero()**: **0** if leading zeroes are not enabled with the **-z**
or **--leading-zeroes** options, non-zero otherwise. See the **OPTIONS**
section. This is a **non-portable extension**.
20. **rand()**: A pseudo-random integer between **0** (inclusive) and
22. **rand()**: A pseudo-random integer between **0** (inclusive) and
**BC_RAND_MAX** (inclusive). Using this operand will change the value of
**seed**. This is a **non-portable extension**.
21. **irand(E)**: A pseudo-random integer between **0** (inclusive) and the
23. **irand(E)**: A pseudo-random integer between **0** (inclusive) and the
value of **E** (exclusive). If **E** is negative or is a non-integer
(**E**'s *scale* is not **0**), an error is raised, and bc(1) resets (see
the **RESET** section) while **seed** remains unchanged. If **E** is larger
@ -573,7 +616,7 @@ The following are valid operands in bc(1):
change the value of **seed**, unless the value of **E** is **0** or **1**.
In that case, **0** is returned, and **seed** is *not* changed. This is a
**non-portable extension**.
22. **maxrand()**: The max integer returned by **rand()**. This is a
24. **maxrand()**: The max integer returned by **rand()**. This is a
**non-portable extension**.
The integers generated by **rand()** and **irand(E)** are guaranteed to be as
@ -592,14 +635,40 @@ use a non-seeded pseudo-random number generator.
Numbers are strings made up of digits, uppercase letters, and at most **1**
period for a radix. Numbers can have up to **BC_NUM_MAX** digits. Uppercase
letters are equal to **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**.
letters are equal to **9** plus their position in the alphabet, starting from
**1** (i.e., **A** equals **10**, or **9+1**).
Single-character numbers (i.e., **A** alone) take the value that they would have
if they were valid digits, regardless of the value of **ibase**. This means that
**A** alone always equals decimal **10** and **Z** alone always equals decimal
**35**.
If a digit or letter makes no sense with the current value of **ibase** (i.e.,
they are greater than or equal to the current value of **ibase**), then the
behavior depends on the existence of the **-c**/**-\-digit-clamp** or
**-C**/**-\-no-digit-clamp** options (see the **OPTIONS** section), the
existence and setting of the **BC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section), or the default, which can be queried with
the **-h**/**-\-help** option.
If clamping is off, then digits or letters that are greater than or equal to the
current value of **ibase** are not changed. Instead, their given value is
multiplied by the appropriate power of **ibase** and added into the number. This
means that, with an **ibase** of **3**, the number **AB** is equal to
**3\^1\*A+3\^0\*B**, which is **3** times **10** plus **11**, or **41**.
If clamping is on, then digits or letters that are greater than or equal to the
current value of **ibase** are set to the value of the highest valid digit in
**ibase** before being multiplied by the appropriate power of **ibase** and
added into the number. This means that, with an **ibase** of **3**, the number
**AB** is equal to **3\^1\*2+3\^0\*2**, which is **3** times **2** plus **2**,
or **8**.
There is one exception to clamping: single-character numbers (i.e., **A**
alone). Such numbers are never clamped and always take the value they would have
in the highest possible **ibase**. This means that **A** alone always equals
decimal **10** and **Z** alone always equals decimal **35**. This behavior is
mandated by the standard (see the STANDARDS section) and is meant to provide an
easy way to set the current **ibase** (with the **i** command) regardless of the
current value of **ibase**.
If clamping is on, and the clamped value of a character is needed, use a leading
zero, i.e., for **A**, use **0A**.
In addition, bc(1) accepts numbers in scientific notation. These have the form
**\<number\>e\<integer\>**. The exponent (the portion after the **e**) must be
@ -849,10 +918,9 @@ The operators will be described in more detail below.
**assignment** operators, which means that **a=b\>c** is interpreted as
**(a=b)\>c**.
Also, unlike the standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html)
requires, these operators can appear anywhere any other expressions can be
used. This allowance is a **non-portable extension**.
Also, unlike the standard (see the **STANDARDS** section) requires, these
operators can appear anywhere any other expressions can be used. This
allowance is a **non-portable extension**.
**&&**
@ -916,6 +984,19 @@ The **if** **else** statement does the same thing as in C.
The **quit** statement causes bc(1) to quit, even if it is on a branch that will
not be executed (it is a compile-time command).
**Warning**: The behavior of this bc(1) on **quit** is slightly different from
other bc(1) implementations. Other bc(1) implementations will exit as soon as
they finish parsing the line that a **quit** command is on. This bc(1) will
execute any completed and executable statements that occur before the **quit**
statement before exiting.
In other words, for the bc(1) code below:
for (i = 0; i < 3; ++i) i; quit
Other bc(1) implementations will print nothing, and this bc(1) will print **0**,
**1**, and **2** on successive lines before exiting.
The **halt** statement causes bc(1) to quit, if it is executed. (Unlike **quit**
if it is on a branch of an **if** statement that is not executed, bc(1) does not
quit.)
@ -1099,9 +1180,8 @@ equivalents are given.
## Standard Library
The standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html) defines the
following functions for the math library:
The standard (see the **STANDARDS** section) defines the following functions for
the math library:
**s(x)**
@ -1149,8 +1229,7 @@ following functions for the math library:
The extended library is *not* loaded when the **-s**/**-\-standard** or
**-w**/**-\-warn** options are given since they are not part of the library
defined by the standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html).
defined by the standard (see the **STANDARDS** section).
The extended library is a **non-portable extension**.
@ -2085,7 +2164,8 @@ be hit.
# ENVIRONMENT VARIABLES
bc(1) recognizes the following environment variables:
As **non-portable extensions**, bc(1) recognizes the following environment
variables:
**POSIXLY_CORRECT**
@ -2191,6 +2271,21 @@ bc(1) recognizes the following environment variables:
This environment variable overrides the default, which can be queried with
the **-h** or **-\-help** options.
**BC_DIGIT_CLAMP**
: 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 **ibase** so that all such digits are considered equal
to the **ibase** 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 **ibase**.
This never applies to single-digit numbers, as per the standard (see the
**STANDARDS** section).
This environment variable overrides the default, which can be queried with
the **-h** or **-\-help** options.
# EXIT STATUS
bc(1) returns the following exit statuses:
@ -2266,12 +2361,10 @@ checking, and its normal behavior can be forced by using the **-i** flag or
# INTERACTIVE MODE
Per the standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html), bc(1) has
an interactive mode and a non-interactive mode. Interactive mode is turned on
automatically when both **stdin** and **stdout** are hooked to a terminal, but
the **-i** flag and **-\-interactive** option can turn it on in other
situations.
Per the standard (see the **STANDARDS** section), bc(1) has an interactive mode
and a non-interactive mode. Interactive mode is turned on automatically when
both **stdin** and **stdout** are hooked to a terminal, but the **-i** flag and
**-\-interactive** option can turn it on in other situations.
In interactive mode, bc(1) attempts to recover from errors (see the **RESET**
section), and in normal execution, flushes **stdout** as soon as execution is
@ -2297,10 +2390,8 @@ setting is used. The default setting can be queried with the **-h** or
**-\-help** options.
TTY mode is different from interactive mode because interactive mode is required
in the bc(1) standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html), and
interactive mode requires only **stdin** and **stdout** to be connected to a
terminal.
in the bc(1) standard (see the **STANDARDS** section), and interactive mode
requires only **stdin** and **stdout** to be connected to a terminal.
## Prompt
@ -2365,6 +2456,10 @@ at https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html . The
flags **-efghiqsvVw**, all long options, and the extensions noted above are
extensions to that specification.
In addition, the behavior of the **quit** implements an interpretation of that
specification that is different from all known implementations. For more
information see the **Statements** subsection of the **SYNTAX** section.
Note that the specification explicitly says that bc(1) only accepts numbers that
use a period (**.**) as a radix point, regardless of the value of
**LC_NUMERIC**.
@ -2374,7 +2469,10 @@ This bc(1) supports error messages for different locales, and thus, it supports
# BUGS
None are known. Report bugs at https://git.yzena.com/gavin/bc.
Before version **6.1.0**, this bc(1) had incorrect behavior for the **quit**
statement.
No other bugs are known. Report bugs at https://git.yzena.com/gavin/bc .
# AUTHORS

459
contrib/bc/manuals/bc/HN.1
View File

@ -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,7 +25,7 @@
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.TH "BC" "1" "June 2022" "Gavin D. Howard" "General Commands Manual"
.TH "BC" "1" "October 2022" "Gavin D. Howard" "General Commands Manual"
.nh
.ad l
.SH NAME
@ -33,24 +33,25 @@
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[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]--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 at
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.
@ -79,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.
@ -172,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.
@ -202,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
@ -217,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
@ -294,38 +431,32 @@ 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
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html).
(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
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.
\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].
@ -351,93 +482,6 @@ extended math library (see the \f[B]LIBRARY\f[R] section).
.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]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.
.PP
This is a \f[B]non-portable extension\f[R].
.RE
.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]-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]-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]-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
.PP
All long options are \f[B]non-portable extensions\f[R].
.SH STDIN
@ -491,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
@ -668,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.
@ -675,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,
@ -683,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).
@ -698,44 +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 "18." 4
.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 "19." 4
.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 "20." 4
.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 "21." 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
@ -753,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 "22." 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
@ -776,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].
@ -1076,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].
@ -1109,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
@ -1136,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
@ -1171,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.)
@ -1384,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.
@ -1441,8 +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
@ -2501,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
@ -2621,6 +2729,22 @@ expressions and expression files, and a zero value makes bc(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
.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:
@ -2702,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.
@ -2736,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) standard
(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
@ -2804,13 +2926,22 @@ 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].
.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.yzena.com/gavin/bc .
.SH AUTHORS
.PP
Gavin D.

370
contrib/bc/manuals/bc/HN.1.md
View File

@ -2,7 +2,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:
@ -34,15 +34,14 @@ bc - arbitrary-precision decimal arithmetic language and calculator
# SYNOPSIS
**bc** [**-ghilPqRsvVw**] [**-\-global-stacks**] [**-\-help**] [**-\-interactive**] [**-\-mathlib**] [**-\-no-prompt**] [**-\-no-read-prompt**] [**-\-quiet**] [**-\-standard**] [**-\-warn**] [**-\-version**] [**-e** *expr*] [**-\-expression**=*expr*...] [**-f** *file*...] [**-\-file**=*file*...] [*file*...] [**-I** *ibase*] [**-\-ibase**=*ibase*] [**-O** *obase*] [**-\-obase**=*obase*] [**-S** *scale*] [**-\-scale**=*scale*] [**-E** *seed*] [**-\-seed**=*seed*]
**bc** [**-cCghilPqRsvVw**] [**-\-digit-clamp**] [**-\-no-digit-clamp**] [**-\-global-stacks**] [**-\-help**] [**-\-interactive**] [**-\-mathlib**] [**-\-no-prompt**] [**-\-no-read-prompt**] [**-\-quiet**] [**-\-standard**] [**-\-warn**] [**-\-version**] [**-e** *expr*] [**-\-expression**=*expr*...] [**-f** *file*...] [**-\-file**=*file*...] [*file*...] [**-I** *ibase*] [**-\-ibase**=*ibase*] [**-O** *obase*] [**-\-obase**=*obase*] [**-S** *scale*] [**-\-scale**=*scale*] [**-E** *seed*] [**-\-seed**=*seed*]
# DESCRIPTION
bc(1) is an interactive processor for a language first standardized in 1991 by
POSIX. (The current standard is at
https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html .) The
language provides unlimited precision decimal arithmetic and is somewhat C-like,
but there are differences. Such differences will be noted in this document.
POSIX. (See the **STANDARDS** 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.
After parsing and handling options, this bc(1) reads any files given on the
command line and executes them before reading from **stdin**.
@ -64,6 +63,86 @@ that is a bug and should be reported. See the **BUGS** section.
The following are the options that bc(1) accepts.
**-C**, **-\-no-digit-clamp**
: Disables clamping of digits greater than or equal to the current **ibase**
when parsing numbers.
This means that the value added to a number from a digit is always that
digit's value multiplied by the value of ibase raised to the power of the
digit's position, which starts from 0 at the least significant digit.
If this and/or the **-c** or **-\-digit-clamp** options are given multiple
times, the last one given is used.
This option overrides the **BC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section) and the default, which can be queried
with the **-h** or **-\-help** options.
This is a **non-portable extension**.
**-c**, **-\-digit-clamp**
: Enables clamping of digits greater than or equal to the current **ibase**
when parsing numbers.
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's
position, which starts from 0 at the least significant digit.
If this and/or the **-C** or **-\-no-digit-clamp** options are given
multiple times, the last one given is used.
This option overrides the **BC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section) and the default, which can be queried
with the **-h** or **-\-help** options.
This is a **non-portable extension**.
**-E** *seed*, **-\-seed**=*seed*
: Sets the builtin variable **seed** to the value *seed* assuming that *seed*
is in base 10. It is a fatal error if *seed* is not a valid number.
If multiple instances of this option are given, the last is used.
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 the **-f** and **-\-file** 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.
If this option is given on the command-line (i.e., not in **BC_ENV_ARGS**,
see the **ENVIRONMENT VARIABLES** section), then after processing all
expressions and files, bc(1) will exit, unless **-** (**stdin**) was given
as an argument at least once to **-f** or **-\-file**, whether on the
command-line or in **BC_ENV_ARGS**. However, if any other **-e**,
**-\-expression**, **-f**, or **-\-file** arguments are given after **-f-**
or equivalent is given, bc(1) will give a fatal error and exit.
This is a **non-portable extension**.
**-f** *file*, **-\-file**=*file*
: Reads in *file* and evaluates it, line by line, as though it were read
through **stdin**. If expressions are also given (see the **-e** and
**-\-expression** options), the expressions are evaluated in the order
given.
If this option is given on the command-line (i.e., not in **BC_ENV_ARGS**,
see the **ENVIRONMENT VARIABLES** section), then after processing all
expressions and files, bc(1) will exit, unless **-** (**stdin**) was given
as an argument at least once to **-f** or **-\-file**. However, if any other
**-e**, **-\-expression**, **-f**, or **-\-file** arguments are given after
**-f-** or equivalent is given, bc(1) will give a fatal error and exit.
This is a **non-portable extension**.
**-g**, **-\-global-stacks**
: Turns the globals **ibase**, **obase**, **scale**, and **seed** into stacks.
@ -134,7 +213,16 @@ The following are the options that bc(1) accepts.
**-h**, **-\-help**
: Prints a usage message and quits.
: Prints a usage message and exits.
**-I** *ibase*, **-\-ibase**=*ibase*
: Sets the builtin variable **ibase** to the value *ibase* assuming that
*ibase* is in base 10. It is a fatal error if *ibase* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-i**, **-\-interactive**
@ -158,6 +246,15 @@ The following are the options that bc(1) accepts.
To learn what is in the libraries, see the **LIBRARY** section.
**-O** *obase*, **-\-obase**=*obase*
: Sets the builtin variable **obase** to the value *obase* assuming that
*obase* is in base 10. It is a fatal error if *obase* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-P**, **-\-no-prompt**
: Disables the prompt in TTY mode. (The prompt is only enabled in TTY mode.
@ -171,6 +268,19 @@ The following are the options that bc(1) accepts.
This is a **non-portable extension**.
**-q**, **-\-quiet**
: 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 **-v**, **-V**, or **-\-version** options are given
unless the **BC_BANNER** environment variable is set and contains a non-zero
integer or if this bc(1) was built with the header displayed by default. If
*any* of that is the case, then this option *does* prevent bc(1) from
printing the header.
This is a **non-portable extension**.
**-R**, **-\-no-read-prompt**
: Disables the read prompt in TTY mode. (The read prompt is only enabled in
@ -224,35 +334,29 @@ The following are the options that bc(1) accepts.
Keywords are *not* redefined when parsing the builtin math library (see the
**LIBRARY** section).
It is a fatal error to redefine keywords mandated by the POSIX standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html). It is
a fatal error to attempt to redefine words that this bc(1) does not reserve
as keywords.
It is a fatal error to redefine keywords mandated by the POSIX standard (see
the **STANDARDS** section). It is a fatal error to attempt to redefine words
that this bc(1) does not reserve as keywords.
**-q**, **-\-quiet**
**-S** *scale*, **-\-scale**=*scale*
: 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 **-v**, **-V**, or **-\-version** options are given
unless the **BC_BANNER** environment variable is set and contains a non-zero
integer or if this bc(1) was built with the header displayed by default. If
*any* of that is the case, then this option *does* prevent bc(1) from
printing the header.
: Sets the builtin variable **scale** to the value *scale* assuming that
*scale* is in base 10. It is a fatal error if *scale* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-s**, **-\-standard**
: 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 **STANDARDS**
section) and error if any extensions are used.
This is a **non-portable extension**.
**-v**, **-V**, **-\-version**
: Print the version information (copyright header) and exit.
: Print the version information (copyright header) and exits.
This is a **non-portable extension**.
@ -274,74 +378,6 @@ The following are the options that bc(1) accepts.
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.
If this option is given on the command-line (i.e., not in **BC_ENV_ARGS**,
see the **ENVIRONMENT VARIABLES** section), then after processing all
expressions and files, bc(1) will exit, unless **-** (**stdin**) was given
as an argument at least once to **-f** or **-\-file**, whether on the
command-line or in **BC_ENV_ARGS**. However, if any other **-e**,
**-\-expression**, **-f**, or **-\-file** arguments are given after **-f-**
or equivalent is given, bc(1) will give a fatal error and exit.
This is a **non-portable extension**.
**-f** *file*, **-\-file**=*file*
: Reads in *file* and evaluates it, line by line, as though it were read
through **stdin**. If expressions are also given (see above), the
expressions are evaluated in the order given.
If this option is given on the command-line (i.e., not in **BC_ENV_ARGS**,
see the **ENVIRONMENT VARIABLES** section), then after processing all
expressions and files, bc(1) will exit, unless **-** (**stdin**) was given
as an argument at least once to **-f** or **-\-file**. However, if any other
**-e**, **-\-expression**, **-f**, or **-\-file** arguments are given after
**-f-** or equivalent is given, bc(1) will give a fatal error and exit.
This is a **non-portable extension**.
**-I** *ibase*, **-\-ibase**=*ibase*
: Sets the builtin variable **ibase** to the value *ibase* assuming that
*ibase* is in base 10. It is a fatal error if *ibase* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-O** *obase*, **-\-obase**=*obase*
: Sets the builtin variable **obase** to the value *obase* assuming that
*obase* is in base 10. It is a fatal error if *obase* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-S** *scale*, **-\-scale**=*scale*
: Sets the builtin variable **scale** to the value *scale* assuming that
*scale* is in base 10. It is a fatal error if *scale* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-E** *seed*, **-\-seed**=*seed*
: Sets the builtin variable **seed** to the value *seed* assuming that *seed*
is in base 10. It is a fatal error if *seed* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
All long options are **non-portable extensions**.
# STDIN
@ -393,8 +429,7 @@ it is recommended that those scripts be changed to redirect **stderr** to
# SYNTAX
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
bc(1) follows the POSIX standard (see the **STANDARDS** 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.
@ -523,46 +558,54 @@ The following are valid operands in bc(1):
7. **scale(E)**: The *scale* of **E**.
8. **abs(E)**: The absolute value of **E**. This is a **non-portable
extension**.
9. **modexp(E, E, E)**: Modular exponentiation, where the first expression is
9. **is_number(E)**: **1** if the given argument is a number, **0** if it is a
string. This is a **non-portable extension**.
10. **is_string(E)**: **1** if the given argument is a string, **0** if it is a
number. This is a **non-portable extension**.
11. **modexp(E, E, E)**: Modular exponentiation, where the first expression is
the base, the second is the exponent, and the third is the modulus. All
three values must be integers. The second argument must be non-negative. The
third argument must be non-zero. This is a **non-portable extension**.
10. **divmod(E, E, I[])**: Division and modulus in one operation. This is for
11. **divmod(E, E, I[])**: Division and modulus in one operation. This is for
optimization. The first expression is the dividend, and the second is the
divisor, which must be non-zero. The return value is the quotient, and the
modulus is stored in index **0** of the provided array (the last argument).
This is a **non-portable extension**.
11. **asciify(E)**: If **E** is a string, returns a string that is the first
12. **asciify(E)**: If **E** is a string, returns a string that is the first
letter of its argument. If it is a number, calculates the number mod **256**
and returns that number as a one-character string. This is a **non-portable
extension**.
12. **I()**, **I(E)**, **I(E, E)**, and so on, where **I** is an identifier for
13. **asciify(I[])**: A string that is made up of the characters that would
result from running **asciify(E)** on each element of the array identified
by the argument. This allows creating multi-character strings and storing
them. This is a **non-portable extension**.
14. **I()**, **I(E)**, **I(E, E)**, and so on, where **I** is an identifier for
a non-**void** function (see the *Void Functions* subsection of the
**FUNCTIONS** section). The **E** argument(s) may also be arrays of the form
**I[]**, which will automatically be turned into array references (see the
*Array References* subsection of the **FUNCTIONS** section) if the
corresponding parameter in the function definition is an array reference.
13. **read()**: Reads a line from **stdin** and uses that as an expression. The
15. **read()**: Reads a line from **stdin** and uses that as an expression. The
result of that expression is the result of the **read()** operand. This is a
**non-portable extension**.
14. **maxibase()**: The max allowable **ibase**. This is a **non-portable
16. **maxibase()**: The max allowable **ibase**. This is a **non-portable
extension**.
15. **maxobase()**: The max allowable **obase**. This is a **non-portable
17. **maxobase()**: The max allowable **obase**. This is a **non-portable
extension**.
16. **maxscale()**: The max allowable **scale**. This is a **non-portable
18. **maxscale()**: The max allowable **scale**. This is a **non-portable
extension**.
17. **line_length()**: The line length set with **BC_LINE_LENGTH** (see the
19. **line_length()**: The line length set with **BC_LINE_LENGTH** (see the
**ENVIRONMENT VARIABLES** section). This is a **non-portable extension**.
18. **global_stacks()**: **0** if global stacks are not enabled with the **-g**
20. **global_stacks()**: **0** if global stacks are not enabled with the **-g**
or **-\-global-stacks** options, non-zero otherwise. See the **OPTIONS**
section. This is a **non-portable extension**.
19. **leading_zero()**: **0** if leading zeroes are not enabled with the **-z**
21. **leading_zero()**: **0** if leading zeroes are not enabled with the **-z**
or **--leading-zeroes** options, non-zero otherwise. See the **OPTIONS**
section. This is a **non-portable extension**.
20. **rand()**: A pseudo-random integer between **0** (inclusive) and
22. **rand()**: A pseudo-random integer between **0** (inclusive) and
**BC_RAND_MAX** (inclusive). Using this operand will change the value of
**seed**. This is a **non-portable extension**.
21. **irand(E)**: A pseudo-random integer between **0** (inclusive) and the
23. **irand(E)**: A pseudo-random integer between **0** (inclusive) and the
value of **E** (exclusive). If **E** is negative or is a non-integer
(**E**'s *scale* is not **0**), an error is raised, and bc(1) resets (see
the **RESET** section) while **seed** remains unchanged. If **E** is larger
@ -573,7 +616,7 @@ The following are valid operands in bc(1):
change the value of **seed**, unless the value of **E** is **0** or **1**.
In that case, **0** is returned, and **seed** is *not* changed. This is a
**non-portable extension**.
22. **maxrand()**: The max integer returned by **rand()**. This is a
24. **maxrand()**: The max integer returned by **rand()**. This is a
**non-portable extension**.
The integers generated by **rand()** and **irand(E)** are guaranteed to be as
@ -592,14 +635,40 @@ use a non-seeded pseudo-random number generator.
Numbers are strings made up of digits, uppercase letters, and at most **1**
period for a radix. Numbers can have up to **BC_NUM_MAX** digits. Uppercase
letters are equal to **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**.
letters are equal to **9** plus their position in the alphabet, starting from
**1** (i.e., **A** equals **10**, or **9+1**).
Single-character numbers (i.e., **A** alone) take the value that they would have
if they were valid digits, regardless of the value of **ibase**. This means that
**A** alone always equals decimal **10** and **Z** alone always equals decimal
**35**.
If a digit or letter makes no sense with the current value of **ibase** (i.e.,
they are greater than or equal to the current value of **ibase**), then the
behavior depends on the existence of the **-c**/**-\-digit-clamp** or
**-C**/**-\-no-digit-clamp** options (see the **OPTIONS** section), the
existence and setting of the **BC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section), or the default, which can be queried with
the **-h**/**-\-help** option.
If clamping is off, then digits or letters that are greater than or equal to the
current value of **ibase** are not changed. Instead, their given value is
multiplied by the appropriate power of **ibase** and added into the number. This
means that, with an **ibase** of **3**, the number **AB** is equal to
**3\^1\*A+3\^0\*B**, which is **3** times **10** plus **11**, or **41**.
If clamping is on, then digits or letters that are greater than or equal to the
current value of **ibase** are set to the value of the highest valid digit in
**ibase** before being multiplied by the appropriate power of **ibase** and
added into the number. This means that, with an **ibase** of **3**, the number
**AB** is equal to **3\^1\*2+3\^0\*2**, which is **3** times **2** plus **2**,
or **8**.
There is one exception to clamping: single-character numbers (i.e., **A**
alone). Such numbers are never clamped and always take the value they would have
in the highest possible **ibase**. This means that **A** alone always equals
decimal **10** and **Z** alone always equals decimal **35**. This behavior is
mandated by the standard (see the STANDARDS section) and is meant to provide an
easy way to set the current **ibase** (with the **i** command) regardless of the
current value of **ibase**.
If clamping is on, and the clamped value of a character is needed, use a leading
zero, i.e., for **A**, use **0A**.
In addition, bc(1) accepts numbers in scientific notation. These have the form
**\<number\>e\<integer\>**. The exponent (the portion after the **e**) must be
@ -849,10 +918,9 @@ The operators will be described in more detail below.
**assignment** operators, which means that **a=b\>c** is interpreted as
**(a=b)\>c**.
Also, unlike the standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html)
requires, these operators can appear anywhere any other expressions can be
used. This allowance is a **non-portable extension**.
Also, unlike the standard (see the **STANDARDS** section) requires, these
operators can appear anywhere any other expressions can be used. This
allowance is a **non-portable extension**.
**&&**
@ -916,6 +984,19 @@ The **if** **else** statement does the same thing as in C.
The **quit** statement causes bc(1) to quit, even if it is on a branch that will
not be executed (it is a compile-time command).
**Warning**: The behavior of this bc(1) on **quit** is slightly different from
other bc(1) implementations. Other bc(1) implementations will exit as soon as
they finish parsing the line that a **quit** command is on. This bc(1) will
execute any completed and executable statements that occur before the **quit**
statement before exiting.
In other words, for the bc(1) code below:
for (i = 0; i < 3; ++i) i; quit
Other bc(1) implementations will print nothing, and this bc(1) will print **0**,
**1**, and **2** on successive lines before exiting.
The **halt** statement causes bc(1) to quit, if it is executed. (Unlike **quit**
if it is on a branch of an **if** statement that is not executed, bc(1) does not
quit.)
@ -1099,9 +1180,8 @@ equivalents are given.
## Standard Library
The standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html) defines the
following functions for the math library:
The standard (see the **STANDARDS** section) defines the following functions for
the math library:
**s(x)**
@ -1149,8 +1229,7 @@ following functions for the math library:
The extended library is *not* loaded when the **-s**/**-\-standard** or
**-w**/**-\-warn** options are given since they are not part of the library
defined by the standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html).
defined by the standard (see the **STANDARDS** section).
The extended library is a **non-portable extension**.
@ -2085,7 +2164,8 @@ be hit.
# ENVIRONMENT VARIABLES
bc(1) recognizes the following environment variables:
As **non-portable extensions**, bc(1) recognizes the following environment
variables:
**POSIXLY_CORRECT**
@ -2191,6 +2271,21 @@ bc(1) recognizes the following environment variables:
This environment variable overrides the default, which can be queried with
the **-h** or **-\-help** options.
**BC_DIGIT_CLAMP**
: 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 **ibase** so that all such digits are considered equal
to the **ibase** 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 **ibase**.
This never applies to single-digit numbers, as per the standard (see the
**STANDARDS** section).
This environment variable overrides the default, which can be queried with
the **-h** or **-\-help** options.
# EXIT STATUS
bc(1) returns the following exit statuses:
@ -2266,12 +2361,10 @@ checking, and its normal behavior can be forced by using the **-i** flag or
# INTERACTIVE MODE
Per the standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html), bc(1) has
an interactive mode and a non-interactive mode. Interactive mode is turned on
automatically when both **stdin** and **stdout** are hooked to a terminal, but
the **-i** flag and **-\-interactive** option can turn it on in other
situations.
Per the standard (see the **STANDARDS** section), bc(1) has an interactive mode
and a non-interactive mode. Interactive mode is turned on automatically when
both **stdin** and **stdout** are hooked to a terminal, but the **-i** flag and
**-\-interactive** option can turn it on in other situations.
In interactive mode, bc(1) attempts to recover from errors (see the **RESET**
section), and in normal execution, flushes **stdout** as soon as execution is
@ -2297,10 +2390,8 @@ setting is used. The default setting can be queried with the **-h** or
**-\-help** options.
TTY mode is different from interactive mode because interactive mode is required
in the bc(1) standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html), and
interactive mode requires only **stdin** and **stdout** to be connected to a
terminal.
in the bc(1) standard (see the **STANDARDS** section), and interactive mode
requires only **stdin** and **stdout** to be connected to a terminal.
## Prompt
@ -2360,13 +2451,20 @@ at https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html . The
flags **-efghiqsvVw**, all long options, and the extensions noted above are
extensions to that specification.
In addition, the behavior of the **quit** implements an interpretation of that
specification that is different from all known implementations. For more
information see the **Statements** subsection of the **SYNTAX** section.
Note that the specification explicitly says that bc(1) only accepts numbers that
use a period (**.**) as a radix point, regardless of the value of
**LC_NUMERIC**.
# BUGS
None are known. Report bugs at https://git.yzena.com/gavin/bc.
Before version **6.1.0**, this bc(1) had incorrect behavior for the **quit**
statement.
No other bugs are known. Report bugs at https://git.yzena.com/gavin/bc .
# AUTHORS

459
contrib/bc/manuals/bc/N.1
View File

@ -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,7 +25,7 @@
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.TH "BC" "1" "June 2022" "Gavin D. Howard" "General Commands Manual"
.TH "BC" "1" "October 2022" "Gavin D. Howard" "General Commands Manual"
.nh
.ad l
.SH NAME
@ -33,24 +33,25 @@
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[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]--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 at
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.
@ -79,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.
@ -172,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.
@ -202,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
@ -217,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
@ -294,38 +431,32 @@ 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
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html).
(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
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.
\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].
@ -351,93 +482,6 @@ extended math library (see the \f[B]LIBRARY\f[R] section).
.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]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.
.PP
This is a \f[B]non-portable extension\f[R].
.RE
.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]-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]-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]-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
.PP
All long options are \f[B]non-portable extensions\f[R].
.SH STDIN
@ -491,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
@ -668,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.
@ -675,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,
@ -683,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).
@ -698,44 +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 "18." 4
.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 "19." 4
.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 "20." 4
.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 "21." 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
@ -753,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 "22." 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
@ -776,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].
@ -1076,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].
@ -1109,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
@ -1136,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
@ -1171,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.)
@ -1384,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.
@ -1441,8 +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
@ -2501,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
@ -2621,6 +2729,22 @@ expressions and expression files, and a zero value makes bc(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
.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:
@ -2702,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.
@ -2736,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) standard
(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 Command-Line History
@ -2833,13 +2955,22 @@ 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].
.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.yzena.com/gavin/bc .
.SH AUTHORS
.PP
Gavin D.

370
contrib/bc/manuals/bc/N.1.md
View File

@ -2,7 +2,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:
@ -34,15 +34,14 @@ bc - arbitrary-precision decimal arithmetic language and calculator
# SYNOPSIS
**bc** [**-ghilPqRsvVw**] [**-\-global-stacks**] [**-\-help**] [**-\-interactive**] [**-\-mathlib**] [**-\-no-prompt**] [**-\-no-read-prompt**] [**-\-quiet**] [**-\-standard**] [**-\-warn**] [**-\-version**] [**-e** *expr*] [**-\-expression**=*expr*...] [**-f** *file*...] [**-\-file**=*file*...] [*file*...] [**-I** *ibase*] [**-\-ibase**=*ibase*] [**-O** *obase*] [**-\-obase**=*obase*] [**-S** *scale*] [**-\-scale**=*scale*] [**-E** *seed*] [**-\-seed**=*seed*]
**bc** [**-cCghilPqRsvVw**] [**-\-digit-clamp**] [**-\-no-digit-clamp**] [**-\-global-stacks**] [**-\-help**] [**-\-interactive**] [**-\-mathlib**] [**-\-no-prompt**] [**-\-no-read-prompt**] [**-\-quiet**] [**-\-standard**] [**-\-warn**] [**-\-version**] [**-e** *expr*] [**-\-expression**=*expr*...] [**-f** *file*...] [**-\-file**=*file*...] [*file*...] [**-I** *ibase*] [**-\-ibase**=*ibase*] [**-O** *obase*] [**-\-obase**=*obase*] [**-S** *scale*] [**-\-scale**=*scale*] [**-E** *seed*] [**-\-seed**=*seed*]
# DESCRIPTION
bc(1) is an interactive processor for a language first standardized in 1991 by
POSIX. (The current standard is at
https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html .) The
language provides unlimited precision decimal arithmetic and is somewhat C-like,
but there are differences. Such differences will be noted in this document.
POSIX. (See the **STANDARDS** 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.
After parsing and handling options, this bc(1) reads any files given on the
command line and executes them before reading from **stdin**.
@ -64,6 +63,86 @@ that is a bug and should be reported. See the **BUGS** section.
The following are the options that bc(1) accepts.
**-C**, **-\-no-digit-clamp**
: Disables clamping of digits greater than or equal to the current **ibase**
when parsing numbers.
This means that the value added to a number from a digit is always that
digit's value multiplied by the value of ibase raised to the power of the
digit's position, which starts from 0 at the least significant digit.
If this and/or the **-c** or **-\-digit-clamp** options are given multiple
times, the last one given is used.
This option overrides the **BC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section) and the default, which can be queried
with the **-h** or **-\-help** options.
This is a **non-portable extension**.
**-c**, **-\-digit-clamp**
: Enables clamping of digits greater than or equal to the current **ibase**
when parsing numbers.
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's
position, which starts from 0 at the least significant digit.
If this and/or the **-C** or **-\-no-digit-clamp** options are given
multiple times, the last one given is used.
This option overrides the **BC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section) and the default, which can be queried
with the **-h** or **-\-help** options.
This is a **non-portable extension**.
**-E** *seed*, **-\-seed**=*seed*
: Sets the builtin variable **seed** to the value *seed* assuming that *seed*
is in base 10. It is a fatal error if *seed* is not a valid number.
If multiple instances of this option are given, the last is used.
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 the **-f** and **-\-file** 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.
If this option is given on the command-line (i.e., not in **BC_ENV_ARGS**,
see the **ENVIRONMENT VARIABLES** section), then after processing all
expressions and files, bc(1) will exit, unless **-** (**stdin**) was given
as an argument at least once to **-f** or **-\-file**, whether on the
command-line or in **BC_ENV_ARGS**. However, if any other **-e**,
**-\-expression**, **-f**, or **-\-file** arguments are given after **-f-**
or equivalent is given, bc(1) will give a fatal error and exit.
This is a **non-portable extension**.
**-f** *file*, **-\-file**=*file*
: Reads in *file* and evaluates it, line by line, as though it were read
through **stdin**. If expressions are also given (see the **-e** and
**-\-expression** options), the expressions are evaluated in the order
given.
If this option is given on the command-line (i.e., not in **BC_ENV_ARGS**,
see the **ENVIRONMENT VARIABLES** section), then after processing all
expressions and files, bc(1) will exit, unless **-** (**stdin**) was given
as an argument at least once to **-f** or **-\-file**. However, if any other
**-e**, **-\-expression**, **-f**, or **-\-file** arguments are given after
**-f-** or equivalent is given, bc(1) will give a fatal error and exit.
This is a **non-portable extension**.
**-g**, **-\-global-stacks**
: Turns the globals **ibase**, **obase**, **scale**, and **seed** into stacks.
@ -134,7 +213,16 @@ The following are the options that bc(1) accepts.
**-h**, **-\-help**
: Prints a usage message and quits.
: Prints a usage message and exits.
**-I** *ibase*, **-\-ibase**=*ibase*
: Sets the builtin variable **ibase** to the value *ibase* assuming that
*ibase* is in base 10. It is a fatal error if *ibase* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-i**, **-\-interactive**
@ -158,6 +246,15 @@ The following are the options that bc(1) accepts.
To learn what is in the libraries, see the **LIBRARY** section.
**-O** *obase*, **-\-obase**=*obase*
: Sets the builtin variable **obase** to the value *obase* assuming that
*obase* is in base 10. It is a fatal error if *obase* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-P**, **-\-no-prompt**
: Disables the prompt in TTY mode. (The prompt is only enabled in TTY mode.
@ -171,6 +268,19 @@ The following are the options that bc(1) accepts.
This is a **non-portable extension**.
**-q**, **-\-quiet**
: 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 **-v**, **-V**, or **-\-version** options are given
unless the **BC_BANNER** environment variable is set and contains a non-zero
integer or if this bc(1) was built with the header displayed by default. If
*any* of that is the case, then this option *does* prevent bc(1) from
printing the header.
This is a **non-portable extension**.
**-R**, **-\-no-read-prompt**
: Disables the read prompt in TTY mode. (The read prompt is only enabled in
@ -224,35 +334,29 @@ The following are the options that bc(1) accepts.
Keywords are *not* redefined when parsing the builtin math library (see the
**LIBRARY** section).
It is a fatal error to redefine keywords mandated by the POSIX standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html). It is
a fatal error to attempt to redefine words that this bc(1) does not reserve
as keywords.
It is a fatal error to redefine keywords mandated by the POSIX standard (see
the **STANDARDS** section). It is a fatal error to attempt to redefine words
that this bc(1) does not reserve as keywords.
**-q**, **-\-quiet**
**-S** *scale*, **-\-scale**=*scale*
: 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 **-v**, **-V**, or **-\-version** options are given
unless the **BC_BANNER** environment variable is set and contains a non-zero
integer or if this bc(1) was built with the header displayed by default. If
*any* of that is the case, then this option *does* prevent bc(1) from
printing the header.
: Sets the builtin variable **scale** to the value *scale* assuming that
*scale* is in base 10. It is a fatal error if *scale* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-s**, **-\-standard**
: 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 **STANDARDS**
section) and error if any extensions are used.
This is a **non-portable extension**.
**-v**, **-V**, **-\-version**
: Print the version information (copyright header) and exit.
: Print the version information (copyright header) and exits.
This is a **non-portable extension**.
@ -274,74 +378,6 @@ The following are the options that bc(1) accepts.
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.
If this option is given on the command-line (i.e., not in **BC_ENV_ARGS**,
see the **ENVIRONMENT VARIABLES** section), then after processing all
expressions and files, bc(1) will exit, unless **-** (**stdin**) was given
as an argument at least once to **-f** or **-\-file**, whether on the
command-line or in **BC_ENV_ARGS**. However, if any other **-e**,
**-\-expression**, **-f**, or **-\-file** arguments are given after **-f-**
or equivalent is given, bc(1) will give a fatal error and exit.
This is a **non-portable extension**.
**-f** *file*, **-\-file**=*file*
: Reads in *file* and evaluates it, line by line, as though it were read
through **stdin**. If expressions are also given (see above), the
expressions are evaluated in the order given.
If this option is given on the command-line (i.e., not in **BC_ENV_ARGS**,
see the **ENVIRONMENT VARIABLES** section), then after processing all
expressions and files, bc(1) will exit, unless **-** (**stdin**) was given
as an argument at least once to **-f** or **-\-file**. However, if any other
**-e**, **-\-expression**, **-f**, or **-\-file** arguments are given after
**-f-** or equivalent is given, bc(1) will give a fatal error and exit.
This is a **non-portable extension**.
**-I** *ibase*, **-\-ibase**=*ibase*
: Sets the builtin variable **ibase** to the value *ibase* assuming that
*ibase* is in base 10. It is a fatal error if *ibase* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-O** *obase*, **-\-obase**=*obase*
: Sets the builtin variable **obase** to the value *obase* assuming that
*obase* is in base 10. It is a fatal error if *obase* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-S** *scale*, **-\-scale**=*scale*
: Sets the builtin variable **scale** to the value *scale* assuming that
*scale* is in base 10. It is a fatal error if *scale* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
**-E** *seed*, **-\-seed**=*seed*
: Sets the builtin variable **seed** to the value *seed* assuming that *seed*
is in base 10. It is a fatal error if *seed* is not a valid number.
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
All long options are **non-portable extensions**.
# STDIN
@ -393,8 +429,7 @@ it is recommended that those scripts be changed to redirect **stderr** to
# SYNTAX
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
bc(1) follows the POSIX standard (see the **STANDARDS** 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.
@ -523,46 +558,54 @@ The following are valid operands in bc(1):
7. **scale(E)**: The *scale* of **E**.
8. **abs(E)**: The absolute value of **E**. This is a **non-portable
extension**.
9. **modexp(E, E, E)**: Modular exponentiation, where the first expression is
9. **is_number(E)**: **1** if the given argument is a number, **0** if it is a
string. This is a **non-portable extension**.
10. **is_string(E)**: **1** if the given argument is a string, **0** if it is a
number. This is a **non-portable extension**.
11. **modexp(E, E, E)**: Modular exponentiation, where the first expression is
the base, the second is the exponent, and the third is the modulus. All
three values must be integers. The second argument must be non-negative. The
third argument must be non-zero. This is a **non-portable extension**.
10. **divmod(E, E, I[])**: Division and modulus in one operation. This is for
11. **divmod(E, E, I[])**: Division and modulus in one operation. This is for
optimization. The first expression is the dividend, and the second is the
divisor, which must be non-zero. The return value is the quotient, and the
modulus is stored in index **0** of the provided array (the last argument).
This is a **non-portable extension**.
11. **asciify(E)**: If **E** is a string, returns a string that is the first
12. **asciify(E)**: If **E** is a string, returns a string that is the first
letter of its argument. If it is a number, calculates the number mod **256**
and returns that number as a one-character string. This is a **non-portable
extension**.
12. **I()**, **I(E)**, **I(E, E)**, and so on, where **I** is an identifier for
13. **asciify(I[])**: A string that is made up of the characters that would
result from running **asciify(E)** on each element of the array identified
by the argument. This allows creating multi-character strings and storing
them. This is a **non-portable extension**.
14. **I()**, **I(E)**, **I(E, E)**, and so on, where **I** is an identifier for
a non-**void** function (see the *Void Functions* subsection of the
**FUNCTIONS** section). The **E** argument(s) may also be arrays of the form
**I[]**, which will automatically be turned into array references (see the
*Array References* subsection of the **FUNCTIONS** section) if the
corresponding parameter in the function definition is an array reference.
13. **read()**: Reads a line from **stdin** and uses that as an expression. The
15. **read()**: Reads a line from **stdin** and uses that as an expression. The
result of that expression is the result of the **read()** operand. This is a
**non-portable extension**.
14. **maxibase()**: The max allowable **ibase**. This is a **non-portable
16. **maxibase()**: The max allowable **ibase**. This is a **non-portable
extension**.
15. **maxobase()**: The max allowable **obase**. This is a **non-portable
17. **maxobase()**: The max allowable **obase**. This is a **non-portable
extension**.
16. **maxscale()**: The max allowable **scale**. This is a **non-portable
18. **maxscale()**: The max allowable **scale**. This is a **non-portable
extension**.
17. **line_length()**: The line length set with **BC_LINE_LENGTH** (see the
19. **line_length()**: The line length set with **BC_LINE_LENGTH** (see the
**ENVIRONMENT VARIABLES** section). This is a **non-portable extension**.
18. **global_stacks()**: **0** if global stacks are not enabled with the **-g**
20. **global_stacks()**: **0** if global stacks are not enabled with the **-g**
or **-\-global-stacks** options, non-zero otherwise. See the **OPTIONS**
section. This is a **non-portable extension**.
19. **leading_zero()**: **0** if leading zeroes are not enabled with the **-z**
21. **leading_zero()**: **0** if leading zeroes are not enabled with the **-z**
or **--leading-zeroes** options, non-zero otherwise. See the **OPTIONS**
section. This is a **non-portable extension**.
20. **rand()**: A pseudo-random integer between **0** (inclusive) and
22. **rand()**: A pseudo-random integer between **0** (inclusive) and
**BC_RAND_MAX** (inclusive). Using this operand will change the value of
**seed**. This is a **non-portable extension**.
21. **irand(E)**: A pseudo-random integer between **0** (inclusive) and the
23. **irand(E)**: A pseudo-random integer between **0** (inclusive) and the
value of **E** (exclusive). If **E** is negative or is a non-integer
(**E**'s *scale* is not **0**), an error is raised, and bc(1) resets (see
the **RESET** section) while **seed** remains unchanged. If **E** is larger
@ -573,7 +616,7 @@ The following are valid operands in bc(1):
change the value of **seed**, unless the value of **E** is **0** or **1**.
In that case, **0** is returned, and **seed** is *not* changed. This is a
**non-portable extension**.
22. **maxrand()**: The max integer returned by **rand()**. This is a
24. **maxrand()**: The max integer returned by **rand()**. This is a
**non-portable extension**.
The integers generated by **rand()** and **irand(E)** are guaranteed to be as
@ -592,14 +635,40 @@ use a non-seeded pseudo-random number generator.
Numbers are strings made up of digits, uppercase letters, and at most **1**
period for a radix. Numbers can have up to **BC_NUM_MAX** digits. Uppercase
letters are equal to **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**.
letters are equal to **9** plus their position in the alphabet, starting from
**1** (i.e., **A** equals **10**, or **9+1**).
Single-character numbers (i.e., **A** alone) take the value that they would have
if they were valid digits, regardless of the value of **ibase**. This means that
**A** alone always equals decimal **10** and **Z** alone always equals decimal
**35**.
If a digit or letter makes no sense with the current value of **ibase** (i.e.,
they are greater than or equal to the current value of **ibase**), then the
behavior depends on the existence of the **-c**/**-\-digit-clamp** or
**-C**/**-\-no-digit-clamp** options (see the **OPTIONS** section), the
existence and setting of the **BC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section), or the default, which can be queried with
the **-h**/**-\-help** option.
If clamping is off, then digits or letters that are greater than or equal to the
current value of **ibase** are not changed. Instead, their given value is
multiplied by the appropriate power of **ibase** and added into the number. This
means that, with an **ibase** of **3**, the number **AB** is equal to
**3\^1\*A+3\^0\*B**, which is **3** times **10** plus **11**, or **41**.
If clamping is on, then digits or letters that are greater than or equal to the
current value of **ibase** are set to the value of the highest valid digit in
**ibase** before being multiplied by the appropriate power of **ibase** and
added into the number. This means that, with an **ibase** of **3**, the number
**AB** is equal to **3\^1\*2+3\^0\*2**, which is **3** times **2** plus **2**,
or **8**.
There is one exception to clamping: single-character numbers (i.e., **A**
alone). Such numbers are never clamped and always take the value they would have
in the highest possible **ibase**. This means that **A** alone always equals
decimal **10** and **Z** alone always equals decimal **35**. This behavior is
mandated by the standard (see the STANDARDS section) and is meant to provide an
easy way to set the current **ibase** (with the **i** command) regardless of the
current value of **ibase**.
If clamping is on, and the clamped value of a character is needed, use a leading
zero, i.e., for **A**, use **0A**.
In addition, bc(1) accepts numbers in scientific notation. These have the form
**\<number\>e\<integer\>**. The exponent (the portion after the **e**) must be
@ -849,10 +918,9 @@ The operators will be described in more detail below.
**assignment** operators, which means that **a=b\>c** is interpreted as
**(a=b)\>c**.
Also, unlike the standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html)
requires, these operators can appear anywhere any other expressions can be
used. This allowance is a **non-portable extension**.
Also, unlike the standard (see the **STANDARDS** section) requires, these
operators can appear anywhere any other expressions can be used. This
allowance is a **non-portable extension**.
**&&**
@ -916,6 +984,19 @@ The **if** **else** statement does the same thing as in C.
The **quit** statement causes bc(1) to quit, even if it is on a branch that will
not be executed (it is a compile-time command).
**Warning**: The behavior of this bc(1) on **quit** is slightly different from
other bc(1) implementations. Other bc(1) implementations will exit as soon as
they finish parsing the line that a **quit** command is on. This bc(1) will
execute any completed and executable statements that occur before the **quit**
statement before exiting.
In other words, for the bc(1) code below:
for (i = 0; i < 3; ++i) i; quit
Other bc(1) implementations will print nothing, and this bc(1) will print **0**,
**1**, and **2** on successive lines before exiting.
The **halt** statement causes bc(1) to quit, if it is executed. (Unlike **quit**
if it is on a branch of an **if** statement that is not executed, bc(1) does not
quit.)
@ -1099,9 +1180,8 @@ equivalents are given.
## Standard Library
The standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html) defines the
following functions for the math library:
The standard (see the **STANDARDS** section) defines the following functions for
the math library:
**s(x)**
@ -1149,8 +1229,7 @@ following functions for the math library:
The extended library is *not* loaded when the **-s**/**-\-standard** or
**-w**/**-\-warn** options are given since they are not part of the library
defined by the standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html).
defined by the standard (see the **STANDARDS** section).
The extended library is a **non-portable extension**.
@ -2085,7 +2164,8 @@ be hit.
# ENVIRONMENT VARIABLES
bc(1) recognizes the following environment variables:
As **non-portable extensions**, bc(1) recognizes the following environment
variables:
**POSIXLY_CORRECT**
@ -2191,6 +2271,21 @@ bc(1) recognizes the following environment variables:
This environment variable overrides the default, which can be queried with
the **-h** or **-\-help** options.
**BC_DIGIT_CLAMP**
: 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 **ibase** so that all such digits are considered equal
to the **ibase** 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 **ibase**.
This never applies to single-digit numbers, as per the standard (see the
**STANDARDS** section).
This environment variable overrides the default, which can be queried with
the **-h** or **-\-help** options.
# EXIT STATUS
bc(1) returns the following exit statuses:
@ -2266,12 +2361,10 @@ checking, and its normal behavior can be forced by using the **-i** flag or
# INTERACTIVE MODE
Per the standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html), bc(1) has
an interactive mode and a non-interactive mode. Interactive mode is turned on
automatically when both **stdin** and **stdout** are hooked to a terminal, but
the **-i** flag and **-\-interactive** option can turn it on in other
situations.
Per the standard (see the **STANDARDS** section), bc(1) has an interactive mode
and a non-interactive mode. Interactive mode is turned on automatically when
both **stdin** and **stdout** are hooked to a terminal, but the **-i** flag and
**-\-interactive** option can turn it on in other situations.
In interactive mode, bc(1) attempts to recover from errors (see the **RESET**
section), and in normal execution, flushes **stdout** as soon as execution is
@ -2297,10 +2390,8 @@ setting is used. The default setting can be queried with the **-h** or
**-\-help** options.
TTY mode is different from interactive mode because interactive mode is required
in the bc(1) standard
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html), and
interactive mode requires only **stdin** and **stdout** to be connected to a
terminal.
in the bc(1) standard (see the **STANDARDS** section), and interactive mode
requires only **stdin** and **stdout** to be connected to a terminal.
## Command-Line History
@ -2386,13 +2477,20 @@ at https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html . The
flags **-efghiqsvVw**, all long options, and the extensions noted above are
extensions to that specification.
In addition, the behavior of the **quit** implements an interpretation of that
specification that is different from all known implementations. For more
information see the **Statements** subsection of the **SYNTAX** section.
Note that the specification explicitly says that bc(1) only accepts numbers that
use a period (**.**) as a radix point, regardless of the value of
**LC_NUMERIC**.
# BUGS
None are known. Report bugs at https://git.yzena.com/gavin/bc.
Before version **6.1.0**, this bc(1) had incorrect behavior for the **quit**
statement.
No other bugs are known. Report bugs at https://git.yzena.com/gavin/bc .
# AUTHORS

207
contrib/bc/manuals/bcl.3
View File

@ -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,7 +25,7 @@
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.TH "BCL" "3" "June 2022" "Gavin D. Howard" "Libraries Manual"
.TH "BCL" "3" "October 2022" "Gavin D. Howard" "Libraries Manual"
.nh
.ad l
.SH NAME
@ -36,19 +36,16 @@ bcl - library of arbitrary precision decimal arithmetic
.PP
\f[I]#include <bcl.h>\f[R]
.PP
Link with \f[I]-lbcl\f[R].
.SS Signals
.PP
This procedure will allow clients to use signals to interrupt
computations running in bcl(3).
.PP
\f[B]void bcl_handleSignal(\f[R]\f[I]void\f[R]\f[B]);\f[R]
.PP
\f[B]bool bcl_running(\f[R]\f[I]void\f[R]\f[B]);\f[R]
Link with \f[I]-lbcl\f[R], and on POSIX systems, \f[I]-lpthread\f[R] is
also required.
.SS Setup
.PP
These items allow clients to set up bcl(3).
.PP
\f[B]BclError bcl_start(\f[R]\f[I]void\f[R]\f[B]);\f[R]
.PP
\f[B]void bcl_end(\f[R]\f[I]void\f[R]\f[B]);\f[R]
.PP
\f[B]BclError bcl_init(\f[R]\f[I]void\f[R]\f[B]);\f[R]
.PP
\f[B]void bcl_free(\f[R]\f[I]void\f[R]\f[B]);\f[R]
@ -63,6 +60,10 @@ These items allow clients to set up bcl(3).
\f[I]leadingZeroes\f[R]\f[B]);\f[R]
.PP
\f[B]void bcl_gc(\f[R]\f[I]void\f[R]\f[B]);\f[R]
.PP
\f[B]bool bcl_digitClamp(\f[R]\f[I]void\f[R]\f[B]);\f[R]
.PP
\f[B]void bcl_setDigitClamp(bool\f[R] \f[I]digitClamp\f[R]\f[B]);\f[R]
.SS Contexts
.PP
These items will allow clients to handle contexts, which are isolated
@ -234,10 +235,6 @@ standardized by POSIX
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html) in
bc(1).
.PP
bcl(3) is async-signal-safe if
\f[B]bcl_handleSignal(\f[R]\f[I]void\f[R]\f[B])\f[R] is used properly.
(See the \f[B]SIGNAL HANDLING\f[R] section.)
.PP
bcl(3) assumes that it is allowed to use the \f[B]bcl\f[R],
\f[B]Bcl\f[R], \f[B]bc\f[R], and \f[B]Bc\f[R] prefixes for symbol names
without collision.
@ -245,45 +242,19 @@ without collision.
All of the items in its interface are described below.
See the documentation for each function for what each function can
return.
.SS Signals
.TP
\f[B]void bcl_handleSignal(\f[R]\f[I]void\f[R]\f[B])\f[R]
An async-signal-safe function that can be called from a signal handler.
If called from a signal handler on the same thread as any executing
bcl(3) functions, it will interrupt the functions and force them to
return early.
It is undefined behavior if this function is called from a thread that
is \f[I]not\f[R] executing any bcl(3) functions while any bcl(3)
functions are executing.
.RS
.PP
If execution \f[I]is\f[R] interrupted,
\f[B]bcl_handleSignal(\f[R]\f[I]void\f[R]\f[B])\f[R] does \f[I]not\f[R]
return to its caller.
.PP
See the \f[B]SIGNAL HANDLING\f[R] section.
.RE
.TP
\f[B]bool bcl_running(\f[R]\f[I]void\f[R]\f[B])\f[R]
An async-signal-safe function that can be called from a signal handler.
It will return \f[B]true\f[R] if any bcl(3) procedures are running,
which means it is safe to call
\f[B]bcl_handleSignal(\f[R]\f[I]void\f[R]\f[B])\f[R].
Otherwise, it returns \f[B]false\f[R].
.RS
.PP
See the \f[B]SIGNAL HANDLING\f[R] section.
.RE
.SS Setup
.TP
\f[B]BclError bcl_init(\f[R]\f[I]void\f[R]\f[B])\f[R]
\f[B]BclError bcl_start(\f[R]\f[I]void\f[R]\f[B])\f[R]
Initializes this library.
This function can be called multiple times, but each call must be
matched by a call to \f[B]bcl_free(\f[R]\f[I]void\f[R]\f[B])\f[R].
This function can be called multiple times, but \f[B]bcl_end()\f[R] must
only be called \f[I]once\f[R].
This is to make it possible for multiple libraries and applications to
initialize bcl(3) without problem.
.RS
.PP
It is suggested that client libraries call this function, but do not
call \f[B]bcl_end()\f[R], and client applications should call both.
.PP
If there was no error, \f[B]BCL_ERROR_NONE\f[R] is returned.
Otherwise, this function can return:
.IP \[bu] 2
@ -294,14 +265,56 @@ Calling any other function without calling this one first is undefined
behavior.
.RE
.TP
\f[B]void bcl_end(\f[R]\f[I]void\f[R]\f[B])\f[R]
Deinitializes this library.
This function must only be called \f[I]once\f[R].
.RS
.PP
All data must have been freed before calling this function.
.PP
This function must be the last one clients call.
Calling this function before calling any other function is undefined
behavior.
.RE
.TP
\f[B]BclError bcl_init(\f[R]\f[I]void\f[R]\f[B])\f[R]
Initializes the library for the current thread.
This function can be called multiple times, but each call must be
matched by a call to \f[B]bcl_free(\f[R]\f[I]void\f[R]\f[B])\f[R].
This is to make it possible for multiple libraries and applications to
initialize threads for bcl(3) without problem.
.RS
.PP
This function \f[I]must\f[R] be called from the thread that it is
supposed to initialize.
.PP
If there was no error, \f[B]BCL_ERROR_NONE\f[R] is returned.
Otherwise, this function can return:
.IP \[bu] 2
\f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R]
.PP
This function must be the second one clients call.
Calling any other function without calling \f[B]bcl_start()\f[R] and
then this one first is undefined behavior, except in the case of new
threads.
New threads can safely call this function without calling
\f[B]bcl_start()\f[R] if another thread has previously called
\f[B]bcl_start()\f[R].
But this function must still be the first function in bcl(3) called by
that new thread.
.RE
.TP
\f[B]void bcl_free(\f[R]\f[I]void\f[R]\f[B])\f[R]
Decrements bcl(3)\[cq]s reference count and frees the data associated
with it if the reference count is \f[B]0\f[R].
.RS
.PP
This function must be the last one clients call.
Calling this function before calling any other function is undefined
behavior.
This function \f[I]must\f[R] be called from the thread that it is
supposed to deinitialize.
.PP
This function must be the second to last one clients call.
Calling this function before calling any other function besides
\f[B]bcl_end()\f[R] is undefined behavior.
.RE
.TP
\f[B]bool bcl_abortOnFatalError(\f[R]\f[I]void\f[R]\f[B])\f[R]
@ -313,6 +326,9 @@ a fatal error occurs.
.PP
If activated, clients do not need to check for fatal errors.
.PP
This value is \f[I]thread-local\f[R]; it applies to just the thread it
is read on.
.PP
The default is \f[B]false\f[R].
.RE
.TP
@ -324,6 +340,9 @@ If \f[I]abrt\f[R] is \f[B]true\f[R], bcl(3) will cause a
\f[B]SIGABRT\f[R] on fatal errors after the call.
.RS
.PP
This value is \f[I]thread-local\f[R]; it applies to just the thread it
is set on.
.PP
If activated, clients do not need to check for fatal errors.
.RE
.TP
@ -334,6 +353,9 @@ strings returned by \f[B]bcl_string()\f[R] when numbers are greater than
If \f[B]true\f[R] is returned, then leading zeroes will be added.
.RS
.PP
This value is \f[I]thread-local\f[R]; it applies to just the thread it
is read on.
.PP
The default is \f[B]false\f[R].
.RE
.TP
@ -343,6 +365,48 @@ by \f[B]bcl_string()\f[R] when numbers are greater than \f[B]-1\f[R],
less than \f[B]1\f[R], and not equal to \f[B]0\f[R].
If \f[I]leadingZeroes\f[R] is \f[B]true\f[R], leading zeroes will be
added to strings returned by \f[B]bcl_string()\f[R].
.RS
.PP
This value is \f[I]thread-local\f[R]; it applies to just the thread it
is set on.
.RE
.TP
\f[B]bool bcl_digitClamp(\f[R]\f[I]void\f[R]\f[B])\f[R]
Queries and returns the state of whether digits in number strings that
are greater than or equal to the current \f[B]ibase\f[R] are clamped or
not.
.RS
.PP
If \f[B]true\f[R] is returned, then digits are treated as though they
are equal to the value of \f[B]ibase\f[R] minus \f[B]1\f[R].
If this is \f[I]not\f[R] true, then digits are treated as though they
are equal to the value they would have if \f[B]ibase\f[R] was large
enough.
They are then multiplied by the appropriate power of \f[B]ibase\f[R].
.PP
For example, with clamping off and an \f[B]ibase\f[R] of \f[B]3\f[R],
the string \[lq]AB\[rq] would equal \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],
while with clamping on and an \f[B]ibase\f[R] of \f[B]3\f[R], the string
\[lq]AB\[rq] would be 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
This value is \f[I]thread-local\f[R]; it applies to just the thread it
is read on.
.PP
The default is \f[B]true\f[R].
.RE
.TP
\f[B]void bcl_setDigitClamp(bool\f[R] \f[I]digitClamp\f[R]\f[B])\f[R]
Sets the state of whether digits in number strings that are greater than
or equal to the current \f[B]ibase\f[R] are clamped or not.
For more information, see the
\f[B]bcl_digitClamp(\f[R]\f[I]void\f[R]\f[B])\f[R] function.
.RS
.PP
This value is \f[I]thread-local\f[R]; it applies to just the thread it
is set on.
.RE
.TP
\f[B]void bcl_gc(\f[R]\f[I]void\f[R]\f[B])\f[R]
Garbage collects cached instances of arbitrary-precision numbers.
@ -392,6 +456,15 @@ Numbers created in one context are not valid in another context.
It is undefined behavior to use a number created in a different context.
Contexts are meant to isolate the numbers used by different clients in
the same application.
.PP
Different threads also have different contexts, so any numbers created
in one thread are not valid in another thread.
To pass values between contexts and threads, use \f[B]bcl_string()\f[R]
to produce a string to pass around, and use \f[B]bcl_parse()\f[R] to
parse the string.
It is suggested that the \f[B]obase\f[R] used to create the string be
passed around with the string and used as the \f[B]ibase\f[R] for
\f[B]bcl_parse()\f[R] to ensure that the number will be the same.
.RE
.TP
\f[B]BclContext bcl_ctxt_create(\f[R]\f[I]void\f[R]\f[B])\f[R]
@ -1200,9 +1273,6 @@ An invalid \f[B]BclNumber\f[R] was given as a parameter.
\f[B]BCL_ERROR_INVALID_CONTEXT\f[R]
An invalid \f[B]BclContext\f[R] is being used.
.TP
\f[B]BCL_ERROR_SIGNAL\f[R]
A signal interrupted execution.
.TP
\f[B]BCL_ERROR_MATH_NEGATIVE\f[R]
A negative number was given as an argument to a parameter that cannot
accept negative numbers, such as for square roots.
@ -1278,11 +1348,16 @@ this behavior.
.RE
.SH ATTRIBUTES
.PP
When \f[B]bcl_handleSignal(\f[R]\f[I]void\f[R]\f[B])\f[R] is used
properly, bcl(3) is async-signal-safe.
bcl(3) is \f[I]MT-Safe\f[R]: it is safe to call any functions from more
than one thread.
However, is is \f[I]not\f[R] safe to pass any data between threads
except for strings returned by \f[B]bcl_string()\f[R].
.PP
bcl(3) is \f[I]MT-Unsafe\f[R]: it is unsafe to call any functions from
more than one thread.
bcl(3) is not \f[I]async-signal-safe\f[R].
It was not possible to make bcl(3) safe with signals and also make it
safe with multiple threads.
If it is necessary to be able to interrupt bcl(3), spawn a separate
thread to run the calculation.
.SH PERFORMANCE
.PP
Most bc(1) implementations use \f[B]char\f[R] types to calculate the
@ -1354,24 +1429,6 @@ These limits are meant to be effectively non-existent; the limits are so
large (at least on 64-bit machines) that there should not be any point
at which they become a problem.
In fact, memory should be exhausted before these limits should be hit.
.SH SIGNAL HANDLING
.PP
If a signal handler calls
\f[B]bcl_handleSignal(\f[R]\f[I]void\f[R]\f[B])\f[R] from the same
thread that there are bcl(3) functions executing in, it will cause all
execution to stop as soon as possible, interrupting long-running
calculations, if necessary and cause the function that was executing to
return.
If possible, the error code \f[B]BC_ERROR_SIGNAL\f[R] is returned.
.PP
If execution \f[I]is\f[R] interrupted,
\f[B]bcl_handleSignal(\f[R]\f[I]void\f[R]\f[B])\f[R] does \f[I]not\f[R]
return to its caller.
.PP
It is undefined behavior if
\f[B]bcl_handleSignal(\f[R]\f[I]void\f[R]\f[B])\f[R] is called from a
thread that is not executing bcl(3) functions, if bcl(3) functions are
executing.
.SH SEE ALSO
.PP
bc(1) and dc(1)

171
contrib/bc/manuals/bcl.3.md
View File

@ -2,7 +2,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:
@ -38,21 +38,16 @@ bcl - library of arbitrary precision decimal arithmetic
*#include <bcl.h>*
Link with *-lbcl*.
## Signals
This procedure will allow clients to use signals to interrupt computations
running in bcl(3).
**void bcl_handleSignal(**_void_**);**
**bool bcl_running(**_void_**);**
Link with *-lbcl*, and on POSIX systems, *-lpthread* is also required.
## Setup
These items allow clients to set up bcl(3).
**BclError bcl_start(**_void_**);**
**void bcl_end(**_void_**);**
**BclError bcl_init(**_void_**);**
**void bcl_free(**_void_**);**
@ -67,6 +62,10 @@ These items allow clients to set up bcl(3).
**void bcl_gc(**_void_**);**
**bool bcl_digitClamp(**_void_**);**
**void bcl_setDigitClamp(bool** _digitClamp_**);**
## Contexts
These items will allow clients to handle contexts, which are isolated from each
@ -218,48 +217,22 @@ bcl(3) is a library that implements arbitrary-precision decimal math, as
standardized by POSIX
(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html) in bc(1).
bcl(3) is async-signal-safe if **bcl_handleSignal(**_void_**)** is used
properly. (See the **SIGNAL HANDLING** section.)
bcl(3) assumes that it is allowed to use the **bcl**, **Bcl**, **bc**, and
**Bc** prefixes for symbol names without collision.
All of the items in its interface are described below. See the documentation for
each function for what each function can return.
## Signals
**void bcl_handleSignal(**_void_**)**
: An async-signal-safe function that can be called from a signal handler. If
called from a signal handler on the same thread as any executing bcl(3)
functions, it will interrupt the functions and force them to return early.
It is undefined behavior if this function is called from a thread that is
*not* executing any bcl(3) functions while any bcl(3) functions are
executing.
If execution *is* interrupted, **bcl_handleSignal(**_void_**)** does *not*
return to its caller.
See the **SIGNAL HANDLING** section.
**bool bcl_running(**_void_**)**
: An async-signal-safe function that can be called from a signal handler. It
will return **true** if any bcl(3) procedures are running, which means it is
safe to call **bcl_handleSignal(**_void_**)**. Otherwise, it returns
**false**.
See the **SIGNAL HANDLING** section.
## Setup
**BclError bcl_init(**_void_**)**
**BclError bcl_start(**_void_**)**
: Initializes this library. This function can be called multiple times, but
each call must be matched by a call to **bcl_free(**_void_**)**. This is to
make it possible for multiple libraries and applications to initialize
bcl(3) without problem.
**bcl_end()** must only be called *once*. This is to make it possible for
multiple libraries and applications to initialize bcl(3) without problem.
It is suggested that client libraries call this function, but do not call
**bcl_end()**, and client applications should call both.
If there was no error, **BCL_ERROR_NONE** is returned. Otherwise, this
function can return:
@ -269,13 +242,48 @@ each function for what each function can return.
This function must be the first one clients call. Calling any other
function without calling this one first is undefined behavior.
**void bcl_end(**_void_**)**
: Deinitializes this library. This function must only be called *once*.
All data must have been freed before calling this function.
This function must be the last one clients call. Calling this function
before calling any other function is undefined behavior.
**BclError bcl_init(**_void_**)**
: Initializes the library for the current thread. This function can be called
multiple times, but each call must be matched by a call to
**bcl_free(**_void_**)**. This is to make it possible for multiple libraries
and applications to initialize threads for bcl(3) without problem.
This function *must* be called from the thread that it is supposed to
initialize.
If there was no error, **BCL_ERROR_NONE** is returned. Otherwise, this
function can return:
* **BCL_ERROR_FATAL_ALLOC_ERR**
This function must be the second one clients call. Calling any other
function without calling **bcl_start()** and then this one first is
undefined behavior, except in the case of new threads. New threads can
safely call this function without calling **bcl_start()** if another thread
has previously called **bcl_start()**. But this function must still be the
first function in bcl(3) called by that new thread.
**void bcl_free(**_void_**)**
: Decrements bcl(3)'s reference count and frees the data associated with it if
the reference count is **0**.
This function must be the last one clients call. Calling this function
before calling any other function is undefined behavior.
This function *must* be called from the thread that it is supposed to
deinitialize.
This function must be the second to last one clients call. Calling this
function before calling any other function besides **bcl_end()** is
undefined behavior.
**bool bcl_abortOnFatalError(**_void_**)**
@ -285,6 +293,8 @@ each function for what each function can return.
If activated, clients do not need to check for fatal errors.
This value is *thread-local*; it applies to just the thread it is read on.
The default is **false**.
**void bcl_setAbortOnFatalError(bool** _abrt_**)**
@ -294,6 +304,8 @@ each function for what each function can return.
call. If *abrt* is **true**, bcl(3) will cause a **SIGABRT** on fatal errors
after the call.
This value is *thread-local*; it applies to just the thread it is set on.
If activated, clients do not need to check for fatal errors.
**bool bcl_leadingZeroes(**_void_**)**
@ -303,6 +315,8 @@ each function for what each function can return.
**1**, and not equal to **0**. If **true** is returned, then leading zeroes
will be added.
This value is *thread-local*; it applies to just the thread it is read on.
The default is **false**.
**void bcl_setLeadingZeroes(bool** _leadingZeroes_**)**
@ -312,6 +326,37 @@ each function for what each function can return.
not equal to **0**. If *leadingZeroes* is **true**, leading zeroes will be
added to strings returned by **bcl_string()**.
This value is *thread-local*; it applies to just the thread it is set on.
**bool bcl_digitClamp(**_void_**)**
: Queries and returns the state of whether digits in number strings that are
greater than or equal to the current **ibase** are clamped or not.
If **true** is returned, then digits are treated as though they are equal to
the value of **ibase** minus **1**. If this is *not* true, then digits are
treated as though they are equal to the value they would have if **ibase**
was large enough. They are then multiplied by the appropriate power of
**ibase**.
For example, with clamping off and an **ibase** of **3**, the string "AB"
would equal **3\^1\*A+3\^0\*B**, which is **3** times **10** plus **11**, or
**41**, while with clamping on and an **ibase** of **3**, the string "AB"
would be equal to **3\^1\*2+3\^0\*2**, which is **3** times **2** plus
**2**, or **8**.
This value is *thread-local*; it applies to just the thread it is read on.
The default is **true**.
**void bcl_setDigitClamp(bool** _digitClamp_**)**
: Sets the state of whether digits in number strings that are greater than or
equal to the current **ibase** are clamped or not. For more information, see
the **bcl_digitClamp(**_void_**)** function.
This value is *thread-local*; it applies to just the thread it is set on.
**void bcl_gc(**_void_**)**
: Garbage collects cached instances of arbitrary-precision numbers. This only
@ -357,6 +402,13 @@ an argument.
are meant to isolate the numbers used by different clients in the same
application.
Different threads also have different contexts, so any numbers created in
one thread are not valid in another thread. To pass values between contexts
and threads, use **bcl_string()** to produce a string to pass around, and
use **bcl_parse()** to parse the string. It is suggested that the **obase**
used to create the string be passed around with the string and used as the
**ibase** for **bcl_parse()** to ensure that the number will be the same.
**BclContext bcl_ctxt_create(**_void_**)**
: Creates a context and returns it. Returns **NULL** if there was an error.
@ -1015,10 +1067,6 @@ codes defined in **BclError**. The complete list of codes is the following:
: An invalid **BclContext** is being used.
**BCL_ERROR_SIGNAL**
: A signal interrupted execution.
**BCL_ERROR_MATH_NEGATIVE**
: A negative number was given as an argument to a parameter that cannot accept
@ -1088,11 +1136,13 @@ codes defined in **BclError**. The complete list of codes is the following:
# ATTRIBUTES
When **bcl_handleSignal(**_void_**)** is used properly, bcl(3) is
async-signal-safe.
bcl(3) is *MT-Safe*: it is safe to call any functions from more than one thread.
However, is is *not* safe to pass any data between threads except for strings
returned by **bcl_string()**.
bcl(3) is *MT-Unsafe*: it is unsafe to call any functions from more than one
thread.
bcl(3) is not *async-signal-safe*. It was not possible to make bcl(3) safe with
signals and also make it safe with multiple threads. If it is necessary to be
able to interrupt bcl(3), spawn a separate thread to run the calculation.
# PERFORMANCE
@ -1164,21 +1214,6 @@ These limits are meant to be effectively non-existent; the limits are so large
become a problem. In fact, memory should be exhausted before these limits should
be hit.
# SIGNAL HANDLING
If a signal handler calls **bcl_handleSignal(**_void_**)** from the same thread
that there are bcl(3) functions executing in, it will cause all execution to
stop as soon as possible, interrupting long-running calculations, if necessary
and cause the function that was executing to return. If possible, the error code
**BC_ERROR_SIGNAL** is returned.
If execution *is* interrupted, **bcl_handleSignal(**_void_**)** does *not*
return to its caller.
It is undefined behavior if **bcl_handleSignal(**_void_**)** is called from
a thread that is not executing bcl(3) functions, if bcl(3) functions are
executing.
# SEE ALSO
bc(1) and dc(1)

131
contrib/bc/manuals/build.md
View File

@ -132,7 +132,7 @@ the environment variable `GEN_EMU`.
This `bc` supports `CC`, `HOSTCC`, `HOST_CC`, `CFLAGS`, `HOSTCFLAGS`,
`HOST_CFLAGS`, `CPPFLAGS`, `LDFLAGS`, `LDLIBS`, `PREFIX`, `DESTDIR`, `BINDIR`,
`DATAROOTDIR`, `DATADIR`, `MANDIR`, `MAN1DIR`, `LOCALEDIR` `EXECSUFFIX`,
`DATAROOTDIR`, `DATADIR`, `MANDIR`, `MAN1DIR`, `MAN3DIR`, `EXECSUFFIX`,
`EXECPREFIX`, `LONG_BIT`, `GEN_HOST`, and `GEN_EMU` environment variables in
`configure.sh`. Any values of those variables given to `configure.sh` will be
put into the generated Makefile.
@ -205,6 +205,10 @@ Can be overridden by passing the `--prefix` option to `configure.sh`.
Defaults to `/usr/local`.
***WARNING***: Locales ignore the prefix because they *must* be installed at a
fixed location to work at all. If you do not want that to happen, you must
disable locales (NLS) completely.
#### `DESTDIR`
Path to prepend onto `PREFIX`. This is mostly for distro and package
@ -272,13 +276,13 @@ Can be overridden by passing the `--man1dir` option to `configure.sh`.
Defaults to `$MANDIR/man1`.
#### `LOCALEDIR`
#### `MAN3DIR`
The directory to install locales in.
The directory to install Section 3 manpages in.
Can be overridden by passing the `--localedir` option to `configure.sh`.
Can be overridden by passing the `--man3dir` option to `configure.sh`.
Defaults to `$DATAROOTDIR/locale`.
Defaults to `$MANDIR/man3`.
#### `EXECSUFFIX`
@ -355,6 +359,30 @@ following forms:
--option=arg
```
#### Predefined Builds
To quickly get a release build of a `bc` and `dc` that is (by default)
compatible with the BSD `bc` and `dc`, use the `-p` or `--predefined-build-type`
options:
```
./configure.sh -pBSD
./configure.sh --predefined-build-type=BSD
```
Both commands are equivalent.
To quickly get a release build of a `bc` and `dc` that is (by default)
compatible with the GNU `bc` and `dc`, use the `-p` or `--predefined-build-type`
options:
```
./configure.sh -pGNU
./configure.sh --predefined-build-type=GNU
```
Both commands are equivalent.
#### Library
To build the math library, use the following commands for the configure step:
@ -435,7 +463,7 @@ This option affects the [build type][7].
History support can be provided by editline, in order to implement `vi`-like
keybindings and other features.
To enable editline support pass either the `-e` flag or the `--enable-editline`
To enable editline support, pass either the `-e` flag or the `--enable-editline`
option to `configure.sh`, as follows:
```
@ -447,12 +475,16 @@ Both commands are equivalent.
This is ignored if history is disabled.
This option is only used if it is after any other `-e`/`--enable-editline`
options, any `-r`/`--enable-readline` options, and any
`-i`/`--enable-internal-history` options.
##### Readline
History support can be provided by readline, in order to implement `vi`-like
keybindings and other features.
To enable readline support pass either the `-r` flag or the `--enable-readline`
To enable readline support, pass either the `-r` flag or the `--enable-readline`
option to `configure.sh`, as follows:
```
@ -464,6 +496,30 @@ Both commands are equivalent.
This is ignored if history is disabled.
This option is only used if it is after any other `-r`/`--enable-readline`
options, any `-e`/`--enable-editline` options, and any
`-i`/`--enable-internal-history` options.
##### Internal History
History support is also available as an internal implementation with no
dependencies. This is the default if editline and readline are not selected.
However, if `-p` option is used, then this option can be useful for selecting
the internal history regardless of what the predefined build has.
To enable the internal history, pass either the `-i` flag or the
`--enable-internal-history` option to `configure.sh` as follows:
```
./configure.sh -i
./configure.sh --enable-internal-history
```
This option is only used if it is after any other
`-i`/`--enable-internal-history` options, any `-e`/`--enable-editline` options,
and any `-r`/`--enable-readline` options.
#### NLS (Locale Support)
To disable locale support (use only English), pass either the `-N` flag or the
@ -481,6 +537,10 @@ another platform that does not support the POSIX locale API or utilities.
This option affects the [build type][7].
***WARNING***: Locales ignore the prefix because they *must* be installed at a
fixed location to work at all. If you do not want that to happen, you must
disable locales (NLS) completely.
#### Extra Math
This `bc` has 7 extra operators:
@ -607,6 +667,32 @@ environment variables to override them, is below:
| | for dc should be on | | |
| | in tty mode. | | |
| --------------- | -------------------- | ------------ | -------------------- |
| bc.expr_exit | Whether to exit bc | 1 | BC_EXPR_EXIT |
| | if an expression or | | |
| | expression file is | | |
| | given with the -e or | | |
| | -f options. | | |
| --------------- | -------------------- | ------------ | -------------------- |
| dc.expr_exit | Whether to exit dc | 1 | DC_EXPR_EXIT |
| | if an expression or | | |
| | expression file is | | |
| | given with the -e or | | |
| | -f options. | | |
| --------------- | -------------------- | ------------ | -------------------- |
| bc.digit_clamp | Whether to have bc | 0 | BC_DIGIT_CLAMP |
| | clamp digits that | | |
| | are greater than or | | |
| | equal to the current | | |
| | ibase when parsing | | |
| | numbers. | | |
| --------------- | -------------------- | ------------ | -------------------- |
| dc.digit_clamp | Whether to have dc | 0 | DC_DIGIT_CLAMP |
| | clamp digits that | | |
| | are greater than or | | |
| | equal to the current | | |
| | ibase when parsing | | |
| | numbers. | | |
| --------------- | -------------------- | ------------ | -------------------- |
```
These settings are not meant to be changed on a whim. They are meant to ensure
@ -623,19 +709,22 @@ The relevant `autotools`-style install options are supported in `configure.sh`:
* `--datadir`
* `--mandir`
* `--man1dir`
* `--localedir`
* `--man3dir`
An example is:
```
./configure.sh --prefix=/usr --localedir /usr/share/nls
./configure.sh --prefix=/usr
make
make install
```
They correspond to the environment variables `$PREFIX`, `$BINDIR`,
`$DATAROOTDIR`, `$DATADIR`, `$MANDIR`, `$MAN1DIR`, and `$LOCALEDIR`,
respectively.
`$DATAROOTDIR`, `$DATADIR`, `$MANDIR`, `$MAN1DIR`, `$MAN3DIR`, and respectively.
***WARNING***: Locales ignore the prefix because they *must* be installed at a
fixed location to work at all. If you do not want that to happen, you must
disable locales (NLS) completely.
***WARNING***: If the option is given, the value of the corresponding
environment variable is overridden.
@ -672,6 +761,10 @@ have, regardless. To enable that behavior, you can pass the `-l` flag or the
Both commands are equivalent.
***WARNING***: Locales ignore the prefix because they *must* be installed at a
fixed location to work at all. If you do not want that to happen, you must
disable locales (NLS) completely.
### Optimization
The `configure.sh` script will accept an optimization level to pass to the
@ -873,6 +966,22 @@ Both commands are equivalent.
***WARNING***: Both `bc` and `dc` must be built for test coverage. Otherwise,
`configure.sh` will give an error.
#### Problematic Tests
Some tests are problematic, in that they can cause `SIGKILL` on FreeBSD or
`SIGSEGV` on Linux from being killed by the "OOM Killer" part of the kernel. On
Linux, these tests are usually fine, but on FreeBSD, they are usually a problem.
To disable problematic tests, pass the `-P` flag or the
`--disable-problematic-tests` option to `configure.sh` as follows:
```
./configure.sh -P
./configure.sh --disable-problematic-tests
```
Both commands are equivalent.
[1]: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html
[2]: https://www.gnu.org/software/bc/
[3]: https://www.musl-libc.org/

316
contrib/bc/manuals/dc/A.1
View File

@ -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,7 +25,7 @@
.\" 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" "October 2022" "Gavin D. Howard" "General Commands Manual"
.nh
.ad l
.SH Name
@ -33,17 +33,19 @@
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.
@ -65,83 +67,54 @@ and this dc(1) will always start with a \f[B]scale\f[R] of \f[B]10\f[R].
.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 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]-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).
\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]-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].
\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
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]-x\f[R] \f[B]--extended-register\f[R]
Enables extended register mode.
See the \f[I]Extended Register Mode\f[R] subsection of the
\f[B]REGISTERS\f[R] section for more information.
.RS
.PP
This is a \f[B]non-portable extension\f[R].
.RE
.TP
\f[B]-z\f[R], \f[B]--leading-zeroes\f[R]
Makes dc(1) print all numbers greater than \f[B]-1\f[R] and less than
\f[B]1\f[R], and not equal to \f[B]0\f[R], with a leading zero.
.RS
.PP
This can be set for individual numbers with the \f[B]plz(x)\f[R],
plznl(x)**, \f[B]pnlz(x)\f[R], and \f[B]pnlznl(x)\f[R] functions in the
extended math library (see the \f[B]LIBRARY\f[R] section).
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 +162,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 +176,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 +205,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,13 +254,26 @@ 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 can be set for individual numbers with the \f[B]plz(x)\f[R],
plznl(x)**, \f[B]pnlz(x)\f[R], and \f[B]pnlznl(x)\f[R] functions in the
extended math library (see the \f[B]LIBRARY\f[R] section).
.PP
This is a \f[B]non-portable extension\f[R].
.RE
@ -360,17 +405,48 @@ This is a \f[B]non-portable extension\f[R].
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].
@ -1081,6 +1157,10 @@ 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.
.RS
.PP
This is a \f[B]non-portable extension\f[R].
.RE
.SS Status
.PP
These commands query status of the stack or its top value.
@ -1107,6 +1187,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.
@ -1298,7 +1396,8 @@ 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,6 +1501,22 @@ 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
.TP
\f[B]DC_DIGIT_CLAMP\f[R]
When parsing numbers and if this environment variable exists and
contains an integer, a non-zero value makes dc(1) clamp digits that are
greater than or equal to the current \f[B]ibase\f[R] so that all such
digits are considered equal to the \f[B]ibase\f[R] minus 1, and a zero
value disables such clamping so that those digits are always equal to
their value, which is multiplied by the power of the \f[B]ibase\f[R].
.RS
.PP
This never applies to single-digit numbers, as per the bc(1) standard
(see the \f[B]STANDARDS\f[R] section).
.PP
This environment variable overrides the default, which can be queried
with the \f[B]-h\f[R] or \f[B]--help\f[R] options.
.RE
.SH EXIT STATUS
.PP
dc(1) returns the following exit statuses:
@ -1505,10 +1620,9 @@ 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
@ -1597,14 +1711,14 @@ locales and thus, supports \f[B]LC_MESSAGES\f[R].
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.yzena.com/gavin/bc .
.SH AUTHOR
.PP
Gavin D.

246
contrib/bc/manuals/dc/A.1.md
View File

@ -2,7 +2,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:
@ -34,7 +34,7 @@ dc - arbitrary-precision decimal reverse-Polish notation calculator
# SYNOPSIS
**dc** [**-hiPRvVx**] [**-\-version**] [**-\-help**] [**-\-interactive**] [**-\-no-prompt**] [**-\-no-read-prompt**] [**-\-extended-register**] [**-e** *expr*] [**-\-expression**=*expr*...] [**-f** *file*...] [**-\-file**=*file*...] [*file*...] [**-I** *ibase*] [**-\-ibase**=*ibase*] [**-O** *obase*] [**-\-obase**=*obase*] [**-S** *scale*] [**-\-scale**=*scale*] [**-E** *seed*] [**-\-seed**=*seed*]
**dc** [**-cChiPRvVx**] [**-\-version**] [**-\-help**] [**-\-digit-clamp**] [**-\-no-digit-clamp**] [**-\-interactive**] [**-\-no-prompt**] [**-\-no-read-prompt**] [**-\-extended-register**] [**-e** *expr*] [**-\-expression**=*expr*...] [**-f** *file*...] [**-\-file**=*file*...] [*file*...] [**-I** *ibase*] [**-\-ibase**=*ibase*] [**-O** *obase*] [**-\-obase**=*obase*] [**-S** *scale*] [**-\-scale**=*scale*] [**-E** *seed*] [**-\-seed**=*seed*]
# DESCRIPTION
@ -55,73 +55,49 @@ this dc(1) will always start with a **scale** of **10**.
The following are the options that dc(1) accepts.
**-h**, **-\-help**
**-C**, **-\-no-digit-clamp**
: Prints a usage message and quits.
: Disables clamping of digits greater than or equal to the current **ibase**
when parsing numbers.
**-v**, **-V**, **-\-version**
This means that the value added to a number from a digit is always that
digit's value multiplied by the value of ibase raised to the power of the
digit's position, which starts from 0 at the least significant digit.
: Print the version information (copyright header) and exit.
If this and/or the **-c** or **-\-digit-clamp** options are given multiple
times, the last one given is used.
**-i**, **-\-interactive**
: Forces interactive mode. (See the **INTERACTIVE MODE** section.)
This option overrides the **DC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section) and the default, which can be queried
with the **-h** or **-\-help** options.
This is a **non-portable extension**.
**-L**, **-\-no-line-length**
**-c**, **-\-digit-clamp**
: Disables line length checking and prints numbers without backslashes and
newlines. In other words, this option sets **BC_LINE_LENGTH** to **0** (see
the **ENVIRONMENT VARIABLES** section).
: Enables clamping of digits greater than or equal to the current **ibase**
when parsing numbers.
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's
position, which starts from 0 at the least significant digit.
If this and/or the **-C** or **-\-no-digit-clamp** options are given
multiple times, the last one given is used.
This option overrides the **DC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section) and the default, which can be queried
with the **-h** or **-\-help** options.
This is a **non-portable extension**.
**-P**, **-\-no-prompt**
**-E** *seed*, **-\-seed**=*seed*
: Disables the prompt in TTY mode. (The prompt is only enabled in TTY mode.
See the **TTY MODE** 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 **DC_ENV_ARGS**.
: Sets the builtin variable **seed** to the value *seed* assuming that *seed*
is in base 10. It is a fatal error if *seed* is not a valid number.
These options override the **DC_PROMPT** and **DC_TTY_MODE** environment
variables (see the **ENVIRONMENT VARIABLES** section).
This is a **non-portable extension**.
**-R**, **-\-no-read-prompt**
: Disables the read prompt in TTY mode. (The read prompt is only enabled in
TTY mode. See the **TTY MODE** 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 **BC_ENV_ARGS** (see the
**ENVIRONMENT VARIABLES** section). This option is also useful in hash bang
lines of dc(1) scripts that prompt for user input.
This option does not disable the regular prompt because the read prompt is
only used when the **?** command is used.
These options *do* override the **DC_PROMPT** and **DC_TTY_MODE**
environment variables (see the **ENVIRONMENT VARIABLES** section), but only
for the read prompt.
This is a **non-portable extension**.
**-x** **-\-extended-register**
: Enables extended register mode. See the *Extended Register Mode* subsection
of the **REGISTERS** section for more information.
This is a **non-portable extension**.
**-z**, **-\-leading-zeroes**
: Makes dc(1) print all numbers greater than **-1** and less than **1**, and
not equal to **0**, with a leading zero.
This can be set for individual numbers with the **plz(x)**, plznl(x)**,
**pnlz(x)**, and **pnlznl(x)** functions in the extended math library (see
the **LIBRARY** section).
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
@ -157,6 +133,10 @@ The following are the options that dc(1) accepts.
This is a **non-portable extension**.
**-h**, **-\-help**
: Prints a usage message and exits.
**-I** *ibase*, **-\-ibase**=*ibase*
: Sets the builtin variable **ibase** to the value *ibase* assuming that
@ -166,6 +146,20 @@ The following are the options that dc(1) accepts.
This is a **non-portable extension**.
**-i**, **-\-interactive**
: Forces interactive mode. (See the **INTERACTIVE MODE** section.)
This is a **non-portable extension**.
**-L**, **-\-no-line-length**
: Disables line length checking and prints numbers without backslashes and
newlines. In other words, this option sets **BC_LINE_LENGTH** to **0** (see
the **ENVIRONMENT VARIABLES** section).
This is a **non-portable extension**.
**-O** *obase*, **-\-obase**=*obase*
: Sets the builtin variable **obase** to the value *obase* assuming that
@ -175,6 +169,36 @@ The following are the options that dc(1) accepts.
This is a **non-portable extension**.
**-P**, **-\-no-prompt**
: Disables the prompt in TTY mode. (The prompt is only enabled in TTY mode.
See the **TTY MODE** 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 **DC_ENV_ARGS**.
These options override the **DC_PROMPT** and **DC_TTY_MODE** environment
variables (see the **ENVIRONMENT VARIABLES** section).
This is a **non-portable extension**.
**-R**, **-\-no-read-prompt**
: Disables the read prompt in TTY mode. (The read prompt is only enabled in
TTY mode. See the **TTY MODE** 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 **BC_ENV_ARGS** (see the
**ENVIRONMENT VARIABLES** section). This option is also useful in hash bang
lines of dc(1) scripts that prompt for user input.
This option does not disable the regular prompt because the read prompt is
only used when the **?** command is used.
These options *do* override the **DC_PROMPT** and **DC_TTY_MODE**
environment variables (see the **ENVIRONMENT VARIABLES** section), but only
for the read prompt.
This is a **non-portable extension**.
**-S** *scale*, **-\-scale**=*scale*
: Sets the builtin variable **scale** to the value *scale* assuming that
@ -184,12 +208,25 @@ The following are the options that dc(1) accepts.
This is a **non-portable extension**.
**-E** *seed*, **-\-seed**=*seed*
**-v**, **-V**, **-\-version**
: Sets the builtin variable **seed** to the value *seed* assuming that *seed*
is in base 10. It is a fatal error if *seed* is not a valid number.
: Print the version information (copyright header) and exits.
If multiple instances of this option are given, the last is used.
**-x** **-\-extended-register**
: Enables extended register mode. See the *Extended Register Mode* subsection
of the **REGISTERS** section for more information.
This is a **non-portable extension**.
**-z**, **-\-leading-zeroes**
: Makes dc(1) print all numbers greater than **-1** and less than **1**, and
not equal to **0**, with a leading zero.
This can be set for individual numbers with the **plz(x)**, plznl(x)**,
**pnlz(x)**, and **pnlznl(x)** functions in the extended math library (see
the **LIBRARY** section).
This is a **non-portable extension**.
@ -302,15 +339,40 @@ Comments go from **#** until, and not including, the next newline. This is a
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 are equal to **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**.
Uppercase letters are equal to **9** plus their position in the alphabet (i.e.,
**A** equals **10**, or **9+1**).
Single-character numbers (i.e., **A** alone) take the value that they would have
if they were valid digits, regardless of the value of **ibase**. This means that
**A** alone always equals decimal **10** and **F** alone always equals decimal
**15**.
If a digit or letter makes no sense with the current value of **ibase** (i.e.,
they are greater than or equal to the current value of **ibase**), then the
behavior depends on the existence of the **-c**/**-\-digit-clamp** or
**-C**/**-\-no-digit-clamp** options (see the **OPTIONS** section), the
existence and setting of the **DC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section), or the default, which can be queried with
the **-h**/**-\-help** option.
If clamping is off, then digits or letters that are greater than or equal to the
current value of **ibase** are not changed. Instead, their given value is
multiplied by the appropriate power of **ibase** and added into the number. This
means that, with an **ibase** of **3**, the number **AB** is equal to
**3\^1\*A+3\^0\*B**, which is **3** times **10** plus **11**, or **41**.
If clamping is on, then digits or letters that are greater than or equal to the
current value of **ibase** are set to the value of the highest valid digit in
**ibase** before being multiplied by the appropriate power of **ibase** and
added into the number. This means that, with an **ibase** of **3**, the number
**AB** is equal to **3\^1\*2+3\^0\*2**, which is **3** times **2** plus **2**,
or **8**.
There is one exception to clamping: single-character numbers (i.e., **A**
alone). Such numbers are never clamped and always take the value they would have
in the highest possible **ibase**. This means that **A** alone always equals
decimal **10** and **Z** alone always equals decimal **35**. 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 **ibase** (with the **i** command)
regardless of the current value of **ibase**.
If clamping is on, and the clamped value of a character is needed, use a leading
zero, i.e., for **A**, use **0A**.
In addition, dc(1) accepts numbers in scientific notation. These have the form
**\<number\>e\<integer\>**. The exponent (the portion after the **e**) must be
@ -938,6 +1000,8 @@ will be printed with a newline after and then popped from the stack.
is exactly as many as is needed to make dc(1) exit with the **Q** command,
so the sequence **,Q** will make dc(1) exit.
This is a **non-portable extension**.
## Status
These commands query status of the stack or its top value.
@ -960,6 +1024,20 @@ These commands query status of the stack or its top value.
If it is a string, pushes **0**.
**u**
: Pops one value off of the stack. If the value is a number, this pushes **1**
onto the stack. Otherwise (if it is a string), it pushes **0**.
This is a **non-portable extension**.
**t**
: Pops one value off of the stack. If the value is a string, this pushes **1**
onto the stack. Otherwise (if it is a number), it pushes **0**.
This is a **non-portable extension**.
**z**
: Pushes the current depth of the stack (before execution of this command)
@ -1148,7 +1226,8 @@ be hit.
# ENVIRONMENT VARIABLES
dc(1) recognizes the following environment variables:
As **non-portable extensions**, dc(1) recognizes the following environment
variables:
**DC_ENV_ARGS**
@ -1237,6 +1316,21 @@ dc(1) recognizes the following environment variables:
This environment variable overrides the default, which can be queried with
the **-h** or **-\-help** options.
**DC_DIGIT_CLAMP**
: 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 **ibase** so that all such digits are considered equal
to the **ibase** 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 **ibase**.
This never applies to single-digit numbers, as per the bc(1) standard (see
the **STANDARDS** section).
This environment variable overrides the default, which can be queried with
the **-h** or **-\-help** options.
# EXIT STATUS
dc(1) returns the following exit statuses:
@ -1333,10 +1427,8 @@ setting is used. The default setting can be queried with the **-h** or
**-\-help** options.
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 **stdin** and **stdout** to be connected to a
terminal.
in the bc(1) specification (see the **STANDARDS** section), and interactive mode
requires only **stdin** and **stdout** to be connected to a terminal.
## Command-Line History
@ -1419,13 +1511,13 @@ bc(1)
# STANDARDS
The dc(1) utility operators are compliant with the operators in the IEEE Std
1003.1-2017 (“POSIX.1-2017”) 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 (“POSIX.1-2017”) bc(1) specification at
https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html .
# BUGS
None are known. Report bugs at https://git.yzena.com/gavin/bc.
None are known. Report bugs at https://git.yzena.com/gavin/bc .
# AUTHOR

302
contrib/bc/manuals/dc/E.1
View File

@ -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,7 +25,7 @@
.\" 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" "October 2022" "Gavin D. Howard" "General Commands Manual"
.nh
.ad l
.SH Name
@ -33,12 +33,14 @@
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
@ -61,83 +63,43 @@ and this dc(1) will always start with a \f[B]scale\f[R] of \f[B]10\f[R].
.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 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]-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).
\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 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
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 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).
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]-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]-x\f[R] \f[B]--extended-register\f[R]
Enables extended register mode.
See the \f[I]Extended Register Mode\f[R] subsection of the
\f[B]REGISTERS\f[R] section for more information.
.RS
.PP
This is a \f[B]non-portable extension\f[R].
.RE
.TP
\f[B]-z\f[R], \f[B]--leading-zeroes\f[R]
Makes dc(1) print all numbers greater than \f[B]-1\f[R] and less than
\f[B]1\f[R], and not equal to \f[B]0\f[R], with a leading zero.
.RS
.PP
This can be set for individual numbers with the \f[B]plz(x)\f[R],
plznl(x)**, \f[B]pnlz(x)\f[R], and \f[B]pnlznl(x)\f[R] functions in the
extended math library (see the \f[B]LIBRARY\f[R] section).
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
@ -185,6 +147,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.
@ -196,6 +161,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.
@ -207,6 +190,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.
@ -217,6 +238,30 @@ If multiple instances of this option are given, the last is used.
.PP
This is a \f[B]non-portable extension\f[R].
.RE
.TP
\f[B]-v\f[R], \f[B]-V\f[R], \f[B]--version\f[R]
Print the version information (copyright header) and exits.
.TP
\f[B]-x\f[R] \f[B]--extended-register\f[R]
Enables extended register mode.
See the \f[I]Extended Register Mode\f[R] subsection of the
\f[B]REGISTERS\f[R] section for more information.
.RS
.PP
This is a \f[B]non-portable extension\f[R].
.RE
.TP
\f[B]-z\f[R], \f[B]--leading-zeroes\f[R]
Makes dc(1) print all numbers greater than \f[B]-1\f[R] and less than
\f[B]1\f[R], and not equal to \f[B]0\f[R], with a leading zero.
.RS
.PP
This can be set for individual numbers with the \f[B]plz(x)\f[R],
plznl(x)**, \f[B]pnlz(x)\f[R], and \f[B]pnlznl(x)\f[R] functions in the
extended math library (see the \f[B]LIBRARY\f[R] section).
.PP
This is a \f[B]non-portable extension\f[R].
.RE
.PP
All long options are \f[B]non-portable extensions\f[R].
.SH STDIN
@ -307,17 +352,48 @@ This is a \f[B]non-portable extension\f[R].
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.
@ -866,6 +942,10 @@ 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.
.RS
.PP
This is a \f[B]non-portable extension\f[R].
.RE
.SS Status
.PP
These commands query status of the stack or its top value.
@ -892,6 +972,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.
@ -1078,7 +1176,8 @@ 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).
@ -1182,6 +1281,22 @@ 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
.TP
\f[B]DC_DIGIT_CLAMP\f[R]
When parsing numbers and if this environment variable exists and
contains an integer, a non-zero value makes dc(1) clamp digits that are
greater than or equal to the current \f[B]ibase\f[R] so that all such
digits are considered equal to the \f[B]ibase\f[R] minus 1, and a zero
value disables such clamping so that those digits are always equal to
their value, which is multiplied by the power of the \f[B]ibase\f[R].
.RS
.PP
This never applies to single-digit numbers, as per the bc(1) standard
(see the \f[B]STANDARDS\f[R] section).
.PP
This environment variable overrides the default, which can be queried
with the \f[B]-h\f[R] or \f[B]--help\f[R] options.
.RE
.SH EXIT STATUS
.PP
dc(1) returns the following exit statuses:
@ -1283,10 +1398,9 @@ 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
@ -1375,14 +1489,14 @@ locales and thus, supports \f[B]LC_MESSAGES\f[R].
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.yzena.com/gavin/bc .
.SH AUTHOR
.PP
Gavin D.

242
contrib/bc/manuals/dc/E.1.md
View File

@ -2,7 +2,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:
@ -34,7 +34,7 @@ dc - arbitrary-precision decimal reverse-Polish notation calculator
# SYNOPSIS
**dc** [**-hiPRvVx**] [**-\-version**] [**-\-help**] [**-\-interactive**] [**-\-no-prompt**] [**-\-no-read-prompt**] [**-\-extended-register**] [**-e** *expr*] [**-\-expression**=*expr*...] [**-f** *file*...] [**-\-file**=*file*...] [*file*...]
**dc** [**-cChiPRvVx**] [**-\-version**] [**-\-help**] [**-\-digit-clamp**] [**-\-no-digit-clamp**] [**-\-interactive**] [**-\-no-prompt**] [**-\-no-read-prompt**] [**-\-extended-register**] [**-e** *expr*] [**-\-expression**=*expr*...] [**-f** *file*...] [**-\-file**=*file*...] [*file*...]
# DESCRIPTION
@ -55,73 +55,40 @@ this dc(1) will always start with a **scale** of **10**.
The following are the options that dc(1) accepts.
**-h**, **-\-help**
**-C**, **-\-no-digit-clamp**
: Prints a usage message and quits.
: Disables clamping of digits greater than or equal to the current **ibase**
when parsing numbers.
**-v**, **-V**, **-\-version**
This means that the value added to a number from a digit is always that
digit's value multiplied by the value of ibase raised to the power of the
digit's position, which starts from 0 at the least significant digit.
: Print the version information (copyright header) and exit.
If this and/or the **-c** or **-\-digit-clamp** options are given multiple
times, the last one given is used.
**-i**, **-\-interactive**
: Forces interactive mode. (See the **INTERACTIVE MODE** section.)
This option overrides the **DC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section) and the default, which can be queried
with the **-h** or **-\-help** options.
This is a **non-portable extension**.
**-L**, **-\-no-line-length**
**-c**, **-\-digit-clamp**
: Disables line length checking and prints numbers without backslashes and
newlines. In other words, this option sets **BC_LINE_LENGTH** to **0** (see
the **ENVIRONMENT VARIABLES** section).
: Enables clamping of digits greater than or equal to the current **ibase**
when parsing numbers.
This is a **non-portable extension**.
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's
position, which starts from 0 at the least significant digit.
**-P**, **-\-no-prompt**
If this and/or the **-C** or **-\-no-digit-clamp** options are given
multiple times, the last one given is used.
: Disables the prompt in TTY mode. (The prompt is only enabled in TTY mode.
See the **TTY MODE** 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 **DC_ENV_ARGS**.
These options override the **DC_PROMPT** and **DC_TTY_MODE** environment
variables (see the **ENVIRONMENT VARIABLES** section).
This is a **non-portable extension**.
**-R**, **-\-no-read-prompt**
: Disables the read prompt in TTY mode. (The read prompt is only enabled in
TTY mode. See the **TTY MODE** 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 **BC_ENV_ARGS** (see the
**ENVIRONMENT VARIABLES** section). This option is also useful in hash bang
lines of dc(1) scripts that prompt for user input.
This option does not disable the regular prompt because the read prompt is
only used when the **?** command is used.
These options *do* override the **DC_PROMPT** and **DC_TTY_MODE**
environment variables (see the **ENVIRONMENT VARIABLES** section), but only
for the read prompt.
This is a **non-portable extension**.
**-x** **-\-extended-register**
: Enables extended register mode. See the *Extended Register Mode* subsection
of the **REGISTERS** section for more information.
This is a **non-portable extension**.
**-z**, **-\-leading-zeroes**
: Makes dc(1) print all numbers greater than **-1** and less than **1**, and
not equal to **0**, with a leading zero.
This can be set for individual numbers with the **plz(x)**, plznl(x)**,
**pnlz(x)**, and **pnlznl(x)** functions in the extended math library (see
the **LIBRARY** section).
This option overrides the **DC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section) and the default, which can be queried
with the **-h** or **-\-help** options.
This is a **non-portable extension**.
@ -157,6 +124,10 @@ The following are the options that dc(1) accepts.
This is a **non-portable extension**.
**-h**, **-\-help**
: Prints a usage message and exits.
**-I** *ibase*, **-\-ibase**=*ibase*
: Sets the builtin variable **ibase** to the value *ibase* assuming that
@ -166,6 +137,20 @@ The following are the options that dc(1) accepts.
This is a **non-portable extension**.
**-i**, **-\-interactive**
: Forces interactive mode. (See the **INTERACTIVE MODE** section.)
This is a **non-portable extension**.
**-L**, **-\-no-line-length**
: Disables line length checking and prints numbers without backslashes and
newlines. In other words, this option sets **BC_LINE_LENGTH** to **0** (see
the **ENVIRONMENT VARIABLES** section).
This is a **non-portable extension**.
**-O** *obase*, **-\-obase**=*obase*
: Sets the builtin variable **obase** to the value *obase* assuming that
@ -175,6 +160,36 @@ The following are the options that dc(1) accepts.
This is a **non-portable extension**.
**-P**, **-\-no-prompt**
: Disables the prompt in TTY mode. (The prompt is only enabled in TTY mode.
See the **TTY MODE** 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 **DC_ENV_ARGS**.
These options override the **DC_PROMPT** and **DC_TTY_MODE** environment
variables (see the **ENVIRONMENT VARIABLES** section).
This is a **non-portable extension**.
**-R**, **-\-no-read-prompt**
: Disables the read prompt in TTY mode. (The read prompt is only enabled in
TTY mode. See the **TTY MODE** 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 **BC_ENV_ARGS** (see the
**ENVIRONMENT VARIABLES** section). This option is also useful in hash bang
lines of dc(1) scripts that prompt for user input.
This option does not disable the regular prompt because the read prompt is
only used when the **?** command is used.
These options *do* override the **DC_PROMPT** and **DC_TTY_MODE**
environment variables (see the **ENVIRONMENT VARIABLES** section), but only
for the read prompt.
This is a **non-portable extension**.
**-S** *scale*, **-\-scale**=*scale*
: Sets the builtin variable **scale** to the value *scale* assuming that
@ -184,6 +199,28 @@ The following are the options that dc(1) accepts.
This is a **non-portable extension**.
**-v**, **-V**, **-\-version**
: Print the version information (copyright header) and exits.
**-x** **-\-extended-register**
: Enables extended register mode. See the *Extended Register Mode* subsection
of the **REGISTERS** section for more information.
This is a **non-portable extension**.
**-z**, **-\-leading-zeroes**
: Makes dc(1) print all numbers greater than **-1** and less than **1**, and
not equal to **0**, with a leading zero.
This can be set for individual numbers with the **plz(x)**, plznl(x)**,
**pnlz(x)**, and **pnlznl(x)** functions in the extended math library (see
the **LIBRARY** section).
This is a **non-portable extension**.
All long options are **non-portable extensions**.
# STDIN
@ -263,15 +300,40 @@ Comments go from **#** until, and not including, the next newline. This is a
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 are equal to **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**.
Uppercase letters are equal to **9** plus their position in the alphabet (i.e.,
**A** equals **10**, or **9+1**).
Single-character numbers (i.e., **A** alone) take the value that they would have
if they were valid digits, regardless of the value of **ibase**. This means that
**A** alone always equals decimal **10** and **F** alone always equals decimal
**15**.
If a digit or letter makes no sense with the current value of **ibase** (i.e.,
they are greater than or equal to the current value of **ibase**), then the
behavior depends on the existence of the **-c**/**-\-digit-clamp** or
**-C**/**-\-no-digit-clamp** options (see the **OPTIONS** section), the
existence and setting of the **DC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section), or the default, which can be queried with
the **-h**/**-\-help** option.
If clamping is off, then digits or letters that are greater than or equal to the
current value of **ibase** are not changed. Instead, their given value is
multiplied by the appropriate power of **ibase** and added into the number. This
means that, with an **ibase** of **3**, the number **AB** is equal to
**3\^1\*A+3\^0\*B**, which is **3** times **10** plus **11**, or **41**.
If clamping is on, then digits or letters that are greater than or equal to the
current value of **ibase** are set to the value of the highest valid digit in
**ibase** before being multiplied by the appropriate power of **ibase** and
added into the number. This means that, with an **ibase** of **3**, the number
**AB** is equal to **3\^1\*2+3\^0\*2**, which is **3** times **2** plus **2**,
or **8**.
There is one exception to clamping: single-character numbers (i.e., **A**
alone). Such numbers are never clamped and always take the value they would have
in the highest possible **ibase**. This means that **A** alone always equals
decimal **10** and **Z** alone always equals decimal **35**. 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 **ibase** (with the **i** command)
regardless of the current value of **ibase**.
If clamping is on, and the clamped value of a character is needed, use a leading
zero, i.e., for **A**, use **0A**.
# COMMANDS
@ -769,6 +831,8 @@ will be printed with a newline after and then popped from the stack.
is exactly as many as is needed to make dc(1) exit with the **Q** command,
so the sequence **,Q** will make dc(1) exit.
This is a **non-portable extension**.
## Status
These commands query status of the stack or its top value.
@ -791,6 +855,20 @@ These commands query status of the stack or its top value.
If it is a string, pushes **0**.
**u**
: Pops one value off of the stack. If the value is a number, this pushes **1**
onto the stack. Otherwise (if it is a string), it pushes **0**.
This is a **non-portable extension**.
**t**
: Pops one value off of the stack. If the value is a string, this pushes **1**
onto the stack. Otherwise (if it is a number), it pushes **0**.
This is a **non-portable extension**.
**z**
: Pushes the current depth of the stack (before execution of this command)
@ -974,7 +1052,8 @@ be hit.
# ENVIRONMENT VARIABLES
dc(1) recognizes the following environment variables:
As **non-portable extensions**, dc(1) recognizes the following environment
variables:
**DC_ENV_ARGS**
@ -1063,6 +1142,21 @@ dc(1) recognizes the following environment variables:
This environment variable overrides the default, which can be queried with
the **-h** or **-\-help** options.
**DC_DIGIT_CLAMP**
: 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 **ibase** so that all such digits are considered equal
to the **ibase** 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 **ibase**.
This never applies to single-digit numbers, as per the bc(1) standard (see
the **STANDARDS** section).
This environment variable overrides the default, which can be queried with
the **-h** or **-\-help** options.
# EXIT STATUS
dc(1) returns the following exit statuses:
@ -1157,10 +1251,8 @@ setting is used. The default setting can be queried with the **-h** or
**-\-help** options.
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 **stdin** and **stdout** to be connected to a
terminal.
in the bc(1) specification (see the **STANDARDS** section), and interactive mode
requires only **stdin** and **stdout** to be connected to a terminal.
## Command-Line History
@ -1243,13 +1335,13 @@ bc(1)
# STANDARDS
The dc(1) utility operators are compliant with the operators in the IEEE Std
1003.1-2017 (“POSIX.1-2017”) 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 (“POSIX.1-2017”) bc(1) specification at
https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html .
# BUGS
None are known. Report bugs at https://git.yzena.com/gavin/bc.
None are known. Report bugs at https://git.yzena.com/gavin/bc .
# AUTHOR

302
contrib/bc/manuals/dc/EH.1
View File

@ -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,7 +25,7 @@
.\" 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" "October 2022" "Gavin D. Howard" "General Commands Manual"
.nh
.ad l
.SH Name
@ -33,12 +33,14 @@
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
@ -61,83 +63,43 @@ and this dc(1) will always start with a \f[B]scale\f[R] of \f[B]10\f[R].
.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 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]-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).
\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 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
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 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).
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]-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]-x\f[R] \f[B]--extended-register\f[R]
Enables extended register mode.
See the \f[I]Extended Register Mode\f[R] subsection of the
\f[B]REGISTERS\f[R] section for more information.
.RS
.PP
This is a \f[B]non-portable extension\f[R].
.RE
.TP
\f[B]-z\f[R], \f[B]--leading-zeroes\f[R]
Makes dc(1) print all numbers greater than \f[B]-1\f[R] and less than
\f[B]1\f[R], and not equal to \f[B]0\f[R], with a leading zero.
.RS
.PP
This can be set for individual numbers with the \f[B]plz(x)\f[R],
plznl(x)**, \f[B]pnlz(x)\f[R], and \f[B]pnlznl(x)\f[R] functions in the
extended math library (see the \f[B]LIBRARY\f[R] section).
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
@ -185,6 +147,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.
@ -196,6 +161,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.
@ -207,6 +190,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.
@ -217,6 +238,30 @@ If multiple instances of this option are given, the last is used.
.PP
This is a \f[B]non-portable extension\f[R].
.RE
.TP
\f[B]-v\f[R], \f[B]-V\f[R], \f[B]--version\f[R]
Print the version information (copyright header) and exits.
.TP
\f[B]-x\f[R] \f[B]--extended-register\f[R]
Enables extended register mode.
See the \f[I]Extended Register Mode\f[R] subsection of the
\f[B]REGISTERS\f[R] section for more information.
.RS
.PP
This is a \f[B]non-portable extension\f[R].
.RE
.TP
\f[B]-z\f[R], \f[B]--leading-zeroes\f[R]
Makes dc(1) print all numbers greater than \f[B]-1\f[R] and less than
\f[B]1\f[R], and not equal to \f[B]0\f[R], with a leading zero.
.RS
.PP
This can be set for individual numbers with the \f[B]plz(x)\f[R],
plznl(x)**, \f[B]pnlz(x)\f[R], and \f[B]pnlznl(x)\f[R] functions in the
extended math library (see the \f[B]LIBRARY\f[R] section).
.PP
This is a \f[B]non-portable extension\f[R].
.RE
.PP
All long options are \f[B]non-portable extensions\f[R].
.SH STDIN
@ -307,17 +352,48 @@ This is a \f[B]non-portable extension\f[R].
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.
@ -866,6 +942,10 @@ 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.
.RS
.PP
This is a \f[B]non-portable extension\f[R].
.RE
.SS Status
.PP
These commands query status of the stack or its top value.
@ -892,6 +972,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.
@ -1078,7 +1176,8 @@ 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).
@ -1182,6 +1281,22 @@ 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
.TP
\f[B]DC_DIGIT_CLAMP\f[R]
When parsing numbers and if this environment variable exists and
contains an integer, a non-zero value makes dc(1) clamp digits that are
greater than or equal to the current \f[B]ibase\f[R] so that all such
digits are considered equal to the \f[B]ibase\f[R] minus 1, and a zero
value disables such clamping so that those digits are always equal to
their value, which is multiplied by the power of the \f[B]ibase\f[R].
.RS
.PP
This never applies to single-digit numbers, as per the bc(1) standard
(see the \f[B]STANDARDS\f[R] section).
.PP
This environment variable overrides the default, which can be queried
with the \f[B]-h\f[R] or \f[B]--help\f[R] options.
.RE
.SH EXIT STATUS
.PP
dc(1) returns the following exit statuses:
@ -1283,10 +1398,9 @@ 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 Prompt
.PP
If TTY mode is available, then a prompt can be enabled.
@ -1349,14 +1463,14 @@ locales and thus, supports \f[B]LC_MESSAGES\f[R].
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.yzena.com/gavin/bc .
.SH AUTHOR
.PP
Gavin D.

242
contrib/bc/manuals/dc/EH.1.md
View File

@ -2,7 +2,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:
@ -34,7 +34,7 @@ dc - arbitrary-precision decimal reverse-Polish notation calculator
# SYNOPSIS
**dc** [**-hiPRvVx**] [**-\-version**] [**-\-help**] [**-\-interactive**] [**-\-no-prompt**] [**-\-no-read-prompt**] [**-\-extended-register**] [**-e** *expr*] [**-\-expression**=*expr*...] [**-f** *file*...] [**-\-file**=*file*...] [*file*...]
**dc** [**-cChiPRvVx**] [**-\-version**] [**-\-help**] [**-\-digit-clamp**] [**-\-no-digit-clamp**] [**-\-interactive**] [**-\-no-prompt**] [**-\-no-read-prompt**] [**-\-extended-register**] [**-e** *expr*] [**-\-expression**=*expr*...] [**-f** *file*...] [**-\-file**=*file*...] [*file*...]
# DESCRIPTION
@ -55,73 +55,40 @@ this dc(1) will always start with a **scale** of **10**.
The following are the options that dc(1) accepts.
**-h**, **-\-help**
**-C**, **-\-no-digit-clamp**
: Prints a usage message and quits.
: Disables clamping of digits greater than or equal to the current **ibase**
when parsing numbers.
**-v**, **-V**, **-\-version**
This means that the value added to a number from a digit is always that
digit's value multiplied by the value of ibase raised to the power of the
digit's position, which starts from 0 at the least significant digit.
: Print the version information (copyright header) and exit.
If this and/or the **-c** or **-\-digit-clamp** options are given multiple
times, the last one given is used.
**-i**, **-\-interactive**
: Forces interactive mode. (See the **INTERACTIVE MODE** section.)
This option overrides the **DC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section) and the default, which can be queried
with the **-h** or **-\-help** options.
This is a **non-portable extension**.
**-L**, **-\-no-line-length**
**-c**, **-\-digit-clamp**
: Disables line length checking and prints numbers without backslashes and
newlines. In other words, this option sets **BC_LINE_LENGTH** to **0** (see
the **ENVIRONMENT VARIABLES** section).
: Enables clamping of digits greater than or equal to the current **ibase**
when parsing numbers.
This is a **non-portable extension**.
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's
position, which starts from 0 at the least significant digit.
**-P**, **-\-no-prompt**
If this and/or the **-C** or **-\-no-digit-clamp** options are given
multiple times, the last one given is used.
: Disables the prompt in TTY mode. (The prompt is only enabled in TTY mode.
See the **TTY MODE** 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 **DC_ENV_ARGS**.
These options override the **DC_PROMPT** and **DC_TTY_MODE** environment
variables (see the **ENVIRONMENT VARIABLES** section).
This is a **non-portable extension**.
**-R**, **-\-no-read-prompt**
: Disables the read prompt in TTY mode. (The read prompt is only enabled in
TTY mode. See the **TTY MODE** 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 **BC_ENV_ARGS** (see the
**ENVIRONMENT VARIABLES** section). This option is also useful in hash bang
lines of dc(1) scripts that prompt for user input.
This option does not disable the regular prompt because the read prompt is
only used when the **?** command is used.
These options *do* override the **DC_PROMPT** and **DC_TTY_MODE**
environment variables (see the **ENVIRONMENT VARIABLES** section), but only
for the read prompt.
This is a **non-portable extension**.
**-x** **-\-extended-register**
: Enables extended register mode. See the *Extended Register Mode* subsection
of the **REGISTERS** section for more information.
This is a **non-portable extension**.
**-z**, **-\-leading-zeroes**
: Makes dc(1) print all numbers greater than **-1** and less than **1**, and
not equal to **0**, with a leading zero.
This can be set for individual numbers with the **plz(x)**, plznl(x)**,
**pnlz(x)**, and **pnlznl(x)** functions in the extended math library (see
the **LIBRARY** section).
This option overrides the **DC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section) and the default, which can be queried
with the **-h** or **-\-help** options.
This is a **non-portable extension**.
@ -157,6 +124,10 @@ The following are the options that dc(1) accepts.
This is a **non-portable extension**.
**-h**, **-\-help**
: Prints a usage message and exits.
**-I** *ibase*, **-\-ibase**=*ibase*
: Sets the builtin variable **ibase** to the value *ibase* assuming that
@ -166,6 +137,20 @@ The following are the options that dc(1) accepts.
This is a **non-portable extension**.
**-i**, **-\-interactive**
: Forces interactive mode. (See the **INTERACTIVE MODE** section.)
This is a **non-portable extension**.
**-L**, **-\-no-line-length**
: Disables line length checking and prints numbers without backslashes and
newlines. In other words, this option sets **BC_LINE_LENGTH** to **0** (see
the **ENVIRONMENT VARIABLES** section).
This is a **non-portable extension**.
**-O** *obase*, **-\-obase**=*obase*
: Sets the builtin variable **obase** to the value *obase* assuming that
@ -175,6 +160,36 @@ The following are the options that dc(1) accepts.
This is a **non-portable extension**.
**-P**, **-\-no-prompt**
: Disables the prompt in TTY mode. (The prompt is only enabled in TTY mode.
See the **TTY MODE** 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 **DC_ENV_ARGS**.
These options override the **DC_PROMPT** and **DC_TTY_MODE** environment
variables (see the **ENVIRONMENT VARIABLES** section).
This is a **non-portable extension**.
**-R**, **-\-no-read-prompt**
: Disables the read prompt in TTY mode. (The read prompt is only enabled in
TTY mode. See the **TTY MODE** 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 **BC_ENV_ARGS** (see the
**ENVIRONMENT VARIABLES** section). This option is also useful in hash bang
lines of dc(1) scripts that prompt for user input.
This option does not disable the regular prompt because the read prompt is
only used when the **?** command is used.
These options *do* override the **DC_PROMPT** and **DC_TTY_MODE**
environment variables (see the **ENVIRONMENT VARIABLES** section), but only
for the read prompt.
This is a **non-portable extension**.
**-S** *scale*, **-\-scale**=*scale*
: Sets the builtin variable **scale** to the value *scale* assuming that
@ -184,6 +199,28 @@ The following are the options that dc(1) accepts.
This is a **non-portable extension**.
**-v**, **-V**, **-\-version**
: Print the version information (copyright header) and exits.
**-x** **-\-extended-register**
: Enables extended register mode. See the *Extended Register Mode* subsection
of the **REGISTERS** section for more information.
This is a **non-portable extension**.
**-z**, **-\-leading-zeroes**
: Makes dc(1) print all numbers greater than **-1** and less than **1**, and
not equal to **0**, with a leading zero.
This can be set for individual numbers with the **plz(x)**, plznl(x)**,
**pnlz(x)**, and **pnlznl(x)** functions in the extended math library (see
the **LIBRARY** section).
This is a **non-portable extension**.
All long options are **non-portable extensions**.
# STDIN
@ -263,15 +300,40 @@ Comments go from **#** until, and not including, the next newline. This is a
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 are equal to **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**.
Uppercase letters are equal to **9** plus their position in the alphabet (i.e.,
**A** equals **10**, or **9+1**).
Single-character numbers (i.e., **A** alone) take the value that they would have
if they were valid digits, regardless of the value of **ibase**. This means that
**A** alone always equals decimal **10** and **F** alone always equals decimal
**15**.
If a digit or letter makes no sense with the current value of **ibase** (i.e.,
they are greater than or equal to the current value of **ibase**), then the
behavior depends on the existence of the **-c**/**-\-digit-clamp** or
**-C**/**-\-no-digit-clamp** options (see the **OPTIONS** section), the
existence and setting of the **DC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section), or the default, which can be queried with
the **-h**/**-\-help** option.
If clamping is off, then digits or letters that are greater than or equal to the
current value of **ibase** are not changed. Instead, their given value is
multiplied by the appropriate power of **ibase** and added into the number. This
means that, with an **ibase** of **3**, the number **AB** is equal to
**3\^1\*A+3\^0\*B**, which is **3** times **10** plus **11**, or **41**.
If clamping is on, then digits or letters that are greater than or equal to the
current value of **ibase** are set to the value of the highest valid digit in
**ibase** before being multiplied by the appropriate power of **ibase** and
added into the number. This means that, with an **ibase** of **3**, the number
**AB** is equal to **3\^1\*2+3\^0\*2**, which is **3** times **2** plus **2**,
or **8**.
There is one exception to clamping: single-character numbers (i.e., **A**
alone). Such numbers are never clamped and always take the value they would have
in the highest possible **ibase**. This means that **A** alone always equals
decimal **10** and **Z** alone always equals decimal **35**. 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 **ibase** (with the **i** command)
regardless of the current value of **ibase**.
If clamping is on, and the clamped value of a character is needed, use a leading
zero, i.e., for **A**, use **0A**.
# COMMANDS
@ -769,6 +831,8 @@ will be printed with a newline after and then popped from the stack.
is exactly as many as is needed to make dc(1) exit with the **Q** command,
so the sequence **,Q** will make dc(1) exit.
This is a **non-portable extension**.
## Status
These commands query status of the stack or its top value.
@ -791,6 +855,20 @@ These commands query status of the stack or its top value.
If it is a string, pushes **0**.
**u**
: Pops one value off of the stack. If the value is a number, this pushes **1**
onto the stack. Otherwise (if it is a string), it pushes **0**.
This is a **non-portable extension**.
**t**
: Pops one value off of the stack. If the value is a string, this pushes **1**
onto the stack. Otherwise (if it is a number), it pushes **0**.
This is a **non-portable extension**.
**z**
: Pushes the current depth of the stack (before execution of this command)
@ -974,7 +1052,8 @@ be hit.
# ENVIRONMENT VARIABLES
dc(1) recognizes the following environment variables:
As **non-portable extensions**, dc(1) recognizes the following environment
variables:
**DC_ENV_ARGS**
@ -1063,6 +1142,21 @@ dc(1) recognizes the following environment variables:
This environment variable overrides the default, which can be queried with
the **-h** or **-\-help** options.
**DC_DIGIT_CLAMP**
: 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 **ibase** so that all such digits are considered equal
to the **ibase** 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 **ibase**.
This never applies to single-digit numbers, as per the bc(1) standard (see
the **STANDARDS** section).
This environment variable overrides the default, which can be queried with
the **-h** or **-\-help** options.
# EXIT STATUS
dc(1) returns the following exit statuses:
@ -1157,10 +1251,8 @@ setting is used. The default setting can be queried with the **-h** or
**-\-help** options.
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 **stdin** and **stdout** to be connected to a
terminal.
in the bc(1) specification (see the **STANDARDS** section), and interactive mode
requires only **stdin** and **stdout** to be connected to a terminal.
## Prompt
@ -1220,13 +1312,13 @@ bc(1)
# STANDARDS
The dc(1) utility operators are compliant with the operators in the IEEE Std
1003.1-2017 (“POSIX.1-2017”) 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 (“POSIX.1-2017”) bc(1) specification at
https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html .
# BUGS
None are known. Report bugs at https://git.yzena.com/gavin/bc.
None are known. Report bugs at https://git.yzena.com/gavin/bc .
# AUTHOR

302
contrib/bc/manuals/dc/EHN.1
View File

@ -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,7 +25,7 @@
.\" 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" "October 2022" "Gavin D. Howard" "General Commands Manual"
.nh
.ad l
.SH Name
@ -33,12 +33,14 @@
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
@ -61,83 +63,43 @@ and this dc(1) will always start with a \f[B]scale\f[R] of \f[B]10\f[R].
.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 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]-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).
\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 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
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 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).
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]-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]-x\f[R] \f[B]--extended-register\f[R]
Enables extended register mode.
See the \f[I]Extended Register Mode\f[R] subsection of the
\f[B]REGISTERS\f[R] section for more information.
.RS
.PP
This is a \f[B]non-portable extension\f[R].
.RE
.TP
\f[B]-z\f[R], \f[B]--leading-zeroes\f[R]
Makes dc(1) print all numbers greater than \f[B]-1\f[R] and less than
\f[B]1\f[R], and not equal to \f[B]0\f[R], with a leading zero.
.RS
.PP
This can be set for individual numbers with the \f[B]plz(x)\f[R],
plznl(x)**, \f[B]pnlz(x)\f[R], and \f[B]pnlznl(x)\f[R] functions in the
extended math library (see the \f[B]LIBRARY\f[R] section).
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
@ -185,6 +147,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.
@ -196,6 +161,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.
@ -207,6 +190,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.
@ -217,6 +238,30 @@ If multiple instances of this option are given, the last is used.
.PP
This is a \f[B]non-portable extension\f[R].
.RE
.TP
\f[B]-v\f[R], \f[B]-V\f[R], \f[B]--version\f[R]
Print the version information (copyright header) and exits.
.TP
\f[B]-x\f[R] \f[B]--extended-register\f[R]
Enables extended register mode.
See the \f[I]Extended Register Mode\f[R] subsection of the
\f[B]REGISTERS\f[R] section for more information.
.RS
.PP
This is a \f[B]non-portable extension\f[R].
.RE
.TP
\f[B]-z\f[R], \f[B]--leading-zeroes\f[R]
Makes dc(1) print all numbers greater than \f[B]-1\f[R] and less than
\f[B]1\f[R], and not equal to \f[B]0\f[R], with a leading zero.
.RS
.PP
This can be set for individual numbers with the \f[B]plz(x)\f[R],
plznl(x)**, \f[B]pnlz(x)\f[R], and \f[B]pnlznl(x)\f[R] functions in the
extended math library (see the \f[B]LIBRARY\f[R] section).
.PP
This is a \f[B]non-portable extension\f[R].
.RE
.PP
All long options are \f[B]non-portable extensions\f[R].
.SH STDIN
@ -307,17 +352,48 @@ This is a \f[B]non-portable extension\f[R].
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.
@ -866,6 +942,10 @@ 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.
.RS
.PP
This is a \f[B]non-portable extension\f[R].
.RE
.SS Status
.PP
These commands query status of the stack or its top value.
@ -892,6 +972,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.
@ -1078,7 +1176,8 @@ 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).
@ -1182,6 +1281,22 @@ 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
.TP
\f[B]DC_DIGIT_CLAMP\f[R]
When parsing numbers and if this environment variable exists and
contains an integer, a non-zero value makes dc(1) clamp digits that are
greater than or equal to the current \f[B]ibase\f[R] so that all such
digits are considered equal to the \f[B]ibase\f[R] minus 1, and a zero
value disables such clamping so that those digits are always equal to
their value, which is multiplied by the power of the \f[B]ibase\f[R].
.RS
.PP
This never applies to single-digit numbers, as per the bc(1) standard
(see the \f[B]STANDARDS\f[R] section).
.PP
This environment variable overrides the default, which can be queried
with the \f[B]-h\f[R] or \f[B]--help\f[R] options.
.RE
.SH EXIT STATUS
.PP
dc(1) returns the following exit statuses:
@ -1283,10 +1398,9 @@ 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 Prompt
.PP
If TTY mode is available, then a prompt can be enabled.
@ -1345,14 +1459,14 @@ exit, and it uses the default handler for all other signals.
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.yzena.com/gavin/bc .
.SH AUTHOR
.PP
Gavin D.

242
contrib/bc/manuals/dc/EHN.1.md
View File

@ -2,7 +2,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:
@ -34,7 +34,7 @@ dc - arbitrary-precision decimal reverse-Polish notation calculator
# SYNOPSIS
**dc** [**-hiPRvVx**] [**-\-version**] [**-\-help**] [**-\-interactive**] [**-\-no-prompt**] [**-\-no-read-prompt**] [**-\-extended-register**] [**-e** *expr*] [**-\-expression**=*expr*...] [**-f** *file*...] [**-\-file**=*file*...] [*file*...]
**dc** [**-cChiPRvVx**] [**-\-version**] [**-\-help**] [**-\-digit-clamp**] [**-\-no-digit-clamp**] [**-\-interactive**] [**-\-no-prompt**] [**-\-no-read-prompt**] [**-\-extended-register**] [**-e** *expr*] [**-\-expression**=*expr*...] [**-f** *file*...] [**-\-file**=*file*...] [*file*...]
# DESCRIPTION
@ -55,73 +55,40 @@ this dc(1) will always start with a **scale** of **10**.
The following are the options that dc(1) accepts.
**-h**, **-\-help**
**-C**, **-\-no-digit-clamp**
: Prints a usage message and quits.
: Disables clamping of digits greater than or equal to the current **ibase**
when parsing numbers.
**-v**, **-V**, **-\-version**
This means that the value added to a number from a digit is always that
digit's value multiplied by the value of ibase raised to the power of the
digit's position, which starts from 0 at the least significant digit.
: Print the version information (copyright header) and exit.
If this and/or the **-c** or **-\-digit-clamp** options are given multiple
times, the last one given is used.
**-i**, **-\-interactive**
: Forces interactive mode. (See the **INTERACTIVE MODE** section.)
This option overrides the **DC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section) and the default, which can be queried
with the **-h** or **-\-help** options.
This is a **non-portable extension**.
**-L**, **-\-no-line-length**
**-c**, **-\-digit-clamp**
: Disables line length checking and prints numbers without backslashes and
newlines. In other words, this option sets **BC_LINE_LENGTH** to **0** (see
the **ENVIRONMENT VARIABLES** section).
: Enables clamping of digits greater than or equal to the current **ibase**
when parsing numbers.
This is a **non-portable extension**.
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's
position, which starts from 0 at the least significant digit.
**-P**, **-\-no-prompt**
If this and/or the **-C** or **-\-no-digit-clamp** options are given
multiple times, the last one given is used.
: Disables the prompt in TTY mode. (The prompt is only enabled in TTY mode.
See the **TTY MODE** 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 **DC_ENV_ARGS**.
These options override the **DC_PROMPT** and **DC_TTY_MODE** environment
variables (see the **ENVIRONMENT VARIABLES** section).
This is a **non-portable extension**.
**-R**, **-\-no-read-prompt**
: Disables the read prompt in TTY mode. (The read prompt is only enabled in
TTY mode. See the **TTY MODE** 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 **BC_ENV_ARGS** (see the
**ENVIRONMENT VARIABLES** section). This option is also useful in hash bang
lines of dc(1) scripts that prompt for user input.
This option does not disable the regular prompt because the read prompt is
only used when the **?** command is used.
These options *do* override the **DC_PROMPT** and **DC_TTY_MODE**
environment variables (see the **ENVIRONMENT VARIABLES** section), but only
for the read prompt.
This is a **non-portable extension**.
**-x** **-\-extended-register**
: Enables extended register mode. See the *Extended Register Mode* subsection
of the **REGISTERS** section for more information.
This is a **non-portable extension**.
**-z**, **-\-leading-zeroes**
: Makes dc(1) print all numbers greater than **-1** and less than **1**, and
not equal to **0**, with a leading zero.
This can be set for individual numbers with the **plz(x)**, plznl(x)**,
**pnlz(x)**, and **pnlznl(x)** functions in the extended math library (see
the **LIBRARY** section).
This option overrides the **DC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section) and the default, which can be queried
with the **-h** or **-\-help** options.
This is a **non-portable extension**.
@ -157,6 +124,10 @@ The following are the options that dc(1) accepts.
This is a **non-portable extension**.
**-h**, **-\-help**
: Prints a usage message and exits.
**-I** *ibase*, **-\-ibase**=*ibase*
: Sets the builtin variable **ibase** to the value *ibase* assuming that
@ -166,6 +137,20 @@ The following are the options that dc(1) accepts.
This is a **non-portable extension**.
**-i**, **-\-interactive**
: Forces interactive mode. (See the **INTERACTIVE MODE** section.)
This is a **non-portable extension**.
**-L**, **-\-no-line-length**
: Disables line length checking and prints numbers without backslashes and
newlines. In other words, this option sets **BC_LINE_LENGTH** to **0** (see
the **ENVIRONMENT VARIABLES** section).
This is a **non-portable extension**.
**-O** *obase*, **-\-obase**=*obase*
: Sets the builtin variable **obase** to the value *obase* assuming that
@ -175,6 +160,36 @@ The following are the options that dc(1) accepts.
This is a **non-portable extension**.
**-P**, **-\-no-prompt**
: Disables the prompt in TTY mode. (The prompt is only enabled in TTY mode.
See the **TTY MODE** 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 **DC_ENV_ARGS**.
These options override the **DC_PROMPT** and **DC_TTY_MODE** environment
variables (see the **ENVIRONMENT VARIABLES** section).
This is a **non-portable extension**.
**-R**, **-\-no-read-prompt**
: Disables the read prompt in TTY mode. (The read prompt is only enabled in
TTY mode. See the **TTY MODE** 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 **BC_ENV_ARGS** (see the
**ENVIRONMENT VARIABLES** section). This option is also useful in hash bang
lines of dc(1) scripts that prompt for user input.
This option does not disable the regular prompt because the read prompt is
only used when the **?** command is used.
These options *do* override the **DC_PROMPT** and **DC_TTY_MODE**
environment variables (see the **ENVIRONMENT VARIABLES** section), but only
for the read prompt.
This is a **non-portable extension**.
**-S** *scale*, **-\-scale**=*scale*
: Sets the builtin variable **scale** to the value *scale* assuming that
@ -184,6 +199,28 @@ The following are the options that dc(1) accepts.
This is a **non-portable extension**.
**-v**, **-V**, **-\-version**
: Print the version information (copyright header) and exits.
**-x** **-\-extended-register**
: Enables extended register mode. See the *Extended Register Mode* subsection
of the **REGISTERS** section for more information.
This is a **non-portable extension**.
**-z**, **-\-leading-zeroes**
: Makes dc(1) print all numbers greater than **-1** and less than **1**, and
not equal to **0**, with a leading zero.
This can be set for individual numbers with the **plz(x)**, plznl(x)**,
**pnlz(x)**, and **pnlznl(x)** functions in the extended math library (see
the **LIBRARY** section).
This is a **non-portable extension**.
All long options are **non-portable extensions**.
# STDIN
@ -263,15 +300,40 @@ Comments go from **#** until, and not including, the next newline. This is a
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 are equal to **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**.
Uppercase letters are equal to **9** plus their position in the alphabet (i.e.,
**A** equals **10**, or **9+1**).
Single-character numbers (i.e., **A** alone) take the value that they would have
if they were valid digits, regardless of the value of **ibase**. This means that
**A** alone always equals decimal **10** and **F** alone always equals decimal
**15**.
If a digit or letter makes no sense with the current value of **ibase** (i.e.,
they are greater than or equal to the current value of **ibase**), then the
behavior depends on the existence of the **-c**/**-\-digit-clamp** or
**-C**/**-\-no-digit-clamp** options (see the **OPTIONS** section), the
existence and setting of the **DC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section), or the default, which can be queried with
the **-h**/**-\-help** option.
If clamping is off, then digits or letters that are greater than or equal to the
current value of **ibase** are not changed. Instead, their given value is
multiplied by the appropriate power of **ibase** and added into the number. This
means that, with an **ibase** of **3**, the number **AB** is equal to
**3\^1\*A+3\^0\*B**, which is **3** times **10** plus **11**, or **41**.
If clamping is on, then digits or letters that are greater than or equal to the
current value of **ibase** are set to the value of the highest valid digit in
**ibase** before being multiplied by the appropriate power of **ibase** and
added into the number. This means that, with an **ibase** of **3**, the number
**AB** is equal to **3\^1\*2+3\^0\*2**, which is **3** times **2** plus **2**,
or **8**.
There is one exception to clamping: single-character numbers (i.e., **A**
alone). Such numbers are never clamped and always take the value they would have
in the highest possible **ibase**. This means that **A** alone always equals
decimal **10** and **Z** alone always equals decimal **35**. 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 **ibase** (with the **i** command)
regardless of the current value of **ibase**.
If clamping is on, and the clamped value of a character is needed, use a leading
zero, i.e., for **A**, use **0A**.
# COMMANDS
@ -769,6 +831,8 @@ will be printed with a newline after and then popped from the stack.
is exactly as many as is needed to make dc(1) exit with the **Q** command,
so the sequence **,Q** will make dc(1) exit.
This is a **non-portable extension**.
## Status
These commands query status of the stack or its top value.
@ -791,6 +855,20 @@ These commands query status of the stack or its top value.
If it is a string, pushes **0**.
**u**
: Pops one value off of the stack. If the value is a number, this pushes **1**
onto the stack. Otherwise (if it is a string), it pushes **0**.
This is a **non-portable extension**.
**t**
: Pops one value off of the stack. If the value is a string, this pushes **1**
onto the stack. Otherwise (if it is a number), it pushes **0**.
This is a **non-portable extension**.
**z**
: Pushes the current depth of the stack (before execution of this command)
@ -974,7 +1052,8 @@ be hit.
# ENVIRONMENT VARIABLES
dc(1) recognizes the following environment variables:
As **non-portable extensions**, dc(1) recognizes the following environment
variables:
**DC_ENV_ARGS**
@ -1063,6 +1142,21 @@ dc(1) recognizes the following environment variables:
This environment variable overrides the default, which can be queried with
the **-h** or **-\-help** options.
**DC_DIGIT_CLAMP**
: 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 **ibase** so that all such digits are considered equal
to the **ibase** 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 **ibase**.
This never applies to single-digit numbers, as per the bc(1) standard (see
the **STANDARDS** section).
This environment variable overrides the default, which can be queried with
the **-h** or **-\-help** options.
# EXIT STATUS
dc(1) returns the following exit statuses:
@ -1157,10 +1251,8 @@ setting is used. The default setting can be queried with the **-h** or
**-\-help** options.
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 **stdin** and **stdout** to be connected to a
terminal.
in the bc(1) specification (see the **STANDARDS** section), and interactive mode
requires only **stdin** and **stdout** to be connected to a terminal.
## Prompt
@ -1215,13 +1307,13 @@ bc(1)
# STANDARDS
The dc(1) utility operators are compliant with the operators in the IEEE Std
1003.1-2017 (“POSIX.1-2017”) 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 (“POSIX.1-2017”) bc(1) specification at
https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html .
# BUGS
None are known. Report bugs at https://git.yzena.com/gavin/bc.
None are known. Report bugs at https://git.yzena.com/gavin/bc .
# AUTHOR

302
contrib/bc/manuals/dc/EN.1
View File

@ -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,7 +25,7 @@
.\" 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" "October 2022" "Gavin D. Howard" "General Commands Manual"
.nh
.ad l
.SH Name
@ -33,12 +33,14 @@
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
@ -61,83 +63,43 @@ and this dc(1) will always start with a \f[B]scale\f[R] of \f[B]10\f[R].
.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 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]-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).
\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 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
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 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).
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]-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]-x\f[R] \f[B]--extended-register\f[R]
Enables extended register mode.
See the \f[I]Extended Register Mode\f[R] subsection of the
\f[B]REGISTERS\f[R] section for more information.
.RS
.PP
This is a \f[B]non-portable extension\f[R].
.RE
.TP
\f[B]-z\f[R], \f[B]--leading-zeroes\f[R]
Makes dc(1) print all numbers greater than \f[B]-1\f[R] and less than
\f[B]1\f[R], and not equal to \f[B]0\f[R], with a leading zero.
.RS
.PP
This can be set for individual numbers with the \f[B]plz(x)\f[R],
plznl(x)**, \f[B]pnlz(x)\f[R], and \f[B]pnlznl(x)\f[R] functions in the
extended math library (see the \f[B]LIBRARY\f[R] section).
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
@ -185,6 +147,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.
@ -196,6 +161,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.
@ -207,6 +190,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.
@ -217,6 +238,30 @@ If multiple instances of this option are given, the last is used.
.PP
This is a \f[B]non-portable extension\f[R].
.RE
.TP
\f[B]-v\f[R], \f[B]-V\f[R], \f[B]--version\f[R]
Print the version information (copyright header) and exits.
.TP
\f[B]-x\f[R] \f[B]--extended-register\f[R]
Enables extended register mode.
See the \f[I]Extended Register Mode\f[R] subsection of the
\f[B]REGISTERS\f[R] section for more information.
.RS
.PP
This is a \f[B]non-portable extension\f[R].
.RE
.TP
\f[B]-z\f[R], \f[B]--leading-zeroes\f[R]
Makes dc(1) print all numbers greater than \f[B]-1\f[R] and less than
\f[B]1\f[R], and not equal to \f[B]0\f[R], with a leading zero.
.RS
.PP
This can be set for individual numbers with the \f[B]plz(x)\f[R],
plznl(x)**, \f[B]pnlz(x)\f[R], and \f[B]pnlznl(x)\f[R] functions in the
extended math library (see the \f[B]LIBRARY\f[R] section).
.PP
This is a \f[B]non-portable extension\f[R].
.RE
.PP
All long options are \f[B]non-portable extensions\f[R].
.SH STDIN
@ -307,17 +352,48 @@ This is a \f[B]non-portable extension\f[R].
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.
@ -866,6 +942,10 @@ 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.
.RS
.PP
This is a \f[B]non-portable extension\f[R].
.RE
.SS Status
.PP
These commands query status of the stack or its top value.
@ -892,6 +972,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.
@ -1078,7 +1176,8 @@ 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).
@ -1182,6 +1281,22 @@ 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
.TP
\f[B]DC_DIGIT_CLAMP\f[R]
When parsing numbers and if this environment variable exists and
contains an integer, a non-zero value makes dc(1) clamp digits that are
greater than or equal to the current \f[B]ibase\f[R] so that all such
digits are considered equal to the \f[B]ibase\f[R] minus 1, and a zero
value disables such clamping so that those digits are always equal to
their value, which is multiplied by the power of the \f[B]ibase\f[R].
.RS
.PP
This never applies to single-digit numbers, as per the bc(1) standard
(see the \f[B]STANDARDS\f[R] section).
.PP
This environment variable overrides the default, which can be queried
with the \f[B]-h\f[R] or \f[B]--help\f[R] options.
.RE
.SH EXIT STATUS
.PP
dc(1) returns the following exit statuses:
@ -1283,10 +1398,9 @@ 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
@ -1371,14 +1485,14 @@ section).
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.yzena.com/gavin/bc .
.SH AUTHOR
.PP
Gavin D.

242
contrib/bc/manuals/dc/EN.1.md
View File

@ -2,7 +2,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:
@ -34,7 +34,7 @@ dc - arbitrary-precision decimal reverse-Polish notation calculator
# SYNOPSIS
**dc** [**-hiPRvVx**] [**-\-version**] [**-\-help**] [**-\-interactive**] [**-\-no-prompt**] [**-\-no-read-prompt**] [**-\-extended-register**] [**-e** *expr*] [**-\-expression**=*expr*...] [**-f** *file*...] [**-\-file**=*file*...] [*file*...]
**dc** [**-cChiPRvVx**] [**-\-version**] [**-\-help**] [**-\-digit-clamp**] [**-\-no-digit-clamp**] [**-\-interactive**] [**-\-no-prompt**] [**-\-no-read-prompt**] [**-\-extended-register**] [**-e** *expr*] [**-\-expression**=*expr*...] [**-f** *file*...] [**-\-file**=*file*...] [*file*...]
# DESCRIPTION
@ -55,73 +55,40 @@ this dc(1) will always start with a **scale** of **10**.
The following are the options that dc(1) accepts.
**-h**, **-\-help**
**-C**, **-\-no-digit-clamp**
: Prints a usage message and quits.
: Disables clamping of digits greater than or equal to the current **ibase**
when parsing numbers.
**-v**, **-V**, **-\-version**
This means that the value added to a number from a digit is always that
digit's value multiplied by the value of ibase raised to the power of the
digit's position, which starts from 0 at the least significant digit.
: Print the version information (copyright header) and exit.
If this and/or the **-c** or **-\-digit-clamp** options are given multiple
times, the last one given is used.
**-i**, **-\-interactive**
: Forces interactive mode. (See the **INTERACTIVE MODE** section.)
This option overrides the **DC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section) and the default, which can be queried
with the **-h** or **-\-help** options.
This is a **non-portable extension**.
**-L**, **-\-no-line-length**
**-c**, **-\-digit-clamp**
: Disables line length checking and prints numbers without backslashes and
newlines. In other words, this option sets **BC_LINE_LENGTH** to **0** (see
the **ENVIRONMENT VARIABLES** section).
: Enables clamping of digits greater than or equal to the current **ibase**
when parsing numbers.
This is a **non-portable extension**.
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's
position, which starts from 0 at the least significant digit.
**-P**, **-\-no-prompt**
If this and/or the **-C** or **-\-no-digit-clamp** options are given
multiple times, the last one given is used.
: Disables the prompt in TTY mode. (The prompt is only enabled in TTY mode.
See the **TTY MODE** 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 **DC_ENV_ARGS**.
These options override the **DC_PROMPT** and **DC_TTY_MODE** environment
variables (see the **ENVIRONMENT VARIABLES** section).
This is a **non-portable extension**.
**-R**, **-\-no-read-prompt**
: Disables the read prompt in TTY mode. (The read prompt is only enabled in
TTY mode. See the **TTY MODE** 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 **BC_ENV_ARGS** (see the
**ENVIRONMENT VARIABLES** section). This option is also useful in hash bang
lines of dc(1) scripts that prompt for user input.
This option does not disable the regular prompt because the read prompt is
only used when the **?** command is used.
These options *do* override the **DC_PROMPT** and **DC_TTY_MODE**
environment variables (see the **ENVIRONMENT VARIABLES** section), but only
for the read prompt.
This is a **non-portable extension**.
**-x** **-\-extended-register**
: Enables extended register mode. See the *Extended Register Mode* subsection
of the **REGISTERS** section for more information.
This is a **non-portable extension**.
**-z**, **-\-leading-zeroes**
: Makes dc(1) print all numbers greater than **-1** and less than **1**, and
not equal to **0**, with a leading zero.
This can be set for individual numbers with the **plz(x)**, plznl(x)**,
**pnlz(x)**, and **pnlznl(x)** functions in the extended math library (see
the **LIBRARY** section).
This option overrides the **DC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section) and the default, which can be queried
with the **-h** or **-\-help** options.
This is a **non-portable extension**.
@ -157,6 +124,10 @@ The following are the options that dc(1) accepts.
This is a **non-portable extension**.
**-h**, **-\-help**
: Prints a usage message and exits.
**-I** *ibase*, **-\-ibase**=*ibase*
: Sets the builtin variable **ibase** to the value *ibase* assuming that
@ -166,6 +137,20 @@ The following are the options that dc(1) accepts.
This is a **non-portable extension**.
**-i**, **-\-interactive**
: Forces interactive mode. (See the **INTERACTIVE MODE** section.)
This is a **non-portable extension**.
**-L**, **-\-no-line-length**
: Disables line length checking and prints numbers without backslashes and
newlines. In other words, this option sets **BC_LINE_LENGTH** to **0** (see
the **ENVIRONMENT VARIABLES** section).
This is a **non-portable extension**.
**-O** *obase*, **-\-obase**=*obase*
: Sets the builtin variable **obase** to the value *obase* assuming that
@ -175,6 +160,36 @@ The following are the options that dc(1) accepts.
This is a **non-portable extension**.
**-P**, **-\-no-prompt**
: Disables the prompt in TTY mode. (The prompt is only enabled in TTY mode.
See the **TTY MODE** 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 **DC_ENV_ARGS**.
These options override the **DC_PROMPT** and **DC_TTY_MODE** environment
variables (see the **ENVIRONMENT VARIABLES** section).
This is a **non-portable extension**.
**-R**, **-\-no-read-prompt**
: Disables the read prompt in TTY mode. (The read prompt is only enabled in
TTY mode. See the **TTY MODE** 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 **BC_ENV_ARGS** (see the
**ENVIRONMENT VARIABLES** section). This option is also useful in hash bang
lines of dc(1) scripts that prompt for user input.
This option does not disable the regular prompt because the read prompt is
only used when the **?** command is used.
These options *do* override the **DC_PROMPT** and **DC_TTY_MODE**
environment variables (see the **ENVIRONMENT VARIABLES** section), but only
for the read prompt.
This is a **non-portable extension**.
**-S** *scale*, **-\-scale**=*scale*
: Sets the builtin variable **scale** to the value *scale* assuming that
@ -184,6 +199,28 @@ The following are the options that dc(1) accepts.
This is a **non-portable extension**.
**-v**, **-V**, **-\-version**
: Print the version information (copyright header) and exits.
**-x** **-\-extended-register**
: Enables extended register mode. See the *Extended Register Mode* subsection
of the **REGISTERS** section for more information.
This is a **non-portable extension**.
**-z**, **-\-leading-zeroes**
: Makes dc(1) print all numbers greater than **-1** and less than **1**, and
not equal to **0**, with a leading zero.
This can be set for individual numbers with the **plz(x)**, plznl(x)**,
**pnlz(x)**, and **pnlznl(x)** functions in the extended math library (see
the **LIBRARY** section).
This is a **non-portable extension**.
All long options are **non-portable extensions**.
# STDIN
@ -263,15 +300,40 @@ Comments go from **#** until, and not including, the next newline. This is a
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 are equal to **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**.
Uppercase letters are equal to **9** plus their position in the alphabet (i.e.,
**A** equals **10**, or **9+1**).
Single-character numbers (i.e., **A** alone) take the value that they would have
if they were valid digits, regardless of the value of **ibase**. This means that
**A** alone always equals decimal **10** and **F** alone always equals decimal
**15**.
If a digit or letter makes no sense with the current value of **ibase** (i.e.,
they are greater than or equal to the current value of **ibase**), then the
behavior depends on the existence of the **-c**/**-\-digit-clamp** or
**-C**/**-\-no-digit-clamp** options (see the **OPTIONS** section), the
existence and setting of the **DC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section), or the default, which can be queried with
the **-h**/**-\-help** option.
If clamping is off, then digits or letters that are greater than or equal to the
current value of **ibase** are not changed. Instead, their given value is
multiplied by the appropriate power of **ibase** and added into the number. This
means that, with an **ibase** of **3**, the number **AB** is equal to
**3\^1\*A+3\^0\*B**, which is **3** times **10** plus **11**, or **41**.
If clamping is on, then digits or letters that are greater than or equal to the
current value of **ibase** are set to the value of the highest valid digit in
**ibase** before being multiplied by the appropriate power of **ibase** and
added into the number. This means that, with an **ibase** of **3**, the number
**AB** is equal to **3\^1\*2+3\^0\*2**, which is **3** times **2** plus **2**,
or **8**.
There is one exception to clamping: single-character numbers (i.e., **A**
alone). Such numbers are never clamped and always take the value they would have
in the highest possible **ibase**. This means that **A** alone always equals
decimal **10** and **Z** alone always equals decimal **35**. 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 **ibase** (with the **i** command)
regardless of the current value of **ibase**.
If clamping is on, and the clamped value of a character is needed, use a leading
zero, i.e., for **A**, use **0A**.
# COMMANDS
@ -769,6 +831,8 @@ will be printed with a newline after and then popped from the stack.
is exactly as many as is needed to make dc(1) exit with the **Q** command,
so the sequence **,Q** will make dc(1) exit.
This is a **non-portable extension**.
## Status
These commands query status of the stack or its top value.
@ -791,6 +855,20 @@ These commands query status of the stack or its top value.
If it is a string, pushes **0**.
**u**
: Pops one value off of the stack. If the value is a number, this pushes **1**
onto the stack. Otherwise (if it is a string), it pushes **0**.
This is a **non-portable extension**.
**t**
: Pops one value off of the stack. If the value is a string, this pushes **1**
onto the stack. Otherwise (if it is a number), it pushes **0**.
This is a **non-portable extension**.
**z**
: Pushes the current depth of the stack (before execution of this command)
@ -974,7 +1052,8 @@ be hit.
# ENVIRONMENT VARIABLES
dc(1) recognizes the following environment variables:
As **non-portable extensions**, dc(1) recognizes the following environment
variables:
**DC_ENV_ARGS**
@ -1063,6 +1142,21 @@ dc(1) recognizes the following environment variables:
This environment variable overrides the default, which can be queried with
the **-h** or **-\-help** options.
**DC_DIGIT_CLAMP**
: 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 **ibase** so that all such digits are considered equal
to the **ibase** 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 **ibase**.
This never applies to single-digit numbers, as per the bc(1) standard (see
the **STANDARDS** section).
This environment variable overrides the default, which can be queried with
the **-h** or **-\-help** options.
# EXIT STATUS
dc(1) returns the following exit statuses:
@ -1157,10 +1251,8 @@ setting is used. The default setting can be queried with the **-h** or
**-\-help** options.
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 **stdin** and **stdout** to be connected to a
terminal.
in the bc(1) specification (see the **STANDARDS** section), and interactive mode
requires only **stdin** and **stdout** to be connected to a terminal.
## Command-Line History
@ -1238,13 +1330,13 @@ bc(1)
# STANDARDS
The dc(1) utility operators are compliant with the operators in the IEEE Std
1003.1-2017 (“POSIX.1-2017”) 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 (“POSIX.1-2017”) bc(1) specification at
https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html .
# BUGS
None are known. Report bugs at https://git.yzena.com/gavin/bc.
None are known. Report bugs at https://git.yzena.com/gavin/bc .
# AUTHOR

316
contrib/bc/manuals/dc/H.1
View File

@ -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,7 +25,7 @@
.\" 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" "October 2022" "Gavin D. Howard" "General Commands Manual"
.nh
.ad l
.SH Name
@ -33,17 +33,19 @@
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.
@ -65,83 +67,54 @@ and this dc(1) will always start with a \f[B]scale\f[R] of \f[B]10\f[R].
.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 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]-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).
\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]-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].
\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
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]-x\f[R] \f[B]--extended-register\f[R]
Enables extended register mode.
See the \f[I]Extended Register Mode\f[R] subsection of the
\f[B]REGISTERS\f[R] section for more information.
.RS
.PP
This is a \f[B]non-portable extension\f[R].
.RE
.TP
\f[B]-z\f[R], \f[B]--leading-zeroes\f[R]
Makes dc(1) print all numbers greater than \f[B]-1\f[R] and less than
\f[B]1\f[R], and not equal to \f[B]0\f[R], with a leading zero.
.RS
.PP
This can be set for individual numbers with the \f[B]plz(x)\f[R],
plznl(x)**, \f[B]pnlz(x)\f[R], and \f[B]pnlznl(x)\f[R] functions in the
extended math library (see the \f[B]LIBRARY\f[R] section).
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 +162,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 +176,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 +205,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,13 +254,26 @@ 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 can be set for individual numbers with the \f[B]plz(x)\f[R],
plznl(x)**, \f[B]pnlz(x)\f[R], and \f[B]pnlznl(x)\f[R] functions in the
extended math library (see the \f[B]LIBRARY\f[R] section).
.PP
This is a \f[B]non-portable extension\f[R].
.RE
@ -360,17 +405,48 @@ This is a \f[B]non-portable extension\f[R].
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].
@ -1081,6 +1157,10 @@ 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.
.RS
.PP
This is a \f[B]non-portable extension\f[R].
.RE
.SS Status
.PP
These commands query status of the stack or its top value.
@ -1107,6 +1187,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.
@ -1298,7 +1396,8 @@ 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,6 +1501,22 @@ 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
.TP
\f[B]DC_DIGIT_CLAMP\f[R]
When parsing numbers and if this environment variable exists and
contains an integer, a non-zero value makes dc(1) clamp digits that are
greater than or equal to the current \f[B]ibase\f[R] so that all such
digits are considered equal to the \f[B]ibase\f[R] minus 1, and a zero
value disables such clamping so that those digits are always equal to
their value, which is multiplied by the power of the \f[B]ibase\f[R].
.RS
.PP
This never applies to single-digit numbers, as per the bc(1) standard
(see the \f[B]STANDARDS\f[R] section).
.PP
This environment variable overrides the default, which can be queried
with the \f[B]-h\f[R] or \f[B]--help\f[R] options.
.RE
.SH EXIT STATUS
.PP
dc(1) returns the following exit statuses:
@ -1505,10 +1620,9 @@ 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 Prompt
.PP
If TTY mode is available, then a prompt can be enabled.
@ -1571,14 +1685,14 @@ locales and thus, supports \f[B]LC_MESSAGES\f[R].
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.yzena.com/gavin/bc .
.SH AUTHOR
.PP
Gavin D.

246
contrib/bc/manuals/dc/H.1.md
View File

@ -2,7 +2,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:
@ -34,7 +34,7 @@ dc - arbitrary-precision decimal reverse-Polish notation calculator
# SYNOPSIS
**dc** [**-hiPRvVx**] [**-\-version**] [**-\-help**] [**-\-interactive**] [**-\-no-prompt**] [**-\-no-read-prompt**] [**-\-extended-register**] [**-e** *expr*] [**-\-expression**=*expr*...] [**-f** *file*...] [**-\-file**=*file*...] [*file*...] [**-I** *ibase*] [**-\-ibase**=*ibase*] [**-O** *obase*] [**-\-obase**=*obase*] [**-S** *scale*] [**-\-scale**=*scale*] [**-E** *seed*] [**-\-seed**=*seed*]
**dc** [**-cChiPRvVx**] [**-\-version**] [**-\-help**] [**-\-digit-clamp**] [**-\-no-digit-clamp**] [**-\-interactive**] [**-\-no-prompt**] [**-\-no-read-prompt**] [**-\-extended-register**] [**-e** *expr*] [**-\-expression**=*expr*...] [**-f** *file*...] [**-\-file**=*file*...] [*file*...] [**-I** *ibase*] [**-\-ibase**=*ibase*] [**-O** *obase*] [**-\-obase**=*obase*] [**-S** *scale*] [**-\-scale**=*scale*] [**-E** *seed*] [**-\-seed**=*seed*]
# DESCRIPTION
@ -55,73 +55,49 @@ this dc(1) will always start with a **scale** of **10**.
The following are the options that dc(1) accepts.
**-h**, **-\-help**
**-C**, **-\-no-digit-clamp**
: Prints a usage message and quits.
: Disables clamping of digits greater than or equal to the current **ibase**
when parsing numbers.
**-v**, **-V**, **-\-version**
This means that the value added to a number from a digit is always that
digit's value multiplied by the value of ibase raised to the power of the
digit's position, which starts from 0 at the least significant digit.
: Print the version information (copyright header) and exit.
If this and/or the **-c** or **-\-digit-clamp** options are given multiple
times, the last one given is used.
**-i**, **-\-interactive**
: Forces interactive mode. (See the **INTERACTIVE MODE** section.)
This option overrides the **DC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section) and the default, which can be queried
with the **-h** or **-\-help** options.
This is a **non-portable extension**.
**-L**, **-\-no-line-length**
**-c**, **-\-digit-clamp**
: Disables line length checking and prints numbers without backslashes and
newlines. In other words, this option sets **BC_LINE_LENGTH** to **0** (see
the **ENVIRONMENT VARIABLES** section).
: Enables clamping of digits greater than or equal to the current **ibase**
when parsing numbers.
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's
position, which starts from 0 at the least significant digit.
If this and/or the **-C** or **-\-no-digit-clamp** options are given
multiple times, the last one given is used.
This option overrides the **DC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section) and the default, which can be queried
with the **-h** or **-\-help** options.
This is a **non-portable extension**.
**-P**, **-\-no-prompt**
**-E** *seed*, **-\-seed**=*seed*
: Disables the prompt in TTY mode. (The prompt is only enabled in TTY mode.
See the **TTY MODE** 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 **DC_ENV_ARGS**.
: Sets the builtin variable **seed** to the value *seed* assuming that *seed*
is in base 10. It is a fatal error if *seed* is not a valid number.
These options override the **DC_PROMPT** and **DC_TTY_MODE** environment
variables (see the **ENVIRONMENT VARIABLES** section).
This is a **non-portable extension**.
**-R**, **-\-no-read-prompt**
: Disables the read prompt in TTY mode. (The read prompt is only enabled in
TTY mode. See the **TTY MODE** 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 **BC_ENV_ARGS** (see the
**ENVIRONMENT VARIABLES** section). This option is also useful in hash bang
lines of dc(1) scripts that prompt for user input.
This option does not disable the regular prompt because the read prompt is
only used when the **?** command is used.
These options *do* override the **DC_PROMPT** and **DC_TTY_MODE**
environment variables (see the **ENVIRONMENT VARIABLES** section), but only
for the read prompt.
This is a **non-portable extension**.
**-x** **-\-extended-register**
: Enables extended register mode. See the *Extended Register Mode* subsection
of the **REGISTERS** section for more information.
This is a **non-portable extension**.
**-z**, **-\-leading-zeroes**
: Makes dc(1) print all numbers greater than **-1** and less than **1**, and
not equal to **0**, with a leading zero.
This can be set for individual numbers with the **plz(x)**, plznl(x)**,
**pnlz(x)**, and **pnlznl(x)** functions in the extended math library (see
the **LIBRARY** section).
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
@ -157,6 +133,10 @@ The following are the options that dc(1) accepts.
This is a **non-portable extension**.
**-h**, **-\-help**
: Prints a usage message and exits.
**-I** *ibase*, **-\-ibase**=*ibase*
: Sets the builtin variable **ibase** to the value *ibase* assuming that
@ -166,6 +146,20 @@ The following are the options that dc(1) accepts.
This is a **non-portable extension**.
**-i**, **-\-interactive**
: Forces interactive mode. (See the **INTERACTIVE MODE** section.)
This is a **non-portable extension**.
**-L**, **-\-no-line-length**
: Disables line length checking and prints numbers without backslashes and
newlines. In other words, this option sets **BC_LINE_LENGTH** to **0** (see
the **ENVIRONMENT VARIABLES** section).
This is a **non-portable extension**.
**-O** *obase*, **-\-obase**=*obase*
: Sets the builtin variable **obase** to the value *obase* assuming that
@ -175,6 +169,36 @@ The following are the options that dc(1) accepts.
This is a **non-portable extension**.
**-P**, **-\-no-prompt**
: Disables the prompt in TTY mode. (The prompt is only enabled in TTY mode.
See the **TTY MODE** 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 **DC_ENV_ARGS**.
These options override the **DC_PROMPT** and **DC_TTY_MODE** environment
variables (see the **ENVIRONMENT VARIABLES** section).
This is a **non-portable extension**.
**-R**, **-\-no-read-prompt**
: Disables the read prompt in TTY mode. (The read prompt is only enabled in
TTY mode. See the **TTY MODE** 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 **BC_ENV_ARGS** (see the
**ENVIRONMENT VARIABLES** section). This option is also useful in hash bang
lines of dc(1) scripts that prompt for user input.
This option does not disable the regular prompt because the read prompt is
only used when the **?** command is used.
These options *do* override the **DC_PROMPT** and **DC_TTY_MODE**
environment variables (see the **ENVIRONMENT VARIABLES** section), but only
for the read prompt.
This is a **non-portable extension**.
**-S** *scale*, **-\-scale**=*scale*
: Sets the builtin variable **scale** to the value *scale* assuming that
@ -184,12 +208,25 @@ The following are the options that dc(1) accepts.
This is a **non-portable extension**.
**-E** *seed*, **-\-seed**=*seed*
**-v**, **-V**, **-\-version**
: Sets the builtin variable **seed** to the value *seed* assuming that *seed*
is in base 10. It is a fatal error if *seed* is not a valid number.
: Print the version information (copyright header) and exits.
If multiple instances of this option are given, the last is used.
**-x** **-\-extended-register**
: Enables extended register mode. See the *Extended Register Mode* subsection
of the **REGISTERS** section for more information.
This is a **non-portable extension**.
**-z**, **-\-leading-zeroes**
: Makes dc(1) print all numbers greater than **-1** and less than **1**, and
not equal to **0**, with a leading zero.
This can be set for individual numbers with the **plz(x)**, plznl(x)**,
**pnlz(x)**, and **pnlznl(x)** functions in the extended math library (see
the **LIBRARY** section).
This is a **non-portable extension**.
@ -302,15 +339,40 @@ Comments go from **#** until, and not including, the next newline. This is a
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 are equal to **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**.
Uppercase letters are equal to **9** plus their position in the alphabet (i.e.,
**A** equals **10**, or **9+1**).
Single-character numbers (i.e., **A** alone) take the value that they would have
if they were valid digits, regardless of the value of **ibase**. This means that
**A** alone always equals decimal **10** and **F** alone always equals decimal
**15**.
If a digit or letter makes no sense with the current value of **ibase** (i.e.,
they are greater than or equal to the current value of **ibase**), then the
behavior depends on the existence of the **-c**/**-\-digit-clamp** or
**-C**/**-\-no-digit-clamp** options (see the **OPTIONS** section), the
existence and setting of the **DC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section), or the default, which can be queried with
the **-h**/**-\-help** option.
If clamping is off, then digits or letters that are greater than or equal to the
current value of **ibase** are not changed. Instead, their given value is
multiplied by the appropriate power of **ibase** and added into the number. This
means that, with an **ibase** of **3**, the number **AB** is equal to
**3\^1\*A+3\^0\*B**, which is **3** times **10** plus **11**, or **41**.
If clamping is on, then digits or letters that are greater than or equal to the
current value of **ibase** are set to the value of the highest valid digit in
**ibase** before being multiplied by the appropriate power of **ibase** and
added into the number. This means that, with an **ibase** of **3**, the number
**AB** is equal to **3\^1\*2+3\^0\*2**, which is **3** times **2** plus **2**,
or **8**.
There is one exception to clamping: single-character numbers (i.e., **A**
alone). Such numbers are never clamped and always take the value they would have
in the highest possible **ibase**. This means that **A** alone always equals
decimal **10** and **Z** alone always equals decimal **35**. 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 **ibase** (with the **i** command)
regardless of the current value of **ibase**.
If clamping is on, and the clamped value of a character is needed, use a leading
zero, i.e., for **A**, use **0A**.
In addition, dc(1) accepts numbers in scientific notation. These have the form
**\<number\>e\<integer\>**. The exponent (the portion after the **e**) must be
@ -938,6 +1000,8 @@ will be printed with a newline after and then popped from the stack.
is exactly as many as is needed to make dc(1) exit with the **Q** command,
so the sequence **,Q** will make dc(1) exit.
This is a **non-portable extension**.
## Status
These commands query status of the stack or its top value.
@ -960,6 +1024,20 @@ These commands query status of the stack or its top value.
If it is a string, pushes **0**.
**u**
: Pops one value off of the stack. If the value is a number, this pushes **1**
onto the stack. Otherwise (if it is a string), it pushes **0**.
This is a **non-portable extension**.
**t**
: Pops one value off of the stack. If the value is a string, this pushes **1**
onto the stack. Otherwise (if it is a number), it pushes **0**.
This is a **non-portable extension**.
**z**
: Pushes the current depth of the stack (before execution of this command)
@ -1148,7 +1226,8 @@ be hit.
# ENVIRONMENT VARIABLES
dc(1) recognizes the following environment variables:
As **non-portable extensions**, dc(1) recognizes the following environment
variables:
**DC_ENV_ARGS**
@ -1237,6 +1316,21 @@ dc(1) recognizes the following environment variables:
This environment variable overrides the default, which can be queried with
the **-h** or **-\-help** options.
**DC_DIGIT_CLAMP**
: 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 **ibase** so that all such digits are considered equal
to the **ibase** 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 **ibase**.
This never applies to single-digit numbers, as per the bc(1) standard (see
the **STANDARDS** section).
This environment variable overrides the default, which can be queried with
the **-h** or **-\-help** options.
# EXIT STATUS
dc(1) returns the following exit statuses:
@ -1333,10 +1427,8 @@ setting is used. The default setting can be queried with the **-h** or
**-\-help** options.
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 **stdin** and **stdout** to be connected to a
terminal.
in the bc(1) specification (see the **STANDARDS** section), and interactive mode
requires only **stdin** and **stdout** to be connected to a terminal.
## Prompt
@ -1396,13 +1488,13 @@ bc(1)
# STANDARDS
The dc(1) utility operators are compliant with the operators in the IEEE Std
1003.1-2017 (“POSIX.1-2017”) 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 (“POSIX.1-2017”) bc(1) specification at
https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html .
# BUGS
None are known. Report bugs at https://git.yzena.com/gavin/bc.
None are known. Report bugs at https://git.yzena.com/gavin/bc .
# AUTHOR

316
contrib/bc/manuals/dc/HN.1
View File

@ -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,7 +25,7 @@
.\" 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" "October 2022" "Gavin D. Howard" "General Commands Manual"
.nh
.ad l
.SH Name
@ -33,17 +33,19 @@
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.
@ -65,83 +67,54 @@ and this dc(1) will always start with a \f[B]scale\f[R] of \f[B]10\f[R].
.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 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]-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).
\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]-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].
\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
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]-x\f[R] \f[B]--extended-register\f[R]
Enables extended register mode.
See the \f[I]Extended Register Mode\f[R] subsection of the
\f[B]REGISTERS\f[R] section for more information.
.RS
.PP
This is a \f[B]non-portable extension\f[R].
.RE
.TP
\f[B]-z\f[R], \f[B]--leading-zeroes\f[R]
Makes dc(1) print all numbers greater than \f[B]-1\f[R] and less than
\f[B]1\f[R], and not equal to \f[B]0\f[R], with a leading zero.
.RS
.PP
This can be set for individual numbers with the \f[B]plz(x)\f[R],
plznl(x)**, \f[B]pnlz(x)\f[R], and \f[B]pnlznl(x)\f[R] functions in the
extended math library (see the \f[B]LIBRARY\f[R] section).
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 +162,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 +176,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 +205,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,13 +254,26 @@ 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 can be set for individual numbers with the \f[B]plz(x)\f[R],
plznl(x)**, \f[B]pnlz(x)\f[R], and \f[B]pnlznl(x)\f[R] functions in the
extended math library (see the \f[B]LIBRARY\f[R] section).
.PP
This is a \f[B]non-portable extension\f[R].
.RE
@ -360,17 +405,48 @@ This is a \f[B]non-portable extension\f[R].
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].
@ -1081,6 +1157,10 @@ 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.
.RS
.PP
This is a \f[B]non-portable extension\f[R].
.RE
.SS Status
.PP
These commands query status of the stack or its top value.
@ -1107,6 +1187,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.
@ -1298,7 +1396,8 @@ 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,6 +1501,22 @@ 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
.TP
\f[B]DC_DIGIT_CLAMP\f[R]
When parsing numbers and if this environment variable exists and
contains an integer, a non-zero value makes dc(1) clamp digits that are
greater than or equal to the current \f[B]ibase\f[R] so that all such
digits are considered equal to the \f[B]ibase\f[R] minus 1, and a zero
value disables such clamping so that those digits are always equal to
their value, which is multiplied by the power of the \f[B]ibase\f[R].
.RS
.PP
This never applies to single-digit numbers, as per the bc(1) standard
(see the \f[B]STANDARDS\f[R] section).
.PP
This environment variable overrides the default, which can be queried
with the \f[B]-h\f[R] or \f[B]--help\f[R] options.
.RE
.SH EXIT STATUS
.PP
dc(1) returns the following exit statuses:
@ -1505,10 +1620,9 @@ 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 Prompt
.PP
If TTY mode is available, then a prompt can be enabled.
@ -1567,14 +1681,14 @@ exit, and it uses the default handler for all other signals.
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.yzena.com/gavin/bc .
.SH AUTHOR
.PP
Gavin D.

246
contrib/bc/manuals/dc/HN.1.md
View File

@ -2,7 +2,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:
@ -34,7 +34,7 @@ dc - arbitrary-precision decimal reverse-Polish notation calculator
# SYNOPSIS
**dc** [**-hiPRvVx**] [**-\-version**] [**-\-help**] [**-\-interactive**] [**-\-no-prompt**] [**-\-no-read-prompt**] [**-\-extended-register**] [**-e** *expr*] [**-\-expression**=*expr*...] [**-f** *file*...] [**-\-file**=*file*...] [*file*...] [**-I** *ibase*] [**-\-ibase**=*ibase*] [**-O** *obase*] [**-\-obase**=*obase*] [**-S** *scale*] [**-\-scale**=*scale*] [**-E** *seed*] [**-\-seed**=*seed*]
**dc** [**-cChiPRvVx**] [**-\-version**] [**-\-help**] [**-\-digit-clamp**] [**-\-no-digit-clamp**] [**-\-interactive**] [**-\-no-prompt**] [**-\-no-read-prompt**] [**-\-extended-register**] [**-e** *expr*] [**-\-expression**=*expr*...] [**-f** *file*...] [**-\-file**=*file*...] [*file*...] [**-I** *ibase*] [**-\-ibase**=*ibase*] [**-O** *obase*] [**-\-obase**=*obase*] [**-S** *scale*] [**-\-scale**=*scale*] [**-E** *seed*] [**-\-seed**=*seed*]
# DESCRIPTION
@ -55,73 +55,49 @@ this dc(1) will always start with a **scale** of **10**.
The following are the options that dc(1) accepts.
**-h**, **-\-help**
**-C**, **-\-no-digit-clamp**
: Prints a usage message and quits.
: Disables clamping of digits greater than or equal to the current **ibase**
when parsing numbers.
**-v**, **-V**, **-\-version**
This means that the value added to a number from a digit is always that
digit's value multiplied by the value of ibase raised to the power of the
digit's position, which starts from 0 at the least significant digit.
: Print the version information (copyright header) and exit.
If this and/or the **-c** or **-\-digit-clamp** options are given multiple
times, the last one given is used.
**-i**, **-\-interactive**
: Forces interactive mode. (See the **INTERACTIVE MODE** section.)
This option overrides the **DC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section) and the default, which can be queried
with the **-h** or **-\-help** options.
This is a **non-portable extension**.
**-L**, **-\-no-line-length**
**-c**, **-\-digit-clamp**
: Disables line length checking and prints numbers without backslashes and
newlines. In other words, this option sets **BC_LINE_LENGTH** to **0** (see
the **ENVIRONMENT VARIABLES** section).
: Enables clamping of digits greater than or equal to the current **ibase**
when parsing numbers.
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's
position, which starts from 0 at the least significant digit.
If this and/or the **-C** or **-\-no-digit-clamp** options are given
multiple times, the last one given is used.
This option overrides the **DC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section) and the default, which can be queried
with the **-h** or **-\-help** options.
This is a **non-portable extension**.
**-P**, **-\-no-prompt**
**-E** *seed*, **-\-seed**=*seed*
: Disables the prompt in TTY mode. (The prompt is only enabled in TTY mode.
See the **TTY MODE** 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 **DC_ENV_ARGS**.
: Sets the builtin variable **seed** to the value *seed* assuming that *seed*
is in base 10. It is a fatal error if *seed* is not a valid number.
These options override the **DC_PROMPT** and **DC_TTY_MODE** environment
variables (see the **ENVIRONMENT VARIABLES** section).
This is a **non-portable extension**.
**-R**, **-\-no-read-prompt**
: Disables the read prompt in TTY mode. (The read prompt is only enabled in
TTY mode. See the **TTY MODE** 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 **BC_ENV_ARGS** (see the
**ENVIRONMENT VARIABLES** section). This option is also useful in hash bang
lines of dc(1) scripts that prompt for user input.
This option does not disable the regular prompt because the read prompt is
only used when the **?** command is used.
These options *do* override the **DC_PROMPT** and **DC_TTY_MODE**
environment variables (see the **ENVIRONMENT VARIABLES** section), but only
for the read prompt.
This is a **non-portable extension**.
**-x** **-\-extended-register**
: Enables extended register mode. See the *Extended Register Mode* subsection
of the **REGISTERS** section for more information.
This is a **non-portable extension**.
**-z**, **-\-leading-zeroes**
: Makes dc(1) print all numbers greater than **-1** and less than **1**, and
not equal to **0**, with a leading zero.
This can be set for individual numbers with the **plz(x)**, plznl(x)**,
**pnlz(x)**, and **pnlznl(x)** functions in the extended math library (see
the **LIBRARY** section).
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
@ -157,6 +133,10 @@ The following are the options that dc(1) accepts.
This is a **non-portable extension**.
**-h**, **-\-help**
: Prints a usage message and exits.
**-I** *ibase*, **-\-ibase**=*ibase*
: Sets the builtin variable **ibase** to the value *ibase* assuming that
@ -166,6 +146,20 @@ The following are the options that dc(1) accepts.
This is a **non-portable extension**.
**-i**, **-\-interactive**
: Forces interactive mode. (See the **INTERACTIVE MODE** section.)
This is a **non-portable extension**.
**-L**, **-\-no-line-length**
: Disables line length checking and prints numbers without backslashes and
newlines. In other words, this option sets **BC_LINE_LENGTH** to **0** (see
the **ENVIRONMENT VARIABLES** section).
This is a **non-portable extension**.
**-O** *obase*, **-\-obase**=*obase*
: Sets the builtin variable **obase** to the value *obase* assuming that
@ -175,6 +169,36 @@ The following are the options that dc(1) accepts.
This is a **non-portable extension**.
**-P**, **-\-no-prompt**
: Disables the prompt in TTY mode. (The prompt is only enabled in TTY mode.
See the **TTY MODE** 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 **DC_ENV_ARGS**.
These options override the **DC_PROMPT** and **DC_TTY_MODE** environment
variables (see the **ENVIRONMENT VARIABLES** section).
This is a **non-portable extension**.
**-R**, **-\-no-read-prompt**
: Disables the read prompt in TTY mode. (The read prompt is only enabled in
TTY mode. See the **TTY MODE** 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 **BC_ENV_ARGS** (see the
**ENVIRONMENT VARIABLES** section). This option is also useful in hash bang
lines of dc(1) scripts that prompt for user input.
This option does not disable the regular prompt because the read prompt is
only used when the **?** command is used.
These options *do* override the **DC_PROMPT** and **DC_TTY_MODE**
environment variables (see the **ENVIRONMENT VARIABLES** section), but only
for the read prompt.
This is a **non-portable extension**.
**-S** *scale*, **-\-scale**=*scale*
: Sets the builtin variable **scale** to the value *scale* assuming that
@ -184,12 +208,25 @@ The following are the options that dc(1) accepts.
This is a **non-portable extension**.
**-E** *seed*, **-\-seed**=*seed*
**-v**, **-V**, **-\-version**
: Sets the builtin variable **seed** to the value *seed* assuming that *seed*
is in base 10. It is a fatal error if *seed* is not a valid number.
: Print the version information (copyright header) and exits.
If multiple instances of this option are given, the last is used.
**-x** **-\-extended-register**
: Enables extended register mode. See the *Extended Register Mode* subsection
of the **REGISTERS** section for more information.
This is a **non-portable extension**.
**-z**, **-\-leading-zeroes**
: Makes dc(1) print all numbers greater than **-1** and less than **1**, and
not equal to **0**, with a leading zero.
This can be set for individual numbers with the **plz(x)**, plznl(x)**,
**pnlz(x)**, and **pnlznl(x)** functions in the extended math library (see
the **LIBRARY** section).
This is a **non-portable extension**.
@ -302,15 +339,40 @@ Comments go from **#** until, and not including, the next newline. This is a
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 are equal to **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**.
Uppercase letters are equal to **9** plus their position in the alphabet (i.e.,
**A** equals **10**, or **9+1**).
Single-character numbers (i.e., **A** alone) take the value that they would have
if they were valid digits, regardless of the value of **ibase**. This means that
**A** alone always equals decimal **10** and **F** alone always equals decimal
**15**.
If a digit or letter makes no sense with the current value of **ibase** (i.e.,
they are greater than or equal to the current value of **ibase**), then the
behavior depends on the existence of the **-c**/**-\-digit-clamp** or
**-C**/**-\-no-digit-clamp** options (see the **OPTIONS** section), the
existence and setting of the **DC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section), or the default, which can be queried with
the **-h**/**-\-help** option.
If clamping is off, then digits or letters that are greater than or equal to the
current value of **ibase** are not changed. Instead, their given value is
multiplied by the appropriate power of **ibase** and added into the number. This
means that, with an **ibase** of **3**, the number **AB** is equal to
**3\^1\*A+3\^0\*B**, which is **3** times **10** plus **11**, or **41**.
If clamping is on, then digits or letters that are greater than or equal to the
current value of **ibase** are set to the value of the highest valid digit in
**ibase** before being multiplied by the appropriate power of **ibase** and
added into the number. This means that, with an **ibase** of **3**, the number
**AB** is equal to **3\^1\*2+3\^0\*2**, which is **3** times **2** plus **2**,
or **8**.
There is one exception to clamping: single-character numbers (i.e., **A**
alone). Such numbers are never clamped and always take the value they would have
in the highest possible **ibase**. This means that **A** alone always equals
decimal **10** and **Z** alone always equals decimal **35**. 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 **ibase** (with the **i** command)
regardless of the current value of **ibase**.
If clamping is on, and the clamped value of a character is needed, use a leading
zero, i.e., for **A**, use **0A**.
In addition, dc(1) accepts numbers in scientific notation. These have the form
**\<number\>e\<integer\>**. The exponent (the portion after the **e**) must be
@ -938,6 +1000,8 @@ will be printed with a newline after and then popped from the stack.
is exactly as many as is needed to make dc(1) exit with the **Q** command,
so the sequence **,Q** will make dc(1) exit.
This is a **non-portable extension**.
## Status
These commands query status of the stack or its top value.
@ -960,6 +1024,20 @@ These commands query status of the stack or its top value.
If it is a string, pushes **0**.
**u**
: Pops one value off of the stack. If the value is a number, this pushes **1**
onto the stack. Otherwise (if it is a string), it pushes **0**.
This is a **non-portable extension**.
**t**
: Pops one value off of the stack. If the value is a string, this pushes **1**
onto the stack. Otherwise (if it is a number), it pushes **0**.
This is a **non-portable extension**.
**z**
: Pushes the current depth of the stack (before execution of this command)
@ -1148,7 +1226,8 @@ be hit.
# ENVIRONMENT VARIABLES
dc(1) recognizes the following environment variables:
As **non-portable extensions**, dc(1) recognizes the following environment
variables:
**DC_ENV_ARGS**
@ -1237,6 +1316,21 @@ dc(1) recognizes the following environment variables:
This environment variable overrides the default, which can be queried with
the **-h** or **-\-help** options.
**DC_DIGIT_CLAMP**
: 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 **ibase** so that all such digits are considered equal
to the **ibase** 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 **ibase**.
This never applies to single-digit numbers, as per the bc(1) standard (see
the **STANDARDS** section).
This environment variable overrides the default, which can be queried with
the **-h** or **-\-help** options.
# EXIT STATUS
dc(1) returns the following exit statuses:
@ -1333,10 +1427,8 @@ setting is used. The default setting can be queried with the **-h** or
**-\-help** options.
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 **stdin** and **stdout** to be connected to a
terminal.
in the bc(1) specification (see the **STANDARDS** section), and interactive mode
requires only **stdin** and **stdout** to be connected to a terminal.
## Prompt
@ -1391,13 +1483,13 @@ bc(1)
# STANDARDS
The dc(1) utility operators are compliant with the operators in the IEEE Std
1003.1-2017 (“POSIX.1-2017”) 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 (“POSIX.1-2017”) bc(1) specification at
https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html .
# BUGS
None are known. Report bugs at https://git.yzena.com/gavin/bc.
None are known. Report bugs at https://git.yzena.com/gavin/bc .
# AUTHOR

316
contrib/bc/manuals/dc/N.1
View File

@ -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,7 +25,7 @@
.\" 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" "October 2022" "Gavin D. Howard" "General Commands Manual"
.nh
.ad l
.SH Name
@ -33,17 +33,19 @@
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.
@ -65,83 +67,54 @@ and this dc(1) will always start with a \f[B]scale\f[R] of \f[B]10\f[R].
.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 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]-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).
\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]-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].
\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
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]-x\f[R] \f[B]--extended-register\f[R]
Enables extended register mode.
See the \f[I]Extended Register Mode\f[R] subsection of the
\f[B]REGISTERS\f[R] section for more information.
.RS
.PP
This is a \f[B]non-portable extension\f[R].
.RE
.TP
\f[B]-z\f[R], \f[B]--leading-zeroes\f[R]
Makes dc(1) print all numbers greater than \f[B]-1\f[R] and less than
\f[B]1\f[R], and not equal to \f[B]0\f[R], with a leading zero.
.RS
.PP
This can be set for individual numbers with the \f[B]plz(x)\f[R],
plznl(x)**, \f[B]pnlz(x)\f[R], and \f[B]pnlznl(x)\f[R] functions in the
extended math library (see the \f[B]LIBRARY\f[R] section).
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 +162,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 +176,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 +205,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,13 +254,26 @@ 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 can be set for individual numbers with the \f[B]plz(x)\f[R],
plznl(x)**, \f[B]pnlz(x)\f[R], and \f[B]pnlznl(x)\f[R] functions in the
extended math library (see the \f[B]LIBRARY\f[R] section).
.PP
This is a \f[B]non-portable extension\f[R].
.RE
@ -360,17 +405,48 @@ This is a \f[B]non-portable extension\f[R].
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].
@ -1081,6 +1157,10 @@ 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.
.RS
.PP
This is a \f[B]non-portable extension\f[R].
.RE
.SS Status
.PP
These commands query status of the stack or its top value.
@ -1107,6 +1187,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.
@ -1298,7 +1396,8 @@ 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,6 +1501,22 @@ 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
.TP
\f[B]DC_DIGIT_CLAMP\f[R]
When parsing numbers and if this environment variable exists and
contains an integer, a non-zero value makes dc(1) clamp digits that are
greater than or equal to the current \f[B]ibase\f[R] so that all such
digits are considered equal to the \f[B]ibase\f[R] minus 1, and a zero
value disables such clamping so that those digits are always equal to
their value, which is multiplied by the power of the \f[B]ibase\f[R].
.RS
.PP
This never applies to single-digit numbers, as per the bc(1) standard
(see the \f[B]STANDARDS\f[R] section).
.PP
This environment variable overrides the default, which can be queried
with the \f[B]-h\f[R] or \f[B]--help\f[R] options.
.RE
.SH EXIT STATUS
.PP
dc(1) returns the following exit statuses:
@ -1505,10 +1620,9 @@ 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
@ -1593,14 +1707,14 @@ section).
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.yzena.com/gavin/bc .
.SH AUTHOR
.PP
Gavin D.

246
contrib/bc/manuals/dc/N.1.md
View File

@ -2,7 +2,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:
@ -34,7 +34,7 @@ dc - arbitrary-precision decimal reverse-Polish notation calculator
# SYNOPSIS
**dc** [**-hiPRvVx**] [**-\-version**] [**-\-help**] [**-\-interactive**] [**-\-no-prompt**] [**-\-no-read-prompt**] [**-\-extended-register**] [**-e** *expr*] [**-\-expression**=*expr*...] [**-f** *file*...] [**-\-file**=*file*...] [*file*...] [**-I** *ibase*] [**-\-ibase**=*ibase*] [**-O** *obase*] [**-\-obase**=*obase*] [**-S** *scale*] [**-\-scale**=*scale*] [**-E** *seed*] [**-\-seed**=*seed*]
**dc** [**-cChiPRvVx**] [**-\-version**] [**-\-help**] [**-\-digit-clamp**] [**-\-no-digit-clamp**] [**-\-interactive**] [**-\-no-prompt**] [**-\-no-read-prompt**] [**-\-extended-register**] [**-e** *expr*] [**-\-expression**=*expr*...] [**-f** *file*...] [**-\-file**=*file*...] [*file*...] [**-I** *ibase*] [**-\-ibase**=*ibase*] [**-O** *obase*] [**-\-obase**=*obase*] [**-S** *scale*] [**-\-scale**=*scale*] [**-E** *seed*] [**-\-seed**=*seed*]
# DESCRIPTION
@ -55,73 +55,49 @@ this dc(1) will always start with a **scale** of **10**.
The following are the options that dc(1) accepts.
**-h**, **-\-help**
**-C**, **-\-no-digit-clamp**
: Prints a usage message and quits.
: Disables clamping of digits greater than or equal to the current **ibase**
when parsing numbers.
**-v**, **-V**, **-\-version**
This means that the value added to a number from a digit is always that
digit's value multiplied by the value of ibase raised to the power of the
digit's position, which starts from 0 at the least significant digit.
: Print the version information (copyright header) and exit.
If this and/or the **-c** or **-\-digit-clamp** options are given multiple
times, the last one given is used.
**-i**, **-\-interactive**
: Forces interactive mode. (See the **INTERACTIVE MODE** section.)
This option overrides the **DC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section) and the default, which can be queried
with the **-h** or **-\-help** options.
This is a **non-portable extension**.
**-L**, **-\-no-line-length**
**-c**, **-\-digit-clamp**
: Disables line length checking and prints numbers without backslashes and
newlines. In other words, this option sets **BC_LINE_LENGTH** to **0** (see
the **ENVIRONMENT VARIABLES** section).
: Enables clamping of digits greater than or equal to the current **ibase**
when parsing numbers.
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's
position, which starts from 0 at the least significant digit.
If this and/or the **-C** or **-\-no-digit-clamp** options are given
multiple times, the last one given is used.
This option overrides the **DC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section) and the default, which can be queried
with the **-h** or **-\-help** options.
This is a **non-portable extension**.
**-P**, **-\-no-prompt**
**-E** *seed*, **-\-seed**=*seed*
: Disables the prompt in TTY mode. (The prompt is only enabled in TTY mode.
See the **TTY MODE** 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 **DC_ENV_ARGS**.
: Sets the builtin variable **seed** to the value *seed* assuming that *seed*
is in base 10. It is a fatal error if *seed* is not a valid number.
These options override the **DC_PROMPT** and **DC_TTY_MODE** environment
variables (see the **ENVIRONMENT VARIABLES** section).
This is a **non-portable extension**.
**-R**, **-\-no-read-prompt**
: Disables the read prompt in TTY mode. (The read prompt is only enabled in
TTY mode. See the **TTY MODE** 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 **BC_ENV_ARGS** (see the
**ENVIRONMENT VARIABLES** section). This option is also useful in hash bang
lines of dc(1) scripts that prompt for user input.
This option does not disable the regular prompt because the read prompt is
only used when the **?** command is used.
These options *do* override the **DC_PROMPT** and **DC_TTY_MODE**
environment variables (see the **ENVIRONMENT VARIABLES** section), but only
for the read prompt.
This is a **non-portable extension**.
**-x** **-\-extended-register**
: Enables extended register mode. See the *Extended Register Mode* subsection
of the **REGISTERS** section for more information.
This is a **non-portable extension**.
**-z**, **-\-leading-zeroes**
: Makes dc(1) print all numbers greater than **-1** and less than **1**, and
not equal to **0**, with a leading zero.
This can be set for individual numbers with the **plz(x)**, plznl(x)**,
**pnlz(x)**, and **pnlznl(x)** functions in the extended math library (see
the **LIBRARY** section).
If multiple instances of this option are given, the last is used.
This is a **non-portable extension**.
@ -157,6 +133,10 @@ The following are the options that dc(1) accepts.
This is a **non-portable extension**.
**-h**, **-\-help**
: Prints a usage message and exits.
**-I** *ibase*, **-\-ibase**=*ibase*
: Sets the builtin variable **ibase** to the value *ibase* assuming that
@ -166,6 +146,20 @@ The following are the options that dc(1) accepts.
This is a **non-portable extension**.
**-i**, **-\-interactive**
: Forces interactive mode. (See the **INTERACTIVE MODE** section.)
This is a **non-portable extension**.
**-L**, **-\-no-line-length**
: Disables line length checking and prints numbers without backslashes and
newlines. In other words, this option sets **BC_LINE_LENGTH** to **0** (see
the **ENVIRONMENT VARIABLES** section).
This is a **non-portable extension**.
**-O** *obase*, **-\-obase**=*obase*
: Sets the builtin variable **obase** to the value *obase* assuming that
@ -175,6 +169,36 @@ The following are the options that dc(1) accepts.
This is a **non-portable extension**.
**-P**, **-\-no-prompt**
: Disables the prompt in TTY mode. (The prompt is only enabled in TTY mode.
See the **TTY MODE** 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 **DC_ENV_ARGS**.
These options override the **DC_PROMPT** and **DC_TTY_MODE** environment
variables (see the **ENVIRONMENT VARIABLES** section).
This is a **non-portable extension**.
**-R**, **-\-no-read-prompt**
: Disables the read prompt in TTY mode. (The read prompt is only enabled in
TTY mode. See the **TTY MODE** 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 **BC_ENV_ARGS** (see the
**ENVIRONMENT VARIABLES** section). This option is also useful in hash bang
lines of dc(1) scripts that prompt for user input.
This option does not disable the regular prompt because the read prompt is
only used when the **?** command is used.
These options *do* override the **DC_PROMPT** and **DC_TTY_MODE**
environment variables (see the **ENVIRONMENT VARIABLES** section), but only
for the read prompt.
This is a **non-portable extension**.
**-S** *scale*, **-\-scale**=*scale*
: Sets the builtin variable **scale** to the value *scale* assuming that
@ -184,12 +208,25 @@ The following are the options that dc(1) accepts.
This is a **non-portable extension**.
**-E** *seed*, **-\-seed**=*seed*
**-v**, **-V**, **-\-version**
: Sets the builtin variable **seed** to the value *seed* assuming that *seed*
is in base 10. It is a fatal error if *seed* is not a valid number.
: Print the version information (copyright header) and exits.
If multiple instances of this option are given, the last is used.
**-x** **-\-extended-register**
: Enables extended register mode. See the *Extended Register Mode* subsection
of the **REGISTERS** section for more information.
This is a **non-portable extension**.
**-z**, **-\-leading-zeroes**
: Makes dc(1) print all numbers greater than **-1** and less than **1**, and
not equal to **0**, with a leading zero.
This can be set for individual numbers with the **plz(x)**, plznl(x)**,
**pnlz(x)**, and **pnlznl(x)** functions in the extended math library (see
the **LIBRARY** section).
This is a **non-portable extension**.
@ -302,15 +339,40 @@ Comments go from **#** until, and not including, the next newline. This is a
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 are equal to **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**.
Uppercase letters are equal to **9** plus their position in the alphabet (i.e.,
**A** equals **10**, or **9+1**).
Single-character numbers (i.e., **A** alone) take the value that they would have
if they were valid digits, regardless of the value of **ibase**. This means that
**A** alone always equals decimal **10** and **F** alone always equals decimal
**15**.
If a digit or letter makes no sense with the current value of **ibase** (i.e.,
they are greater than or equal to the current value of **ibase**), then the
behavior depends on the existence of the **-c**/**-\-digit-clamp** or
**-C**/**-\-no-digit-clamp** options (see the **OPTIONS** section), the
existence and setting of the **DC_DIGIT_CLAMP** environment variable (see the
**ENVIRONMENT VARIABLES** section), or the default, which can be queried with
the **-h**/**-\-help** option.
If clamping is off, then digits or letters that are greater than or equal to the
current value of **ibase** are not changed. Instead, their given value is
multiplied by the appropriate power of **ibase** and added into the number. This
means that, with an **ibase** of **3**, the number **AB** is equal to
**3\^1\*A+3\^0\*B**, which is **3** times **10** plus **11**, or **41**.
If clamping is on, then digits or letters that are greater than or equal to the
current value of **ibase** are set to the value of the highest valid digit in
**ibase** before being multiplied by the appropriate power of **ibase** and
added into the number. This means that, with an **ibase** of **3**, the number
**AB** is equal to **3\^1\*2+3\^0\*2**, which is **3** times **2** plus **2**,
or **8**.
There is one exception to clamping: single-character numbers (i.e., **A**
alone). Such numbers are never clamped and always take the value they would have
in the highest possible **ibase**. This means that **A** alone always equals
decimal **10** and **Z** alone always equals decimal **35**. 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 **ibase** (with the **i** command)
regardless of the current value of **ibase**.
If clamping is on, and the clamped value of a character is needed, use a leading
zero, i.e., for **A**, use **0A**.
In addition, dc(1) accepts numbers in scientific notation. These have the form
**\<number\>e\<integer\>**. The exponent (the portion after the **e**) must be
@ -938,6 +1000,8 @@ will be printed with a newline after and then popped from the stack.
is exactly as many as is needed to make dc(1) exit with the **Q** command,
so the sequence **,Q** will make dc(1) exit.
This is a **non-portable extension**.
## Status
These commands query status of the stack or its top value.
@ -960,6 +1024,20 @@ These commands query status of the stack or its top value.
If it is a string, pushes **0**.
**u**
: Pops one value off of the stack. If the value is a number, this pushes **1**
onto the stack. Otherwise (if it is a string), it pushes **0**.
This is a **non-portable extension**.
**t**
: Pops one value off of the stack. If the value is a string, this pushes **1**
onto the stack. Otherwise (if it is a number), it pushes **0**.
This is a **non-portable extension**.
**z**
: Pushes the current depth of the stack (before execution of this command)
@ -1148,7 +1226,8 @@ be hit.
# ENVIRONMENT VARIABLES
dc(1) recognizes the following environment variables:
As **non-portable extensions**, dc(1) recognizes the following environment
variables:
**DC_ENV_ARGS**
@ -1237,6 +1316,21 @@ dc(1) recognizes the following environment variables:
This environment variable overrides the default, which can be queried with
the **-h** or **-\-help** options.
**DC_DIGIT_CLAMP**
: 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 **ibase** so that all such digits are considered equal
to the **ibase** 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 **ibase**.
This never applies to single-digit numbers, as per the bc(1) standard (see
the **STANDARDS** section).
This environment variable overrides the default, which can be queried with
the **-h** or **-\-help** options.
# EXIT STATUS
dc(1) returns the following exit statuses:
@ -1333,10 +1427,8 @@ setting is used. The default setting can be queried with the **-h** or
**-\-help** options.
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 **stdin** and **stdout** to be connected to a
terminal.
in the bc(1) specification (see the **STANDARDS** section), and interactive mode
requires only **stdin** and **stdout** to be connected to a terminal.
## Command-Line History
@ -1414,13 +1506,13 @@ bc(1)
# STANDARDS
The dc(1) utility operators are compliant with the operators in the IEEE Std
1003.1-2017 (“POSIX.1-2017”) 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 (“POSIX.1-2017”) bc(1) specification at
https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html .
# BUGS
None are known. Report bugs at https://git.yzena.com/gavin/bc.
None are known. Report bugs at https://git.yzena.com/gavin/bc .
# AUTHOR

2
contrib/bc/scripts/exec-install.sh
View File

@ -2,7 +2,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:

4
contrib/bc/scripts/format.sh
View File

@ -2,7 +2,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:
@ -47,3 +47,5 @@ for f in $files; do
sed -i 's|^#else //|#else //|g' "$f"
done
sed -i 's|^ // clang-format on| // clang-format on|g' src/program.c

2
contrib/bc/scripts/functions.sh
View File

@ -2,7 +2,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:

2
contrib/bc/scripts/karatsuba.py
View File

@ -2,7 +2,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:

Some files were not shown because too many files have changed in this diff Show More