diff options
Diffstat (limited to 'contrib/bc')
206 files changed, 24714 insertions, 11467 deletions
diff --git a/contrib/bc/.clang-format b/contrib/bc/.clang-format deleted file mode 100644 index 845db62a72e6..000000000000 --- a/contrib/bc/.clang-format +++ /dev/null @@ -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: [] -... diff --git a/contrib/bc/.clang-tidy b/contrib/bc/.clang-tidy deleted file mode 100644 index 04e13de763a2..000000000000 --- a/contrib/bc/.clang-tidy +++ /dev/null @@ -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' -... diff --git a/contrib/bc/.gitignore b/contrib/bc/.gitignore deleted file mode 100644 index 8d0c7d33935c..000000000000 --- a/contrib/bc/.gitignore +++ /dev/null @@ -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 diff --git a/contrib/bc/LICENSE.md b/contrib/bc/LICENSE.md index 8ab2e6069881..c8f6758e6d4b 100644 --- a/contrib/bc/LICENSE.md +++ b/contrib/bc/LICENSE.md @@ -1,6 +1,6 @@ # License -Copyright (c) 2018-2021 Gavin D. Howard <yzena.tech@gmail.com> +Copyright (c) 2018-2024 Gavin D. Howard <gavin@gavinhoward.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@gavinhoward.com> Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: @@ -59,8 +59,8 @@ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 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) 2014-2017 Melissa O'Neill and PCG Project contributors<br> +Copyright (c) 2018-2024 Gavin D. Howard <gavin@gavinhoward.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 diff --git a/contrib/bc/MEMORY_BUGS.md b/contrib/bc/MEMORY_BUGS.md new file mode 100644 index 000000000000..2e41ad3d75c9 --- /dev/null +++ b/contrib/bc/MEMORY_BUGS.md @@ -0,0 +1,65 @@ +# 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 `3.0.0` until `6.7.5` (inclusive) of `bc` and `dc`, there is a + possible out-of-bounds read when there is an error flushing `stdout` on exit + because such an error would cause `bc` and `dc` to attempt to use a `jmp_buf` + when none exists. + + The first version without this bug is `6.7.6`. + +* 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`. + +* In version `6.0.0` until `6.2.4` (inclusive) of `bcl`, there is a possible + use-after-free if `bcl_init()` fails. + + The first version without this bug is `6.2.5`. diff --git a/contrib/bc/Makefile.in b/contrib/bc/Makefile.in index 041b9b014cfd..c63dc242e79a 100644 --- a/contrib/bc/Makefile.in +++ b/contrib/bc/Makefile.in @@ -1,7 +1,7 @@ # # SPDX-License-Identifier: BSD-2-Clause # -# Copyright (c) 2018-2021 Gavin D. Howard and contributors. +# Copyright (c) 2018-2024 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 @@ -94,6 +94,10 @@ BC = bc DC = dc BC_EXEC = $(BIN)/$(EXEC_PREFIX)$(BC) DC_EXEC = $(BIN)/$(EXEC_PREFIX)$(DC) +BC_FUZZER = $(BIN)/$(BC)_fuzzer_c +BC_FUZZER_C = $(BIN)/$(BC)_fuzzer_C +DC_FUZZER = $(BIN)/$(DC)_fuzzer_c +DC_FUZZER_C = $(BIN)/$(DC)_fuzzer_C BC_TEST_OUTPUTS = tests/bc_outputs BC_FUZZ_OUTPUTS = tests/fuzzing/bc_outputs1 tests/fuzzing/bc_outputs2 tests/fuzzing/bc_outputs3 @@ -146,12 +150,14 @@ 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%% +BC_ENABLE_OSSFUZZ = %%OSSFUZZ%% BC_ENABLE_MEMCHECK = %%MEMCHECK%% +LIB_FUZZING_ENGINE = %%LIB_FUZZING_ENGINE%% + BC_DEFAULT_BANNER = %%BC_DEFAULT_BANNER%% BC_DEFAULT_SIGINT_RESET = %%BC_DEFAULT_SIGINT_RESET%% DC_DEFAULT_SIGINT_RESET = %%DC_DEFAULT_SIGINT_RESET%% @@ -161,6 +167,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,24 +200,27 @@ 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%% CPPFLAGS3 = $(CPPFLAGS2) -DEXECPREFIX=$(EXEC_PREFIX) -DMAINEXEC=$(MAIN_EXEC) -CPPFLAGS4 = $(CPPFLAGS3) %%BSD%% +CPPFLAGS4 = $(CPPFLAGS3) %%BSD%% %%APPLE%% CPPFLAGS5 = $(CPPFLAGS4) -DBC_NUM_KARATSUBA_LEN=$(BC_NUM_KARATSUBA_LEN) 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) +CPPFLAGS9 = $(CPPFLAGS8) -DBC_ENABLE_MEMCHECK=$(BC_ENABLE_MEMCHECK) -DBC_ENABLE_AFL=$(BC_ENABLE_AFL) +CPPFLAGS = $(CPPFLAGS9) -DBC_ENABLE_OSSFUZZ=$(BC_ENABLE_OSSFUZZ) +CFLAGS = $(CPPFLAGS) $(BC_DEFS) $(DC_DEFS) %%CPPFLAGS%% %%CFLAGS%% +LDFLAGS = %%LDFLAGS%% HOSTCFLAGS = %%HOSTCFLAGS%% @@ -236,25 +247,25 @@ $(GEN_EXEC): $(GEN_DIR) %%GEN_EXEC_TARGET%% $(BC_LIB_C): $(GEN_EXEC) $(BC_LIB) - $(GEN_EMU) $(GEN_EXEC) $(BC_LIB) $(BC_LIB_C) $(BC_EXCLUDE_EXTRA_MATH) $(BC_LIB_C_ARGS) + $(GEN_EMU) $(GEN_EXEC) $(BC_LIB) $(BC_LIB_C) $(BC_EXCLUDE_EXTRA_MATH) $(BC_LIB_C_ARGS) "" "" 1 $(BC_LIB_O): $(BC_LIB_C) $(CC) $(CFLAGS) -o $@ -c $< $(BC_LIB2_C): $(GEN_EXEC) $(BC_LIB2) - $(GEN_EMU) $(GEN_EXEC) $(BC_LIB2) $(BC_LIB2_C) $(BC_EXCLUDE_EXTRA_MATH) $(BC_LIB2_C_ARGS) + $(GEN_EMU) $(GEN_EXEC) $(BC_LIB2) $(BC_LIB2_C) $(BC_EXCLUDE_EXTRA_MATH) $(BC_LIB2_C_ARGS) "" "" 1 $(BC_LIB2_O): $(BC_LIB2_C) $(CC) $(CFLAGS) -o $@ -c $< $(BC_HELP_C): $(GEN_EXEC) $(BC_HELP) - $(GEN_EMU) $(GEN_EXEC) $(BC_HELP) $(BC_HELP_C) $(BC_EXCLUDE_EXTRA_MATH) bc_help "" $(BC_ENABLED_NAME) + $(GEN_EMU) $(GEN_EXEC) $(BC_HELP) $(BC_HELP_C) $(BC_EXCLUDE_EXTRA_MATH) bc_help "" $(BC_ENABLED_NAME) 0 $(BC_HELP_O): $(BC_HELP_C) $(CC) $(CFLAGS) -o $@ -c $< $(DC_HELP_C): $(GEN_EXEC) $(DC_HELP) - $(GEN_EMU) $(GEN_EXEC) $(DC_HELP) $(DC_HELP_C) $(BC_EXCLUDE_EXTRA_MATH) dc_help "" $(DC_ENABLED_NAME) + $(GEN_EMU) $(GEN_EXEC) $(DC_HELP) $(DC_HELP_C) $(BC_EXCLUDE_EXTRA_MATH) dc_help "" $(DC_ENABLED_NAME) 0 $(DC_HELP_O): $(DC_HELP_C) $(CC) $(CFLAGS) -o $@ -c $< @@ -299,11 +310,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 +508,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%% @@ -550,11 +556,13 @@ clean_config: clean clean_benchmarks @$(RM) -f Makefile @$(RM) -f $(BC_MD) $(BC_MANPAGE) @$(RM) -f $(DC_MD) $(DC_MANPAGE) + @$(RM) -f compile_commands.json + @$(RM) -f $(BCL_PC) clean_coverage: @printf 'Cleaning coverage files...\n' @$(RM) -f *.gcov - @$(RM) -f *.html + @$(RM) -f *.html *.css @$(RM) -f *.gcda *.gcno @$(RM) -f *.profraw @$(RM) -f $(GCDA) $(GCNO) diff --git a/contrib/bc/NEWS.md b/contrib/bc/NEWS.md index 543507c717df..e3b1f9ecb7bc 100644 --- a/contrib/bc/NEWS.md +++ b/contrib/bc/NEWS.md @@ -1,5 +1,299 @@ # News +## 7.0.2 + +This is a production release that fixes `Ctrl+d` on FreeBSD and Linux when using +`editline`. + +This bug was caused by the macOS fix in `7.0.0`. Unfortunately, this means that +macOS does not respond properly to `Ctrl+d`. + +## 7.0.1 + +This is a production release that fixes a warning using GCC on FreeBSD. + +Other users do ***NOT*** need to upgrade. + +## 7.0.0 + +This is a production release to fix three bugs. + +The first bug is that `bc`/`dc` will exit on macOS when the terminal is resized. + +The second bug is that an array, which should only be a function parameter, was +accepted as part of larger expressions. + +The third bug is that value stack for `dc` was cleared on any error. However, +this is not how other `dc` behave. To bring `dc` more in line with other +implementations, this behavior was changed. This change is why this version is a +new major version. + +## 6.7.6 + +This is a production release to fix one bug. + +The bug was that `bc` attempted to jump out when flushing `stdout` on exit, but +there is no jump buf at that point. + +## 6.7.5 + +This is a production release to fix one small bug. + +The bug is that sometimes numbers are printed to incorrect line lengths. The +number is always correct; the line is just longer than the limit. + +Users who do not care do not need to update. + +## 6.7.4 + +This is a production release to fix problems in the `bc` manual. + +Users only need to update if desired. + +## 6.7.3 + +This is a production release to fix the library build on Mac OSX. + +Users on other platforms do *not* need to update. + +## 6.7.2 + +This is a production release to remove some debugging code that I accidentally +committed. + +## 6.7.1 + +This is a production release with a bug fix for `SIGINT` only being handled +once. + +## 6.7.0 + +This is a production release with three new functions in the [extended math +library][16]: `min()`, `max()`, and `i2rand()`. + +## 6.6.1 + +This is a production release with an improved `p()` function in the [extended +math library][16]. + +Users who don't care do not need to upgrade. + +## 6.6.0 + +This is a production release with two bug fixes and one change. + +The first bug fix is to fix the build on Mac OSX. + +The second bug was to remove printing a leading zero in scientific or +engineering output modes. + +The change was that the implementation of `irand()` was improved to call the +PRNG less. + +## 6.5.0 + +This is a production release that fixes an infinite loop bug in `root()` and +`cbrt()`, fixes a bug with `BC_LINE_LENGTH=0`, and adds the `fib()` function to +the extended math library to calculate Fibonacci numbers. + +## 6.4.0 + +This is a production release that fixes a `read()`/`?` bug and adds features to +`bcl`. + +The bug was that multiple read calls could repeat old data. + +The new features in `bcl` are functions to preserve `BclNumber` arguments and +not free them. + +***WARNING for `bcl` Users***: The `bcl_rand_seedWithNum()` function used to not +consume its arguments. Now it does. This change could have made this version +`7.0.0`, but I'm 99.9% confident that there are no `bcl` users, or if there are, +they probably don't use the PRNG. So I took a risk and didn't update the major +version. + +`bcl` now includes more capacity to check for invalid numbers when built to run +under Valgrind. + +## 6.3.1 + +This is a production release that fixes a `bc` dependency loop for minimal +environments and Linux from Scratch. + +## 6.3.0 + +This is a production release with a couple of fixes for manuals and a new +feature for `dc`: there is now a command to query whether extended registers are +enabled or not. + +Users who don't care do not need to upgrade. + +## 6.2.6 + +This is a production release that fixes an install bug that affected locale +installation of all locales when using `mksh`. Users do ***NOT*** need to +upgrade if they don't use `mksh` and/or don't need to install all locales. + +## 6.2.5 + +This is a production release that fixes a test bug that affected Android and +`mksh`. Users do ***NOT*** need to upgrade unless they use `mksh` or another +affected shell and need to run the test suite. + +## 6.2.4 + +This is a production release that fixes a test failure that happens when +`tests/bc/scripts/timeconst.bc` doesn't exist. This should only affect +packagers. + +This bug happened because I forgot something I added in the previous release: +better error checking in tests to help packagers. Unfortunately, I was too +zealous with the error checking. + +## 6.2.3 + +This is a production release that moves `bc` to <https://git.gavinhoward.com>. + +That's all it does: update links. Users do ***NOT*** need to upgrade; there are +redirects that will stay in place indefinitely. This release is only for new +users. + +## 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 @@ -535,7 +829,7 @@ function, `strdup()`, which is not in POSIX 2001, and it is in the X/Open System Interfaces group 2001. It is, however, in POSIX 2008, and since POSIX 2008 is old enough to be supported anywhere that I care, that should be the requirement. -Second, the BcVm global variable was put into `bss`. This actually slightly +Second, the `BcVm` global variable was put into `bss`. This actually slightly reduces the size of the executable from a massive code shrink, and it will stop `bc` from allocating a large set of memory when `bc` starts. diff --git a/contrib/bc/NOTICE.md b/contrib/bc/NOTICE.md index 56d2935ab4b3..35536b2c27d7 100644 --- a/contrib/bc/NOTICE.md +++ b/contrib/bc/NOTICE.md @@ -1,6 +1,6 @@ # Notice -Copyright 2018-2021 Gavin D. Howard and contributors. +Copyright 2018-2024 Gavin D. Howard and contributors. ## Contributors diff --git a/contrib/bc/README.md b/contrib/bc/README.md index 64c58410162c..696e6186b8bd 100644 --- a/contrib/bc/README.md +++ b/contrib/bc/README.md @@ -1,12 +1,12 @@ # `bc` -***WARNING: New user registration for https://git.yzena.com/ is disabled because -of spam. If you need to report a bug with `bc`, email gavin at this site minus -the `git.` part for an account, and I will create one for you. Or you can report -an issue at [GitHub][29].*** +***WARNING: New user registration for <https://git.gavinhoward.com/> is disabled +because of spam. If you need to report a bug with `bc`, email gavin at this site +minus the `git.` part for an account, and I will create one for you. Or you can +report an issue at [GitHub][29].*** -***WARNING: This project has moved to [https://git.yzena.com/][20] for [these -reasons][21], though GitHub will remain a mirror.*** +***WARNING: This project has moved to [https://git.gavinhoward.com/][20] for +[these reasons][21], though GitHub will remain a mirror.*** This is an implementation of the [POSIX `bc` calculator][12] that implements [GNU `bc`][1] extensions, as well as the period (`.`) extension for the BSD @@ -48,7 +48,7 @@ POSIX-compatible systems that are known to work: * FreeBSD * OpenBSD * NetBSD -* Mac OSX +* macOS * Solaris* (as long as the Solaris version supports POSIX 2008) * AIX * HP-UX* (except for history) @@ -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,60 @@ 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. + +* **The `!` operator has higher precedence than the `!` operator in other `bc` + implementations.** +* 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]. @@ -369,13 +424,23 @@ Other projects based on this bc are: * [busybox `bc`][8]. The busybox maintainers have made their own changes, so any bugs in the busybox `bc` should be reported to them. - * [toybox `bc`][9]. The maintainer has also made his own changes, so bugs in the toybox `bc` should be reported there. - * [FreeBSD `bc`][23]. While the `bc` in FreeBSD is kept up-to-date, it is better to [report bugs there][24], as well as [submit patches][25], and the maintainers of the package will contact me if necessary. +* [macOS `bc`][35]. Any bugs in that `bc` should be reported to me, but do + expect bugs because the version is old. +* [Android Open Source `bc`][32]. Any bugs in that `bc` can be reported here. + +This is a non-comprehensive list of Linux distros that use this `bc` as the +system `bc`: + +* [Gentoo][33]; it is a first-class alternative to GNU `bc`, but not exclusive. +* [Linux from Scratch][34]. + +Other Linux distros package it as a second-class alternative, usually as `bc-gh` +or `howard-bc`. ## Language @@ -390,6 +455,10 @@ This `bc` uses the commit message guidelines laid out in [this blog post][10]. This `bc` uses [semantic versioning][11]. +## AI-Free + +This repository is 100% AI-Free code. + ## Contents Items labeled with `(maintainer use only)` are not included in release source @@ -428,10 +497,10 @@ Folders: [10]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html [11]: http://semver.org/ [12]: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html -[17]: https://git.yzena.com/gavin/vim-bc -[18]: https://git.yzena.com/gavin/bc_libs +[17]: https://git.gavinhoward.com/gavin/vim-bc +[18]: https://git.gavinhoward.com/gavin/bc_libs [19]: ./manuals/benchmarks.md -[20]: https://git.yzena.com/gavin/bc +[20]: https://git.gavinhoward.com/gavin/bc [21]: https://gavinhoward.com/2020/04/i-am-moving-away-from-github/ [22]: https://www.deepl.com/translator [23]: https://cgit.freebsd.org/src/tree/contrib/bc @@ -441,3 +510,9 @@ 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 +[32]: https://android.googlesource.com/platform/external/bc/ +[33]: https://github.com/gentoo/gentoo/blob/master/app-alternatives/bc/bc-0.ebuild#L8 +[34]: https://www.linuxfromscratch.org/lfs/view/stable/chapter08/bc.html +[35]: https://github.com/apple-oss-distributions/bc/tree/main/bc diff --git a/contrib/bc/compile_flags.txt b/contrib/bc/compile_flags.txt new file mode 100644 index 000000000000..3324798013c6 --- /dev/null +++ b/contrib/bc/compile_flags.txt @@ -0,0 +1,16 @@ +-Weverything +-pedantic +-Wno-unsafe-buffer-usage +-D_POSIX_C_SOURCE=200809L +-D_XOPEN_SOURCE=700 +-D_BSD_SOURCE +-D_GNU_SOURCE +-D_DEFAULT_SOURCE +-Iinclude/ +-DBC_DEBUG=1 +-DBC_ENABLED=1 +-DDC_ENABLED=1 +-DBC_ENABLE_EXTRA_MATH=1 +-DBC_ENABLE_HISTORY=1 +-DBC_ENABLE_NLS=1 +-DBC_ENABLE_OSSFUZZ=0 diff --git a/contrib/bc/configure.sh b/contrib/bc/configure.sh index 5dc4853fbb47..442165d15693 100755 --- a/contrib/bc/configure.sh +++ b/contrib/bc/configure.sh @@ -2,7 +2,7 @@ # # SPDX-License-Identifier: BSD-2-Clause # -# Copyright (c) 2018-2021 Gavin D. Howard and contributors. +# Copyright (c) 2018-2024 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 "$_usage_val" + 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,8 +121,13 @@ 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 ' Set the karatsuba length to KARATSUBA_LEN (default is 32).\n' printf ' It is an error if KARATSUBA_LEN is not a number or is less than 16.\n' printf ' -l, --install-all-locales\n' printf ' Installs all locales, regardless of how many are on the system. This\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 -i, 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' @@ -153,10 +181,15 @@ usage() { printf ' Enable a build appropriate for valgrind. For development only.\n' printf ' -z, --enable-fuzz-mode\n' printf ' Enable fuzzing mode. THIS IS FOR DEVELOPMENT ONLY.\n' + printf ' -Z, --enable-ossfuzz-mode\n' + printf ' Enable fuzzing mode for OSS-Fuzz. THIS IS FOR DEVELOPMENT ONLY.\n' printf ' --prefix PREFIX\n' 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 +235,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 +353,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 +463,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 +565,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 +605,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 +659,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 +689,169 @@ 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 + ossfuzz=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 + ossfuzz=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="-Weverything -Wno-padded -Wno-unsafe-buffer-usage -Wno-poison-system-directories" + CFLAGS="$CFLAGS -Wno-switch-default -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 + ossfuzz=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 -Wno-unsafe-buffer-usage -Wno-poison-system-directories" + CFLAGS="$CFLAGS -Wno-switch-default -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 + ossfuzz=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 +885,7 @@ coverage=0 karatsuba_len=32 debug=0 hist=1 -editline=0 -readline=0 +hist_impl="internal" extra_math=1 optimization="" generate_tests=1 @@ -689,10 +896,12 @@ strip_bin=1 all_locales=0 library=0 fuzz=0 +ossfuzz=0 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 +914,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:tTvzZ-" opt; do case "$opt" in a) library=1 ;; @@ -719,26 +930,30 @@ 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 ;; T) strip_bin=0 ;; v) vg=1 ;; z) fuzz=1 ;; + Z) ossfuzz=1 ;; -) arg="$1" arg="${arg#--}" @@ -814,13 +1029,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 +1057,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,11 +1073,14 @@ 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 ;; + enable-ossfuzz-mode) ossfuzz=1 ;; enable-memcheck) memcheck=1 ;; install-all-locales) all_locales=1 ;; help* | bc-only* | dc-only* | coverage* | debug*) @@ -875,12 +1093,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 +1151,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 +1223,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 +1236,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" @@ -1107,6 +1331,45 @@ elif [ "$dc_only" -eq 1 ]; then tests="test_dc" +elif [ "$ossfuzz" -eq 1 ]; then + + if [ "$bc_only" -ne 0 ] || [ "$dc_only" -ne 0 ]; then + usage "An OSS-Fuzz build must build both fuzzers." + fi + + bc=1 + dc=1 + + # Expressions *cannot* exit in an OSS-Fuzz build. + bc_default_expr_exit=0 + dc_default_expr_exit=0 + + executables="bc_fuzzer and dc_fuzzer" + + karatsuba="@\$(KARATSUBA) 30 0 \$(BC_EXEC)" + karatsuba_test="@\$(KARATSUBA) 1 100 \$(BC_EXEC)" + + if [ "$library" -eq 0 ]; then + install_prereqs=" install_execs" + install_man_prereqs=" install_bc_manpage install_dc_manpage" + uninstall_prereqs=" uninstall_bc uninstall_dc" + uninstall_man_prereqs=" uninstall_bc_manpage uninstall_dc_manpage" + else + install_prereqs=" install_library install_bcl_header" + install_man_prereqs=" install_bcl_manpage" + uninstall_prereqs=" uninstall_library uninstall_bcl_header" + uninstall_man_prereqs=" uninstall_bcl_manpage" + tests="test_library" + fi + + second_target_prereqs="src/bc_fuzzer.o $default_target_prereqs" + default_target_prereqs="\$(BC_FUZZER) src/dc_fuzzer.o $default_target_prereqs" + default_target_cmd="\$(CXX) \$(CFLAGS) src/dc_fuzzer.o \$(LIB_FUZZING_ENGINE) \$(OBJS) \$(LDFLAGS) -o \$(DC_FUZZER) \&\& ln -sf ./dc_fuzzer_c \$(DC_FUZZER_C)" + second_target_cmd="\$(CXX) \$(CFLAGS) src/bc_fuzzer.o \$(LIB_FUZZING_ENGINE) \$(OBJS) \$(LDFLAGS) -o \$(BC_FUZZER) \&\& ln -sf ./bc_fuzzer_c \$(BC_FUZZER_C)" + + default_target="\$(DC_FUZZER) \$(DC_FUZZER_C)" + second_target="\$(BC_FUZZER) \$(BC_FUZZER_C)" + else bc=1 @@ -1136,8 +1399,12 @@ else fi +if [ "$fuzz" -ne 0 ] && [ "$ossfuzz" -ne 0 ]; then + usage "Fuzzing mode and OSS-Fuzz mode are mutually exclusive" +fi + # We need specific stuff for fuzzing. -if [ "$fuzz" -ne 0 ]; then +if [ "$fuzz" -ne 0 ] || [ "$ossfuzz" -ne 0 ]; then debug=1 hist=0 nls=0 @@ -1154,12 +1421,7 @@ if [ "$debug" -eq 1 ]; then CFLAGS="-g $CFLAGS" else - CPPFLAGS="-DNDEBUG $CPPFLAGS" - - if [ "$strip_bin" -ne 0 ]; then - LDFLAGS="-s $LDFLAGS" - fi fi # Set optimization CFLAGS. @@ -1187,7 +1449,6 @@ else COVERAGE_PREREQS="" fi - # Set some defaults. if [ -z "${DESTDIR+set}" ]; then destdir="" @@ -1195,8 +1456,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 +1495,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 @@ -1273,17 +1538,23 @@ if [ "$nls" -ne 0 ]; then flags="-DBC_ENABLE_NLS=1 -DBC_ENABLED=$bc -DDC_ENABLED=$dc" flags="$flags -DBC_ENABLE_HISTORY=$hist -DBC_ENABLE_LIBRARY=0 -DBC_ENABLE_AFL=0" - flags="$flags -DBC_ENABLE_EXTRA_MATH=$extra_math -I$scriptdir/include/" - flags="$flags -D_POSIX_C_SOURCE=200809L -D_XOPEN_SOURCE=700" + flags="$flags -DBC_ENABLE_EXTRA_MATH=$extra_math -DBC_ENABLE_OSSFUZZ=0" + flags="$flags -I$scriptdir/include/ -D_POSIX_C_SOURCE=200809L -D_XOPEN_SOURCE=700" + + ccbase=$(basename "$CC") - "$CC" $CPPFLAGS $CFLAGS $flags -c "$scriptdir/src/vm.c" -o "./vm.o" > /dev/null 2>&1 + if [ "$ccbase" = "clang" ]; then + flags="$flags -Wno-unreachable-code" + fi + + "$CC" $CPPFLAGS $CFLAGS $flags -c "$scriptdir/src/vm.c" -E > /dev/null err="$?" rm -rf "./vm.o" - # If this errors, it is probably because of building on Windows, - # and NLS is not supported on Windows, so disable it. + # If this errors, it is probably because of building on Windows or musl, + # and NLS is not supported on Windows or musl, so disable it. if [ "$err" -ne 0 ]; then printf 'NLS does not work.\n' if [ $force -eq 0 ]; then @@ -1296,7 +1567,7 @@ if [ "$nls" -ne 0 ]; then printf 'NLS works.\n\n' printf 'Testing gencat...\n' - gencat "./en_US.cat" "$scriptdir/locales/en_US.msg" > /dev/null 2>&1 + gencat "./en_US.cat" "$scriptdir/locales/en_US.msg" > /dev/null err="$?" @@ -1351,8 +1622,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 @@ -1362,10 +1640,10 @@ if [ "$hist" -eq 1 ]; then flags="-DBC_ENABLE_HISTORY=1 -DBC_ENABLED=$bc -DDC_ENABLED=$dc" flags="$flags -DBC_ENABLE_NLS=$nls -DBC_ENABLE_LIBRARY=0 -DBC_ENABLE_AFL=0" flags="$flags -DBC_ENABLE_EDITLINE=$editline -DBC_ENABLE_READLINE=$readline" - flags="$flags -DBC_ENABLE_EXTRA_MATH=$extra_math -I$scriptdir/include/" - flags="$flags -D_POSIX_C_SOURCE=200809L -D_XOPEN_SOURCE=700" + flags="$flags -DBC_ENABLE_EXTRA_MATH=$extra_math -DBC_ENABLE_OSSFUZZ=0" + flags="$flags -I$scriptdir/include/ -D_POSIX_C_SOURCE=200809L -D_XOPEN_SOURCE=700" - "$CC" $CPPFLAGS $CFLAGS $flags -c "$scriptdir/src/history.c" -o "./history.o" > /dev/null 2>&1 + "$CC" $CPPFLAGS $CFLAGS $flags -c "$scriptdir/src/history.c" -E > /dev/null err="$?" @@ -1387,6 +1665,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 @@ -1412,12 +1695,12 @@ else # We are also setting the CFLAGS and LDFLAGS here. if [ "$editline" -ne 0 ]; then LDFLAGS="$LDFLAGS -ledit" - CFLAGS="$CFLAGS -DBC_ENABLE_EDITLINE=1 -DBC_ENABLE_READLINE=0" + CPPFLAGS="$CPPFLAGS -DBC_ENABLE_EDITLINE=1 -DBC_ENABLE_READLINE=0" elif [ "$readline" -ne 0 ]; then LDFLAGS="$LDFLAGS -lreadline" - CFLAGS="$CFLAGS -DBC_ENABLE_EDITLINE=0 -DBC_ENABLE_READLINE=1" + CPPFLAGS="$CPPFLAGS -DBC_ENABLE_EDITLINE=0 -DBC_ENABLE_READLINE=1" else - CFLAGS="$CFLAGS -DBC_ENABLE_EDITLINE=0 -DBC_ENABLE_READLINE=0" + CPPFLAGS="$CPPFLAGS -DBC_ENABLE_EDITLINE=0 -DBC_ENABLE_READLINE=0" fi fi @@ -1430,7 +1713,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/scripts/os.c" > /dev/null err="$?" @@ -1441,6 +1724,29 @@ else CPPFLAGS="$CPPFLAGS -D_POSIX_C_SOURCE=200809L -D_XOPEN_SOURCE=700" fi +# Test macOS. This is not in an if statement because regardless of whatever the +# user says, we need to know if we are on macOS. If we are, we have to set +# _DARWIN_C_SOURCE. +printf 'Testing for macOS...\n' + +flags="-DBC_TEST_APPLE -DBC_ENABLE_AFL=0" +"$CC" $CPPFLAGS $CFLAGS $flags "-I$scriptdir/include" -E "$scriptdir/scripts/os.c" > /dev/null + +err="$?" + +if [ "$err" -ne 0 ]; then + printf 'On macOS. Using _DARWIN_C_SOURCE.\n\n' + apple="-D_DARWIN_C_SOURCE" +else + printf 'Not on macOS.\n\n' + apple="" +fi + +# We can't use the linker's strip flag on macOS. +if [ "$debug" -eq 0 ] && [ "$apple" = "" ] && [ "$strip_bin" -ne 0 ]; then + LDFLAGS="-s $LDFLAGS" +fi + # Test OpenBSD. This is not in an if statement because regardless of whatever # the user says, we need to know if we are on OpenBSD to activate _BSD_SOURCE. # No, I cannot `#define _BSD_SOURCE` in a header because OpenBSD's patched GCC @@ -1449,22 +1755,30 @@ fi # we have to set it because we also set _POSIX_C_SOURCE, which OpenBSD headers # detect, and when they detect it, they turn off _BSD_SOURCE unless it is # specifically requested. -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/scripts/os.c" > /dev/null 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="" fi +set -e + if [ "$library" -eq 1 ]; then bc_lib="" fi @@ -1475,10 +1789,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 -DBC_ENABLE_OSSFUZZ=0 -I$scriptdir/include/ \$(HOSTCFLAGS) -o \$(GEN_EXEC) \$(GEN_C)" CLEAN_PREREQS=" clean_gen clean_coverage" if [ -z "${GEN_HOST+set}" ]; then @@ -1491,8 +1807,9 @@ else fi fi +# The fuzzer files are always unneeded because they'll be built separately. manpage_args="" -unneeded="" +unneeded="bc_fuzzer.c dc_fuzzer.c" headers="\$(HEADERS)" # This series of if statements figure out what source files are *not* needed. @@ -1551,7 +1868,7 @@ if [ "$library" -ne 0 ]; then contents=$(replace "$contents" "LIBDIR" "$LIBDIR") contents=$(replace "$contents" "VERSION" "$version") - printf '%s\n' "$contents" > "./bcl.pc" + printf '%s\n' "$contents" > "$scriptdir/bcl.pc" pkg_config_install="\$(SAFE_INSTALL) \$(PC_INSTALL_ARGS) \"\$(BCL_PC)\" \"\$(DESTDIR)\$(PC_PATH)/\$(BCL_PC)\"" pkg_config_uninstall="\$(RM) -f \"\$(DESTDIR)\$(PC_PATH)/\$(BCL_PC)\"" @@ -1563,6 +1880,14 @@ if [ "$library" -ne 0 ]; then fi +elif [ "$ossfuzz" -ne 0 ]; then + + unneeded="$unneeded library.c main.c" + + PC_PATH="" + pkg_config_install="" + pkg_config_uninstall="" + else unneeded="$unneeded library.c" @@ -1573,9 +1898,10 @@ else fi -# library.c is not needed under normal circumstances. +# library.c, bc_fuzzer.c, and dc_fuzzer.c are not needed under normal +# circumstances. if [ "$unneeded" = "" ]; then - unneeded="library.c" + unneeded="library.c bc_fuzzer.c dc_fuzzer.c" fi # This sets the appropriate manpage for a full build. @@ -1583,7 +1909,7 @@ if [ "$manpage_args" = "" ]; then manpage_args="A" fi -if [ "$vg" -ne 0 ]; then +if [ "$vg" -ne 0 ] || [ "$ossfuzz" -ne 0 ]; then memcheck=1 fi @@ -1603,6 +1929,8 @@ dc_tests=$(gen_std_test_targets dc) dc_script_tests=$(gen_script_test_targets dc) dc_err_tests=$(gen_err_test_targets dc) +printf 'unneeded: %s\n' "$unneeded" + # Print out the values; this is for debugging. printf 'Version: %s\n' "$version" @@ -1620,7 +1948,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 +1988,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 +2064,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") @@ -1720,7 +2074,9 @@ contents=$(replace "$contents" "HISTORY" "$hist") contents=$(replace "$contents" "EXTRA_MATH" "$extra_math") contents=$(replace "$contents" "NLS" "$nls") contents=$(replace "$contents" "FUZZ" "$fuzz") +contents=$(replace "$contents" "OSSFUZZ" "$ossfuzz") contents=$(replace "$contents" "MEMCHECK" "$memcheck") +contents=$(replace "$contents" "LIB_FUZZING_ENGINE" "$LIB_FUZZING_ENGINE") contents=$(replace "$contents" "BC_LIB_O" "$bc_lib") contents=$(replace "$contents" "BC_HELP_O" "$bc_help") @@ -1787,15 +2143,16 @@ 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") contents=$(replace "$contents" "GEN_EMU" "$GEN_EMU") contents=$(replace "$contents" "BSD" "$bsd") +contents=$(replace "$contents" "APPLE" "$apple") contents=$(replace "$contents" "BC_DEFAULT_BANNER" "$bc_default_banner") contents=$(replace "$contents" "BC_DEFAULT_SIGINT_RESET" "$bc_default_sigint_reset") @@ -1806,6 +2163,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" @@ -1823,6 +2182,15 @@ if [ "$dc" -ne 0 ]; then gen_err_tests dc $dc_test_exec fi +if [ "$ossfuzz" -ne 0 ]; then + + printf 'bc_fuzzer_c: $(BC_FUZZER)\n\tln -sf $(BC_FUZZER) bc_fuzzer_c\n' >> Makefile + printf 'bc_fuzzer_C: $(BC_FUZZER)\n\tln -sf $(BC_FUZZER) bc_fuzzer_C\n' >> Makefile + printf 'dc_fuzzer_c: $(DC_FUZZER)\n\tln -sf $(DC_FUZZER) dc_fuzzer_c\n' >> Makefile + printf 'dc_fuzzer_C: $(DC_FUZZER)\n\tln -sf $(DC_FUZZER) dc_fuzzer_C\n' >> Makefile + +fi + # Copy the correct manuals to the expected places. mkdir -p manuals cp -f "$scriptdir/manuals/bc/$manpage_args.1.md" manuals/bc.1.md diff --git a/contrib/bc/gen/bc_help.txt b/contrib/bc/gen/bc_help.txt index 7189d5bae723..489b54a185f1 100644 --- a/contrib/bc/gen/bc_help.txt +++ b/contrib/bc/gen/bc_help.txt @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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,7 +37,7 @@ usage: %s [options] [file...] bc is a command-line, arbitrary-precision calculator with a Turing-complete language. For details, use `man %s` or see the online documentation at -https://git.yzena.com/gavin/bc/src/tag/%s/manuals/bc/%s.1.md. +https://git.gavinhoward.com/gavin/bc/src/tag/%s/manuals/bc/%s.1.md. This bc is compatible with both the GNU bc and the POSIX bc spec. See the GNU bc manual (https://www.gnu.org/software/bc/manual/bc.html) and bc spec @@ -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. diff --git a/contrib/bc/gen/dc_help.txt b/contrib/bc/gen/dc_help.txt index 05a9a68fafc1..df4ede1583a2 100644 --- a/contrib/bc/gen/dc_help.txt +++ b/contrib/bc/gen/dc_help.txt @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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,7 +37,7 @@ usage: %s [options] [file...] dc is a reverse-polish notation command-line calculator which supports unlimited precision arithmetic. For details, use `man %s` or see the online documentation -at https://git.yzena.com/gavin/bc/src/tag/%s/manuals/bc/%s.1.md. +at https://git.gavinhoward.com/gavin/bc/src/tag/%s/manuals/bc/%s.1.md. This dc is (mostly) compatible with the OpenBSD dc and the GNU dc. See the OpenBSD man page (http://man.openbsd.org/OpenBSD-current/man1/dc.1) and the GNU @@ -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. diff --git a/contrib/bc/gen/lib.bc b/contrib/bc/gen/lib.bc index c0cd7f7dc8d4..0c9389b8510d 100644 --- a/contrib/bc/gen/lib.bc +++ b/contrib/bc/gen/lib.bc @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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 diff --git a/contrib/bc/gen/lib2.bc b/contrib/bc/gen/lib2.bc index 23cbec104d02..d6d9f70fe063 100644 --- a/contrib/bc/gen/lib2.bc +++ b/contrib/bc/gen/lib2.bc @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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,10 +34,34 @@ */ define p(x,y){ - auto a + auto a,i,s,z + if(y==0)return 1@scale + if(x==0){ + if(y>0)return 0 + return 1/0 + } a=y$ - if(y==a)return (x^a)@scale - return e(y*l(x)) + if(y==a)return(x^a)@scale + z=0 + if(x<1){ + y=-y + a=-a + z=x + x=1/x + } + if(y<0){ + return e(y*l(x)) + } + i=x^a + s=scale + scale+=length(i)+5 + if(z){ + x=1/z + i=x^a + } + i*=e((y-a)*l(x)) + scale=s + return i@scale } define r(x,p){ auto t,n @@ -66,6 +90,14 @@ define f(n){ for(r=1;n>1;--n)r*=n return r } +define max(a,b){ + if(a>b)return a + return b +} +define min(a,b){ + if(a<b)return a + return b +} define perm(n,k){ auto f,g,s if(k>n)return 0 @@ -93,6 +125,18 @@ define comb(n,r){ scale=s return f } +define fib(n){ + auto i,t,p,r + if(!n)return 0 + n=abs(n)$ + t=1 + for (i=1;i<n;++i){ + r=p + p=t + t+=r + } + return t +} define log(x,b){ auto p,s s=scale @@ -106,7 +150,7 @@ define log(x,b){ define l2(x){return log(x,2)} define l10(x){return log(x,A)} define root(x,n){ - auto s,m,r,q,p + auto s,t,m,r,q,p if(n<0)sqrt(n) n=n$ if(n==0)x/n @@ -114,13 +158,17 @@ define root(x,n){ if(n==2)return sqrt(x) s=scale scale=0 - if(x<0&&n%2==0)sqrt(x) - scale=s+2 + if(x<0&&n%2==0){ + scale=s + sqrt(x) + } + scale=s+scale(x)+5 + t=s+5 m=(x<0) x=abs(x) p=n-1 q=A^ceil((length(x$)/n)$,0) - while(r!=q){ + while(r@t!=q@t){ r=q q=(p*r+x/r^p)/n } @@ -226,6 +274,15 @@ define frand(p){ return irand(A^p)>>p } define ifrand(i,p){return irand(abs(i)$)+frand(p)} +define i2rand(a,b){ + auto n,x + a=a$ + b=b$ + if(a==b)return a + n=min(a,b) + x=max(a,b) + return irand(x-n+1)+n +} define srand(x){ if(irand(2))return -x return x @@ -250,8 +307,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 +367,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 @@ -477,7 +531,7 @@ define bxor(a,b){ return bunrev(t) } define bshl(a,b){return abs(a)$*2^abs(b)$} -define bshr(a,b){return (abs(a)$/2^abs(b)$)$} +define bshr(a,b){return(abs(a)$/2^abs(b)$)$} define bnotn(x,n){ auto s,t,m[] s=scale diff --git a/contrib/bc/gen/strgen.c b/contrib/bc/gen/strgen.c index f4d01ca1391e..1394a05c4a76 100644 --- a/contrib/bc/gen/strgen.c +++ b/contrib/bc/gen/strgen.c @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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-2024 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 @@ -159,11 +157,11 @@ bc_read_file(const char* path) assert(path != NULL); -#ifndef NDEBUG +#if BC_DEBUG // Need this to quiet MSan. // NOLINTNEXTLINE memset(&pstat, 0, sizeof(struct stat)); -#endif // NDEBUG +#endif // BC_DEBUG fd = bc_read_open(path, O_RDONLY); @@ -362,7 +360,7 @@ main(int argc, char* argv[]) has_define = (argc > 6 && strcmp("", argv[6]) != 0); define = has_define ? argv[6] : ""; - remove_tabs = (argc > 7); + remove_tabs = (argc > 7 && atoi(argv[7]) != 0); in = bc_read_file(argv[1]); if (in == NULL) return INVALID_INPUT_FILE; diff --git a/contrib/bc/gen/strgen.sh b/contrib/bc/gen/strgen.sh index ca67fda3ae71..8542bd40ee83 100755 --- a/contrib/bc/gen/strgen.sh +++ b/contrib/bc/gen/strgen.sh @@ -2,7 +2,7 @@ # # SPDX-License-Identifier: BSD-2-Clause # -# Copyright (c) 2018-2021 Gavin D. Howard and contributors. +# Copyright (c) 2018-2024 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,23 +36,37 @@ script="$0" scriptdir=$(dirname "$script") . "$scriptdir/../scripts/functions.sh" +# Just print the usage and exit with an error. This can receive a message to +# print. +# @param 1 A message to print. +usage() { + if [ $# -eq 1 ]; then + printf '%s\n\n' "$1" + fi + printf 'usage: %s input output exclude name [label [define [remove_tabs]]]\n' "$progname" + exit 1 +} + # See strgen.c comment on main() for what these mean. Note, however, that this # script generates a string literal, not a char array. To understand the # consequences of that, see manuals/development.md#strgenc. if [ $# -lt 3 ]; then - echo "usage: $progname input output exclude name [label [define [remove_tabs]]]" - exit 1 + usage "Not enough arguments" fi input="$1" +check_file_arg "$input" output="$2" exclude="$3" name="$4" label="$5" define="$6" remove_tabs="$7" +if [ "$remove_tabs" != "" ]; then + check_bool_arg "$remove_tabs" +fi -tmpinput=$(mktemp -t "${input##*/}") +tmpinput=$(mktemp -t "${input##*/}_XXXXXX") if [ "$exclude" -ne 0 ]; then filter_text "$input" "$tmpinput" "E" @@ -82,7 +96,7 @@ if [ -n "$remove_tabs" ]; then fi cat<<EOF -// Copyright (c) 2018-2021 Gavin D. Howard and contributors. +// Copyright (c) 2018-2024 Gavin D. Howard and contributors. // Licensed under the 2-clause BSD license. // *** AUTOMATICALLY GENERATED FROM ${input}. DO NOT MODIFY. *** diff --git a/contrib/bc/include/args.h b/contrib/bc/include/args.h index cf6bcbef621c..8f8f00be4630 100644 --- a/contrib/bc/include/args.h +++ b/contrib/bc/include/args.h @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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, const 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[]; diff --git a/contrib/bc/include/bc.h b/contrib/bc/include/bc.h index 06b2131c967b..2213278be1da 100644 --- a/contrib/bc/include/bc.h +++ b/contrib/bc/include/bc.h @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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: @@ -48,9 +48,10 @@ /** * The main function for bc. It just sets variables and passes its arguments * through to @a bc_vm_boot(). + * @return A status. */ -void -bc_main(int argc, char* argv[]); +BcStatus +bc_main(int argc, const char* argv[]); // These are references to the help text, the library text, and the "filename" // for the library. @@ -88,22 +89,20 @@ typedef struct BcLexKeyword #define BC_LEX_KW_LEN(kw) ((size_t) ((kw)->data & ~(BC_LEX_CHAR_MSB(1)))) /// A macro to easily build a keyword entry. See bc_lex_kws in src/data.c. -#define BC_LEX_KW_ENTRY(a, b, c) \ - { \ - .data = ((b) & ~(BC_LEX_CHAR_MSB(1))) | BC_LEX_CHAR_MSB(c), .name = a \ - } +#define BC_LEX_KW_ENTRY(a, b, c) \ + { .data = ((b) & ~(BC_LEX_CHAR_MSB(1))) | BC_LEX_CHAR_MSB(c), .name = a } #if 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 (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 @@ -234,7 +233,7 @@ bc_lex_token(BcLex* l); * @param t The token to return operator data for. * @return The operator data for @a t. */ -#define BC_PARSE_OP_DATA(t) bc_parse_ops[((t) -BC_LEX_OP_INC)] +#define BC_PARSE_OP_DATA(t) bc_parse_ops[((t) - BC_LEX_OP_INC)] /** * Returns non-zero if operator @a op is left associative, zero otherwise. @@ -276,7 +275,7 @@ bc_lex_token(BcLex* l); * @return True if i is an expression token, false otherwise. */ #define BC_PARSE_EXPR(i) \ - (bc_parse_exprs[(((i) & (uchar) ~(0x07)) >> 3)] & (1 << (7 - ((i) &0x07)))) + (bc_parse_exprs[(((i) & (uchar) ~(0x07)) >> 3)] & (1 << (7 - ((i) & 0x07)))) /** * Returns the operator (by lex token) that is at the top of the operator @@ -341,7 +340,7 @@ bc_lex_token(BcLex* l); * @param t The token to turn into an instruction. * @return The token as an instruction. */ -#define BC_PARSE_TOKEN_INST(t) ((uchar) ((t) -BC_LEX_NEG + BC_INST_NEG)) +#define BC_PARSE_TOKEN_INST(t) ((uchar) ((t) - BC_LEX_NEG + BC_INST_NEG)) /** * Returns true if the token is a bc keyword. @@ -372,10 +371,8 @@ typedef struct BcParseNext /// A macro to generate a BcParseNext literal from BcParseNext data. See /// src/data.c for examples. -#define BC_PARSE_NEXT(a, ...) \ - { \ - .len = (uchar) (a), BC_PARSE_NEXT_TOKENS(__VA_ARGS__) \ - } +#define BC_PARSE_NEXT(a, ...) \ + { .len = (uchar) (a), BC_PARSE_NEXT_TOKENS(__VA_ARGS__) } /// A status returned by @a bc_parse_expr_err(). It can either return success or /// an error indicating an empty expression. diff --git a/contrib/bc/include/bcl.h b/contrib/bc/include/bcl.h index 54be3239d241..8e762b694f4d 100644 --- a/contrib/bc/include/bcl.h +++ b/contrib/bc/include/bcl.h @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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,17 @@ #ifndef BC_BCL_H #define BC_BCL_H +#include <stdbool.h> +#include <stdlib.h> +#include <limits.h> +#include <stdint.h> + +#ifndef NDEBUG +#define BC_DEBUG (1) +#else // NDEBUG +#define BC_DEBUG (0) +#endif // NDEBUG + #ifdef _WIN32 #include <Windows.h> #include <BaseTsd.h> @@ -43,44 +54,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 +136,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 +160,12 @@ bcl_leadingZeroes(void); void bcl_setLeadingZeroes(bool leadingZeroes); +bool +bcl_digitClamp(void); + +void +bcl_setDigitClamp(bool digitClamp); + void bcl_gc(void); @@ -257,6 +238,9 @@ bcl_dup(BclNumber s); BclError bcl_bigdig(BclNumber n, BclBigDig* result); +BclError +bcl_bigdig_keep(BclNumber n, BclBigDig* result); + BclNumber bcl_bigdig2num(BclBigDig val); @@ -264,35 +248,68 @@ BclNumber bcl_add(BclNumber a, BclNumber b); BclNumber +bcl_add_keep(BclNumber a, BclNumber b); + +BclNumber bcl_sub(BclNumber a, BclNumber b); BclNumber +bcl_sub_keep(BclNumber a, BclNumber b); + +BclNumber bcl_mul(BclNumber a, BclNumber b); BclNumber +bcl_mul_keep(BclNumber a, BclNumber b); + +BclNumber bcl_div(BclNumber a, BclNumber b); BclNumber +bcl_div_keep(BclNumber a, BclNumber b); + +BclNumber bcl_mod(BclNumber a, BclNumber b); BclNumber +bcl_mod_keep(BclNumber a, BclNumber b); + +BclNumber bcl_pow(BclNumber a, BclNumber b); BclNumber +bcl_pow_keep(BclNumber a, BclNumber b); + +BclNumber bcl_lshift(BclNumber a, BclNumber b); BclNumber +bcl_lshift_keep(BclNumber a, BclNumber b); + +BclNumber bcl_rshift(BclNumber a, BclNumber b); BclNumber +bcl_rshift_keep(BclNumber a, BclNumber b); + +BclNumber bcl_sqrt(BclNumber a); +BclNumber +bcl_sqrt_keep(BclNumber a); + BclError bcl_divmod(BclNumber a, BclNumber b, BclNumber* c, BclNumber* d); +BclError +bcl_divmod_keep(BclNumber a, BclNumber b, BclNumber* c, BclNumber* d); + BclNumber bcl_modexp(BclNumber a, BclNumber b, BclNumber c); +BclNumber +bcl_modexp_keep(BclNumber a, BclNumber b, BclNumber c); + ssize_t bcl_cmp(BclNumber a, BclNumber b); @@ -308,19 +325,31 @@ bcl_parse(const char* restrict val); char* bcl_string(BclNumber n); +char* +bcl_string_keep(BclNumber n); + BclNumber bcl_irand(BclNumber a); BclNumber +bcl_irand_keep(BclNumber a); + +BclNumber bcl_frand(size_t places); BclNumber bcl_ifrand(BclNumber a, size_t places); +BclNumber +bcl_ifrand_keep(BclNumber a, size_t places); + BclError bcl_rand_seedWithNum(BclNumber n); BclError +bcl_rand_seedWithNum_keep(BclNumber n); + +BclError bcl_rand_seed(unsigned char seed[BCL_SEED_SIZE]); void diff --git a/contrib/bc/include/dc.h b/contrib/bc/include/dc.h index 42cd842b57ce..63f5ccbd10e3 100644 --- a/contrib/bc/include/dc.h +++ b/contrib/bc/include/dc.h @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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: @@ -45,9 +45,10 @@ /** * The main function for dc. It just sets variables and passes its arguments * through to @a bc_vm_boot(). + * @return A status. */ -void -dc_main(int argc, char* argv[]); +BcStatus +dc_main(int argc, const char* argv[]); // A reference to the dc help text. extern const char dc_help[]; diff --git a/contrib/bc/include/file.h b/contrib/bc/include/file.h index 30a0d9011c00..86f368db11c6 100644 --- a/contrib/bc/include/file.h +++ b/contrib/bc/include/file.h @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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,6 +54,9 @@ typedef struct BcFile // with the existing code as possible. FILE* f; + // True if errors should be fatal, false otherwise. + bool errors_fatal; + } BcFile; #else // BC_ENABLE_LINE_LIB @@ -64,6 +67,9 @@ typedef struct BcFile // The actual file descriptor. int fd; + // True if errors should be fatal, false otherwise. + bool errors_fatal; + // The buffer for the file. char* buf; @@ -98,16 +104,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 @@ -115,23 +129,25 @@ typedef enum BcFlushType /** * Initialize a file. - * @param f The file to initialize. - * @param file The stdio file. + * @param f The file to initialize. + * @param file The stdio file. + * @param errors_fatal True if errors should be fatal, false otherwise. */ void -bc_file_init(BcFile* f, FILE* file); +bc_file_init(BcFile* f, FILE* file, bool errors_fatal); #else // BC_ENABLE_LINE_LIB /** * Initialize a file. - * @param f The file to initialize. - * @param fd The file descriptor. - * @param buf The buffer for the file. - * @param cap The capacity of the buffer. + * @param f The file to initialize. + * @param fd The file descriptor. + * @param buf The buffer for the file. + * @param cap The capacity of the buffer. + * @param errors_fatal True if errors should be fatal, false otherwise. */ void -bc_file_init(BcFile* f, int fd, char* buf, size_t cap); +bc_file_init(BcFile* f, int fd, char* buf, size_t cap, bool errors_fatal); #endif // BC_ENABLE_LINE_LIB diff --git a/contrib/bc/include/history.h b/contrib/bc/include/history.h index 1e9962ded1eb..13f6dc6e985c 100644 --- a/contrib/bc/include/history.h +++ b/contrib/bc/include/history.h @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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; @@ -140,6 +120,30 @@ typedef struct BcHistory extern const char bc_history_editrc[]; extern const size_t bc_history_editrc_len; +#ifdef __APPLE__ + +/** + * Returns true if the line is a valid line, false otherwise. + * @param line The line. + * @param len The length of the line. + * @return True if the line is valid, false otherwise. + */ +#define BC_HISTORY_INVALID_LINE(line, len) \ + ((line) == NULL && ((len) == -1 || errno == EINTR)) + +#else // __APPLE__ + +/** + * Returns true if the line is a valid line, false otherwise. + * @param line The line. + * @param len The length of the line. + * @return True if the line is valid, false otherwise. + */ +#define BC_HISTORY_INVALID_LINE(line, len) \ + ((line) == NULL && (len) == -1 && errno == EINTR) + +#endif // __APPLE__ + #else // BC_ENABLE_EDITLINE #if BC_ENABLE_READLINE @@ -193,10 +197,6 @@ typedef struct BcHistory #include <vector.h> #include <read.h> -#if BC_DEBUG_CODE -#include <file.h> -#endif // BC_DEBUG_CODE - /// Default columns. #define BC_HIST_DEF_COLS (80) diff --git a/contrib/bc/include/lang.h b/contrib/bc/include/lang.h index 6b8ebabf6a95..6c8245139719 100644 --- a/contrib/bc/include/lang.h +++ b/contrib/bc/include/lang.h @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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. @@ -275,6 +277,9 @@ typedef enum BcInst #if DC_ENABLED + /// dc extended registers command. + BC_INST_EXTENDED_REGISTERS, + /// dc's return; it pops an executing string off of the stack. BC_INST_POP_EXEC, @@ -350,6 +355,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 +403,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; @@ -573,7 +578,7 @@ bc_func_insert(BcFunc* f, struct BcProgram* p, char* name, BcType type, void bc_func_reset(BcFunc* f); -#ifndef NDEBUG +#if BC_DEBUG /** * Frees a function. This is a destructor. This is only used in debug builds * because all functions are freed at exit. We free them in debug builds to @@ -582,7 +587,7 @@ bc_func_reset(BcFunc* f); */ void bc_func_free(void* func); -#endif // NDEBUG +#endif // BC_DEBUG /** * Initializes an array, which is the array type in bc and dc source code. Since @@ -660,17 +665,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 /** diff --git a/contrib/bc/include/lex.h b/contrib/bc/include/lex.h index 20be6efa9cde..d2be3c7526ef 100644 --- a/contrib/bc/include/lex.h +++ b/contrib/bc/include/lex.h @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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. + */ +#if BC_DEBUG +#define bc_lex_err(l, e) (bc_vm_handleError((e), __FILE__, __LINE__, (l)->line)) +#else // BC_DEBUG #define bc_lex_err(l, e) (bc_vm_handleError((e), (l)->line)) +#endif // BC_DEBUG + +/** + * 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. + */ +#if BC_DEBUG +#define bc_lex_verr(l, e, ...) \ + (bc_vm_handleError((e), __FILE__, __LINE__, (l)->line, __VA_ARGS__)) +#else // BC_DEBUG #define bc_lex_verr(l, e, ...) (bc_vm_handleError((e), (l)->line, __VA_ARGS__)) +#endif // BC_DEBUG // 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. @@ -378,6 +409,9 @@ typedef enum BcLexType #if DC_ENABLED + /// dc extended registers keyword. + BC_LEX_EXTENDED_REGISTERS, + /// A special token for dc to calculate equal without a register. BC_LEX_EQ_NO_REG, @@ -418,8 +452,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 +523,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; @@ -506,7 +536,7 @@ void bc_lex_init(BcLex* l); /** - * Frees a lexer. This is not guarded by #ifndef NDEBUG because a separate + * Frees a lexer. This is not guarded by #if BC_DEBUG because a separate * parser is created at runtime to parse read() expressions and dc strings, and * that parser needs a lexer. * @param l The lexer to free. @@ -524,14 +554,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 diff --git a/contrib/bc/include/library.h b/contrib/bc/include/library.h index 63d24ee5f7a9..9942705a5f36 100644 --- a/contrib/bc/include/library.h +++ b/contrib/bc/include/library.h @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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,190 @@ #ifndef LIBBC_PRIVATE_H #define LIBBC_PRIVATE_H +#ifndef _WIN32 + +#include <pthread.h> + +#endif // _WIN32 + #include <bcl.h> #include <num.h> +#include <vm.h> + +#if BC_ENABLE_MEMCHECK /** - * 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 typedef for Valgrind builds. This is to add a generation index for error + * checking. */ -#define BC_FUNC_HEADER_LOCK(l) \ - do \ - { \ - BC_SIG_LOCK; \ - BC_SETJMP_LOCKED(l); \ - vm.err = BCL_ERROR_NONE; \ - vm.running = 1; \ - } \ - while (0) +typedef struct BclNum +{ + /// The number. + BcNum n; + + /// The generation index. + size_t gen_idx; + +} BclNum; /** - * 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. + * Clears the generation byte in a BclNumber and returns the value. + * @param n The BclNumber. + * @return The value of the index. */ -#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; \ - } \ - while (0) +#define BCL_NO_GEN(n) \ + ((n).i & ~(((size_t) UCHAR_MAX) << ((sizeof(size_t) - 1) * CHAR_BIT))) /** - * A header that sets a jump and sets running. - * @param l The label to jump to on error. + * Gets the generation index in a BclNumber. + * @param n The BclNumber. + * @return The generation index. */ -#define BC_FUNC_HEADER(l) \ - do \ - { \ - BC_SETJMP(l); \ - vm.err = BCL_ERROR_NONE; \ - vm.running = 1; \ - } \ +#define BCL_GET_GEN(n) ((n).i >> ((sizeof(size_t) - 1) * CHAR_BIT)) + +/** + * Turns a BclNumber into a BcNum. + * @param c The context. + * @param n The BclNumber. + */ +#define BCL_NUM(c, n) ((BclNum*) bc_vec_item(&(c)->nums, BCL_NO_GEN(n))) + +/** + * Clears the generation index top byte in the BclNumber. + * @param n The BclNumber. + */ +#define BCL_CLEAR_GEN(n) \ + do \ + { \ + (n).i &= ~(((size_t) UCHAR_MAX) << ((sizeof(size_t) - 1) * CHAR_BIT)); \ + } \ + while (0) + +#define BCL_CHECK_NUM_GEN(c, bn) \ + do \ + { \ + size_t gen_ = BCL_GET_GEN(bn); \ + BclNum* ptr_ = BCL_NUM(c, bn); \ + if (BCL_NUM_ARRAY(ptr_) == NULL) \ + { \ + bcl_nonexistentNum(); \ + } \ + if (gen_ != ptr_->gen_idx) \ + { \ + bcl_invalidGeneration(); \ + } \ + } \ while (0) +#define BCL_CHECK_NUM_VALID(c, bn) \ + do \ + { \ + size_t idx_ = BCL_NO_GEN(bn); \ + if ((c)->nums.len <= idx_) \ + { \ + bcl_numIdxOutOfRange(); \ + } \ + BCL_CHECK_NUM_GEN(c, bn); \ + } \ + while (0) + +/** + * Returns the limb array of the number. + * @param bn The number. + * @return The limb array. + */ +#define BCL_NUM_ARRAY(bn) ((bn)->n.num) + +/** + * Returns the limb array of the number for a non-pointer. + * @param bn The number. + * @return The limb array. + */ +#define BCL_NUM_ARRAY_NP(bn) ((bn).n.num) + /** - * A header that assumes that signals are already locked. It sets a jump and - * running. - * @param l The label to jump to on error. + * Returns the BcNum pointer. + * @param bn The number. + * @return The BcNum pointer. */ -#define BC_FUNC_HEADER_INIT(l) \ - do \ - { \ - BC_SETJMP_LOCKED(l); \ - vm.err = BCL_ERROR_NONE; \ - vm.running = 1; \ - } \ +#define BCL_NUM_NUM(bn) (&(bn)->n) + +/** + * Returns the BcNum pointer for a non-pointer. + * @param bn The number. + * @return The BcNum pointer. + */ +#define BCL_NUM_NUM_NP(bn) (&(bn).n) + +// These functions only abort. They exist to give developers some idea of what +// went wrong when bugs are found, if they look at the Valgrind stack trace. + +BC_NORETURN void +bcl_invalidGeneration(void); + +BC_NORETURN void +bcl_nonexistentNum(void); + +BC_NORETURN void +bcl_numIdxOutOfRange(void); + +#else // BC_ENABLE_MEMCHECK + +/** + * A typedef for non-Valgrind builds. + */ +typedef BcNum BclNum; + +#define BCL_NO_GEN(n) ((n).i) +#define BCL_NUM(c, n) ((BclNum*) bc_vec_item(&(c)->nums, (n).i)) +#define BCL_CLEAR_GEN(n) ((void) (n)) + +#define BCL_CHECK_NUM_GEN(c, bn) +#define BCL_CHECK_NUM_VALID(c, n) + +#define BCL_NUM_ARRAY(bn) ((bn)->num) +#define BCL_NUM_ARRAY_NP(bn) ((bn).num) + +#define BCL_NUM_NUM(bn) (bn) +#define BCL_NUM_NUM_NP(bn) (&(bn)) + +#endif // BC_ENABLE_MEMCHECK + +/** + * A header that sets a jump. + * @param vm The thread data. + * @param l The label to jump to on error. + */ +#define BC_FUNC_HEADER(vm, l) \ + do \ + { \ + BC_SETJMP(vm, l); \ + vm->err = BCL_ERROR_NONE; \ + } \ 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. + * A footer for functions that do not return an error code. */ -#define BC_FUNC_FOOTER_NO_ERR \ - do \ - { \ - 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 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. + * 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_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) /** @@ -131,19 +227,19 @@ * idx. * @param c The context. * @param e The error. - * @param n The number. + * @param bn The number. * @param idx The idx to set as the return value. */ -#define BC_MAYBE_SETUP(c, e, n, idx) \ - do \ - { \ - if (BC_ERR((e) != BCL_ERROR_NONE)) \ - { \ - if ((n).num != NULL) bc_num_free(&(n)); \ - idx.i = 0 - (size_t) (e); \ - } \ - else idx = bcl_num_insert(c, &(n)); \ - } \ +#define BC_MAYBE_SETUP(c, e, bn, idx) \ + do \ + { \ + if (BC_ERR((e) != BCL_ERROR_NONE)) \ + { \ + if (BCL_NUM_ARRAY_NP(bn) != NULL) bc_num_free(BCL_NUM_NUM_NP(bn)); \ + idx.i = 0 - (size_t) (e); \ + } \ + else idx = bcl_num_insert(c, &(bn)); \ + } \ while (0) /** @@ -151,27 +247,27 @@ * is bad. * @param c The context. */ -#define BC_CHECK_CTXT(c) \ - do \ - { \ - c = bcl_context(); \ - if (BC_ERR(c == NULL)) \ - { \ - BclNumber n_num; \ - n_num.i = 0 - (size_t) BCL_ERROR_INVALID_CONTEXT; \ - return n_num; \ - } \ - } \ +#define BC_CHECK_CTXT(vm, c) \ + do \ + { \ + c = bcl_contextHelper(vm); \ + if (BC_ERR(c == NULL)) \ + { \ + BclNumber n_num_; \ + n_num_.i = 0 - (size_t) BCL_ERROR_INVALID_CONTEXT; \ + return n_num_; \ + } \ + } \ while (0) /** * 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 +279,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) /** @@ -200,16 +296,18 @@ #define BC_CHECK_NUM(c, n) \ do \ { \ - if (BC_ERR((n).i >= (c)->nums.len)) \ + size_t no_gen_ = BCL_NO_GEN(n); \ + if (BC_ERR(no_gen_ >= (c)->nums.len)) \ { \ if ((n).i > 0 - (size_t) BCL_ERROR_NELEMS) return (n); \ else \ { \ - BclNumber n_num; \ - n_num.i = 0 - (size_t) BCL_ERROR_INVALID_NUM; \ - return n_num; \ + BclNumber n_num_; \ + n_num_.i = 0 - (size_t) BCL_ERROR_INVALID_NUM; \ + return n_num_; \ } \ } \ + BCL_CHECK_NUM_GEN(c, n); \ } \ while (0) @@ -224,7 +322,8 @@ #define BC_CHECK_NUM_ERR(c, n) \ do \ { \ - if (BC_ERR((n).i >= (c)->nums.len)) \ + size_t no_gen_ = BCL_NO_GEN(n); \ + if (BC_ERR(no_gen_ >= (c)->nums.len)) \ { \ if ((n).i > 0 - (size_t) BCL_ERROR_NELEMS) \ { \ @@ -232,17 +331,25 @@ } \ else return BCL_ERROR_INVALID_NUM; \ } \ + BCL_CHECK_NUM_GEN(c, n); \ } \ while (0) //clang-format on /** - * Turns a BclNumber into a BcNum. + * Grows the context's nums array if necessary. * @param c The context. - * @param n The BclNumber. */ -#define BC_NUM(c, n) ((BcNum*) bc_vec_item(&(c)->nums, (n).i)) +#define BCL_GROW_NUMS(c) \ + do \ + { \ + if ((c)->free_nums.len == 0) \ + { \ + bc_vec_grow(&((c)->nums), 1); \ + } \ + } \ + while (0) /** * Frees a BcNum for bcl. This is a destructor. @@ -272,4 +379,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 diff --git a/contrib/bc/include/num.h b/contrib/bc/include/num.h index 4a4dc5bc54fa..6cead6eb3823 100644 --- a/contrib/bc/include/num.h +++ b/contrib/bc/include/num.h @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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) @@ -75,6 +71,10 @@ typedef BclBigDig BcBigDig; /// An alias for portability. #define BC_NUM_BIGDIG_C UINT64_C +/// The max number + 1 that two limbs can hold. This is used for generating +/// numbers because the PRNG can generate a number that will fill two limbs. +#define BC_BASE_RAND_POW (BC_NUM_BIGDIG_C(1000000000000000000)) + /// The actual limb type. typedef int_least32_t BcDig; @@ -92,6 +92,10 @@ typedef int_least32_t BcDig; /// An alias for portability. #define BC_NUM_BIGDIG_C UINT32_C +/// The max number + 1 that two limbs can hold. This is used for generating +/// numbers because the PRNG can generate a number that will fill two limbs. +#define BC_BASE_RAND_POW (UINT64_C(100000000)) + /// The actual limb type. typedef int_least16_t BcDig; @@ -207,9 +211,9 @@ struct BcRNG; #define BC_NUM_KARATSUBA_ALLOCS (6) /** - * Rounds @a s (scale) up to the next power of BC_BASE_DIGS. This also check for - * overflow and gives a fatal error if that happens because we just can't go - * over the limits we have imposed. + * Rounds @a s (scale) up to the next power of BC_BASE_DIGS. This will also + * check for overflow and gives a fatal error if that happens because we just + * can't go over the limits we have imposed. * @param s The scale to round up. * @return @a s rounded up to the next power of BC_BASE_DIGS. */ @@ -829,6 +833,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 /** diff --git a/contrib/bc/include/opt.h b/contrib/bc/include/opt.h index 3c465c80fbf6..41058cb4e29c 100644 --- a/contrib/bc/include/opt.h +++ b/contrib/bc/include/opt.h @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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,7 +47,7 @@ typedef struct BcOpt { /// The array of arguments. - char** argv; + const char** argv; /// The index of the current argument. size_t optind; @@ -59,7 +59,7 @@ typedef struct BcOpt int subopt; /// The option argument. - char* optarg; + const char* optarg; } BcOpt; @@ -103,7 +103,7 @@ typedef struct BcOptLong * @param argv The array of arguments. */ void -bc_opt_init(BcOpt* o, char** argv); +bc_opt_init(BcOpt* o, const char** argv); /** * Parse an option. This returns a value the same way getopt() and getopt_long() diff --git a/contrib/bc/include/ossfuzz.h b/contrib/bc/include/ossfuzz.h new file mode 100644 index 000000000000..5c12a3c9c9fb --- /dev/null +++ b/contrib/bc/include/ossfuzz.h @@ -0,0 +1,79 @@ +/* + * ***************************************************************************** + * + * SPDX-License-Identifier: BSD-2-Clause + * + * Copyright (c) 2018-2024 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: + * + * * Redistributions of source code must retain the above copyright notice, this + * list of conditions and the following disclaimer. + * + * * Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + * + * ***************************************************************************** + * + * Declarations for the OSS-Fuzz build of bc and dc. + * + */ + +#include <stdint.h> +#include <stdlib.h> + +#ifndef BC_OSSFUZZ_H +#define BC_OSSFUZZ_H + +/// The number of args in fuzzer arguments, including the NULL terminator. +extern const size_t bc_fuzzer_args_len; + +/// The standard arguments for the bc fuzzer with the -c argument. +extern const char* bc_fuzzer_args_c[]; + +/// The standard arguments for the bc fuzzer with the -C argument. +extern const char* bc_fuzzer_args_C[]; + +/// The standard arguments for the dc fuzzer with the -c argument. +extern const char* dc_fuzzer_args_c[]; + +/// The standard arguments for the dc fuzzer with the -C argument. +extern const char* dc_fuzzer_args_C[]; + +/// The data pointer. +extern uint8_t* bc_fuzzer_data; + +/** + * The function that the fuzzer runs. + * @param Data The data. + * @param Size The number of bytes in @a Data. + * @return 0 on success, -1 on error. + * @pre @a Data must not be equal to NULL if @a Size > 0. + */ +int +LLVMFuzzerTestOneInput(const uint8_t* Data, size_t Size); + +/** + * The initialization function for the fuzzer. + * @param argc A pointer to the argument count. + * @param argv A pointer to the argument list. + * @return 0 on success, -1 on error. + */ +int +LLVMFuzzerInitialize(int* argc, char*** argv); + +#endif // BC_OSSFUZZ_H diff --git a/contrib/bc/include/parse.h b/contrib/bc/include/parse.h index e692462395ca..7f0f8768b0db 100644 --- a/contrib/bc/include/parse.h +++ b/contrib/bc/include/parse.h @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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. */ +#if BC_DEBUG +#define bc_parse_err(p, e) \ + (bc_vm_handleError((e), __FILE__, __LINE__, (p)->l.line)) +#else // BC_DEBUG #define bc_parse_err(p, e) (bc_vm_handleError((e), (p)->l.line)) +#endif // BC_DEBUG /** - * 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. */ +#if BC_DEBUG +#define bc_parse_verr(p, e, ...) \ + (bc_vm_handleError((e), __FILE__, __LINE__, (p)->l.line, __VA_ARGS__)) +#else // BC_DEBUG #define bc_parse_verr(p, e, ...) \ (bc_vm_handleError((e), (p)->l.line, __VA_ARGS__)) +#endif // BC_DEBUG // Forward declarations. struct BcParse; @@ -219,7 +215,7 @@ void bc_parse_init(BcParse* p, struct BcProgram* prog, size_t func); /** - * Frees a parser. This is not guarded by #ifndef NDEBUG because a separate + * Frees a parser. This is not guarded by #if BC_DEBUG because a separate * parser is created at runtime to parse read() expressions and dc strings. * @param p The parser to free. */ @@ -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 diff --git a/contrib/bc/include/program.h b/contrib/bc/include/program.h index 1a87aa612c90..e16e5c079d7d 100644 --- a/contrib/bc/include/program.h +++ b/contrib/bc/include/program.h @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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; + + /// The map of constants to go with consts. + BcVec const_map; - /// A pointer to the current function's strings. - BcVec* strs; + /// 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,25 +220,36 @@ 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 // items. -#ifdef NDEBUG +#ifdef BC_DEBUG #define BC_PROG_NO_STACK_CHECK -#endif // NDEBUG +#endif // BC_DEBUG #endif // DC_ENABLED @@ -271,7 +298,7 @@ typedef void (*BcProgramUnary)(BcResult* r, BcNum* n); void bc_program_init(BcProgram* p); -#ifndef NDEBUG +#if BC_DEBUG /** * Frees a BcProgram. This is only used in debug builds because a BcProgram is @@ -282,7 +309,14 @@ bc_program_init(BcProgram* p); void bc_program_free(BcProgram* p); -#endif // NDEBUG +#endif // BC_DEBUG + +/** + * 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, \ @@ -572,6 +608,7 @@ extern const char bc_program_esc_seqs[]; &&lbl_BC_INST_MODEXP, \ &&lbl_BC_INST_DIVMOD, \ &&lbl_BC_INST_PRINT_STREAM, \ + &&lbl_BC_INST_EXTENDED_REGISTERS, \ &&lbl_BC_INST_POP_EXEC, \ &&lbl_BC_INST_EXECUTE, \ &&lbl_BC_INST_EXEC_COND, \ @@ -639,6 +676,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, \ @@ -663,6 +702,7 @@ extern const char bc_program_esc_seqs[]; &&lbl_BC_INST_MODEXP, \ &&lbl_BC_INST_DIVMOD, \ &&lbl_BC_INST_PRINT_STREAM, \ + &&lbl_BC_INST_EXTENDED_REGISTERS, \ &&lbl_BC_INST_POP_EXEC, \ &&lbl_BC_INST_EXECUTE, \ &&lbl_BC_INST_EXEC_COND, \ @@ -745,6 +785,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 +867,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, \ @@ -860,142 +904,82 @@ extern const char bc_program_esc_seqs[]; #if BC_ENABLE_EXTRA_MATH -#define BC_PROG_LBLS \ - static const void* const bc_program_inst_lbls[] = { \ - &&lbl_BC_INST_NEG, \ - &&lbl_BC_INST_BOOL_NOT, \ - &&lbl_BC_INST_TRUNC, \ - &&lbl_BC_INST_POWER, \ - &&lbl_BC_INST_MULTIPLY, \ - &&lbl_BC_INST_DIVIDE, \ - &&lbl_BC_INST_MODULUS, \ - &&lbl_BC_INST_PLUS, \ - &&lbl_BC_INST_MINUS, \ - &&lbl_BC_INST_PLACES, \ - &&lbl_BC_INST_LSHIFT, \ - &&lbl_BC_INST_RSHIFT, \ - &&lbl_BC_INST_REL_EQ, \ - &&lbl_BC_INST_REL_LE, \ - &&lbl_BC_INST_REL_GE, \ - &&lbl_BC_INST_REL_NE, \ - &&lbl_BC_INST_REL_LT, \ - &&lbl_BC_INST_REL_GT, \ - &&lbl_BC_INST_BOOL_OR, \ - &&lbl_BC_INST_BOOL_AND, \ - &&lbl_BC_INST_ASSIGN_NO_VAL, \ - &&lbl_BC_INST_NUM, \ - &&lbl_BC_INST_VAR, \ - &&lbl_BC_INST_ARRAY_ELEM, \ - &&lbl_BC_INST_ARRAY, \ - &&lbl_BC_INST_ZERO, \ - &&lbl_BC_INST_ONE, \ - &&lbl_BC_INST_IBASE, \ - &&lbl_BC_INST_OBASE, \ - &&lbl_BC_INST_SCALE, \ - &&lbl_BC_INST_SEED, \ - &&lbl_BC_INST_LENGTH, \ - &&lbl_BC_INST_SCALE_FUNC, \ - &&lbl_BC_INST_SQRT, \ - &&lbl_BC_INST_ABS, \ - &&lbl_BC_INST_IRAND, \ - &&lbl_BC_INST_ASCIIFY, \ - &&lbl_BC_INST_READ, \ - &&lbl_BC_INST_RAND, \ - &&lbl_BC_INST_MAXIBASE, \ - &&lbl_BC_INST_MAXOBASE, \ - &&lbl_BC_INST_MAXSCALE, \ - &&lbl_BC_INST_MAXRAND, \ - &&lbl_BC_INST_LINE_LENGTH, \ - &&lbl_BC_INST_LEADING_ZERO, \ - &&lbl_BC_INST_PRINT, \ - &&lbl_BC_INST_PRINT_POP, \ - &&lbl_BC_INST_STR, \ - &&lbl_BC_INST_POP, \ - &&lbl_BC_INST_SWAP, \ - &&lbl_BC_INST_MODEXP, \ - &&lbl_BC_INST_DIVMOD, \ - &&lbl_BC_INST_PRINT_STREAM, \ - &&lbl_BC_INST_POP_EXEC, \ - &&lbl_BC_INST_EXECUTE, \ - &&lbl_BC_INST_EXEC_COND, \ - &&lbl_BC_INST_PRINT_STACK, \ - &&lbl_BC_INST_CLEAR_STACK, \ - &&lbl_BC_INST_REG_STACK_LEN, \ - &&lbl_BC_INST_STACK_LEN, \ - &&lbl_BC_INST_DUPLICATE, \ - &&lbl_BC_INST_LOAD, \ - &&lbl_BC_INST_PUSH_VAR, \ - &&lbl_BC_INST_PUSH_TO_VAR, \ - &&lbl_BC_INST_QUIT, \ - &&lbl_BC_INST_NQUIT, \ - &&lbl_BC_INST_EXEC_STACK_LEN, \ - &&lbl_BC_INST_INVALID, \ +#define BC_PROG_LBLS \ + static const void* const bc_program_inst_lbls[] = { \ + &&lbl_BC_INST_NEG, &&lbl_BC_INST_BOOL_NOT, \ + &&lbl_BC_INST_TRUNC, &&lbl_BC_INST_POWER, \ + &&lbl_BC_INST_MULTIPLY, &&lbl_BC_INST_DIVIDE, \ + &&lbl_BC_INST_MODULUS, &&lbl_BC_INST_PLUS, \ + &&lbl_BC_INST_MINUS, &&lbl_BC_INST_PLACES, \ + &&lbl_BC_INST_LSHIFT, &&lbl_BC_INST_RSHIFT, \ + &&lbl_BC_INST_REL_EQ, &&lbl_BC_INST_REL_LE, \ + &&lbl_BC_INST_REL_GE, &&lbl_BC_INST_REL_NE, \ + &&lbl_BC_INST_REL_LT, &&lbl_BC_INST_REL_GT, \ + &&lbl_BC_INST_BOOL_OR, &&lbl_BC_INST_BOOL_AND, \ + &&lbl_BC_INST_ASSIGN_NO_VAL, &&lbl_BC_INST_NUM, \ + &&lbl_BC_INST_VAR, &&lbl_BC_INST_ARRAY_ELEM, \ + &&lbl_BC_INST_ARRAY, &&lbl_BC_INST_ZERO, \ + &&lbl_BC_INST_ONE, &&lbl_BC_INST_IBASE, \ + &&lbl_BC_INST_OBASE, &&lbl_BC_INST_SCALE, \ + &&lbl_BC_INST_SEED, &&lbl_BC_INST_LENGTH, \ + &&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, \ + &&lbl_BC_INST_RAND, &&lbl_BC_INST_MAXIBASE, \ + &&lbl_BC_INST_MAXOBASE, &&lbl_BC_INST_MAXSCALE, \ + &&lbl_BC_INST_MAXRAND, &&lbl_BC_INST_LINE_LENGTH, \ + &&lbl_BC_INST_LEADING_ZERO, &&lbl_BC_INST_PRINT, \ + &&lbl_BC_INST_PRINT_POP, &&lbl_BC_INST_STR, \ + &&lbl_BC_INST_POP, &&lbl_BC_INST_SWAP, \ + &&lbl_BC_INST_MODEXP, &&lbl_BC_INST_DIVMOD, \ + &&lbl_BC_INST_PRINT_STREAM, &&lbl_BC_INST_EXTENDED_REGISTERS, \ + &&lbl_BC_INST_POP_EXEC, &&lbl_BC_INST_EXECUTE, \ + &&lbl_BC_INST_EXEC_COND, &&lbl_BC_INST_PRINT_STACK, \ + &&lbl_BC_INST_CLEAR_STACK, &&lbl_BC_INST_REG_STACK_LEN, \ + &&lbl_BC_INST_STACK_LEN, &&lbl_BC_INST_DUPLICATE, \ + &&lbl_BC_INST_LOAD, &&lbl_BC_INST_PUSH_VAR, \ + &&lbl_BC_INST_PUSH_TO_VAR, &&lbl_BC_INST_QUIT, \ + &&lbl_BC_INST_NQUIT, &&lbl_BC_INST_EXEC_STACK_LEN, \ + &&lbl_BC_INST_INVALID, \ } #else // BC_ENABLE_EXTRA_MATH -#define BC_PROG_LBLS \ - static const void* const bc_program_inst_lbls[] = { \ - &&lbl_BC_INST_NEG, \ - &&lbl_BC_INST_BOOL_NOT, \ - &&lbl_BC_INST_POWER, \ - &&lbl_BC_INST_MULTIPLY, \ - &&lbl_BC_INST_DIVIDE, \ - &&lbl_BC_INST_MODULUS, \ - &&lbl_BC_INST_PLUS, \ - &&lbl_BC_INST_MINUS, \ - &&lbl_BC_INST_REL_EQ, \ - &&lbl_BC_INST_REL_LE, \ - &&lbl_BC_INST_REL_GE, \ - &&lbl_BC_INST_REL_NE, \ - &&lbl_BC_INST_REL_LT, \ - &&lbl_BC_INST_REL_GT, \ - &&lbl_BC_INST_BOOL_OR, \ - &&lbl_BC_INST_BOOL_AND, \ - &&lbl_BC_INST_ASSIGN_NO_VAL, \ - &&lbl_BC_INST_NUM, \ - &&lbl_BC_INST_VAR, \ - &&lbl_BC_INST_ARRAY_ELEM, \ - &&lbl_BC_INST_ARRAY, \ - &&lbl_BC_INST_ZERO, \ - &&lbl_BC_INST_ONE, \ - &&lbl_BC_INST_IBASE, \ - &&lbl_BC_INST_OBASE, \ - &&lbl_BC_INST_SCALE, \ - &&lbl_BC_INST_LENGTH, \ - &&lbl_BC_INST_SCALE_FUNC, \ - &&lbl_BC_INST_SQRT, \ - &&lbl_BC_INST_ABS, \ - &&lbl_BC_INST_ASCIIFY, \ - &&lbl_BC_INST_READ, \ - &&lbl_BC_INST_MAXIBASE, \ - &&lbl_BC_INST_MAXOBASE, \ - &&lbl_BC_INST_MAXSCALE, \ - &&lbl_BC_INST_LINE_LENGTH, \ - &&lbl_BC_INST_LEADING_ZERO, \ - &&lbl_BC_INST_PRINT, \ - &&lbl_BC_INST_PRINT_POP, \ - &&lbl_BC_INST_STR, \ - &&lbl_BC_INST_POP, \ - &&lbl_BC_INST_SWAP, \ - &&lbl_BC_INST_MODEXP, \ - &&lbl_BC_INST_DIVMOD, \ - &&lbl_BC_INST_PRINT_STREAM, \ - &&lbl_BC_INST_POP_EXEC, \ - &&lbl_BC_INST_EXECUTE, \ - &&lbl_BC_INST_EXEC_COND, \ - &&lbl_BC_INST_PRINT_STACK, \ - &&lbl_BC_INST_CLEAR_STACK, \ - &&lbl_BC_INST_REG_STACK_LEN, \ - &&lbl_BC_INST_STACK_LEN, \ - &&lbl_BC_INST_DUPLICATE, \ - &&lbl_BC_INST_LOAD, \ - &&lbl_BC_INST_PUSH_VAR, \ - &&lbl_BC_INST_PUSH_TO_VAR, \ - &&lbl_BC_INST_QUIT, \ - &&lbl_BC_INST_NQUIT, \ - &&lbl_BC_INST_EXEC_STACK_LEN, \ - &&lbl_BC_INST_INVALID, \ +#define BC_PROG_LBLS \ + static const void* const bc_program_inst_lbls[] = { \ + &&lbl_BC_INST_NEG, &&lbl_BC_INST_BOOL_NOT, \ + &&lbl_BC_INST_POWER, &&lbl_BC_INST_MULTIPLY, \ + &&lbl_BC_INST_DIVIDE, &&lbl_BC_INST_MODULUS, \ + &&lbl_BC_INST_PLUS, &&lbl_BC_INST_MINUS, \ + &&lbl_BC_INST_REL_EQ, &&lbl_BC_INST_REL_LE, \ + &&lbl_BC_INST_REL_GE, &&lbl_BC_INST_REL_NE, \ + &&lbl_BC_INST_REL_LT, &&lbl_BC_INST_REL_GT, \ + &&lbl_BC_INST_BOOL_OR, &&lbl_BC_INST_BOOL_AND, \ + &&lbl_BC_INST_ASSIGN_NO_VAL, &&lbl_BC_INST_NUM, \ + &&lbl_BC_INST_VAR, &&lbl_BC_INST_ARRAY_ELEM, \ + &&lbl_BC_INST_ARRAY, &&lbl_BC_INST_ZERO, \ + &&lbl_BC_INST_ONE, &&lbl_BC_INST_IBASE, \ + &&lbl_BC_INST_OBASE, &&lbl_BC_INST_SCALE, \ + &&lbl_BC_INST_LENGTH, &&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, &&lbl_BC_INST_MAXOBASE, \ + &&lbl_BC_INST_MAXSCALE, &&lbl_BC_INST_LINE_LENGTH, \ + &&lbl_BC_INST_LEADING_ZERO, &&lbl_BC_INST_PRINT, \ + &&lbl_BC_INST_PRINT_POP, &&lbl_BC_INST_STR, \ + &&lbl_BC_INST_POP, &&lbl_BC_INST_SWAP, \ + &&lbl_BC_INST_MODEXP, &&lbl_BC_INST_DIVMOD, \ + &&lbl_BC_INST_PRINT_STREAM, &&lbl_BC_INST_EXTENDED_REGISTERS, \ + &&lbl_BC_INST_POP_EXEC, &&lbl_BC_INST_EXECUTE, \ + &&lbl_BC_INST_EXEC_COND, &&lbl_BC_INST_PRINT_STACK, \ + &&lbl_BC_INST_CLEAR_STACK, &&lbl_BC_INST_REG_STACK_LEN, \ + &&lbl_BC_INST_STACK_LEN, &&lbl_BC_INST_DUPLICATE, \ + &&lbl_BC_INST_LOAD, &&lbl_BC_INST_PUSH_VAR, \ + &&lbl_BC_INST_PUSH_TO_VAR, &&lbl_BC_INST_QUIT, \ + &&lbl_BC_INST_NQUIT, &&lbl_BC_INST_EXEC_STACK_LEN, \ + &&lbl_BC_INST_INVALID, \ } #endif // BC_ENABLE_EXTRA_MATH diff --git a/contrib/bc/include/rand.h b/contrib/bc/include/rand.h index 7546891dbd64..aee63b866cf6 100644 --- a/contrib/bc/include/rand.h +++ b/contrib/bc/include/rand.h @@ -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-2024 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 @@ -53,11 +53,11 @@ #if BC_ENABLE_LIBRARY #define BC_RAND_USE_FREE (1) #else // BC_ENABLE_LIBRARY -#ifndef NDEBUG +#if BC_DEBUG #define BC_RAND_USE_FREE (1) -#else // NDEBUG +#else // BC_DEBUG #define BC_RAND_USE_FREE (0) -#endif // NDEBUG +#endif // BC_DEBUG #endif // BC_ENABLE_LIBRARY /** @@ -241,10 +241,7 @@ typedef struct BcRandState * @param l The low 64 bits. * @return The constant built from @a h and @a l. */ -#define BC_RAND_CONSTANT(h, l) \ - { \ - .lo = (l), .hi = (h) \ - } +#define BC_RAND_CONSTANT(h, l) { .lo = (l), .hi = (h) } /** * Truncates a PCG state to the number of bits in a random integer. diff --git a/contrib/bc/include/read.h b/contrib/bc/include/read.h index 0e824d941b50..62e6897635a2 100644 --- a/contrib/bc/include/read.h +++ b/contrib/bc/include/read.h @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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: diff --git a/contrib/bc/include/status.h b/contrib/bc/include/status.h index d038944d40c9..203f09af628b 100644 --- a/contrib/bc/include/status.h +++ b/contrib/bc/include/status.h @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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,21 +36,48 @@ #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 -#ifdef __OpenBSD__ -#error On OpenBSD without _BSD_SOURCE -#endif // __OpenBSD__ -#endif // BC_TEST_OPENBSD +// 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 -// This is used by configure.sh to test for FreeBSD. -#ifdef BC_TEST_FREEBSD -#ifdef __FreeBSD__ -#error On FreeBSD with _POSIX_C_SOURCE -#endif // __FreeBSD__ -#endif // BC_TEST_FREEBSD +#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) @@ -60,10 +87,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 +185,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 +206,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 +230,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 +240,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 +281,7 @@ #endif // BC_HAS_UNREACHABLE -#ifdef __GNUC__ +#if BC_GCC #if __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 5) @@ -203,9 +290,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 +301,7 @@ #endif // __clang_major__ >= 4 -#endif // __GNUC__ +#endif // BC_CLANG #ifdef BC_NO_COMPUTED_GOTO @@ -223,12 +310,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 +366,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 +391,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 +644,26 @@ 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, + +#if !BC_ENABLE_OSSFUZZ + + /// stdin mode. + BC_MODE_STDIN, + +#endif // !BC_ENABLE_OSSFUZZ + +} 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,39 +673,48 @@ 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 +#if BC_DEBUG /// Assert that signals are locked. 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 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 +#else // BC_DEBUG /// Assert that signals are locked. There are non-async-signal-safe functions in /// bc, and they *must* have signals locked. Other functions are expected to @@ -604,14 +728,14 @@ typedef enum BcErr /// (no-op in non-debug mode) that check that signals are unlocked. #define BC_SIG_ASSERT_NOT_LOCKED -#endif // NDEBUG +#endif // BC_DEBUG /// Locks signals. #define BC_SIG_LOCK \ do \ { \ BC_SIG_ASSERT_NOT_LOCKED; \ - vm.sig_lock = 1; \ + vm->sig_lock = 1; \ } \ while (0) @@ -620,8 +744,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 +753,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,47 +778,33 @@ 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) \ - do \ - { \ - vm.sig_lock = (v); \ - if (!(v) && vm.sig) BC_JMP; \ - } \ +#define BC_SIG_TRYUNLOCK(v) \ + do \ + { \ + vm->sig_lock = (v); \ + if (!(v) && vm->sig) BC_JMP; \ + } \ while (0) -/** - * 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 - * signals are not locked and will lock them, set the jump, and unlock them. - * Setting the jump also includes pushing the jmp_buf onto the jmp_buf stack. - * This grows the jmp_bufs vector first to prevent a fatal error from happening - * after the setjmp(). This is done because BC_SETJMP(l) is assumed to be used - * *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; \ - } \ +/// 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) /** @@ -704,59 +814,108 @@ typedef enum BcErr * 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); \ - } \ +#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 \ - 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_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 \ + { \ + 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 + * signals are not locked and will lock them, set the jump, and unlock them. + * Setting the jump also includes pushing the jmp_buf onto the jmp_buf stack. + * This grows the jmp_bufs vector first to prevent a fatal error from happening + * after the setjmp(). This is done because BC_SETJMP(l) is assumed to be used + * *before* the actual initialization calls that need the setjmp(). + * param l The label to jump to on a longjmp(). + */ +#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 +939,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. */ +#if BC_DEBUG +#define bc_error(e, l, ...) \ + (bc_vm_handleError((e), __FILE__, __LINE__, (l), __VA_ARGS__)) +#else // BC_DEBUG #define bc_error(e, l, ...) (bc_vm_handleError((e), (l), __VA_ARGS__)) +#endif // BC_DEBUG /** * Call bc's error handling routine. * @param e The error. */ +#if BC_DEBUG +#define bc_err(e) (bc_vm_handleError((e), __FILE__, __LINE__, 0)) +#else // BC_DEBUG #define bc_err(e) (bc_vm_handleError((e), 0)) +#endif // BC_DEBUG /** * Call bc's error handling routine. * @param e The error. */ +#if BC_DEBUG +#define bc_verr(e, ...) \ + (bc_vm_handleError((e), __FILE__, __LINE__, 0, __VA_ARGS__)) +#else // BC_DEBUG #define bc_verr(e, ...) (bc_vm_handleError((e), 0, __VA_ARGS__)) +#endif // BC_DEBUG #endif // BC_ENABLE_LIBRARY @@ -813,34 +988,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 diff --git a/contrib/bc/include/vector.h b/contrib/bc/include/vector.h index 43158ef4ba63..cad5fc2aa7c3 100644 --- a/contrib/bc/include/vector.h +++ b/contrib/bc/include/vector.h @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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. @@ -88,12 +85,12 @@ typedef enum BcDtorType #if !BC_ENABLE_LIBRARY -#ifndef NDEBUG +#if BC_DEBUG /// BcFunc destructor. BC_DTOR_FUNC, -#endif // NDEBUG +#endif // BC_DEBUG /// BcSlab destructor. BC_DTOR_SLAB, @@ -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. diff --git a/contrib/bc/include/version.h b/contrib/bc/include/version.h index 4400e4f59ccd..a4fb8def5024 100644 --- a/contrib/bc/include/version.h +++ b/contrib/bc/include/version.h @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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 7.0.2 #endif // BC_VERSION_H diff --git a/contrib/bc/include/vm.h b/contrib/bc/include/vm.h index dd4577489467..e81206b63871 100644 --- a/contrib/bc/include/vm.h +++ b/contrib/bc/include/vm.h @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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 @@ -358,7 +493,7 @@ #define BC_VM_SAFE_RESULT(r) ((r)->t >= BC_RESULT_TEMP) /// The invalid locale catalog return value. -#define BC_VM_INVALID_CATALOG ((nl_catd) -1) +#define BC_VM_INVALID_CATALOG ((nl_catd) - 1) /** * Returns true if the *unsigned* multiplication overflows. @@ -425,9 +560,13 @@ typedef struct BcVm /// The vector for creating strings to pass to the client. BcVec out; +#if BC_ENABLE_EXTRA_MATH + /// The PRNG. BcRNG rng; +#endif // BC_ENABLE_EXTRA_MATH + /// The current error. BclError err; @@ -437,18 +576,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 +592,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 +605,6 @@ typedef struct BcVm /// information. volatile sig_atomic_t sig; -#if !BC_ENABLE_LIBRARY - /// The length of sigmsg. uchar siglen; @@ -501,8 +632,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 +643,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 +672,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 +683,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 +756,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 +769,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. @@ -672,9 +791,10 @@ bc_vm_info(const char* const help); * The entrance point for bc/dc together. * @param argc The count of arguments. * @param argv The argument array. + * @return A status. */ -void -bc_vm_boot(int argc, char* argv[]); +BcStatus +bc_vm_boot(int argc, const char* argv[]); /** * Initializes some of the BcVm global. This is separate to make things easier @@ -697,27 +817,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) + +#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 +#endif // !BC_ENABLE_HISTORY || BC_ENABLE_LINE_LIB || BC_ENABLE_LIBRARY /** * Print to stdout with limited formating. @@ -826,6 +959,7 @@ bc_vm_getenvFree(char* val); */ void bc_vm_jmp(const char* f); + #else // BC_DEBUG_CODE /** @@ -863,15 +997,41 @@ 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); + +#if BC_DEBUG + +/** + * 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 // BC_DEBUG + +/** * 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 // BC_DEBUG + /** * Handle a fatal error. * @param e The error. @@ -886,19 +1046,14 @@ bc_vm_fatalError(BcErr e); * A function to call at exit. * @param status The exit status. */ -int -bc_vm_atexit(int status); +BcStatus +bc_vm_atexit(BcStatus status); + #endif // BC_ENABLE_LIBRARY /// 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 +1076,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 diff --git a/contrib/bc/locales/de_DE.ISO8859-1.msg b/contrib/bc/locales/de_DE.ISO8859-1.msg index dc7545e3ed72..9700ab070b2c 100644 --- a/contrib/bc/locales/de_DE.ISO8859-1.msg +++ b/contrib/bc/locales/de_DE.ISO8859-1.msg @@ -1,7 +1,7 @@ $ $ $ SPDX-License-Identifier: BSD-2-Clause $ $ -$ Copyright (c) 2018-2021 Gavin D. Howard and contributors. +$ Copyright (c) 2018-2024 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" diff --git a/contrib/bc/locales/de_DE.UTF-8.msg b/contrib/bc/locales/de_DE.UTF-8.msg index 7956615e849f..7b918fc6d1cd 100644 --- a/contrib/bc/locales/de_DE.UTF-8.msg +++ b/contrib/bc/locales/de_DE.UTF-8.msg @@ -1,7 +1,7 @@ $ $ $ SPDX-License-Identifier: BSD-2-Clause $ $ -$ Copyright (c) 2018-2021 Gavin D. Howard and contributors. +$ Copyright (c) 2018-2024 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" diff --git a/contrib/bc/locales/en_US.msg b/contrib/bc/locales/en_US.msg index c6bfe6dc3f6a..4afcbcd1f813 100644 --- a/contrib/bc/locales/en_US.msg +++ b/contrib/bc/locales/en_US.msg @@ -1,7 +1,7 @@ $ $ $ SPDX-License-Identifier: BSD-2-Clause $ $ -$ Copyright (c) 2018-2021 Gavin D. Howard and contributors. +$ Copyright (c) 2018-2024 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" diff --git a/contrib/bc/locales/es_ES.ISO8859-1.msg b/contrib/bc/locales/es_ES.ISO8859-1.msg index 30c965111de6..4d022d9bf664 100644 --- a/contrib/bc/locales/es_ES.ISO8859-1.msg +++ b/contrib/bc/locales/es_ES.ISO8859-1.msg @@ -1,7 +1,7 @@ $ $ $ SPDX-License-Identifier: BSD-2-Clause $ $ -$ Copyright (c) 2018-2021 Gavin D. Howard and contributors. +$ Copyright (c) 2018-2024 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" diff --git a/contrib/bc/locales/es_ES.UTF-8.msg b/contrib/bc/locales/es_ES.UTF-8.msg index 1721dd3d8f2a..364cff6ee57f 100644 --- a/contrib/bc/locales/es_ES.UTF-8.msg +++ b/contrib/bc/locales/es_ES.UTF-8.msg @@ -1,7 +1,7 @@ $ $ $ SPDX-License-Identifier: BSD-2-Clause $ $ -$ Copyright (c) 2018-2021 Gavin D. Howard and contributors. +$ Copyright (c) 2018-2024 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" diff --git a/contrib/bc/locales/fr_FR.ISO8859-1.msg b/contrib/bc/locales/fr_FR.ISO8859-1.msg index 5d772abcc4ef..b4b39866c96e 100644 --- a/contrib/bc/locales/fr_FR.ISO8859-1.msg +++ b/contrib/bc/locales/fr_FR.ISO8859-1.msg @@ -1,7 +1,7 @@ $ $ $ SPDX-License-Identifier: BSD-2-Clause $ $ -$ Copyright (c) 2018-2021 Gavin D. Howard and contributors. +$ Copyright (c) 2018-2024 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" diff --git a/contrib/bc/locales/fr_FR.UTF-8.msg b/contrib/bc/locales/fr_FR.UTF-8.msg index 6393ab0e5f70..c3387e31ae9f 100644 --- a/contrib/bc/locales/fr_FR.UTF-8.msg +++ b/contrib/bc/locales/fr_FR.UTF-8.msg @@ -1,7 +1,7 @@ $ $ $ SPDX-License-Identifier: BSD-2-Clause $ $ -$ Copyright (c) 2018-2021 Gavin D. Howard and contributors. +$ Copyright (c) 2018-2024 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" diff --git a/contrib/bc/locales/ja_JP.UTF-8.msg b/contrib/bc/locales/ja_JP.UTF-8.msg index 3c51aca8194f..21640eb9f1cb 100644 --- a/contrib/bc/locales/ja_JP.UTF-8.msg +++ b/contrib/bc/locales/ja_JP.UTF-8.msg @@ -1,7 +1,7 @@ $ $ $ SPDX-License-Identifier: BSD-2-Clause $ $ -$ Copyright (c) 2018-2021 Gavin D. Howard and contributors. +$ Copyright (c) 2018-2024 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エラー" diff --git a/contrib/bc/locales/ja_JP.eucJP.msg b/contrib/bc/locales/ja_JP.eucJP.msg index 74bd09c27fd5..3e3b73d20f4e 100644 --- a/contrib/bc/locales/ja_JP.eucJP.msg +++ b/contrib/bc/locales/ja_JP.eucJP.msg @@ -1,7 +1,7 @@ $ $ $ SPDX-License-Identifier: BSD-2-Clause $ $ -$ Copyright (c) 2018-2021 Gavin D. Howard and contributors. +$ Copyright (c) 2018-2024 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¥¨¥é¡¼" diff --git a/contrib/bc/locales/nl_NL.ISO8859-1.msg b/contrib/bc/locales/nl_NL.ISO8859-1.msg index 2f60de23cca1..aaf41c65b04d 100644 --- a/contrib/bc/locales/nl_NL.ISO8859-1.msg +++ b/contrib/bc/locales/nl_NL.ISO8859-1.msg @@ -1,7 +1,7 @@ $ $ $ SPDX-License-Identifier: BSD-2-Clause $ $ -$ Copyright (c) 2018-2021 Gavin D. Howard and contributors. +$ Copyright (c) 2018-2024 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" diff --git a/contrib/bc/locales/nl_NL.UTF-8.msg b/contrib/bc/locales/nl_NL.UTF-8.msg index 599628a6cc51..0ab0b9c3dc61 100644 --- a/contrib/bc/locales/nl_NL.UTF-8.msg +++ b/contrib/bc/locales/nl_NL.UTF-8.msg @@ -1,7 +1,7 @@ $ $ $ SPDX-License-Identifier: BSD-2-Clause $ $ -$ Copyright (c) 2018-2021 Gavin D. Howard and contributors. +$ Copyright (c) 2018-2024 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" diff --git a/contrib/bc/locales/pl_PL.ISO8859-2.msg b/contrib/bc/locales/pl_PL.ISO8859-2.msg index a36d5fe8beb5..5b427c808fdd 100644 --- a/contrib/bc/locales/pl_PL.ISO8859-2.msg +++ b/contrib/bc/locales/pl_PL.ISO8859-2.msg @@ -1,7 +1,7 @@ $ $ $ SPDX-License-Identifier: BSD-2-Clause $ $ -$ Copyright (c) 2018-2021 Gavin D. Howard and contributors. +$ Copyright (c) 2018-2024 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" diff --git a/contrib/bc/locales/pl_PL.UTF-8.msg b/contrib/bc/locales/pl_PL.UTF-8.msg index ee297161a895..fd0f85b5f767 100644 --- a/contrib/bc/locales/pl_PL.UTF-8.msg +++ b/contrib/bc/locales/pl_PL.UTF-8.msg @@ -1,7 +1,7 @@ $ $ $ SPDX-License-Identifier: BSD-2-Clause $ $ -$ Copyright (c) 2018-2021 Gavin D. Howard and contributors. +$ Copyright (c) 2018-2024 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" diff --git a/contrib/bc/locales/pt_PT.ISO8859-1.msg b/contrib/bc/locales/pt_PT.ISO8859-1.msg index 6197a73d0fe2..9b365b4a7bd1 100644 --- a/contrib/bc/locales/pt_PT.ISO8859-1.msg +++ b/contrib/bc/locales/pt_PT.ISO8859-1.msg @@ -1,7 +1,7 @@ $ $ $ SPDX-License-Identifier: BSD-2-Clause $ $ -$ Copyright (c) 2018-2021 Gavin D. Howard and contributors. +$ Copyright (c) 2018-2024 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" diff --git a/contrib/bc/locales/pt_PT.UTF-8.msg b/contrib/bc/locales/pt_PT.UTF-8.msg index 768f8807ebfc..f5054a178cf4 100644 --- a/contrib/bc/locales/pt_PT.UTF-8.msg +++ b/contrib/bc/locales/pt_PT.UTF-8.msg @@ -1,7 +1,7 @@ $ $ $ SPDX-License-Identifier: BSD-2-Clause $ $ -$ Copyright (c) 2018-2021 Gavin D. Howard and contributors. +$ Copyright (c) 2018-2024 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" diff --git a/contrib/bc/locales/ru_RU.CP1251.msg b/contrib/bc/locales/ru_RU.CP1251.msg index a094e08e4afb..ac8957cc6aa8 100644 --- a/contrib/bc/locales/ru_RU.CP1251.msg +++ b/contrib/bc/locales/ru_RU.CP1251.msg @@ -1,7 +1,7 @@ $ $ $ SPDX-License-Identifier: BSD-2-Clause $ $ -$ Copyright (c) 2018-2021 Gavin D. Howard and contributors. +$ Copyright (c) 2018-2024 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 "Îøèáêà ââîäà/âûâîäà" diff --git a/contrib/bc/locales/ru_RU.CP866.msg b/contrib/bc/locales/ru_RU.CP866.msg index 79070cda2e0c..763fd55a3653 100644 --- a/contrib/bc/locales/ru_RU.CP866.msg +++ b/contrib/bc/locales/ru_RU.CP866.msg @@ -1,7 +1,7 @@ $ $ $ SPDX-License-Identifier: BSD-2-Clause $ $ -$ Copyright (c) 2018-2021 Gavin D. Howard and contributors. +$ Copyright (c) 2018-2024 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 "Žè¨¡ª ¢¢®¤ /¢ë¢®¤ " diff --git a/contrib/bc/locales/ru_RU.ISO8859-5.msg b/contrib/bc/locales/ru_RU.ISO8859-5.msg index 4c544e94f846..bbb1f418c3a9 100644 --- a/contrib/bc/locales/ru_RU.ISO8859-5.msg +++ b/contrib/bc/locales/ru_RU.ISO8859-5.msg @@ -1,7 +1,7 @@ $ $ $ SPDX-License-Identifier: BSD-2-Clause $ $ -$ Copyright (c) 2018-2021 Gavin D. Howard and contributors. +$ Copyright (c) 2018-2024 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 "¾èØÑÚÐ ÒÒÞÔÐ/ÒëÒÞÔÐ" diff --git a/contrib/bc/locales/ru_RU.KOI8-R.msg b/contrib/bc/locales/ru_RU.KOI8-R.msg index 50c716b5ca2e..d1e2bdc014d2 100644 --- a/contrib/bc/locales/ru_RU.KOI8-R.msg +++ b/contrib/bc/locales/ru_RU.KOI8-R.msg @@ -1,7 +1,7 @@ $ $ $ SPDX-License-Identifier: BSD-2-Clause $ $ -$ Copyright (c) 2018-2021 Gavin D. Howard and contributors. +$ Copyright (c) 2018-2024 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 "ïÛÉÂËÁ ××ÏÄÁ/×Ù×ÏÄÁ" diff --git a/contrib/bc/locales/ru_RU.UTF-8.msg b/contrib/bc/locales/ru_RU.UTF-8.msg index e37bb2182caf..b45b3634a76b 100644 --- a/contrib/bc/locales/ru_RU.UTF-8.msg +++ b/contrib/bc/locales/ru_RU.UTF-8.msg @@ -1,7 +1,7 @@ $ $ $ SPDX-License-Identifier: BSD-2-Clause $ $ -$ Copyright (c) 2018-2021 Gavin D. Howard and contributors. +$ Copyright (c) 2018-2024 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 "Ошибка ввода/вывода" diff --git a/contrib/bc/locales/zh_CN.GB18030.msg b/contrib/bc/locales/zh_CN.GB18030.msg index a2210b19ed29..3625c5b40fdf 100644 --- a/contrib/bc/locales/zh_CN.GB18030.msg +++ b/contrib/bc/locales/zh_CN.GB18030.msg @@ -1,7 +1,7 @@ $ $ $ SPDX-License-Identifier: BSD-2-Clause $ $ -$ Copyright (c) 2018-2021 Gavin D. Howard and contributors. +$ Copyright (c) 2018-2024 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´íÎó" diff --git a/contrib/bc/locales/zh_CN.GB2312.msg b/contrib/bc/locales/zh_CN.GB2312.msg index a2210b19ed29..3625c5b40fdf 100644 --- a/contrib/bc/locales/zh_CN.GB2312.msg +++ b/contrib/bc/locales/zh_CN.GB2312.msg @@ -1,7 +1,7 @@ $ $ $ SPDX-License-Identifier: BSD-2-Clause $ $ -$ Copyright (c) 2018-2021 Gavin D. Howard and contributors. +$ Copyright (c) 2018-2024 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´íÎó" diff --git a/contrib/bc/locales/zh_CN.GBK.msg b/contrib/bc/locales/zh_CN.GBK.msg index a2210b19ed29..3625c5b40fdf 100644 --- a/contrib/bc/locales/zh_CN.GBK.msg +++ b/contrib/bc/locales/zh_CN.GBK.msg @@ -1,7 +1,7 @@ $ $ $ SPDX-License-Identifier: BSD-2-Clause $ $ -$ Copyright (c) 2018-2021 Gavin D. Howard and contributors. +$ Copyright (c) 2018-2024 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´íÎó" diff --git a/contrib/bc/locales/zh_CN.UTF-8.msg b/contrib/bc/locales/zh_CN.UTF-8.msg index 92d1bb767cb0..95813f411698 100644 --- a/contrib/bc/locales/zh_CN.UTF-8.msg +++ b/contrib/bc/locales/zh_CN.UTF-8.msg @@ -1,7 +1,7 @@ $ $ $ SPDX-License-Identifier: BSD-2-Clause $ $ -$ Copyright (c) 2018-2021 Gavin D. Howard and contributors. +$ Copyright (c) 2018-2024 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错误" diff --git a/contrib/bc/locales/zh_CN.eucCN.msg b/contrib/bc/locales/zh_CN.eucCN.msg index a2210b19ed29..3625c5b40fdf 100644 --- a/contrib/bc/locales/zh_CN.eucCN.msg +++ b/contrib/bc/locales/zh_CN.eucCN.msg @@ -1,7 +1,7 @@ $ $ $ SPDX-License-Identifier: BSD-2-Clause $ $ -$ Copyright (c) 2018-2021 Gavin D. Howard and contributors. +$ Copyright (c) 2018-2024 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´íÎó" diff --git a/contrib/bc/manuals/algorithms.md b/contrib/bc/manuals/algorithms.md index ef6b6d99a657..ce27bf026b69 100644 --- a/contrib/bc/manuals/algorithms.md +++ b/contrib/bc/manuals/algorithms.md @@ -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 @@ -193,6 +193,74 @@ The algorithm used is to use the formula `e(y*l(x))`. It has a complexity of `O(n^3)` because both `e()` and `l()` do. +However, there are details to this algorithm, described by the author, +TediusTimmy, in GitHub issue [#69][12]. + +First, check if the exponent is 0. If it is, return 1 at the appropriate +`scale`. + +Next, check if the number is 0. If so, check if the exponent is greater than +zero; if it is, return 0. If the exponent is less than 0, error (with a divide +by 0) because that is undefined. + +Next, check if the exponent is actually an integer, and if it is, use the +exponentiation operator. + +At the `z=0` line is the start of the meat of the new code. + +`z` is set to zero as a flag and as a value. What I mean by that will be clear +later. + +Then we check if the number is less than 0. If it is, we negate the exponent +(and the integer version of the exponent, which we calculated earlier to check +if it was an integer). We also save the number in `z`; being non-zero is a flag +for later and a value to be used. Then we store the reciprocal of the number in +itself. + +All of the above paragraph will not make sense unless you remember the +relationship `l(x) == -l(1/x)`; we negated the exponent, which is equivalent to +the negative sign in that relationship, and we took the reciprocal of the +number, which is equivalent to the reciprocal in the relationship. + +But what if the number is negative? We ignore that for now because we eventually +call `l(x)`, which will raise an error if `x` is negative. + +Now, we can keep going. + +If at this point, the exponent is negative, we need to use the original formula +(`e(y * l(x))`) and return that result because the result will go to zero +anyway. + +But if we did *not* return, we know the exponent is *not* negative, so we can +get clever. + +We then compute the integral portion of the power by computing the number to +power of the integral portion of the exponent. + +Then we have the most clever trick: we add the length of that integer power (and +a little extra) to the `scale`. Why? Because this will ensure that the next part +is calculated to at least as many digits as should be in the integer *plus* any +extra `scale` that was wanted. + +Then we check `z`, which, if it is not zero, is the original value of the +number. If it is not zero, we need to take the take the reciprocal *again* +because now we have the correct `scale`. And we *also* have to calculate the +integer portion of the power again. + +Then we need to calculate the fractional portion of the number. We do this by +using the original formula, but we instead of calculating `e(y * l(x))`, we +calculate `e((y - a) * l(x))`, where `a` is the integer portion of `y`. It's +easy to see that `y - a` will be just the fractional portion of `y` (the +exponent), so this makes sense. + +But then we *multiply* it into the integer portion of the power. Why? Because +remember: we're dealing with an exponent and a power; the relationship is +`x^(y+z) == (x^y)*(x^z)`. + +So we multiply it into the integer portion of the power. + +Finally, we set the result to the `scale`. + ### Rounding (`bc` Math Library 2 Only) This is implemented in the function `r(x,p)`. @@ -327,3 +395,4 @@ It has a complexity of `O(n^3)` because of arctangent. [9]: https://en.wikipedia.org/wiki/Root-finding_algorithms#Newton's_method_(and_similar_derivative-based_methods) [10]: https://en.wikipedia.org/wiki/Euclidean_algorithm [11]: https://en.wikipedia.org/wiki/Atan2#Definition_and_computation +[12]: https://github.com/gavinhoward/bc/issues/69 diff --git a/contrib/bc/manuals/bc/A.1 b/contrib/bc/manuals/bc/A.1 index f19ed3c9ac78..adeb62f82e6a 100644 --- a/contrib/bc/manuals/bc/A.1 +++ b/contrib/bc/manuals/bc/A.1 @@ -1,7 +1,7 @@ .\" .\" SPDX-License-Identifier: BSD-2-Clause .\" -.\" Copyright (c) 2018-2021 Gavin D. Howard and contributors. +.\" Copyright (c) 2018-2024 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,40 +25,38 @@ .\" 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" "August 2024" "Gavin D. Howard" "General Commands Manual" .nh .ad l .SH NAME -.PP -bc - arbitrary-precision decimal arithmetic language and calculator +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]--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]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]] .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. +somewhat C\-like, but there are differences. Such differences will be noted in this document. .PP After parsing and handling options, this bc(1) reads any files given on 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 +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. @@ -67,19 +65,114 @@ implementations. another bc(1) gives a parse error, it is probably because a word this bc(1) reserves as a keyword is used as the name of a function, variable, or array. -To fix that, use the command-line option \f[B]-r\f[R] \f[I]keyword\f[R], -where \f[I]keyword\f[R] is the keyword that is used as a name in the -script. +To fix that, use the command\-line option \f[B]\-r\f[R] +\f[I]keyword\f[R], where \f[I]keyword\f[R] is the keyword that is used +as a name in the script. For more information, see the \f[B]OPTIONS\f[R] section. .PP If parsing scripts meant for other bc(1) implementations still does not work, that is a bug and should be reported. See the \f[B]BUGS\f[R] section. .SH OPTIONS -.PP The following are the options that bc(1) accepts. .TP -\f[B]-g\f[R], \f[B]--global-stacks\f[R] +\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. .RS @@ -92,19 +185,16 @@ without worrying that the change will affect other functions. Thus, a hypothetical function named \f[B]output(x,b)\f[R] that simply printed \f[B]x\f[R] in base \f[B]b\f[R] could be written like this: .IP -.nf -\f[C] +.EX define void output(x, b) { obase=b x } -\f[R] -.fi +.EE .PP instead of like this: .IP -.nf -\f[C] +.EX define void output(x, b) { auto c c=obase @@ -112,8 +202,7 @@ define void output(x, b) { x obase=c } -\f[R] -.fi +.EE .PP This makes writing functions much easier. .PP @@ -131,12 +220,10 @@ converter, it is possible to replace that capability with various shell aliases. Examples: .IP -.nf -\f[C] -alias d2o=\[dq]bc -e ibase=A -e obase=8\[dq] -alias h2b=\[dq]bc -e ibase=G -e obase=2\[dq] -\f[R] -.fi +.EX +alias d2o=\[dq]bc \-e ibase=A \-e obase=8\[dq] +alias h2b=\[dq]bc \-e ibase=G \-e obase=2\[dq] +.EE .PP Second, if the purpose of a function is to set \f[B]ibase\f[R], \f[B]obase\f[R], \f[B]scale\f[R], or \f[B]seed\f[R] globally for any @@ -146,53 +233,63 @@ desired value for a global. .PP For functions that set \f[B]seed\f[R], the value assigned to \f[B]seed\f[R] is not propagated to parent functions. -This means that the sequence of pseudo-random numbers that they see will -not be the same sequence of pseudo-random numbers that any parent sees. +This means that the sequence of pseudo\-random numbers that they see +will not be the same sequence of pseudo\-random numbers that any parent +sees. This is only the case once \f[B]seed\f[R] has been set. .PP -If a function desires to not affect the sequence of pseudo-random +If a function desires to not affect the sequence of pseudo\-random numbers of its parents, but wants to use the same \f[B]seed\f[R], it can use the following line: .IP -.nf -\f[C] +.EX seed = seed -\f[R] -.fi +.EE .PP If the behavior of this option is desired for every run of bc(1), then users could make sure to define \f[B]BC_ENV_ARGS\f[R] and include this option (see the \f[B]ENVIRONMENT VARIABLES\f[R] section for more details). .PP -If \f[B]-s\f[R], \f[B]-w\f[R], or any equivalents are used, this option -is ignored. +If \f[B]\-s\f[R], \f[B]\-w\f[R], or any equivalents are used, this +option is ignored. .PP -This is a \f[B]non-portable extension\f[R]. +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. +\f[B]\-h\f[R], \f[B]\-\-help\f[R] +Prints a usage message and exits. .TP -\f[B]-i\f[R], \f[B]--interactive\f[R] +\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. (See the \f[B]INTERACTIVE MODE\f[R] section.) .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-L\f[R], \f[B]--no-line-length\f[R] +\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]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-l\f[R], \f[B]--mathlib\f[R] +\f[B]\-l\f[R], \f[B]\-\-mathlib\f[R] Sets \f[B]scale\f[R] (see the \f[B]SYNTAX\f[R] section) to \f[B]20\f[R] and loads the included math library and the extended math library before running any code, including any expressions or files specified on the @@ -202,11 +299,23 @@ command line. To learn what is in the libraries, see the \f[B]LIBRARY\f[R] section. .RE .TP -\f[B]-P\f[R], \f[B]--no-prompt\f[R] +\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 @@ -214,14 +323,31 @@ Most of those users would want to put this option in These options override the \f[B]BC_PROMPT\f[R] and \f[B]BC_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]. +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] +\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 @@ -229,16 +355,16 @@ 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]read()\f[R] built-in function is called. +is only used when the \f[B]read()\f[R] built\-in function is called. .PP These options \f[I]do\f[R] override the \f[B]BC_PROMPT\f[R] and \f[B]BC_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]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-r\f[R] \f[I]keyword\f[R], \f[B]--redefine\f[R]=\f[I]keyword\f[R] +\f[B]\-r\f[R] \f[I]keyword\f[R], \f[B]\-\-redefine\f[R]=\f[I]keyword\f[R] Redefines \f[I]keyword\f[R] in order to allow it to be used as a function, variable, or array name. This is useful when this bc(1) gives parse errors when parsing scripts @@ -294,157 +420,63 @@ 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 -This is a \f[B]non-portable extension\f[R]. +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. +\f[B]\-s\f[R], \f[B]\-\-standard\f[R] +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]. +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. +\f[B]\-v\f[R], \f[B]\-V\f[R], \f[B]\-\-version\f[R] +Print the version information (copyright header) and exits. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-w\f[R], \f[B]--warn\f[R] -Like \f[B]-s\f[R] and \f[B]--standard\f[R], except that warnings (and -not errors) are printed for non-standard extensions and execution +\f[B]\-w\f[R], \f[B]\-\-warn\f[R] +Like \f[B]\-s\f[R] and \f[B]\-\-standard\f[R], except that warnings (and +not errors) are printed for non\-standard extensions and execution continues normally. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-z\f[R], \f[B]--leading-zeroes\f[R] -Makes bc(1) print all numbers greater than \f[B]-1\f[R] and less than +\f[B]\-z\f[R], \f[B]\-\-leading\-zeroes\f[R] +Makes bc(1) print all numbers greater than \f[B]\-1\f[R] and less than \f[B]1\f[R], and not equal to \f[B]0\f[R], with a leading zero. .RS .PP This can be set for individual numbers with the \f[B]plz(x)\f[R], -plznl(x)**, \f[B]pnlz(x)\f[R], and \f[B]pnlznl(x)\f[R] functions in the -extended math library (see the \f[B]LIBRARY\f[R] section). +\f[B]plznl(x)\f[R], \f[B]pnlz(x)\f[R], and \f[B]pnlznl(x)\f[R] functions +in the extended math library (see the \f[B]LIBRARY\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +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]. +All long options are \f[B]non\-portable extensions\f[R]. .SH STDIN -.PP -If no files or expressions are given by the \f[B]-f\f[R], -\f[B]--file\f[R], \f[B]-e\f[R], or \f[B]--expression\f[R] options, then -bc(1) reads from \f[B]stdin\f[R]. +If no files or expressions are given by the \f[B]\-f\f[R], +\f[B]\-\-file\f[R], \f[B]\-e\f[R], or \f[B]\-\-expression\f[R] options, +then bc(1) reads from \f[B]stdin\f[R]. .PP However, there are a few caveats to this. .PP @@ -458,8 +490,7 @@ Second, after an \f[B]if\f[R] statement, bc(1) doesn\[cq]t know if an \f[B]else\f[R] statement will follow, so it will not execute until it knows there will not be an \f[B]else\f[R] statement. .SH STDOUT -.PP -Any non-error output is written to \f[B]stdout\f[R]. +Any non\-error output is written to \f[B]stdout\f[R]. In addition, if history (see the \f[B]HISTORY\f[R] section) and the prompt (see the \f[B]TTY MODE\f[R] section) are enabled, both are output to \f[B]stdout\f[R]. @@ -467,7 +498,7 @@ to \f[B]stdout\f[R]. \f[B]Note\f[R]: Unlike other bc(1) implementations, this bc(1) will issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot write to \f[B]stdout\f[R], so if \f[B]stdout\f[R] is closed, as in -\f[B]bc >&-\f[R], it will quit with an error. +\f[B]bc >&\-\f[R], it will quit with an error. This is done so that bc(1) can report problems when \f[B]stdout\f[R] is redirected to a file. .PP @@ -475,13 +506,12 @@ If there are scripts that depend on the behavior of other bc(1) implementations, it is recommended that those scripts be changed to redirect \f[B]stdout\f[R] to \f[B]/dev/null\f[R]. .SH STDERR -.PP Any error output is written to \f[B]stderr\f[R]. .PP \f[B]Note\f[R]: Unlike other bc(1) implementations, this bc(1) will issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot write to \f[B]stderr\f[R], so if \f[B]stderr\f[R] is closed, as in -\f[B]bc 2>&-\f[R], it will quit with an error. +\f[B]bc 2>&\-\f[R], it will quit with an error. This is done so that bc(1) can exit with an error code when \f[B]stderr\f[R] is redirected to a file. .PP @@ -489,12 +519,10 @@ If there are scripts that depend on the behavior of other bc(1) implementations, it is recommended that those scripts be changed to redirect \f[B]stderr\f[R] to \f[B]/dev/null\f[R]. .SH SYNTAX -.PP -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. +The syntax for bc(1) programs is mostly C\-like, with some differences. +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 @@ -502,32 +530,32 @@ In the sections below, \f[B]E\f[R] means expression, \f[B]S\f[R] means statement, and \f[B]I\f[R] means identifier. .PP Identifiers (\f[B]I\f[R]) start with a lowercase letter and can be -followed by any number (up to \f[B]BC_NAME_MAX-1\f[R]) of lowercase -letters (\f[B]a-z\f[R]), digits (\f[B]0-9\f[R]), and underscores +followed by any number (up to \f[B]BC_NAME_MAX\-1\f[R]) of lowercase +letters (\f[B]a\-z\f[R]), digits (\f[B]0\-9\f[R]), and underscores (\f[B]_\f[R]). -The regex is \f[B][a-z][a-z0-9_]*\f[R]. +The regex is \f[B][a\-z][a\-z0\-9_]*\f[R]. Identifiers with more than one character (letter) are a -\f[B]non-portable extension\f[R]. +\f[B]non\-portable extension\f[R]. .PP \f[B]ibase\f[R] is a global variable determining how to interpret constant numbers. It is the \[lq]input\[rq] base, or the number base used for interpreting input numbers. \f[B]ibase\f[R] is initially \f[B]10\f[R]. -If the \f[B]-s\f[R] (\f[B]--standard\f[R]) and \f[B]-w\f[R] -(\f[B]--warn\f[R]) flags were not given on the command line, the max +If the \f[B]\-s\f[R] (\f[B]\-\-standard\f[R]) and \f[B]\-w\f[R] +(\f[B]\-\-warn\f[R]) flags were not given on the command line, the max allowable value for \f[B]ibase\f[R] is \f[B]36\f[R]. Otherwise, it is \f[B]16\f[R]. The min allowable value for \f[B]ibase\f[R] is \f[B]2\f[R]. The max allowable value for \f[B]ibase\f[R] can be queried in bc(1) -programs with the \f[B]maxibase()\f[R] built-in function. +programs with the \f[B]maxibase()\f[R] built\-in function. .PP \f[B]obase\f[R] is a global variable determining how to output results. It is the \[lq]output\[rq] base, or the number base used for outputting numbers. \f[B]obase\f[R] is initially \f[B]10\f[R]. The max allowable value for \f[B]obase\f[R] is \f[B]BC_BASE_MAX\f[R] and -can be queried in bc(1) programs with the \f[B]maxobase()\f[R] built-in +can be queried in bc(1) programs with the \f[B]maxobase()\f[R] built\-in function. The min allowable value for \f[B]obase\f[R] is \f[B]0\f[R]. If \f[B]obase\f[R] is \f[B]0\f[R], values are output in scientific @@ -535,8 +563,8 @@ notation, and if \f[B]obase\f[R] is \f[B]1\f[R], values are output in engineering notation. Otherwise, values are output in the specified base. .PP -Outputting in scientific and engineering notations are \f[B]non-portable -extensions\f[R]. +Outputting in scientific and engineering notations are +\f[B]non\-portable extensions\f[R]. .PP The \f[I]scale\f[R] of an expression is the number of digits in the result of the expression right of the decimal point, and \f[B]scale\f[R] @@ -546,7 +574,7 @@ exceptions. \f[B]scale\f[R] cannot be negative. The max allowable value for \f[B]scale\f[R] is \f[B]BC_SCALE_MAX\f[R] and can be queried in bc(1) programs with the \f[B]maxscale()\f[R] -built-in function. +built\-in function. .PP bc(1) has both \f[I]global\f[R] variables and \f[I]local\f[R] variables. All \f[I]local\f[R] variables are local to the function; they are @@ -571,20 +599,18 @@ The value that is printed is also assigned to the special variable \f[B]last\f[R]. A single dot (\f[B].\f[R]) may also be used as a synonym for \f[B]last\f[R]. -These are \f[B]non-portable extensions\f[R]. +These are \f[B]non\-portable extensions\f[R]. .PP Either semicolons or newlines may separate statements. .SS Comments -.PP There are two kinds of comments: .IP "1." 3 Block comments are enclosed in \f[B]/*\f[R] and \f[B]*/\f[R]. .IP "2." 3 Line comments go from \f[B]#\f[R] until, and not including, the next newline. -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .SS Named Expressions -.PP The following are named expressions in bc(1): .IP "1." 3 Variables: \f[B]I\f[R] @@ -601,26 +627,26 @@ Array Elements: \f[B]I[E]\f[R] .IP "7." 3 \f[B]last\f[R] or a single dot (\f[B].\f[R]) .PP -Numbers 6 and 7 are \f[B]non-portable extensions\f[R]. +Numbers 6 and 7 are \f[B]non\-portable extensions\f[R]. .PP -The meaning of \f[B]seed\f[R] is dependent on the current pseudo-random +The meaning of \f[B]seed\f[R] is dependent on the current pseudo\-random number generator but is guaranteed to not change except for new major versions. .PP The \f[I]scale\f[R] and sign of the value may be significant. .PP If a previously used \f[B]seed\f[R] value is assigned to \f[B]seed\f[R] -and used again, the pseudo-random number generator is guaranteed to -produce the same sequence of pseudo-random numbers as it did when the +and used again, the pseudo\-random number generator is guaranteed to +produce the same sequence of pseudo\-random numbers as it did when the \f[B]seed\f[R] value was previously used. .PP The exact value assigned to \f[B]seed\f[R] is not guaranteed to be returned if \f[B]seed\f[R] is queried again immediately. However, if \f[B]seed\f[R] \f[I]does\f[R] return a different value, both values, when assigned to \f[B]seed\f[R], are guaranteed to produce the -same sequence of pseudo-random numbers. +same sequence of pseudo\-random numbers. This means that certain values assigned to \f[B]seed\f[R] will -\f[I]not\f[R] produce unique sequences of pseudo-random numbers. +\f[I]not\f[R] produce unique sequences of pseudo\-random numbers. The value of \f[B]seed\f[R] will change after any use of the \f[B]rand()\f[R] and \f[B]irand(E)\f[R] operands (see the \f[I]Operands\f[R] subsection below), except if the parameter passed to @@ -641,7 +667,6 @@ Named expressions are required as the operand of of \f[B]assignment\f[R] operators (see the \f[I]Operators\f[R] subsection). .SS Operands -.PP The following are valid operands in bc(1): .IP " 1." 4 Numbers (see the \f[I]Numbers\f[R] subsection below). @@ -651,99 +676,113 @@ Array indices (\f[B]I[E]\f[R]). \f[B](E)\f[R]: The value of \f[B]E\f[R] (used to change precedence). .IP " 4." 4 \f[B]sqrt(E)\f[R]: The square root of \f[B]E\f[R]. -\f[B]E\f[R] must be non-negative. +\f[B]E\f[R] must be non\-negative. .IP " 5." 4 \f[B]length(E)\f[R]: The number of significant decimal digits in \f[B]E\f[R]. Returns \f[B]1\f[R] for \f[B]0\f[R] with no decimal places. If given a string, the length of the string is returned. -Passing a string to \f[B]length(E)\f[R] is a \f[B]non-portable +Passing a string to \f[B]length(E)\f[R] is a \f[B]non\-portable extension\f[R]. .IP " 6." 4 \f[B]length(I[])\f[R]: The number of elements in the array \f[B]I\f[R]. -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .IP " 7." 4 \f[B]scale(E)\f[R]: The \f[I]scale\f[R] of \f[B]E\f[R]. .IP " 8." 4 \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]. +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. 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 +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 "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, -which must be non-zero. +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 +This is a \f[B]non\-portable extension\f[R]. +.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 +that number as a one\-character string. +This is a \f[B]non\-portable extension\f[R]. +.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[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). The \f[B]E\f[R] argument(s) may also be arrays of the form \f[B]I[]\f[R], which will automatically be turned into array references (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 +This is a \f[B]non\-portable extension\f[R]. +.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 +This is a \f[B]non\-portable extension\f[R]. +.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 +This is a \f[B]non\-portable extension\f[R]. +.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 +This is a \f[B]non\-portable extension\f[R]. +.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 +This is a \f[B]non\-portable extension\f[R]. +.IP "21." 4 \f[B]global_stacks()\f[R]: \f[B]0\f[R] if global stacks are not enabled -with the \f[B]-g\f[R] or \f[B]--global-stacks\f[R] options, non-zero -otherwise. +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 +This is a \f[B]non\-portable extension\f[R]. +.IP "22." 4 \f[B]leading_zero()\f[R]: \f[B]0\f[R] if leading zeroes are not enabled -with the \f[B]-z\f[R] or \f[B]\[en]leading-zeroes\f[R] options, non-zero -otherwise. +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 -\f[B]rand()\f[R]: A pseudo-random integer between \f[B]0\f[R] +This is a \f[B]non\-portable extension\f[R]. +.IP "23." 4 +\f[B]rand()\f[R]: A pseudo\-random integer between \f[B]0\f[R] (inclusive) and \f[B]BC_RAND_MAX\f[R] (inclusive). Using this operand will change the value of \f[B]seed\f[R]. -This is a \f[B]non-portable extension\f[R]. -.IP "21." 4 -\f[B]irand(E)\f[R]: A pseudo-random integer between \f[B]0\f[R] +This is a \f[B]non\-portable extension\f[R]. +.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 +If \f[B]E\f[R] is negative or is a non\-integer (\f[B]E\f[R]\[cq]s \f[I]scale\f[R] is not \f[B]0\f[R]), an error is raised, and bc(1) resets (see the \f[B]RESET\f[R] section) while \f[B]seed\f[R] remains unchanged. If \f[B]E\f[R] is larger than \f[B]BC_RAND_MAX\f[R], the higher bound is -honored by generating several pseudo-random integers, multiplying them +honored by generating several pseudo\-random integers, multiplying them by appropriate powers of \f[B]BC_RAND_MAX+1\f[R], and adding them together. Thus, the size of integer that can be generated with this operand is @@ -752,52 +791,83 @@ Using this operand will change the value of \f[B]seed\f[R], unless the 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 +This is a \f[B]non\-portable extension\f[R]. +.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]. +This is a \f[B]non\-portable extension\f[R]. .PP The integers generated by \f[B]rand()\f[R] and \f[B]irand(E)\f[R] are guaranteed to be as unbiased as possible, subject to the limitations of -the pseudo-random number generator. +the pseudo\-random number generator. .PP -\f[B]Note\f[R]: The values returned by the pseudo-random number +\f[B]Note\f[R]: The values returned by the pseudo\-random number generator with \f[B]rand()\f[R] and \f[B]irand(E)\f[R] are guaranteed to \f[I]NOT\f[R] be cryptographically secure. -This is a consequence of using a seeded pseudo-random number generator. +This is a consequence of using a seeded pseudo\-random number generator. However, they \f[I]are\f[R] guaranteed to be reproducible with identical \f[B]seed\f[R] values. -This means that the pseudo-random values from bc(1) should only be used -where a reproducible stream of pseudo-random numbers is +This means that the pseudo\-random values from bc(1) should only be used +where a reproducible stream of pseudo\-random numbers is \f[I]ESSENTIAL\f[R]. -In any other case, use a non-seeded pseudo-random number generator. +In any other case, use a non\-seeded pseudo\-random number generator. .SS Numbers -.PP 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]. The exponent (the portion after the \f[B]e\f[R]) must be an integer. An example is \f[B]1.89237e9\f[R], which is equal to \f[B]1892370000\f[R]. -Negative exponents are also allowed, so \f[B]4.2890e-3\f[R] is equal to +Negative exponents are also allowed, so \f[B]4.2890e\-3\f[R] is equal to \f[B]0.0042890\f[R]. .PP -Using scientific notation is an error or warning if the \f[B]-s\f[R] or -\f[B]-w\f[R], respectively, command-line options (or equivalents) are +Using scientific notation is an error or warning if the \f[B]\-s\f[R] or +\f[B]\-w\f[R], respectively, command\-line options (or equivalents) are given. .PP \f[B]WARNING\f[R]: Both the number and the exponent in scientific @@ -807,17 +877,16 @@ of the current \f[B]ibase\f[R]. For example, if \f[B]ibase\f[R] is \f[B]16\f[R] and bc(1) is given the number string \f[B]FFeA\f[R], the resulting decimal number will be \f[B]2550000000000\f[R], and if bc(1) is given the number string -\f[B]10e-4\f[R], the resulting decimal number will be \f[B]0.0016\f[R]. +\f[B]10e\-4\f[R], the resulting decimal number will be \f[B]0.0016\f[R]. .PP -Accepting input as scientific notation is a \f[B]non-portable +Accepting input as scientific notation is a \f[B]non\-portable extension\f[R]. .SS Operators -.PP The following arithmetic and logical operators can be used. They are listed in order of decreasing precedence. Operators in the same group have the same precedence. .TP -\f[B]++\f[R] \f[B]--\f[R] +\f[B]++\f[R] \f[B]\-\-\f[R] Type: Prefix and Postfix .RS .PP @@ -826,7 +895,7 @@ Associativity: None Description: \f[B]increment\f[R], \f[B]decrement\f[R] .RE .TP -\f[B]-\f[R] \f[B]!\f[R] +\f[B]\-\f[R] \f[B]!\f[R] Type: Prefix .RS .PP @@ -871,7 +940,7 @@ Associativity: Left Description: \f[B]multiply\f[R], \f[B]divide\f[R], \f[B]modulus\f[R] .RE .TP -\f[B]+\f[R] \f[B]-\f[R] +\f[B]+\f[R] \f[B]\-\f[R] Type: Binary .RS .PP @@ -889,7 +958,7 @@ Associativity: Left Description: \f[B]shift left\f[R], \f[B]shift right\f[R] .RE .TP -\f[B]=\f[R] \f[B]<<=\f[R] \f[B]>>=\f[R] \f[B]+=\f[R] \f[B]-=\f[R] \f[B]*=\f[R] \f[B]/=\f[R] \f[B]%=\f[R] \f[B]\[ha]=\f[R] \f[B]\[at]=\f[R] +\f[B]=\f[R] \f[B]<<=\f[R] \f[B]>>=\f[R] \f[B]+=\f[R] \f[B]\-=\f[R] \f[B]*=\f[R] \f[B]/=\f[R] \f[B]%=\f[R] \f[B]\[ha]=\f[R] \f[B]\[at]=\f[R] Type: Binary .RS .PP @@ -927,18 +996,18 @@ Description: \f[B]boolean or\f[R] .PP The operators will be described in more detail below. .TP -\f[B]++\f[R] \f[B]--\f[R] +\f[B]++\f[R] \f[B]\-\-\f[R] The prefix and postfix \f[B]increment\f[R] and \f[B]decrement\f[R] -operators behave exactly like they would in C. -They require a named expression (see the \f[I]Named Expressions\f[R] -subsection) as an operand. +operators behave exactly like they would in C. They require a named +expression (see the \f[I]Named Expressions\f[R] subsection) as an +operand. .RS .PP The prefix versions of these operators are more efficient; use them where possible. .RE .TP -\f[B]-\f[R] +\f[B]\-\f[R] The \f[B]negation\f[R] operator returns \f[B]0\f[R] if a user attempts to negate any expression with the value \f[B]0\f[R]. Otherwise, a copy of the expression with its sign flipped is returned. @@ -948,7 +1017,11 @@ The \f[B]boolean not\f[R] operator returns \f[B]1\f[R] if the expression is \f[B]0\f[R], or \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +\f[B]Warning\f[R]: This operator has a \f[B]different precedence\f[R] +than the equivalent operator in GNU bc(1) and other bc(1) +implementations! +.PP +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]$\f[R] @@ -956,7 +1029,7 @@ The \f[B]truncation\f[R] operator returns a copy of the given expression with all of its \f[I]scale\f[R] removed. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]\[at]\f[R] @@ -970,9 +1043,9 @@ more). .RS .PP The second expression must be an integer (no \f[I]scale\f[R]) and -non-negative. +non\-negative. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]\[ha]\f[R] @@ -983,7 +1056,7 @@ The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R]. .RS .PP The second expression must be an integer (no \f[I]scale\f[R]), and if it -is negative, the first value must be non-zero. +is negative, the first value must be non\-zero. .RE .TP \f[B]*\f[R] @@ -1001,18 +1074,18 @@ returns the quotient. The \f[I]scale\f[R] of the result shall be the value of \f[B]scale\f[R]. .RS .PP -The second expression must be non-zero. +The second expression must be non\-zero. .RE .TP \f[B]%\f[R] The \f[B]modulus\f[R] operator takes two expressions, \f[B]a\f[R] and \f[B]b\f[R], and evaluates them by 1) Computing \f[B]a/b\f[R] to current \f[B]scale\f[R] and 2) Using the result of step 1 to calculate -\f[B]a-(a/b)*b\f[R] to \f[I]scale\f[R] +\f[B]a\-(a/b)*b\f[R] to \f[I]scale\f[R] \f[B]max(scale+scale(b),scale(a))\f[R]. .RS .PP -The second expression must be non-zero. +The second expression must be non\-zero. .RE .TP \f[B]+\f[R] @@ -1020,7 +1093,7 @@ The \f[B]add\f[R] operator takes two expressions, \f[B]a\f[R] and \f[B]b\f[R], and returns the sum, with a \f[I]scale\f[R] equal to the max of the \f[I]scale\f[R]s of \f[B]a\f[R] and \f[B]b\f[R]. .TP -\f[B]-\f[R] +\f[B]\-\f[R] The \f[B]subtract\f[R] operator takes two expressions, \f[B]a\f[R] and \f[B]b\f[R], and returns the difference, with a \f[I]scale\f[R] equal to the max of the \f[I]scale\f[R]s of \f[B]a\f[R] and \f[B]b\f[R]. @@ -1032,9 +1105,9 @@ decimal point moved \f[B]b\f[R] places to the right. .RS .PP The second expression must be an integer (no \f[I]scale\f[R]) and -non-negative. +non\-negative. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]>>\f[R] @@ -1044,12 +1117,12 @@ decimal point moved \f[B]b\f[R] places to the left. .RS .PP The second expression must be an integer (no \f[I]scale\f[R]) and -non-negative. +non\-negative. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]=\f[R] \f[B]<<=\f[R] \f[B]>>=\f[R] \f[B]+=\f[R] \f[B]-=\f[R] \f[B]*=\f[R] \f[B]/=\f[R] \f[B]%=\f[R] \f[B]\[ha]=\f[R] \f[B]\[at]=\f[R] +\f[B]=\f[R] \f[B]<<=\f[R] \f[B]>>=\f[R] \f[B]+=\f[R] \f[B]\-=\f[R] \f[B]*=\f[R] \f[B]/=\f[R] \f[B]%=\f[R] \f[B]\[ha]=\f[R] \f[B]\[at]=\f[R] The \f[B]assignment\f[R] operators take two expressions, \f[B]a\f[R] and \f[B]b\f[R] where \f[B]a\f[R] is a named expression (see the \f[I]Named Expressions\f[R] subsection). @@ -1062,7 +1135,7 @@ the corresponding arithmetic operator and the result is assigned to \f[B]a\f[R]. .PP The \f[B]assignment\f[R] operators that correspond to operators that are -extensions are themselves \f[B]non-portable extensions\f[R]. +extensions are themselves \f[B]non\-portable extensions\f[R]. .RE .TP \f[B]==\f[R] \f[B]<=\f[R] \f[B]>=\f[R] \f[B]!=\f[R] \f[B]<\f[R] \f[B]>\f[R] @@ -1076,41 +1149,39 @@ 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]. +This allowance is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]&&\f[R] The \f[B]boolean and\f[R] operator takes two expressions and returns -\f[B]1\f[R] if both expressions are non-zero, \f[B]0\f[R] otherwise. +\f[B]1\f[R] if both expressions are non\-zero, \f[B]0\f[R] otherwise. .RS .PP -This is \f[I]not\f[R] a short-circuit operator. +This is \f[I]not\f[R] a short\-circuit operator. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]||\f[R] The \f[B]boolean or\f[R] operator takes two expressions and returns -\f[B]1\f[R] if one of the expressions is non-zero, \f[B]0\f[R] +\f[B]1\f[R] if one of the expressions is non\-zero, \f[B]0\f[R] otherwise. .RS .PP -This is \f[I]not\f[R] a short-circuit operator. +This is \f[I]not\f[R] a short\-circuit operator. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .SS Statements -.PP 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 +1207,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 @@ -1149,10 +1222,10 @@ The \f[B]E\f[R] argument(s) may also be arrays of the form \f[B]FUNCTIONS\f[R] section) if the corresponding parameter in the function definition is an array reference. .PP -Numbers 4, 9, 11, 12, 14, 15, and 16 are \f[B]non-portable +Numbers 4, 9, 11, 12, 14, 15, and 16 are \f[B]non\-portable extensions\f[R]. .PP -Also, as a \f[B]non-portable extension\f[R], any or all of the +Also, as a \f[B]non\-portable extension\f[R], any or all of the expressions in the header of a for loop may be omitted. If the condition (second expression) is omitted, it is assumed to be a constant \f[B]1\f[R]. @@ -1169,7 +1242,24 @@ This is only allowed in loops. The \f[B]if\f[R] \f[B]else\f[R] statement does the same thing as in C. .PP 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). +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 +.EX +for (i = 0; i < 3; ++i) i; quit +.EE +.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 @@ -1177,7 +1267,7 @@ that is not executed, bc(1) does not quit.) .PP The \f[B]limits\f[R] statement prints the limits that this bc(1) is subject to. -This is like the \f[B]quit\f[R] statement in that it is a compile-time +This is like the \f[B]quit\f[R] statement in that it is a compile\-time command. .PP An expression by itself is evaluated and printed, followed by a newline. @@ -1190,13 +1280,12 @@ Scientific notation is activated by assigning \f[B]0\f[R] to To deactivate them, just assign a different value to \f[B]obase\f[R]. .PP Scientific notation and engineering notation are disabled if bc(1) is -run with either the \f[B]-s\f[R] or \f[B]-w\f[R] command-line options +run with either the \f[B]\-s\f[R] or \f[B]\-w\f[R] command\-line options (or equivalents). .PP Printing numbers in scientific notation and/or engineering notation is a -\f[B]non-portable extension\f[R]. +\f[B]non\-portable extension\f[R]. .SS Strings -.PP If strings appear as a statement by themselves, they are printed without a trailing newline. .PP @@ -1213,9 +1302,8 @@ element that has been assigned a string, an error is raised, and bc(1) resets (see the \f[B]RESET\f[R] section). .PP Assigning strings to variables and array elements and passing them to -functions are \f[B]non-portable extensions\f[R]. +functions are \f[B]non\-portable extensions\f[R]. .SS Print Statement -.PP The \[lq]expressions\[rq] in a \f[B]print\f[R] statement may also be strings. If they are, there are backslash escape sequences that are interpreted @@ -1242,14 +1330,12 @@ below: \f[B]\[rs]t\f[R]: \f[B]\[rs]t\f[R] .PP Any other character following a backslash causes the backslash and -character to be printed as-is. +character to be printed as\-is. .PP -Any non-string expression in a print statement shall be assigned to +Any non\-string expression in a print statement shall be assigned to \f[B]last\f[R], like any other expression that is printed. .SS Stream Statement -.PP -The \[lq]expressions in a \f[B]stream\f[R] statement may also be -strings. +The expressions in a \f[B]stream\f[R] statement may also be strings. .PP If a \f[B]stream\f[R] statement is given a string, it prints the string as though the string had appeared as its own statement. @@ -1259,20 +1345,17 @@ without a newline. If a \f[B]stream\f[R] statement is given a number, a copy of it is truncated and its absolute value is calculated. The result is then printed as though \f[B]obase\f[R] is \f[B]256\f[R] -and each digit is interpreted as an 8-bit ASCII character, making it a +and each digit is interpreted as an 8\-bit ASCII character, making it a byte stream. .SS Order of Evaluation -.PP All expressions in a statment are evaluated left to right, except as necessary to maintain order of operations. This means, for example, assuming that \f[B]i\f[R] is equal to \f[B]0\f[R], in the expression .IP -.nf -\f[C] +.EX a[i++] = i++ -\f[R] -.fi +.EE .PP the first (or 0th) element of \f[B]a\f[R] is set to \f[B]1\f[R], and \f[B]i\f[R] is equal to \f[B]2\f[R] at the end of the expression. @@ -1281,28 +1364,23 @@ This includes function arguments. Thus, assuming \f[B]i\f[R] is equal to \f[B]0\f[R], this means that in the expression .IP -.nf -\f[C] +.EX x(i++, i++) -\f[R] -.fi +.EE .PP the first argument passed to \f[B]x()\f[R] is \f[B]0\f[R], and the second argument is \f[B]1\f[R], while \f[B]i\f[R] is equal to \f[B]2\f[R] before the function starts executing. .SH FUNCTIONS -.PP Function definitions are as follows: .IP -.nf -\f[C] +.EX define I(I,...,I){ auto I,...,I S;...;S return(E) } -\f[R] -.fi +.EE .PP Any \f[B]I\f[R] in the parameter list or \f[B]auto\f[R] list may be replaced with \f[B]I[]\f[R] to make a parameter or \f[B]auto\f[R] var an @@ -1313,10 +1391,10 @@ asterisk in the call; they must be called with just \f[B]I[]\f[R] like normal array parameters and will be automatically converted into references. .PP -As a \f[B]non-portable extension\f[R], the opening brace of a +As a \f[B]non\-portable extension\f[R], the opening brace of a \f[B]define\f[R] statement may appear on the next line. .PP -As a \f[B]non-portable extension\f[R], the return statement may also be +As a \f[B]non\-portable extension\f[R], the return statement may also be in one of the following forms: .IP "1." 3 \f[B]return\f[R] @@ -1330,18 +1408,15 @@ equivalent to \f[B]return (0)\f[R], unless the function is a \f[B]void\f[R] function (see the \f[I]Void Functions\f[R] subsection below). .SS Void Functions -.PP Functions can also be \f[B]void\f[R] functions, defined as follows: .IP -.nf -\f[C] +.EX define void I(I,...,I){ auto I,...,I S;...;S return } -\f[R] -.fi +.EE .PP They can only be used as standalone expressions, where such an expression would be printed alone, except in a print statement. @@ -1355,17 +1430,14 @@ possible to have variables, arrays, and functions named \f[B]void\f[R]. The word \[lq]void\[rq] is only treated specially right after the \f[B]define\f[R] keyword. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .SS Array References -.PP For any array in the parameter list, if the array is declared in the form .IP -.nf -\f[C] +.EX *I[] -\f[R] -.fi +.EE .PP it is a \f[B]reference\f[R]. Any changes to the array in the function are reflected, when the @@ -1373,20 +1445,17 @@ function returns, to the array that was passed in. .PP Other than this, all function arguments are passed by value. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .SH LIBRARY -.PP All of the functions below, including the functions in the extended math library (see the \f[I]Extended Library\f[R] subsection below), are -available when the \f[B]-l\f[R] or \f[B]--mathlib\f[R] command-line +available when the \f[B]\-l\f[R] or \f[B]\-\-mathlib\f[R] command\-line flags are given, except that the extended math library is not available -when the \f[B]-s\f[R] option, the \f[B]-w\f[R] option, or equivalents +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. @@ -1437,14 +1506,12 @@ This is a transcendental function (see the \f[I]Transcendental Functions\f[R] subsection below). .RE .SS Extended Library -.PP 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] +\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]. +The extended library is a \f[B]non\-portable extension\f[R]. .TP \f[B]p(x, y)\f[R] Calculates \f[B]x\f[R] to the power of \f[B]y\f[R], even if \f[B]y\f[R] @@ -1472,6 +1539,14 @@ the rounding mode round away from \f[B]0\f[R] \f[B]f(x)\f[R] Returns the factorial of the truncated absolute value of \f[B]x\f[R]. .TP +\f[B]max(a, b)\f[R] +Returns \f[B]a\f[R] if \f[B]a\f[R] is greater than \f[B]b\f[R]; +otherwise, returns \f[B]b\f[R]. +.TP +\f[B]min(a, b)\f[R] +Returns \f[B]a\f[R] if \f[B]a\f[R] is less than \f[B]b\f[R]; otherwise, +returns \f[B]b\f[R]. +.TP \f[B]perm(n, k)\f[R] Returns the permutation of the truncated absolute value of \f[B]n\f[R] of the truncated absolute value of \f[B]k\f[R], if \f[B]k <= n\f[R]. @@ -1482,6 +1557,10 @@ Returns the combination of the truncated absolute value of \f[B]n\f[R] of the truncated absolute value of \f[B]k\f[R], if \f[B]k <= n\f[R]. If not, it returns \f[B]0\f[R]. .TP +\f[B]fib(n)\f[R] +Returns the Fibonacci number of the truncated absolute value of +\f[B]n\f[R]. +.TP \f[B]l2(x)\f[R] Returns the logarithm base \f[B]2\f[R] of \f[B]x\f[R]. .RS @@ -1553,11 +1632,11 @@ Otherwise, if \f[B]x\f[R] is greater than \f[B]0\f[R], it returns If \f[B]x\f[R] is less than \f[B]0\f[R], and \f[B]y\f[R] is greater than or equal to \f[B]0\f[R], it returns \f[B]a(y/x)+pi\f[R]. If \f[B]x\f[R] is less than \f[B]0\f[R], and \f[B]y\f[R] is less than -\f[B]0\f[R], it returns \f[B]a(y/x)-pi\f[R]. +\f[B]0\f[R], it returns \f[B]a(y/x)\-pi\f[R]. If \f[B]x\f[R] is equal to \f[B]0\f[R], and \f[B]y\f[R] is greater than \f[B]0\f[R], it returns \f[B]pi/2\f[R]. If \f[B]x\f[R] is equal to \f[B]0\f[R], and \f[B]y\f[R] is less than -\f[B]0\f[R], it returns \f[B]-pi/2\f[R]. +\f[B]0\f[R], it returns \f[B]\-pi/2\f[R]. .RS .PP This function is the same as the \f[B]atan2()\f[R] function in many @@ -1591,7 +1670,7 @@ Functions\f[R] subsection below). Returns the tangent of \f[B]x\f[R], which is assumed to be in radians. .RS .PP -If \f[B]x\f[R] is equal to \f[B]1\f[R] or \f[B]-1\f[R], this raises an +If \f[B]x\f[R] is equal to \f[B]1\f[R] or \f[B]\-1\f[R], this raises an error and causes bc(1) to reset (see the \f[B]RESET\f[R] section). .PP This is an alias of \f[B]t(x)\f[R]. @@ -1619,11 +1698,11 @@ Otherwise, if \f[B]x\f[R] is greater than \f[B]0\f[R], it returns If \f[B]x\f[R] is less than \f[B]0\f[R], and \f[B]y\f[R] is greater than or equal to \f[B]0\f[R], it returns \f[B]a(y/x)+pi\f[R]. If \f[B]x\f[R] is less than \f[B]0\f[R], and \f[B]y\f[R] is less than -\f[B]0\f[R], it returns \f[B]a(y/x)-pi\f[R]. +\f[B]0\f[R], it returns \f[B]a(y/x)\-pi\f[R]. If \f[B]x\f[R] is equal to \f[B]0\f[R], and \f[B]y\f[R] is greater than \f[B]0\f[R], it returns \f[B]pi/2\f[R]. If \f[B]x\f[R] is equal to \f[B]0\f[R], and \f[B]y\f[R] is less than -\f[B]0\f[R], it returns \f[B]-pi/2\f[R]. +\f[B]0\f[R], it returns \f[B]\-pi/2\f[R]. .RS .PP This function is the same as the \f[B]atan2()\f[R] function in many @@ -1652,7 +1731,7 @@ Functions\f[R] subsection below). .RE .TP \f[B]frand(p)\f[R] -Generates a pseudo-random number between \f[B]0\f[R] (inclusive) and +Generates a pseudo\-random number between \f[B]0\f[R] (inclusive) and \f[B]1\f[R] (exclusive) with the number of decimal digits after the decimal point equal to the truncated absolute value of \f[B]p\f[R]. If \f[B]p\f[R] is not \f[B]0\f[R], then calling this function will @@ -1661,14 +1740,22 @@ If \f[B]p\f[R] is \f[B]0\f[R], then \f[B]0\f[R] is returned, and \f[B]seed\f[R] is \f[I]not\f[R] changed. .TP \f[B]ifrand(i, p)\f[R] -Generates a pseudo-random number that is between \f[B]0\f[R] (inclusive) -and the truncated absolute value of \f[B]i\f[R] (exclusive) with the -number of decimal digits after the decimal point equal to the truncated -absolute value of \f[B]p\f[R]. +Generates a pseudo\-random number that is between \f[B]0\f[R] +(inclusive) and the truncated absolute value of \f[B]i\f[R] (exclusive) +with the number of decimal digits after the decimal point equal to the +truncated absolute value of \f[B]p\f[R]. If the absolute value of \f[B]i\f[R] is greater than or equal to \f[B]2\f[R], and \f[B]p\f[R] is not \f[B]0\f[R], then calling this function will change the value of \f[B]seed\f[R]; otherwise, \f[B]0\f[R] -is returned and \f[B]seed\f[R] is not changed. +is returned, and \f[B]seed\f[R] is not changed. +.TP +\f[B]i2rand(a, b)\f[R] +Takes the truncated value of \f[B]a\f[R] and \f[B]b\f[R] and uses them +as inclusive bounds to enerate a pseudo\-random integer. +If the difference of the truncated values of \f[B]a\f[R] and \f[B]b\f[R] +is \f[B]0\f[R], then the truncated value is returned, and \f[B]seed\f[R] +is \f[I]not\f[R] changed. +Otherwise, this function will change the value of \f[B]seed\f[R]. .TP \f[B]srand(x)\f[R] Returns \f[B]x\f[R] with its sign flipped with probability @@ -1710,8 +1797,8 @@ If you want to use signed two\[cq]s complement arguments, use .TP \f[B]bshl(a, b)\f[R] Takes the truncated absolute value of both \f[B]a\f[R] and \f[B]b\f[R] -and calculates and returns the result of \f[B]a\f[R] bit-shifted left by -\f[B]b\f[R] places. +and calculates and returns the result of \f[B]a\f[R] bit\-shifted left +by \f[B]b\f[R] places. .RS .PP If you want to use signed two\[cq]s complement arguments, use @@ -1721,7 +1808,7 @@ If you want to use signed two\[cq]s complement arguments, use \f[B]bshr(a, b)\f[R] Takes the truncated absolute value of both \f[B]a\f[R] and \f[B]b\f[R] and calculates and returns the truncated result of \f[B]a\f[R] -bit-shifted right by \f[B]b\f[R] places. +bit\-shifted right by \f[B]b\f[R] places. .RS .PP If you want to use signed two\[cq]s complement arguments, use @@ -1740,7 +1827,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]bnot8(x)\f[R] Does a bitwise not of the truncated absolute value of \f[B]x\f[R] as -though it has \f[B]8\f[R] binary digits (1 unsigned byte). +though it has \f[B]8\f[R] binary digits (\f[B]1\f[R] unsigned byte). .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1749,7 +1836,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]bnot16(x)\f[R] Does a bitwise not of the truncated absolute value of \f[B]x\f[R] as -though it has \f[B]16\f[R] binary digits (2 unsigned bytes). +though it has \f[B]16\f[R] binary digits (\f[B]2\f[R] unsigned bytes). .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1758,7 +1845,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]bnot32(x)\f[R] Does a bitwise not of the truncated absolute value of \f[B]x\f[R] as -though it has \f[B]32\f[R] binary digits (4 unsigned bytes). +though it has \f[B]32\f[R] binary digits (\f[B]4\f[R] unsigned bytes). .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1767,7 +1854,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]bnot64(x)\f[R] Does a bitwise not of the truncated absolute value of \f[B]x\f[R] as -though it has \f[B]64\f[R] binary digits (8 unsigned bytes). +though it has \f[B]64\f[R] binary digits (\f[B]8\f[R] unsigned bytes). .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1785,7 +1872,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]brevn(x, n)\f[R] Runs a bit reversal on the truncated absolute value of \f[B]x\f[R] as -though it has the same number of 8-bit bytes as the truncated absolute +though it has the same number of 8\-bit bytes as the truncated absolute value of \f[B]n\f[R]. .RS .PP @@ -1795,7 +1882,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]brev8(x)\f[R] Runs a bit reversal on the truncated absolute value of \f[B]x\f[R] as -though it has 8 binary digits (1 unsigned byte). +though it has 8 binary digits (\f[B]1\f[R] unsigned byte). .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1804,7 +1891,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]brev16(x)\f[R] Runs a bit reversal on the truncated absolute value of \f[B]x\f[R] as -though it has 16 binary digits (2 unsigned bytes). +though it has 16 binary digits (\f[B]2\f[R] unsigned bytes). .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1813,7 +1900,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]brev32(x)\f[R] Runs a bit reversal on the truncated absolute value of \f[B]x\f[R] as -though it has 32 binary digits (4 unsigned bytes). +though it has 32 binary digits (\f[B]4\f[R] unsigned bytes). .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1822,7 +1909,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]brev64(x)\f[R] Runs a bit reversal on the truncated absolute value of \f[B]x\f[R] as -though it has 64 binary digits (8 unsigned bytes). +though it has 64 binary digits (\f[B]8\f[R] unsigned bytes). .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1840,11 +1927,11 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]broln(x, p, n)\f[R] Does a left bitwise rotatation of the truncated absolute value of -\f[B]x\f[R], as though it has the same number of unsigned 8-bit bytes as -the truncated absolute value of \f[B]n\f[R], by the number of places +\f[B]x\f[R], as though it has the same number of unsigned 8\-bit bytes +as the truncated absolute value of \f[B]n\f[R], by the number of places equal to the truncated absolute value of \f[B]p\f[R] modded by the \f[B]2\f[R] to the power of the number of binary digits in \f[B]n\f[R] -8-bit bytes. +8\-bit bytes. .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1875,7 +1962,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]brol32(x, p)\f[R] Does a left bitwise rotatation of the truncated absolute value of -\f[B]x\f[R], as though it has \f[B]32\f[R] binary digits (\f[B]2\f[R] +\f[B]x\f[R], as though it has \f[B]32\f[R] binary digits (\f[B]4\f[R] unsigned bytes), by the number of places equal to the truncated absolute value of \f[B]p\f[R] modded by \f[B]2\f[R] to the power of \f[B]32\f[R]. .RS @@ -1886,7 +1973,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]brol64(x, p)\f[R] Does a left bitwise rotatation of the truncated absolute value of -\f[B]x\f[R], as though it has \f[B]64\f[R] binary digits (\f[B]2\f[R] +\f[B]x\f[R], as though it has \f[B]64\f[R] binary digits (\f[B]8\f[R] unsigned bytes), by the number of places equal to the truncated absolute value of \f[B]p\f[R] modded by \f[B]2\f[R] to the power of \f[B]64\f[R]. .RS @@ -1898,9 +1985,9 @@ If you want to a use signed two\[cq]s complement argument, use \f[B]brol(x, p)\f[R] Does a left bitwise rotatation of the truncated absolute value of \f[B]x\f[R], as though it has the minimum number of power of two -unsigned 8-bit bytes, by the number of places equal to the truncated +unsigned 8\-bit bytes, by the number of places equal to the truncated absolute value of \f[B]p\f[R] modded by 2 to the power of the number of -binary digits in the minimum number of 8-bit bytes. +binary digits in the minimum number of 8\-bit bytes. .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1909,11 +1996,11 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]brorn(x, p, n)\f[R] Does a right bitwise rotatation of the truncated absolute value of -\f[B]x\f[R], as though it has the same number of unsigned 8-bit bytes as -the truncated absolute value of \f[B]n\f[R], by the number of places +\f[B]x\f[R], as though it has the same number of unsigned 8\-bit bytes +as the truncated absolute value of \f[B]n\f[R], by the number of places equal to the truncated absolute value of \f[B]p\f[R] modded by the \f[B]2\f[R] to the power of the number of binary digits in \f[B]n\f[R] -8-bit bytes. +8\-bit bytes. .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1967,9 +2054,9 @@ If you want to a use signed two\[cq]s complement argument, use \f[B]bror(x, p)\f[R] Does a right bitwise rotatation of the truncated absolute value of \f[B]x\f[R], as though it has the minimum number of power of two -unsigned 8-bit bytes, by the number of places equal to the truncated +unsigned 8\-bit bytes, by the number of places equal to the truncated absolute value of \f[B]p\f[R] modded by 2 to the power of the number of -binary digits in the minimum number of 8-bit bytes. +binary digits in the minimum number of 8\-bit bytes. .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -2023,7 +2110,7 @@ If you want to a use signed two\[cq]s complement argument, use .RE .TP \f[B]bunrev(t)\f[R] -Assumes \f[B]t\f[R] is a bitwise-reversed number with an extra set bit +Assumes \f[B]t\f[R] is a bitwise\-reversed number with an extra set bit one place more significant than the real most significant bit (which was the least significant bit in the original number). This number is reversed and returned without the extra set bit. @@ -2034,29 +2121,29 @@ meant to be used by users, but it can be. .RE .TP \f[B]plz(x)\f[R] -If \f[B]x\f[R] is not equal to \f[B]0\f[R] and greater that \f[B]-1\f[R] -and less than \f[B]1\f[R], it is printed with a leading zero, regardless -of the use of the \f[B]-z\f[R] option (see the \f[B]OPTIONS\f[R] -section) and without a trailing newline. +If \f[B]x\f[R] is not equal to \f[B]0\f[R] and greater that +\f[B]\-1\f[R] and less than \f[B]1\f[R], it is printed with a leading +zero, regardless of the use of the \f[B]\-z\f[R] option (see the +\f[B]OPTIONS\f[R] section) and without a trailing newline. .RS .PP Otherwise, \f[B]x\f[R] is printed normally, without a trailing newline. .RE .TP \f[B]plznl(x)\f[R] -If \f[B]x\f[R] is not equal to \f[B]0\f[R] and greater that \f[B]-1\f[R] -and less than \f[B]1\f[R], it is printed with a leading zero, regardless -of the use of the \f[B]-z\f[R] option (see the \f[B]OPTIONS\f[R] -section) and with a trailing newline. +If \f[B]x\f[R] is not equal to \f[B]0\f[R] and greater that +\f[B]\-1\f[R] and less than \f[B]1\f[R], it is printed with a leading +zero, regardless of the use of the \f[B]\-z\f[R] option (see the +\f[B]OPTIONS\f[R] section) and with a trailing newline. .RS .PP Otherwise, \f[B]x\f[R] is printed normally, with a trailing newline. .RE .TP \f[B]pnlz(x)\f[R] -If \f[B]x\f[R] is not equal to \f[B]0\f[R] and greater that \f[B]-1\f[R] -and less than \f[B]1\f[R], it is printed without a leading zero, -regardless of the use of the \f[B]-z\f[R] option (see the +If \f[B]x\f[R] is not equal to \f[B]0\f[R] and greater that +\f[B]\-1\f[R] and less than \f[B]1\f[R], it is printed without a leading +zero, regardless of the use of the \f[B]\-z\f[R] option (see the \f[B]OPTIONS\f[R] section) and without a trailing newline. .RS .PP @@ -2064,9 +2151,9 @@ Otherwise, \f[B]x\f[R] is printed normally, without a trailing newline. .RE .TP \f[B]pnlznl(x)\f[R] -If \f[B]x\f[R] is not equal to \f[B]0\f[R] and greater that \f[B]-1\f[R] -and less than \f[B]1\f[R], it is printed without a leading zero, -regardless of the use of the \f[B]-z\f[R] option (see the +If \f[B]x\f[R] is not equal to \f[B]0\f[R] and greater that +\f[B]\-1\f[R] and less than \f[B]1\f[R], it is printed without a leading +zero, regardless of the use of the \f[B]\-z\f[R] option (see the \f[B]OPTIONS\f[R] section) and with a trailing newline. .RS .PP @@ -2078,22 +2165,22 @@ Returns the numbers of unsigned integer bytes required to hold the truncated absolute value of \f[B]x\f[R]. .TP \f[B]sbytes(x)\f[R] -Returns the numbers of signed, two\[cq]s-complement integer bytes +Returns the numbers of signed, two\[cq]s\-complement integer bytes required to hold the truncated value of \f[B]x\f[R]. .TP \f[B]s2u(x)\f[R] -Returns \f[B]x\f[R] if it is non-negative. +Returns \f[B]x\f[R] if it is non\-negative. If it \f[I]is\f[R] negative, then it calculates what \f[B]x\f[R] would -be as a 2\[cq]s-complement signed integer and returns the non-negative +be as a 2\[cq]s\-complement signed integer and returns the non\-negative integer that would have the same representation in binary. .TP \f[B]s2un(x,n)\f[R] -Returns \f[B]x\f[R] if it is non-negative. +Returns \f[B]x\f[R] if it is non\-negative. If it \f[I]is\f[R] negative, then it calculates what \f[B]x\f[R] would -be as a 2\[cq]s-complement signed integer with \f[B]n\f[R] bytes and -returns the non-negative integer that would have the same representation -in binary. -If \f[B]x\f[R] cannot fit into \f[B]n\f[R] 2\[cq]s-complement signed +be as a 2\[cq]s\-complement signed integer with \f[B]n\f[R] bytes and +returns the non\-negative integer that would have the same +representation in binary. +If \f[B]x\f[R] cannot fit into \f[B]n\f[R] 2\[cq]s\-complement signed bytes, it is truncated to fit. .TP \f[B]hex(x)\f[R] @@ -2137,7 +2224,7 @@ subsection of the \f[B]FUNCTIONS\f[R] section). .TP \f[B]int(x)\f[R] Outputs the representation, in binary and hexadecimal, of \f[B]x\f[R] as -a signed, two\[cq]s-complement integer in as few power of two bytes as +a signed, two\[cq]s\-complement integer in as few power of two bytes as possible. Both outputs are split into bytes separated by spaces. .RS @@ -2165,7 +2252,7 @@ subsection of the \f[B]FUNCTIONS\f[R] section). .TP \f[B]intn(x, n)\f[R] Outputs the representation, in binary and hexadecimal, of \f[B]x\f[R] as -a signed, two\[cq]s-complement integer in \f[B]n\f[R] bytes. +a signed, two\[cq]s\-complement integer in \f[B]n\f[R] bytes. Both outputs are split into bytes separated by spaces. .RS .PP @@ -2193,7 +2280,7 @@ subsection of the \f[B]FUNCTIONS\f[R] section). .TP \f[B]int8(x)\f[R] Outputs the representation, in binary and hexadecimal, of \f[B]x\f[R] as -a signed, two\[cq]s-complement integer in \f[B]1\f[R] byte. +a signed, two\[cq]s\-complement integer in \f[B]1\f[R] byte. Both outputs are split into bytes separated by spaces. .RS .PP @@ -2221,7 +2308,7 @@ subsection of the \f[B]FUNCTIONS\f[R] section). .TP \f[B]int16(x)\f[R] Outputs the representation, in binary and hexadecimal, of \f[B]x\f[R] as -a signed, two\[cq]s-complement integer in \f[B]2\f[R] bytes. +a signed, two\[cq]s\-complement integer in \f[B]2\f[R] bytes. Both outputs are split into bytes separated by spaces. .RS .PP @@ -2249,7 +2336,7 @@ subsection of the \f[B]FUNCTIONS\f[R] section). .TP \f[B]int32(x)\f[R] Outputs the representation, in binary and hexadecimal, of \f[B]x\f[R] as -a signed, two\[cq]s-complement integer in \f[B]4\f[R] bytes. +a signed, two\[cq]s\-complement integer in \f[B]4\f[R] bytes. Both outputs are split into bytes separated by spaces. .RS .PP @@ -2277,7 +2364,7 @@ subsection of the \f[B]FUNCTIONS\f[R] section). .TP \f[B]int64(x)\f[R] Outputs the representation, in binary and hexadecimal, of \f[B]x\f[R] as -a signed, two\[cq]s-complement integer in \f[B]8\f[R] bytes. +a signed, two\[cq]s\-complement integer in \f[B]8\f[R] bytes. Both outputs are split into bytes separated by spaces. .RS .PP @@ -2324,14 +2411,13 @@ subsection of the \f[B]FUNCTIONS\f[R] section). \f[B]output_byte(x, i)\f[R] Outputs byte \f[B]i\f[R] of the truncated absolute value of \f[B]x\f[R], where \f[B]0\f[R] is the least significant byte and \f[B]number_of_bytes -- 1\f[R] is the most significant byte. +\- 1\f[R] is the most significant byte. .RS .PP This is a \f[B]void\f[R] function (see the \f[I]Void Functions\f[R] subsection of the \f[B]FUNCTIONS\f[R] section). .RE .SS Transcendental Functions -.PP All transcendental functions can return slightly inaccurate results, up to 1 ULP (https://en.wikipedia.org/wiki/Unit_in_the_last_place). This is unavoidable, and the article at @@ -2387,8 +2473,7 @@ The transcendental functions in the extended math library are: .IP \[bu] 2 \f[B]d2r(x)\f[R] .SH RESET -.PP -When bc(1) encounters an error or a signal that it has a non-default +When bc(1) encounters an error or a signal that it has a non\-default handler for, it resets. This means that several things happen. .PP @@ -2408,7 +2493,6 @@ Note that this reset behavior is different from the GNU bc(1), which attempts to start executing the statement right after the one that caused an error. .SH PERFORMANCE -.PP Most bc(1) implementations use \f[B]char\f[R] types to calculate the value of \f[B]1\f[R] decimal digit at a time, but that can be slow. This bc(1) does something different. @@ -2431,7 +2515,6 @@ checking. This integer type depends on the value of \f[B]BC_LONG_BIT\f[R], but is always at least twice as large as the integer type used to store digits. .SH LIMITS -.PP The following are the limits on bc(1): .TP \f[B]BC_LONG_BIT\f[R] @@ -2461,29 +2544,29 @@ Set at \f[B]BC_BASE_POW\f[R]. .TP \f[B]BC_DIM_MAX\f[R] The maximum size of arrays. -Set at \f[B]SIZE_MAX-1\f[R]. +Set at \f[B]SIZE_MAX\-1\f[R]. .TP \f[B]BC_SCALE_MAX\f[R] The maximum \f[B]scale\f[R]. -Set at \f[B]BC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]BC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]BC_STRING_MAX\f[R] The maximum length of strings. -Set at \f[B]BC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]BC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]BC_NAME_MAX\f[R] The maximum length of identifiers. -Set at \f[B]BC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]BC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]BC_NUM_MAX\f[R] The maximum length of a number (in decimal digits), which includes digits after the decimal point. -Set at \f[B]BC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]BC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]BC_RAND_MAX\f[R] The maximum integer (inclusive) returned by the \f[B]rand()\f[R] operand. -Set at \f[B]2\[ha]BC_LONG_BIT-1\f[R]. +Set at \f[B]2\[ha]BC_LONG_BIT\-1\f[R]. .TP Exponent The maximum allowable exponent (positive or negative). @@ -2491,28 +2574,28 @@ Set at \f[B]BC_OVERFLOW_MAX\f[R]. .TP Number of vars The maximum number of vars/arrays. -Set at \f[B]SIZE_MAX-1\f[R]. +Set at \f[B]SIZE_MAX\-1\f[R]. .PP The actual values can be queried with the \f[B]limits\f[R] statement. .PP -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. +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 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 -the \f[B]-s\f[R] option was given. +the \f[B]\-s\f[R] option was given. .TP \f[B]BC_ENV_ARGS\f[R] -This is another way to give command-line arguments to bc(1). -They should be in the same format as all other command-line arguments. +This is another way to give command\-line arguments to bc(1). +They should be in the same format as all other command\-line arguments. These are always processed first, so any files given in \f[B]BC_ENV_ARGS\f[R] will be processed before arguments and files given -on the command-line. +on the command\-line. This gives the user the ability to set up \[lq]standard\[rq] options and files to be used at every invocation. The most useful thing for such files to contain would be useful @@ -2533,14 +2616,14 @@ you can use double quotes as the outside quotes, as in \f[B]\[lq]some quotes. However, handling a file with both kinds of quotes in \f[B]BC_ENV_ARGS\f[R] is not supported due to the complexity of the -parsing, though such files are still supported on the command-line where -the parsing is done by the shell. +parsing, though such files are still supported on the command\-line +where the parsing is done by the shell. .RE .TP \f[B]BC_LINE_LENGTH\f[R] If this environment variable exists and contains an integer that is greater than \f[B]1\f[R] and is less than \f[B]UINT16_MAX\f[R] -(\f[B]2\[ha]16-1\f[R]), bc(1) will output lines to that length, +(\f[B]2\[ha]16\-1\f[R]), bc(1) will output lines to that length, including the backslash (\f[B]\[rs]\f[R]). The default line length is \f[B]70\f[R]. .RS @@ -2552,7 +2635,7 @@ newlines. .TP \f[B]BC_BANNER\f[R] If this environment variable exists and contains an integer, then a -non-zero value activates the copyright banner when bc(1) is in +non\-zero value activates the copyright banner when bc(1) is in interactive mode, while zero deactivates it. .RS .PP @@ -2561,7 +2644,7 @@ section), then this environment variable has no effect because bc(1) does not print the banner when not in interactive mode. .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. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]BC_SIGINT_RESET\f[R] @@ -2571,13 +2654,13 @@ exits on \f[B]SIGINT\f[R] when not in interactive mode. .RS .PP However, when bc(1) is in interactive mode, then if this environment -variable exists and contains an integer, a non-zero value makes bc(1) +variable exists and contains an integer, a non\-zero value makes bc(1) reset on \f[B]SIGINT\f[R], rather than exit, and zero makes bc(1) exit. If this environment variable exists and is \f[I]not\f[R] an integer, then bc(1) will exit on \f[B]SIGINT\f[R]. .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. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]BC_TTY_MODE\f[R] @@ -2586,11 +2669,11 @@ section), then this environment variable has no effect. .RS .PP However, when TTY mode is available, then if this environment variable -exists and contains an integer, then a non-zero value makes bc(1) use +exists and contains an integer, then a non\-zero value makes bc(1) use TTY mode, and zero makes bc(1) not use TTY mode. .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. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]BC_PROMPT\f[R] @@ -2599,30 +2682,46 @@ section), then this environment variable has no effect. .RS .PP However, when TTY mode is available, then if this environment variable -exists and contains an integer, a non-zero value makes bc(1) use a -prompt, and zero or a non-integer makes bc(1) not use a prompt. +exists and contains an integer, a non\-zero value makes bc(1) use a +prompt, and zero or a non\-integer makes bc(1) not use a prompt. If this environment variable does not exist and \f[B]BC_TTY_MODE\f[R] does, then the value of the \f[B]BC_TTY_MODE\f[R] environment variable is used. .PP This environment variable and the \f[B]BC_TTY_MODE\f[R] environment variable override the default, which can be queried with the -\f[B]-h\f[R] or \f[B]--help\f[R] options. +\f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]BC_EXPR_EXIT\f[R] -If any expressions or expression files are given on the command-line -with \f[B]-e\f[R], \f[B]--expression\f[R], \f[B]-f\f[R], or -\f[B]--file\f[R], then if this environment variable exists and contains -an integer, a non-zero value makes bc(1) exit after executing the -expressions and expression files, and a zero value makes bc(1) not exit. +If any expressions or expression files are given on the command\-line +with \f[B]\-e\f[R], \f[B]\-\-expression\f[R], \f[B]\-f\f[R], or +\f[B]\-\-file\f[R], then if this environment variable exists and +contains an integer, a non\-zero value makes bc(1) exit after executing +the expressions and expression files, and a zero value makes bc(1) not +exit. .RS .PP This environment variable overrides the default, which can be queried -with the \f[B]-h\f[R] or \f[B]--help\f[R] options. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE -.SH EXIT STATUS +.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 bc(1) returns the following exit statuses: .TP \f[B]0\f[R] @@ -2636,10 +2735,10 @@ since math errors will happen in the process of normal execution. .PP Math errors include divide by \f[B]0\f[R], taking the square root of a negative number, using a negative number as a bound for the -pseudo-random number generator, attempting to convert a negative number +pseudo\-random number generator, attempting to convert a negative number to a hardware integer, overflow when converting a number to a hardware integer, overflow when calculating the size of a number, and attempting -to use a non-integer where an integer is required. +to use a non\-integer where an integer is required. .PP Converting to a hardware integer happens for the second operand of the power (\f[B]\[ha]\f[R]), places (\f[B]\[at]\f[R]), left shift @@ -2661,7 +2760,7 @@ giving an invalid \f[B]auto\f[R] list, having a duplicate \f[B]auto\f[R]/function parameter, failing to find the end of a code block, attempting to return a value from a \f[B]void\f[R] function, attempting to use a variable as a reference, and using any extensions -when the option \f[B]-s\f[R] or any equivalents were given. +when the option \f[B]\-s\f[R] or any equivalents were given. .RE .TP \f[B]3\f[R] @@ -2684,7 +2783,7 @@ A fatal error occurred. Fatal errors include memory allocation errors, I/O errors, failing to open files, attempting to use files that do not have only ASCII characters (bc(1) only accepts ASCII characters), attempting to open a -directory as a file, and giving invalid command-line options. +directory as a file, and giving invalid command\-line options. .RE .PP The exit status \f[B]4\f[R] is special; when a fatal error occurs, bc(1) @@ -2695,19 +2794,18 @@ interactive mode (see the \f[B]INTERACTIVE MODE\f[R] section), since bc(1) resets its state (see the \f[B]RESET\f[R] section) and accepts more input when one of those errors occurs in interactive mode. This is also the case when interactive mode is forced by the -\f[B]-i\f[R] flag or \f[B]--interactive\f[R] option. +\f[B]\-i\f[R] flag or \f[B]\-\-interactive\f[R] option. .PP These exit statuses allow bc(1) to be used in shell scripting with error checking, and its normal behavior can be forced by using the -\f[B]-i\f[R] flag or \f[B]--interactive\f[R] option. +\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. +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. .PP In interactive mode, bc(1) attempts to recover from errors (see the \f[B]RESET\f[R] section), and in normal execution, flushes @@ -2716,7 +2814,6 @@ bc(1) may also reset on \f[B]SIGINT\f[R] instead of exit, depending on the contents of, or default for, the \f[B]BC_SIGINT_RESET\f[R] environment variable (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). .SH TTY MODE -.PP If \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all connected to a TTY, then \[lq]TTY mode\[rq] is considered to be available, and thus, bc(1) can turn on TTY mode, subject to some @@ -2724,53 +2821,49 @@ settings. .PP If there is the environment variable \f[B]BC_TTY_MODE\f[R] in the environment (see the \f[B]ENVIRONMENT VARIABLES\f[R] section), then if -that environment variable contains a non-zero integer, bc(1) will turn +that environment variable contains a non\-zero integer, bc(1) will turn on TTY mode when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all connected to a TTY. If the \f[B]BC_TTY_MODE\f[R] environment variable exists but is -\f[I]not\f[R] a non-zero integer, then bc(1) will not turn TTY mode on. +\f[I]not\f[R] a non\-zero integer, then bc(1) will not turn TTY mode on. .PP If the environment variable \f[B]BC_TTY_MODE\f[R] does \f[I]not\f[R] exist, the default setting is used. -The default setting can be queried with the \f[B]-h\f[R] or -\f[B]--help\f[R] options. +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 -.PP -Command-line history is only enabled if TTY mode is, i.e., that +.SS Command\-Line History +Command\-line history is only enabled if TTY mode is, i.e., that \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are connected to a TTY and the \f[B]BC_TTY_MODE\f[R] environment variable (see the \f[B]ENVIRONMENT VARIABLES\f[R] section) and its default do not disable TTY mode. See the \f[B]COMMAND LINE HISTORY\f[R] section for more information. .SS Prompt -.PP If TTY mode is available, then a prompt can be enabled. Like TTY mode itself, it can be turned on or off with an environment variable: \f[B]BC_PROMPT\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). .PP -If the environment variable \f[B]BC_PROMPT\f[R] exists and is a non-zero -integer, then the prompt is turned on when \f[B]stdin\f[R], +If the environment variable \f[B]BC_PROMPT\f[R] exists and is a +non\-zero integer, then the prompt is turned on when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are connected to a TTY and the -\f[B]-P\f[R] and \f[B]--no-prompt\f[R] options were not used. +\f[B]\-P\f[R] and \f[B]\-\-no\-prompt\f[R] options were not used. The read prompt will be turned on under the same conditions, except that -the \f[B]-R\f[R] and \f[B]--no-read-prompt\f[R] options must also not be -used. +the \f[B]\-R\f[R] and \f[B]\-\-no\-read\-prompt\f[R] options must also +not be used. .PP However, if \f[B]BC_PROMPT\f[R] does not exist, the prompt can be enabled or disabled with the \f[B]BC_TTY_MODE\f[R] environment variable, -the \f[B]-P\f[R] and \f[B]--no-prompt\f[R] options, and the \f[B]-R\f[R] -and \f[B]--no-read-prompt\f[R] options. +the \f[B]\-P\f[R] and \f[B]\-\-no\-prompt\f[R] options, and the +\f[B]\-R\f[R] and \f[B]\-\-no\-read\-prompt\f[R] options. See the \f[B]ENVIRONMENT VARIABLES\f[R] and \f[B]OPTIONS\f[R] sections for more details. .SH SIGNAL HANDLING -.PP Sending a \f[B]SIGINT\f[R] will cause bc(1) to do one of two things. .PP If bc(1) is not in interactive mode (see the \f[B]INTERACTIVE MODE\f[R] @@ -2779,7 +2872,7 @@ section), or the \f[B]BC_SIGINT_RESET\f[R] environment variable (see the an integer or it is zero, bc(1) will exit. .PP However, if bc(1) is in interactive mode, and the -\f[B]BC_SIGINT_RESET\f[R] or its default is an integer and non-zero, +\f[B]BC_SIGINT_RESET\f[R] or its default is an integer and non\-zero, then bc(1) will stop executing the current input and reset (see the \f[B]RESET\f[R] section) upon receiving a \f[B]SIGINT\f[R]. .PP @@ -2805,12 +2898,11 @@ The one exception is \f[B]SIGHUP\f[R]; in that case, and only when bc(1) is in TTY mode (see the \f[B]TTY MODE\f[R] section), a \f[B]SIGHUP\f[R] will cause bc(1) to clean up and exit. .SH COMMAND LINE HISTORY -.PP -bc(1) supports interactive command-line editing. +bc(1) supports interactive command\-line editing. .PP If bc(1) can be in TTY mode (see the \f[B]TTY MODE\f[R] section), history can be enabled. -This means that command-line history can only be enabled when +This means that command\-line history can only be enabled when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all connected to a TTY. .PP @@ -2823,20 +2915,23 @@ the arrow keys. .PP \f[B]Note\f[R]: tabs are converted to 8 spaces. .SH LOCALES -.PP This bc(1) ships with support for adding error messages for different locales and thus, supports \f[B]LC_MESSAGES\f[R]. .SH SEE ALSO -.PP dc(1) .SH STANDARDS -.PP -bc(1) is compliant with the IEEE Std 1003.1-2017 -(\[lq]POSIX.1-2017\[rq]) specification at +bc(1) is compliant with the IEEE Std 1003.1\-2017 +(\[lq]POSIX.1\-2017\[rq]) specification at https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html . -The flags \f[B]-efghiqsvVw\f[R], all long options, and the extensions +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]. @@ -2844,10 +2939,13 @@ the value of \f[B]LC_NUMERIC\f[R]. This bc(1) supports error messages for different locales, and thus, it supports \f[B]LC_MESSAGES\f[R]. .SH BUGS +Before version \f[B]6.1.0\f[R], this bc(1) had incorrect behavior for +the \f[B]quit\f[R] statement. .PP -None are known. -Report bugs at https://git.yzena.com/gavin/bc. +No other bugs are known. +Report bugs at https://git.gavinhoward.com/gavin/bc . .SH AUTHORS -.PP -Gavin D. -Howard <gavin@yzena.com> and contributors. +Gavin D. Howard \c +.MT gavin@gavinhoward.com +.ME \c +\ and contributors. diff --git a/contrib/bc/manuals/bc/A.1.md b/contrib/bc/manuals/bc/A.1.md index 6061260ee087..e89305b1af44 100644 --- a/contrib/bc/manuals/bc/A.1.md +++ b/contrib/bc/manuals/bc/A.1.md @@ -2,7 +2,7 @@ SPDX-License-Identifier: BSD-2-Clause -Copyright (c) 2018-2021 Gavin D. Howard and contributors. +Copyright (c) 2018-2024 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**. @@ -268,80 +372,12 @@ The following are the options that bc(1) accepts. : Makes bc(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)**, + 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**. -**-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**. - -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**. +letters are equal to **9** plus their position in the alphabet, starting from +**1** (i.e., **A** equals **10**, or **9+1**). + +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 @@ -742,6 +811,9 @@ The operators will be described in more detail below. : The **boolean not** operator returns **1** if the expression is **0**, or **0** otherwise. + **Warning**: This operator has a **different precedence** than the + equivalent operator in GNU bc(1) and other bc(1) implementations! + This is a **non-portable extension**. **\$** @@ -849,10 +921,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 +987,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.) @@ -987,7 +1071,7 @@ like any other expression that is printed. ## Stream Statement -The "expressions in a **stream** statement may also be strings. +The expressions in a **stream** statement may also be strings. If a **stream** statement is given a string, it prints the string as though the string had appeared as its own statement. In other words, the **stream** @@ -1099,9 +1183,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 +1232,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**. @@ -1180,6 +1262,14 @@ The extended library is a **non-portable extension**. : Returns the factorial of the truncated absolute value of **x**. +**max(a, b)** + +: Returns **a** if **a** is greater than **b**; otherwise, returns **b**. + +**min(a, b)** + +: Returns **a** if **a** is less than **b**; otherwise, returns **b**. + **perm(n, k)** : Returns the permutation of the truncated absolute value of **n** of the @@ -1190,6 +1280,10 @@ The extended library is a **non-portable extension**. : Returns the combination of the truncated absolute value of **n** of the truncated absolute value of **k**, if **k \<= n**. If not, it returns **0**. +**fib(n)** + +: Returns the Fibonacci number of the truncated absolute value of **n**. + **l2(x)** : Returns the logarithm base **2** of **x**. @@ -1352,7 +1446,15 @@ The extended library is a **non-portable extension**. digits after the decimal point equal to the truncated absolute value of **p**. If the absolute value of **i** is greater than or equal to **2**, and **p** is not **0**, then calling this function will change the value of - **seed**; otherwise, **0** is returned and **seed** is not changed. + **seed**; otherwise, **0** is returned, and **seed** is not changed. + +**i2rand(a, b)** + +: Takes the truncated value of **a** and **b** and uses them as inclusive + bounds to enerate a pseudo-random integer. If the difference of the + truncated values of **a** and **b** is **0**, then the truncated value is + returned, and **seed** is *not* changed. Otherwise, this function will + change the value of **seed**. **srand(x)** @@ -1414,7 +1516,7 @@ The extended library is a **non-portable extension**. **bnot8(x)** : Does a bitwise not of the truncated absolute value of **x** as though it has - **8** binary digits (1 unsigned byte). + **8** binary digits (**1** unsigned byte). If you want to a use signed two's complement argument, use **s2u(x)** to convert. @@ -1422,7 +1524,7 @@ The extended library is a **non-portable extension**. **bnot16(x)** : Does a bitwise not of the truncated absolute value of **x** as though it has - **16** binary digits (2 unsigned bytes). + **16** binary digits (**2** unsigned bytes). If you want to a use signed two's complement argument, use **s2u(x)** to convert. @@ -1430,7 +1532,7 @@ The extended library is a **non-portable extension**. **bnot32(x)** : Does a bitwise not of the truncated absolute value of **x** as though it has - **32** binary digits (4 unsigned bytes). + **32** binary digits (**4** unsigned bytes). If you want to a use signed two's complement argument, use **s2u(x)** to convert. @@ -1438,7 +1540,7 @@ The extended library is a **non-portable extension**. **bnot64(x)** : Does a bitwise not of the truncated absolute value of **x** as though it has - **64** binary digits (8 unsigned bytes). + **64** binary digits (**8** unsigned bytes). If you want to a use signed two's complement argument, use **s2u(x)** to convert. @@ -1462,7 +1564,7 @@ The extended library is a **non-portable extension**. **brev8(x)** : Runs a bit reversal on the truncated absolute value of **x** as though it - has 8 binary digits (1 unsigned byte). + has 8 binary digits (**1** unsigned byte). If you want to a use signed two's complement argument, use **s2u(x)** to convert. @@ -1470,7 +1572,7 @@ The extended library is a **non-portable extension**. **brev16(x)** : Runs a bit reversal on the truncated absolute value of **x** as though it - has 16 binary digits (2 unsigned bytes). + has 16 binary digits (**2** unsigned bytes). If you want to a use signed two's complement argument, use **s2u(x)** to convert. @@ -1478,7 +1580,7 @@ The extended library is a **non-portable extension**. **brev32(x)** : Runs a bit reversal on the truncated absolute value of **x** as though it - has 32 binary digits (4 unsigned bytes). + has 32 binary digits (**4** unsigned bytes). If you want to a use signed two's complement argument, use **s2u(x)** to convert. @@ -1486,7 +1588,7 @@ The extended library is a **non-portable extension**. **brev64(x)** : Runs a bit reversal on the truncated absolute value of **x** as though it - has 64 binary digits (8 unsigned bytes). + has 64 binary digits (**8** unsigned bytes). If you want to a use signed two's complement argument, use **s2u(x)** to convert. @@ -1533,7 +1635,7 @@ The extended library is a **non-portable extension**. **brol32(x, p)** : Does a left bitwise rotatation of the truncated absolute value of **x**, as - though it has **32** binary digits (**2** unsigned bytes), by the number of + though it has **32** binary digits (**4** unsigned bytes), by the number of places equal to the truncated absolute value of **p** modded by **2** to the power of **32**. @@ -1543,7 +1645,7 @@ The extended library is a **non-portable extension**. **brol64(x, p)** : Does a left bitwise rotatation of the truncated absolute value of **x**, as - though it has **64** binary digits (**2** unsigned bytes), by the number of + though it has **64** binary digits (**8** unsigned bytes), by the number of places equal to the truncated absolute value of **p** modded by **2** to the power of **64**. @@ -2085,7 +2187,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 +2294,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 +2384,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 +2413,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 +2505,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,8 +2518,11 @@ 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.gavinhoward.com/gavin/bc . # AUTHORS -Gavin D. Howard <gavin@yzena.com> and contributors. +Gavin D. Howard <gavin@gavinhoward.com> and contributors. diff --git a/contrib/bc/manuals/bc/E.1 b/contrib/bc/manuals/bc/E.1 index d57b8b50c4af..e2f1b034e69a 100644 --- a/contrib/bc/manuals/bc/E.1 +++ b/contrib/bc/manuals/bc/E.1 @@ -1,7 +1,7 @@ .\" .\" SPDX-License-Identifier: BSD-2-Clause .\" -.\" Copyright (c) 2018-2021 Gavin D. Howard and contributors. +.\" Copyright (c) 2018-2024 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,55 +25,139 @@ .\" 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" "August 2024" "Gavin D. Howard" "General Commands Manual" .nh .ad l .SH NAME -.PP -bc - arbitrary-precision decimal arithmetic language and calculator +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]--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]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]\&...] .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. +somewhat C\-like, but there are differences. Such differences will be noted in this document. .PP After parsing and handling options, this bc(1) reads any files given on 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 +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 bc(1) reserves as a keyword is used as the name of a function, variable, or array. -To fix that, use the command-line option \f[B]-r\f[R] \f[I]keyword\f[R], -where \f[I]keyword\f[R] is the keyword that is used as a name in the -script. +To fix that, use the command\-line option \f[B]\-r\f[R] +\f[I]keyword\f[R], where \f[I]keyword\f[R] is the keyword that is used +as a name in the script. For more information, see the \f[B]OPTIONS\f[R] section. .PP If parsing scripts meant for other bc(1) implementations still does not work, that is a bug and should be reported. See the \f[B]BUGS\f[R] section. .SH OPTIONS -.PP The following are the options that bc(1) accepts. .TP -\f[B]-g\f[R], \f[B]--global-stacks\f[R] +\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. .RS @@ -86,19 +170,16 @@ without worrying that the change will affect other functions. Thus, a hypothetical function named \f[B]output(x,b)\f[R] that simply printed \f[B]x\f[R] in base \f[B]b\f[R] could be written like this: .IP -.nf -\f[C] +.EX define void output(x, b) { obase=b x } -\f[R] -.fi +.EE .PP instead of like this: .IP -.nf -\f[C] +.EX define void output(x, b) { auto c c=obase @@ -106,8 +187,7 @@ define void output(x, b) { x obase=c } -\f[R] -.fi +.EE .PP This makes writing functions much easier. .PP @@ -121,12 +201,10 @@ converter, it is possible to replace that capability with various shell aliases. Examples: .IP -.nf -\f[C] -alias d2o=\[dq]bc -e ibase=A -e obase=8\[dq] -alias h2b=\[dq]bc -e ibase=G -e obase=2\[dq] -\f[R] -.fi +.EX +alias d2o=\[dq]bc \-e ibase=A \-e obase=8\[dq] +alias h2b=\[dq]bc \-e ibase=G \-e obase=2\[dq] +.EE .PP Second, if the purpose of a function is to set \f[B]ibase\f[R], \f[B]obase\f[R], or \f[B]scale\f[R] globally for any other purpose, it @@ -139,34 +217,45 @@ users could make sure to define \f[B]BC_ENV_ARGS\f[R] and include this option (see the \f[B]ENVIRONMENT VARIABLES\f[R] section for more details). .PP -If \f[B]-s\f[R], \f[B]-w\f[R], or any equivalents are used, this option -is ignored. +If \f[B]\-s\f[R], \f[B]\-w\f[R], or any equivalents are used, this +option is ignored. .PP -This is a \f[B]non-portable extension\f[R]. +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. +\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. +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] +\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]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-L\f[R], \f[B]--no-line-length\f[R] +\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]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-l\f[R], \f[B]--mathlib\f[R] +\f[B]\-l\f[R], \f[B]\-\-mathlib\f[R] Sets \f[B]scale\f[R] (see the \f[B]SYNTAX\f[R] section) to \f[B]20\f[R] and loads the included math library before running any code, including any expressions or files specified on the command line. @@ -175,11 +264,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]-P\f[R], \f[B]--no-prompt\f[R] +\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 @@ -187,14 +288,31 @@ Most of those users would want to put this option in These options override the \f[B]BC_PROMPT\f[R] and \f[B]BC_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]. +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] +\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 @@ -202,16 +320,16 @@ 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]read()\f[R] built-in function is called. +is only used when the \f[B]read()\f[R] built\-in function is called. .PP These options \f[I]do\f[R] override the \f[B]BC_PROMPT\f[R] and \f[B]BC_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]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-r\f[R] \f[I]keyword\f[R], \f[B]--redefine\f[R]=\f[I]keyword\f[R] +\f[B]\-r\f[R] \f[I]keyword\f[R], \f[B]\-\-redefine\f[R]=\f[I]keyword\f[R] Redefines \f[I]keyword\f[R] in order to allow it to be used as a function, variable, or array name. This is useful when this bc(1) gives parse errors when parsing scripts @@ -259,146 +377,63 @@ 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 -This is a \f[B]non-portable extension\f[R]. +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. +\f[B]\-s\f[R], \f[B]\-\-standard\f[R] +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]. +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. +\f[B]\-v\f[R], \f[B]\-V\f[R], \f[B]\-\-version\f[R] +Print the version information (copyright header) and exits. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-w\f[R], \f[B]--warn\f[R] -Like \f[B]-s\f[R] and \f[B]--standard\f[R], except that warnings (and -not errors) are printed for non-standard extensions and execution +\f[B]\-w\f[R], \f[B]\-\-warn\f[R] +Like \f[B]\-s\f[R] and \f[B]\-\-standard\f[R], except that warnings (and +not errors) are printed for non\-standard extensions and execution continues normally. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-z\f[R], \f[B]--leading-zeroes\f[R] -Makes bc(1) print all numbers greater than \f[B]-1\f[R] and less than +\f[B]\-z\f[R], \f[B]\-\-leading\-zeroes\f[R] +Makes bc(1) print all numbers greater than \f[B]\-1\f[R] and less than \f[B]1\f[R], and not equal to \f[B]0\f[R], with a leading zero. .RS .PP This can be set for individual numbers with the \f[B]plz(x)\f[R], -plznl(x)**, \f[B]pnlz(x)\f[R], and \f[B]pnlznl(x)\f[R] functions in the -extended math library (see the \f[B]LIBRARY\f[R] section). -.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. +\f[B]plznl(x)\f[R], \f[B]pnlz(x)\f[R], and \f[B]pnlznl(x)\f[R] functions +in the extended math library (see the \f[B]LIBRARY\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +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]. +All long options are \f[B]non\-portable extensions\f[R]. .SH STDIN -.PP -If no files or expressions are given by the \f[B]-f\f[R], -\f[B]--file\f[R], \f[B]-e\f[R], or \f[B]--expression\f[R] options, then -bc(1) reads from \f[B]stdin\f[R]. +If no files or expressions are given by the \f[B]\-f\f[R], +\f[B]\-\-file\f[R], \f[B]\-e\f[R], or \f[B]\-\-expression\f[R] options, +then bc(1) reads from \f[B]stdin\f[R]. .PP However, there are a few caveats to this. .PP @@ -412,8 +447,7 @@ Second, after an \f[B]if\f[R] statement, bc(1) doesn\[cq]t know if an \f[B]else\f[R] statement will follow, so it will not execute until it knows there will not be an \f[B]else\f[R] statement. .SH STDOUT -.PP -Any non-error output is written to \f[B]stdout\f[R]. +Any non\-error output is written to \f[B]stdout\f[R]. In addition, if history (see the \f[B]HISTORY\f[R] section) and the prompt (see the \f[B]TTY MODE\f[R] section) are enabled, both are output to \f[B]stdout\f[R]. @@ -421,7 +455,7 @@ to \f[B]stdout\f[R]. \f[B]Note\f[R]: Unlike other bc(1) implementations, this bc(1) will issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot write to \f[B]stdout\f[R], so if \f[B]stdout\f[R] is closed, as in -\f[B]bc >&-\f[R], it will quit with an error. +\f[B]bc >&\-\f[R], it will quit with an error. This is done so that bc(1) can report problems when \f[B]stdout\f[R] is redirected to a file. .PP @@ -429,13 +463,12 @@ If there are scripts that depend on the behavior of other bc(1) implementations, it is recommended that those scripts be changed to redirect \f[B]stdout\f[R] to \f[B]/dev/null\f[R]. .SH STDERR -.PP Any error output is written to \f[B]stderr\f[R]. .PP \f[B]Note\f[R]: Unlike other bc(1) implementations, this bc(1) will issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot write to \f[B]stderr\f[R], so if \f[B]stderr\f[R] is closed, as in -\f[B]bc 2>&-\f[R], it will quit with an error. +\f[B]bc 2>&\-\f[R], it will quit with an error. This is done so that bc(1) can exit with an error code when \f[B]stderr\f[R] is redirected to a file. .PP @@ -443,12 +476,10 @@ If there are scripts that depend on the behavior of other bc(1) implementations, it is recommended that those scripts be changed to redirect \f[B]stderr\f[R] to \f[B]/dev/null\f[R]. .SH SYNTAX -.PP -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. +The syntax for bc(1) programs is mostly C\-like, with some differences. +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 @@ -456,32 +487,32 @@ In the sections below, \f[B]E\f[R] means expression, \f[B]S\f[R] means statement, and \f[B]I\f[R] means identifier. .PP Identifiers (\f[B]I\f[R]) start with a lowercase letter and can be -followed by any number (up to \f[B]BC_NAME_MAX-1\f[R]) of lowercase -letters (\f[B]a-z\f[R]), digits (\f[B]0-9\f[R]), and underscores +followed by any number (up to \f[B]BC_NAME_MAX\-1\f[R]) of lowercase +letters (\f[B]a\-z\f[R]), digits (\f[B]0\-9\f[R]), and underscores (\f[B]_\f[R]). -The regex is \f[B][a-z][a-z0-9_]*\f[R]. +The regex is \f[B][a\-z][a\-z0\-9_]*\f[R]. Identifiers with more than one character (letter) are a -\f[B]non-portable extension\f[R]. +\f[B]non\-portable extension\f[R]. .PP \f[B]ibase\f[R] is a global variable determining how to interpret constant numbers. It is the \[lq]input\[rq] base, or the number base used for interpreting input numbers. \f[B]ibase\f[R] is initially \f[B]10\f[R]. -If the \f[B]-s\f[R] (\f[B]--standard\f[R]) and \f[B]-w\f[R] -(\f[B]--warn\f[R]) flags were not given on the command line, the max +If the \f[B]\-s\f[R] (\f[B]\-\-standard\f[R]) and \f[B]\-w\f[R] +(\f[B]\-\-warn\f[R]) flags were not given on the command line, the max allowable value for \f[B]ibase\f[R] is \f[B]36\f[R]. Otherwise, it is \f[B]16\f[R]. The min allowable value for \f[B]ibase\f[R] is \f[B]2\f[R]. The max allowable value for \f[B]ibase\f[R] can be queried in bc(1) -programs with the \f[B]maxibase()\f[R] built-in function. +programs with the \f[B]maxibase()\f[R] built\-in function. .PP \f[B]obase\f[R] is a global variable determining how to output results. It is the \[lq]output\[rq] base, or the number base used for outputting numbers. \f[B]obase\f[R] is initially \f[B]10\f[R]. The max allowable value for \f[B]obase\f[R] is \f[B]BC_BASE_MAX\f[R] and -can be queried in bc(1) programs with the \f[B]maxobase()\f[R] built-in +can be queried in bc(1) programs with the \f[B]maxobase()\f[R] built\-in function. The min allowable value for \f[B]obase\f[R] is \f[B]2\f[R]. Values are output in the specified base. @@ -494,7 +525,7 @@ exceptions. \f[B]scale\f[R] cannot be negative. The max allowable value for \f[B]scale\f[R] is \f[B]BC_SCALE_MAX\f[R] and can be queried in bc(1) programs with the \f[B]maxscale()\f[R] -built-in function. +built\-in function. .PP bc(1) has both \f[I]global\f[R] variables and \f[I]local\f[R] variables. All \f[I]local\f[R] variables are local to the function; they are @@ -519,20 +550,18 @@ The value that is printed is also assigned to the special variable \f[B]last\f[R]. A single dot (\f[B].\f[R]) may also be used as a synonym for \f[B]last\f[R]. -These are \f[B]non-portable extensions\f[R]. +These are \f[B]non\-portable extensions\f[R]. .PP Either semicolons or newlines may separate statements. .SS Comments -.PP There are two kinds of comments: .IP "1." 3 Block comments are enclosed in \f[B]/*\f[R] and \f[B]*/\f[R]. .IP "2." 3 Line comments go from \f[B]#\f[R] until, and not including, the next newline. -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .SS Named Expressions -.PP The following are named expressions in bc(1): .IP "1." 3 Variables: \f[B]I\f[R] @@ -547,7 +576,7 @@ Array Elements: \f[B]I[E]\f[R] .IP "6." 3 \f[B]last\f[R] or a single dot (\f[B].\f[R]) .PP -Number 6 is a \f[B]non-portable extension\f[R]. +Number 6 is a \f[B]non\-portable extension\f[R]. .PP Variables and arrays do not interfere; users can have arrays named the same as variables. @@ -561,7 +590,6 @@ Named expressions are required as the operand of of \f[B]assignment\f[R] operators (see the \f[I]Operators\f[R] subsection). .SS Operands -.PP The following are valid operands in bc(1): .IP " 1." 4 Numbers (see the \f[I]Numbers\f[R] subsection below). @@ -571,108 +599,152 @@ Array indices (\f[B]I[E]\f[R]). \f[B](E)\f[R]: The value of \f[B]E\f[R] (used to change precedence). .IP " 4." 4 \f[B]sqrt(E)\f[R]: The square root of \f[B]E\f[R]. -\f[B]E\f[R] must be non-negative. +\f[B]E\f[R] must be non\-negative. .IP " 5." 4 \f[B]length(E)\f[R]: The number of significant decimal digits in \f[B]E\f[R]. Returns \f[B]1\f[R] for \f[B]0\f[R] with no decimal places. If given a string, the length of the string is returned. -Passing a string to \f[B]length(E)\f[R] is a \f[B]non-portable +Passing a string to \f[B]length(E)\f[R] is a \f[B]non\-portable extension\f[R]. .IP " 6." 4 \f[B]length(I[])\f[R]: The number of elements in the array \f[B]I\f[R]. -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .IP " 7." 4 \f[B]scale(E)\f[R]: The \f[I]scale\f[R] of \f[B]E\f[R]. .IP " 8." 4 \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]. +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. 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 +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 "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, -which must be non-zero. +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 +This is a \f[B]non\-portable extension\f[R]. +.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 +that number as a one\-character string. +This is a \f[B]non\-portable extension\f[R]. +.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[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). The \f[B]E\f[R] argument(s) may also be arrays of the form \f[B]I[]\f[R], which will automatically be turned into array references (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 +This is a \f[B]non\-portable extension\f[R]. +.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 +This is a \f[B]non\-portable extension\f[R]. +.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 +This is a \f[B]non\-portable extension\f[R]. +.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 +This is a \f[B]non\-portable extension\f[R]. +.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 +This is a \f[B]non\-portable extension\f[R]. +.IP "21." 4 \f[B]global_stacks()\f[R]: \f[B]0\f[R] if global stacks are not enabled -with the \f[B]-g\f[R] or \f[B]--global-stacks\f[R] options, non-zero -otherwise. +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 +This is a \f[B]non\-portable extension\f[R]. +.IP "22." 4 \f[B]leading_zero()\f[R]: \f[B]0\f[R] if leading zeroes are not enabled -with the \f[B]-z\f[R] or \f[B]\[en]leading-zeroes\f[R] options, non-zero -otherwise. +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]. +This is a \f[B]non\-portable extension\f[R]. .SS Numbers -.PP 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]. -.SS Operators +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 The following arithmetic and logical operators can be used. They are listed in order of decreasing precedence. Operators in the same group have the same precedence. .TP -\f[B]++\f[R] \f[B]--\f[R] +\f[B]++\f[R] \f[B]\-\-\f[R] Type: Prefix and Postfix .RS .PP @@ -681,7 +753,7 @@ Associativity: None Description: \f[B]increment\f[R], \f[B]decrement\f[R] .RE .TP -\f[B]-\f[R] \f[B]!\f[R] +\f[B]\-\f[R] \f[B]!\f[R] Type: Prefix .RS .PP @@ -708,7 +780,7 @@ Associativity: Left Description: \f[B]multiply\f[R], \f[B]divide\f[R], \f[B]modulus\f[R] .RE .TP -\f[B]+\f[R] \f[B]-\f[R] +\f[B]+\f[R] \f[B]\-\f[R] Type: Binary .RS .PP @@ -717,7 +789,7 @@ Associativity: Left Description: \f[B]add\f[R], \f[B]subtract\f[R] .RE .TP -\f[B]=\f[R] \f[B]+=\f[R] \f[B]-=\f[R] \f[B]*=\f[R] \f[B]/=\f[R] \f[B]%=\f[R] \f[B]\[ha]=\f[R] +\f[B]=\f[R] \f[B]+=\f[R] \f[B]\-=\f[R] \f[B]*=\f[R] \f[B]/=\f[R] \f[B]%=\f[R] \f[B]\[ha]=\f[R] Type: Binary .RS .PP @@ -755,18 +827,18 @@ Description: \f[B]boolean or\f[R] .PP The operators will be described in more detail below. .TP -\f[B]++\f[R] \f[B]--\f[R] +\f[B]++\f[R] \f[B]\-\-\f[R] The prefix and postfix \f[B]increment\f[R] and \f[B]decrement\f[R] -operators behave exactly like they would in C. -They require a named expression (see the \f[I]Named Expressions\f[R] -subsection) as an operand. +operators behave exactly like they would in C. They require a named +expression (see the \f[I]Named Expressions\f[R] subsection) as an +operand. .RS .PP The prefix versions of these operators are more efficient; use them where possible. .RE .TP -\f[B]-\f[R] +\f[B]\-\f[R] The \f[B]negation\f[R] operator returns \f[B]0\f[R] if a user attempts to negate any expression with the value \f[B]0\f[R]. Otherwise, a copy of the expression with its sign flipped is returned. @@ -776,7 +848,11 @@ The \f[B]boolean not\f[R] operator returns \f[B]1\f[R] if the expression is \f[B]0\f[R], or \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +\f[B]Warning\f[R]: This operator has a \f[B]different precedence\f[R] +than the equivalent operator in GNU bc(1) and other bc(1) +implementations! +.PP +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]\[ha]\f[R] @@ -787,7 +863,7 @@ The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R]. .RS .PP The second expression must be an integer (no \f[I]scale\f[R]), and if it -is negative, the first value must be non-zero. +is negative, the first value must be non\-zero. .RE .TP \f[B]*\f[R] @@ -805,18 +881,18 @@ returns the quotient. The \f[I]scale\f[R] of the result shall be the value of \f[B]scale\f[R]. .RS .PP -The second expression must be non-zero. +The second expression must be non\-zero. .RE .TP \f[B]%\f[R] The \f[B]modulus\f[R] operator takes two expressions, \f[B]a\f[R] and \f[B]b\f[R], and evaluates them by 1) Computing \f[B]a/b\f[R] to current \f[B]scale\f[R] and 2) Using the result of step 1 to calculate -\f[B]a-(a/b)*b\f[R] to \f[I]scale\f[R] +\f[B]a\-(a/b)*b\f[R] to \f[I]scale\f[R] \f[B]max(scale+scale(b),scale(a))\f[R]. .RS .PP -The second expression must be non-zero. +The second expression must be non\-zero. .RE .TP \f[B]+\f[R] @@ -824,12 +900,12 @@ The \f[B]add\f[R] operator takes two expressions, \f[B]a\f[R] and \f[B]b\f[R], and returns the sum, with a \f[I]scale\f[R] equal to the max of the \f[I]scale\f[R]s of \f[B]a\f[R] and \f[B]b\f[R]. .TP -\f[B]-\f[R] +\f[B]\-\f[R] The \f[B]subtract\f[R] operator takes two expressions, \f[B]a\f[R] and \f[B]b\f[R], and returns the difference, with a \f[I]scale\f[R] equal to the max of the \f[I]scale\f[R]s of \f[B]a\f[R] and \f[B]b\f[R]. .TP -\f[B]=\f[R] \f[B]+=\f[R] \f[B]-=\f[R] \f[B]*=\f[R] \f[B]/=\f[R] \f[B]%=\f[R] \f[B]\[ha]=\f[R] +\f[B]=\f[R] \f[B]+=\f[R] \f[B]\-=\f[R] \f[B]*=\f[R] \f[B]/=\f[R] \f[B]%=\f[R] \f[B]\[ha]=\f[R] The \f[B]assignment\f[R] operators take two expressions, \f[B]a\f[R] and \f[B]b\f[R] where \f[B]a\f[R] is a named expression (see the \f[I]Named Expressions\f[R] subsection). @@ -853,41 +929,39 @@ 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]. +This allowance is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]&&\f[R] The \f[B]boolean and\f[R] operator takes two expressions and returns -\f[B]1\f[R] if both expressions are non-zero, \f[B]0\f[R] otherwise. +\f[B]1\f[R] if both expressions are non\-zero, \f[B]0\f[R] otherwise. .RS .PP -This is \f[I]not\f[R] a short-circuit operator. +This is \f[I]not\f[R] a short\-circuit operator. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]||\f[R] The \f[B]boolean or\f[R] operator takes two expressions and returns -\f[B]1\f[R] if one of the expressions is non-zero, \f[B]0\f[R] +\f[B]1\f[R] if one of the expressions is non\-zero, \f[B]0\f[R] otherwise. .RS .PP -This is \f[I]not\f[R] a short-circuit operator. +This is \f[I]not\f[R] a short\-circuit operator. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .SS Statements -.PP 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 +987,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 @@ -926,10 +1002,10 @@ The \f[B]E\f[R] argument(s) may also be arrays of the form \f[B]FUNCTIONS\f[R] section) if the corresponding parameter in the function definition is an array reference. .PP -Numbers 4, 9, 11, 12, 14, 15, and 16 are \f[B]non-portable +Numbers 4, 9, 11, 12, 14, 15, and 16 are \f[B]non\-portable extensions\f[R]. .PP -Also, as a \f[B]non-portable extension\f[R], any or all of the +Also, as a \f[B]non\-portable extension\f[R], any or all of the expressions in the header of a for loop may be omitted. If the condition (second expression) is omitted, it is assumed to be a constant \f[B]1\f[R]. @@ -946,7 +1022,24 @@ This is only allowed in loops. The \f[B]if\f[R] \f[B]else\f[R] statement does the same thing as in C. .PP 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). +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 +.EX +for (i = 0; i < 3; ++i) i; quit +.EE +.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 @@ -954,12 +1047,11 @@ that is not executed, bc(1) does not quit.) .PP The \f[B]limits\f[R] statement prints the limits that this bc(1) is subject to. -This is like the \f[B]quit\f[R] statement in that it is a compile-time +This is like the \f[B]quit\f[R] statement in that it is a compile\-time command. .PP An expression by itself is evaluated and printed, followed by a newline. .SS Strings -.PP If strings appear as a statement by themselves, they are printed without a trailing newline. .PP @@ -976,9 +1068,8 @@ element that has been assigned a string, an error is raised, and bc(1) resets (see the \f[B]RESET\f[R] section). .PP Assigning strings to variables and array elements and passing them to -functions are \f[B]non-portable extensions\f[R]. +functions are \f[B]non\-portable extensions\f[R]. .SS Print Statement -.PP The \[lq]expressions\[rq] in a \f[B]print\f[R] statement may also be strings. If they are, there are backslash escape sequences that are interpreted @@ -1005,14 +1096,12 @@ below: \f[B]\[rs]t\f[R]: \f[B]\[rs]t\f[R] .PP Any other character following a backslash causes the backslash and -character to be printed as-is. +character to be printed as\-is. .PP -Any non-string expression in a print statement shall be assigned to +Any non\-string expression in a print statement shall be assigned to \f[B]last\f[R], like any other expression that is printed. .SS Stream Statement -.PP -The \[lq]expressions in a \f[B]stream\f[R] statement may also be -strings. +The expressions in a \f[B]stream\f[R] statement may also be strings. .PP If a \f[B]stream\f[R] statement is given a string, it prints the string as though the string had appeared as its own statement. @@ -1022,20 +1111,17 @@ without a newline. If a \f[B]stream\f[R] statement is given a number, a copy of it is truncated and its absolute value is calculated. The result is then printed as though \f[B]obase\f[R] is \f[B]256\f[R] -and each digit is interpreted as an 8-bit ASCII character, making it a +and each digit is interpreted as an 8\-bit ASCII character, making it a byte stream. .SS Order of Evaluation -.PP All expressions in a statment are evaluated left to right, except as necessary to maintain order of operations. This means, for example, assuming that \f[B]i\f[R] is equal to \f[B]0\f[R], in the expression .IP -.nf -\f[C] +.EX a[i++] = i++ -\f[R] -.fi +.EE .PP the first (or 0th) element of \f[B]a\f[R] is set to \f[B]1\f[R], and \f[B]i\f[R] is equal to \f[B]2\f[R] at the end of the expression. @@ -1044,28 +1130,23 @@ This includes function arguments. Thus, assuming \f[B]i\f[R] is equal to \f[B]0\f[R], this means that in the expression .IP -.nf -\f[C] +.EX x(i++, i++) -\f[R] -.fi +.EE .PP the first argument passed to \f[B]x()\f[R] is \f[B]0\f[R], and the second argument is \f[B]1\f[R], while \f[B]i\f[R] is equal to \f[B]2\f[R] before the function starts executing. .SH FUNCTIONS -.PP Function definitions are as follows: .IP -.nf -\f[C] +.EX define I(I,...,I){ auto I,...,I S;...;S return(E) } -\f[R] -.fi +.EE .PP Any \f[B]I\f[R] in the parameter list or \f[B]auto\f[R] list may be replaced with \f[B]I[]\f[R] to make a parameter or \f[B]auto\f[R] var an @@ -1076,10 +1157,10 @@ asterisk in the call; they must be called with just \f[B]I[]\f[R] like normal array parameters and will be automatically converted into references. .PP -As a \f[B]non-portable extension\f[R], the opening brace of a +As a \f[B]non\-portable extension\f[R], the opening brace of a \f[B]define\f[R] statement may appear on the next line. .PP -As a \f[B]non-portable extension\f[R], the return statement may also be +As a \f[B]non\-portable extension\f[R], the return statement may also be in one of the following forms: .IP "1." 3 \f[B]return\f[R] @@ -1093,18 +1174,15 @@ equivalent to \f[B]return (0)\f[R], unless the function is a \f[B]void\f[R] function (see the \f[I]Void Functions\f[R] subsection below). .SS Void Functions -.PP Functions can also be \f[B]void\f[R] functions, defined as follows: .IP -.nf -\f[C] +.EX define void I(I,...,I){ auto I,...,I S;...;S return } -\f[R] -.fi +.EE .PP They can only be used as standalone expressions, where such an expression would be printed alone, except in a print statement. @@ -1118,17 +1196,14 @@ possible to have variables, arrays, and functions named \f[B]void\f[R]. The word \[lq]void\[rq] is only treated specially right after the \f[B]define\f[R] keyword. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .SS Array References -.PP For any array in the parameter list, if the array is declared in the form .IP -.nf -\f[C] +.EX *I[] -\f[R] -.fi +.EE .PP it is a \f[B]reference\f[R]. Any changes to the array in the function are reflected, when the @@ -1136,16 +1211,13 @@ function returns, to the array that was passed in. .PP Other than this, all function arguments are passed by value. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .SH LIBRARY -.PP -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. +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. @@ -1196,7 +1268,6 @@ This is a transcendental function (see the \f[I]Transcendental Functions\f[R] subsection below). .RE .SS Transcendental Functions -.PP All transcendental functions can return slightly inaccurate results, up to 1 ULP (https://en.wikipedia.org/wiki/Unit_in_the_last_place). This is unavoidable, and the article at @@ -1224,8 +1295,7 @@ The transcendental functions in the standard math library are: .IP \[bu] 2 \f[B]j(x, n)\f[R] .SH RESET -.PP -When bc(1) encounters an error or a signal that it has a non-default +When bc(1) encounters an error or a signal that it has a non\-default handler for, it resets. This means that several things happen. .PP @@ -1245,7 +1315,6 @@ Note that this reset behavior is different from the GNU bc(1), which attempts to start executing the statement right after the one that caused an error. .SH PERFORMANCE -.PP Most bc(1) implementations use \f[B]char\f[R] types to calculate the value of \f[B]1\f[R] decimal digit at a time, but that can be slow. This bc(1) does something different. @@ -1268,7 +1337,6 @@ checking. This integer type depends on the value of \f[B]BC_LONG_BIT\f[R], but is always at least twice as large as the integer type used to store digits. .SH LIMITS -.PP The following are the limits on bc(1): .TP \f[B]BC_LONG_BIT\f[R] @@ -1298,24 +1366,24 @@ Set at \f[B]BC_BASE_POW\f[R]. .TP \f[B]BC_DIM_MAX\f[R] The maximum size of arrays. -Set at \f[B]SIZE_MAX-1\f[R]. +Set at \f[B]SIZE_MAX\-1\f[R]. .TP \f[B]BC_SCALE_MAX\f[R] The maximum \f[B]scale\f[R]. -Set at \f[B]BC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]BC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]BC_STRING_MAX\f[R] The maximum length of strings. -Set at \f[B]BC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]BC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]BC_NAME_MAX\f[R] The maximum length of identifiers. -Set at \f[B]BC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]BC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]BC_NUM_MAX\f[R] The maximum length of a number (in decimal digits), which includes digits after the decimal point. -Set at \f[B]BC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]BC_OVERFLOW_MAX\-1\f[R]. .TP Exponent The maximum allowable exponent (positive or negative). @@ -1323,28 +1391,28 @@ Set at \f[B]BC_OVERFLOW_MAX\f[R]. .TP Number of vars The maximum number of vars/arrays. -Set at \f[B]SIZE_MAX-1\f[R]. +Set at \f[B]SIZE_MAX\-1\f[R]. .PP The actual values can be queried with the \f[B]limits\f[R] statement. .PP -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. +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 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 -the \f[B]-s\f[R] option was given. +the \f[B]\-s\f[R] option was given. .TP \f[B]BC_ENV_ARGS\f[R] -This is another way to give command-line arguments to bc(1). -They should be in the same format as all other command-line arguments. +This is another way to give command\-line arguments to bc(1). +They should be in the same format as all other command\-line arguments. These are always processed first, so any files given in \f[B]BC_ENV_ARGS\f[R] will be processed before arguments and files given -on the command-line. +on the command\-line. This gives the user the ability to set up \[lq]standard\[rq] options and files to be used at every invocation. The most useful thing for such files to contain would be useful @@ -1365,14 +1433,14 @@ you can use double quotes as the outside quotes, as in \f[B]\[lq]some quotes. However, handling a file with both kinds of quotes in \f[B]BC_ENV_ARGS\f[R] is not supported due to the complexity of the -parsing, though such files are still supported on the command-line where -the parsing is done by the shell. +parsing, though such files are still supported on the command\-line +where the parsing is done by the shell. .RE .TP \f[B]BC_LINE_LENGTH\f[R] If this environment variable exists and contains an integer that is greater than \f[B]1\f[R] and is less than \f[B]UINT16_MAX\f[R] -(\f[B]2\[ha]16-1\f[R]), bc(1) will output lines to that length, +(\f[B]2\[ha]16\-1\f[R]), bc(1) will output lines to that length, including the backslash (\f[B]\[rs]\f[R]). The default line length is \f[B]70\f[R]. .RS @@ -1384,7 +1452,7 @@ newlines. .TP \f[B]BC_BANNER\f[R] If this environment variable exists and contains an integer, then a -non-zero value activates the copyright banner when bc(1) is in +non\-zero value activates the copyright banner when bc(1) is in interactive mode, while zero deactivates it. .RS .PP @@ -1393,7 +1461,7 @@ section), then this environment variable has no effect because bc(1) does not print the banner when not in interactive mode. .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. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]BC_SIGINT_RESET\f[R] @@ -1403,13 +1471,13 @@ exits on \f[B]SIGINT\f[R] when not in interactive mode. .RS .PP However, when bc(1) is in interactive mode, then if this environment -variable exists and contains an integer, a non-zero value makes bc(1) +variable exists and contains an integer, a non\-zero value makes bc(1) reset on \f[B]SIGINT\f[R], rather than exit, and zero makes bc(1) exit. If this environment variable exists and is \f[I]not\f[R] an integer, then bc(1) will exit on \f[B]SIGINT\f[R]. .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. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]BC_TTY_MODE\f[R] @@ -1418,11 +1486,11 @@ section), then this environment variable has no effect. .RS .PP However, when TTY mode is available, then if this environment variable -exists and contains an integer, then a non-zero value makes bc(1) use +exists and contains an integer, then a non\-zero value makes bc(1) use TTY mode, and zero makes bc(1) not use TTY mode. .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. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]BC_PROMPT\f[R] @@ -1431,30 +1499,46 @@ section), then this environment variable has no effect. .RS .PP However, when TTY mode is available, then if this environment variable -exists and contains an integer, a non-zero value makes bc(1) use a -prompt, and zero or a non-integer makes bc(1) not use a prompt. +exists and contains an integer, a non\-zero value makes bc(1) use a +prompt, and zero or a non\-integer makes bc(1) not use a prompt. If this environment variable does not exist and \f[B]BC_TTY_MODE\f[R] does, then the value of the \f[B]BC_TTY_MODE\f[R] environment variable is used. .PP This environment variable and the \f[B]BC_TTY_MODE\f[R] environment variable override the default, which can be queried with the -\f[B]-h\f[R] or \f[B]--help\f[R] options. +\f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]BC_EXPR_EXIT\f[R] -If any expressions or expression files are given on the command-line -with \f[B]-e\f[R], \f[B]--expression\f[R], \f[B]-f\f[R], or -\f[B]--file\f[R], then if this environment variable exists and contains -an integer, a non-zero value makes bc(1) exit after executing the -expressions and expression files, and a zero value makes bc(1) not exit. +If any expressions or expression files are given on the command\-line +with \f[B]\-e\f[R], \f[B]\-\-expression\f[R], \f[B]\-f\f[R], or +\f[B]\-\-file\f[R], then if this environment variable exists and +contains an integer, a non\-zero value makes bc(1) exit after executing +the expressions and expression files, and a zero value makes bc(1) not +exit. .RS .PP This environment variable overrides the default, which can be queried -with the \f[B]-h\f[R] or \f[B]--help\f[R] options. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE -.SH EXIT STATUS +.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 bc(1) returns the following exit statuses: .TP \f[B]0\f[R] @@ -1470,7 +1554,7 @@ Math errors include divide by \f[B]0\f[R], taking the square root of a negative number, attempting to convert a negative number to a hardware integer, overflow when converting a number to a hardware integer, overflow when calculating the size of a number, and attempting to use a -non-integer where an integer is required. +non\-integer where an integer is required. .PP Converting to a hardware integer happens for the second operand of the power (\f[B]\[ha]\f[R]) operator and the corresponding assignment @@ -1491,7 +1575,7 @@ giving an invalid \f[B]auto\f[R] list, having a duplicate \f[B]auto\f[R]/function parameter, failing to find the end of a code block, attempting to return a value from a \f[B]void\f[R] function, attempting to use a variable as a reference, and using any extensions -when the option \f[B]-s\f[R] or any equivalents were given. +when the option \f[B]\-s\f[R] or any equivalents were given. .RE .TP \f[B]3\f[R] @@ -1514,7 +1598,7 @@ A fatal error occurred. Fatal errors include memory allocation errors, I/O errors, failing to open files, attempting to use files that do not have only ASCII characters (bc(1) only accepts ASCII characters), attempting to open a -directory as a file, and giving invalid command-line options. +directory as a file, and giving invalid command\-line options. .RE .PP The exit status \f[B]4\f[R] is special; when a fatal error occurs, bc(1) @@ -1525,19 +1609,18 @@ interactive mode (see the \f[B]INTERACTIVE MODE\f[R] section), since bc(1) resets its state (see the \f[B]RESET\f[R] section) and accepts more input when one of those errors occurs in interactive mode. This is also the case when interactive mode is forced by the -\f[B]-i\f[R] flag or \f[B]--interactive\f[R] option. +\f[B]\-i\f[R] flag or \f[B]\-\-interactive\f[R] option. .PP These exit statuses allow bc(1) to be used in shell scripting with error checking, and its normal behavior can be forced by using the -\f[B]-i\f[R] flag or \f[B]--interactive\f[R] option. +\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. +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. .PP In interactive mode, bc(1) attempts to recover from errors (see the \f[B]RESET\f[R] section), and in normal execution, flushes @@ -1546,7 +1629,6 @@ bc(1) may also reset on \f[B]SIGINT\f[R] instead of exit, depending on the contents of, or default for, the \f[B]BC_SIGINT_RESET\f[R] environment variable (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). .SH TTY MODE -.PP If \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all connected to a TTY, then \[lq]TTY mode\[rq] is considered to be available, and thus, bc(1) can turn on TTY mode, subject to some @@ -1554,53 +1636,49 @@ settings. .PP If there is the environment variable \f[B]BC_TTY_MODE\f[R] in the environment (see the \f[B]ENVIRONMENT VARIABLES\f[R] section), then if -that environment variable contains a non-zero integer, bc(1) will turn +that environment variable contains a non\-zero integer, bc(1) will turn on TTY mode when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all connected to a TTY. If the \f[B]BC_TTY_MODE\f[R] environment variable exists but is -\f[I]not\f[R] a non-zero integer, then bc(1) will not turn TTY mode on. +\f[I]not\f[R] a non\-zero integer, then bc(1) will not turn TTY mode on. .PP If the environment variable \f[B]BC_TTY_MODE\f[R] does \f[I]not\f[R] exist, the default setting is used. -The default setting can be queried with the \f[B]-h\f[R] or -\f[B]--help\f[R] options. +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 -.PP -Command-line history is only enabled if TTY mode is, i.e., that +.SS Command\-Line History +Command\-line history is only enabled if TTY mode is, i.e., that \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are connected to a TTY and the \f[B]BC_TTY_MODE\f[R] environment variable (see the \f[B]ENVIRONMENT VARIABLES\f[R] section) and its default do not disable TTY mode. See the \f[B]COMMAND LINE HISTORY\f[R] section for more information. .SS Prompt -.PP If TTY mode is available, then a prompt can be enabled. Like TTY mode itself, it can be turned on or off with an environment variable: \f[B]BC_PROMPT\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). .PP -If the environment variable \f[B]BC_PROMPT\f[R] exists and is a non-zero -integer, then the prompt is turned on when \f[B]stdin\f[R], +If the environment variable \f[B]BC_PROMPT\f[R] exists and is a +non\-zero integer, then the prompt is turned on when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are connected to a TTY and the -\f[B]-P\f[R] and \f[B]--no-prompt\f[R] options were not used. +\f[B]\-P\f[R] and \f[B]\-\-no\-prompt\f[R] options were not used. The read prompt will be turned on under the same conditions, except that -the \f[B]-R\f[R] and \f[B]--no-read-prompt\f[R] options must also not be -used. +the \f[B]\-R\f[R] and \f[B]\-\-no\-read\-prompt\f[R] options must also +not be used. .PP However, if \f[B]BC_PROMPT\f[R] does not exist, the prompt can be enabled or disabled with the \f[B]BC_TTY_MODE\f[R] environment variable, -the \f[B]-P\f[R] and \f[B]--no-prompt\f[R] options, and the \f[B]-R\f[R] -and \f[B]--no-read-prompt\f[R] options. +the \f[B]\-P\f[R] and \f[B]\-\-no\-prompt\f[R] options, and the +\f[B]\-R\f[R] and \f[B]\-\-no\-read\-prompt\f[R] options. See the \f[B]ENVIRONMENT VARIABLES\f[R] and \f[B]OPTIONS\f[R] sections for more details. .SH SIGNAL HANDLING -.PP Sending a \f[B]SIGINT\f[R] will cause bc(1) to do one of two things. .PP If bc(1) is not in interactive mode (see the \f[B]INTERACTIVE MODE\f[R] @@ -1609,7 +1687,7 @@ section), or the \f[B]BC_SIGINT_RESET\f[R] environment variable (see the an integer or it is zero, bc(1) will exit. .PP However, if bc(1) is in interactive mode, and the -\f[B]BC_SIGINT_RESET\f[R] or its default is an integer and non-zero, +\f[B]BC_SIGINT_RESET\f[R] or its default is an integer and non\-zero, then bc(1) will stop executing the current input and reset (see the \f[B]RESET\f[R] section) upon receiving a \f[B]SIGINT\f[R]. .PP @@ -1635,12 +1713,11 @@ The one exception is \f[B]SIGHUP\f[R]; in that case, and only when bc(1) is in TTY mode (see the \f[B]TTY MODE\f[R] section), a \f[B]SIGHUP\f[R] will cause bc(1) to clean up and exit. .SH COMMAND LINE HISTORY -.PP -bc(1) supports interactive command-line editing. +bc(1) supports interactive command\-line editing. .PP If bc(1) can be in TTY mode (see the \f[B]TTY MODE\f[R] section), history can be enabled. -This means that command-line history can only be enabled when +This means that command\-line history can only be enabled when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all connected to a TTY. .PP @@ -1653,20 +1730,23 @@ the arrow keys. .PP \f[B]Note\f[R]: tabs are converted to 8 spaces. .SH LOCALES -.PP This bc(1) ships with support for adding error messages for different locales and thus, supports \f[B]LC_MESSAGES\f[R]. .SH SEE ALSO -.PP dc(1) .SH STANDARDS -.PP -bc(1) is compliant with the IEEE Std 1003.1-2017 -(\[lq]POSIX.1-2017\[rq]) specification at +bc(1) is compliant with the IEEE Std 1003.1\-2017 +(\[lq]POSIX.1\-2017\[rq]) specification at https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html . -The flags \f[B]-efghiqsvVw\f[R], all long options, and the extensions +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]. @@ -1674,10 +1754,13 @@ the value of \f[B]LC_NUMERIC\f[R]. This bc(1) supports error messages for different locales, and thus, it supports \f[B]LC_MESSAGES\f[R]. .SH BUGS +Before version \f[B]6.1.0\f[R], this bc(1) had incorrect behavior for +the \f[B]quit\f[R] statement. .PP -None are known. -Report bugs at https://git.yzena.com/gavin/bc. +No other bugs are known. +Report bugs at https://git.gavinhoward.com/gavin/bc . .SH AUTHORS -.PP -Gavin D. -Howard <gavin@yzena.com> and contributors. +Gavin D. Howard \c +.MT gavin@gavinhoward.com +.ME \c +\ and contributors. diff --git a/contrib/bc/manuals/bc/E.1.md b/contrib/bc/manuals/bc/E.1.md index 6c562cf69d24..0082caea8408 100644 --- a/contrib/bc/manuals/bc/E.1.md +++ b/contrib/bc/manuals/bc/E.1.md @@ -2,7 +2,7 @@ SPDX-License-Identifier: BSD-2-Clause -Copyright (c) 2018-2021 Gavin D. Howard and contributors. +Copyright (c) 2018-2024 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**. @@ -248,71 +344,12 @@ The following are the options that bc(1) accepts. : Makes bc(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)**, + 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**. -**-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**. - -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**. +letters are equal to **9** plus their position in the alphabet, starting from +**1** (i.e., **A** equals **10**, or **9+1**). + +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 @@ -618,6 +688,9 @@ The operators will be described in more detail below. : The **boolean not** operator returns **1** if the expression is **0**, or **0** otherwise. + **Warning**: This operator has a **different precedence** than the + equivalent operator in GNU bc(1) and other bc(1) implementations! + This is a **non-portable extension**. **\^** @@ -683,10 +756,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 +822,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.) @@ -810,7 +895,7 @@ like any other expression that is printed. ## Stream Statement -The "expressions in a **stream** statement may also be strings. +The expressions in a **stream** statement may also be strings. If a **stream** statement is given a string, it prints the string as though the string had appeared as its own statement. In other words, the **stream** @@ -919,9 +1004,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 +1177,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 +1284,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 +1372,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 +1401,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 +1493,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,8 +1506,11 @@ 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.gavinhoward.com/gavin/bc . # AUTHORS -Gavin D. Howard <gavin@yzena.com> and contributors. +Gavin D. Howard <gavin@gavinhoward.com> and contributors. diff --git a/contrib/bc/manuals/bc/EH.1 b/contrib/bc/manuals/bc/EH.1 index 95b94ae90e8e..c132a0b76a49 100644 --- a/contrib/bc/manuals/bc/EH.1 +++ b/contrib/bc/manuals/bc/EH.1 @@ -1,7 +1,7 @@ .\" .\" SPDX-License-Identifier: BSD-2-Clause .\" -.\" Copyright (c) 2018-2021 Gavin D. Howard and contributors. +.\" Copyright (c) 2018-2024 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,55 +25,139 @@ .\" 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" "August 2024" "Gavin D. Howard" "General Commands Manual" .nh .ad l .SH NAME -.PP -bc - arbitrary-precision decimal arithmetic language and calculator +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]--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]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]\&...] .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. +somewhat C\-like, but there are differences. Such differences will be noted in this document. .PP After parsing and handling options, this bc(1) reads any files given on 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 +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 bc(1) reserves as a keyword is used as the name of a function, variable, or array. -To fix that, use the command-line option \f[B]-r\f[R] \f[I]keyword\f[R], -where \f[I]keyword\f[R] is the keyword that is used as a name in the -script. +To fix that, use the command\-line option \f[B]\-r\f[R] +\f[I]keyword\f[R], where \f[I]keyword\f[R] is the keyword that is used +as a name in the script. For more information, see the \f[B]OPTIONS\f[R] section. .PP If parsing scripts meant for other bc(1) implementations still does not work, that is a bug and should be reported. See the \f[B]BUGS\f[R] section. .SH OPTIONS -.PP The following are the options that bc(1) accepts. .TP -\f[B]-g\f[R], \f[B]--global-stacks\f[R] +\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. .RS @@ -86,19 +170,16 @@ without worrying that the change will affect other functions. Thus, a hypothetical function named \f[B]output(x,b)\f[R] that simply printed \f[B]x\f[R] in base \f[B]b\f[R] could be written like this: .IP -.nf -\f[C] +.EX define void output(x, b) { obase=b x } -\f[R] -.fi +.EE .PP instead of like this: .IP -.nf -\f[C] +.EX define void output(x, b) { auto c c=obase @@ -106,8 +187,7 @@ define void output(x, b) { x obase=c } -\f[R] -.fi +.EE .PP This makes writing functions much easier. .PP @@ -121,12 +201,10 @@ converter, it is possible to replace that capability with various shell aliases. Examples: .IP -.nf -\f[C] -alias d2o=\[dq]bc -e ibase=A -e obase=8\[dq] -alias h2b=\[dq]bc -e ibase=G -e obase=2\[dq] -\f[R] -.fi +.EX +alias d2o=\[dq]bc \-e ibase=A \-e obase=8\[dq] +alias h2b=\[dq]bc \-e ibase=G \-e obase=2\[dq] +.EE .PP Second, if the purpose of a function is to set \f[B]ibase\f[R], \f[B]obase\f[R], or \f[B]scale\f[R] globally for any other purpose, it @@ -139,34 +217,45 @@ users could make sure to define \f[B]BC_ENV_ARGS\f[R] and include this option (see the \f[B]ENVIRONMENT VARIABLES\f[R] section for more details). .PP -If \f[B]-s\f[R], \f[B]-w\f[R], or any equivalents are used, this option -is ignored. +If \f[B]\-s\f[R], \f[B]\-w\f[R], or any equivalents are used, this +option is ignored. .PP -This is a \f[B]non-portable extension\f[R]. +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. +\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. +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] +\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]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-L\f[R], \f[B]--no-line-length\f[R] +\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]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-l\f[R], \f[B]--mathlib\f[R] +\f[B]\-l\f[R], \f[B]\-\-mathlib\f[R] Sets \f[B]scale\f[R] (see the \f[B]SYNTAX\f[R] section) to \f[B]20\f[R] and loads the included math library before running any code, including any expressions or files specified on the command line. @@ -175,11 +264,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]-P\f[R], \f[B]--no-prompt\f[R] +\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 @@ -187,14 +288,31 @@ Most of those users would want to put this option in These options override the \f[B]BC_PROMPT\f[R] and \f[B]BC_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]. +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] +\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 @@ -202,16 +320,16 @@ 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]read()\f[R] built-in function is called. +is only used when the \f[B]read()\f[R] built\-in function is called. .PP These options \f[I]do\f[R] override the \f[B]BC_PROMPT\f[R] and \f[B]BC_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]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-r\f[R] \f[I]keyword\f[R], \f[B]--redefine\f[R]=\f[I]keyword\f[R] +\f[B]\-r\f[R] \f[I]keyword\f[R], \f[B]\-\-redefine\f[R]=\f[I]keyword\f[R] Redefines \f[I]keyword\f[R] in order to allow it to be used as a function, variable, or array name. This is useful when this bc(1) gives parse errors when parsing scripts @@ -259,146 +377,63 @@ 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 -This is a \f[B]non-portable extension\f[R]. +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. +\f[B]\-s\f[R], \f[B]\-\-standard\f[R] +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]. +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. +\f[B]\-v\f[R], \f[B]\-V\f[R], \f[B]\-\-version\f[R] +Print the version information (copyright header) and exits. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-w\f[R], \f[B]--warn\f[R] -Like \f[B]-s\f[R] and \f[B]--standard\f[R], except that warnings (and -not errors) are printed for non-standard extensions and execution +\f[B]\-w\f[R], \f[B]\-\-warn\f[R] +Like \f[B]\-s\f[R] and \f[B]\-\-standard\f[R], except that warnings (and +not errors) are printed for non\-standard extensions and execution continues normally. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-z\f[R], \f[B]--leading-zeroes\f[R] -Makes bc(1) print all numbers greater than \f[B]-1\f[R] and less than +\f[B]\-z\f[R], \f[B]\-\-leading\-zeroes\f[R] +Makes bc(1) print all numbers greater than \f[B]\-1\f[R] and less than \f[B]1\f[R], and not equal to \f[B]0\f[R], with a leading zero. .RS .PP This can be set for individual numbers with the \f[B]plz(x)\f[R], -plznl(x)**, \f[B]pnlz(x)\f[R], and \f[B]pnlznl(x)\f[R] functions in the -extended math library (see the \f[B]LIBRARY\f[R] section). +\f[B]plznl(x)\f[R], \f[B]pnlz(x)\f[R], and \f[B]pnlznl(x)\f[R] functions +in the extended math library (see the \f[B]LIBRARY\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +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]. +All long options are \f[B]non\-portable extensions\f[R]. .SH STDIN -.PP -If no files or expressions are given by the \f[B]-f\f[R], -\f[B]--file\f[R], \f[B]-e\f[R], or \f[B]--expression\f[R] options, then -bc(1) reads from \f[B]stdin\f[R]. +If no files or expressions are given by the \f[B]\-f\f[R], +\f[B]\-\-file\f[R], \f[B]\-e\f[R], or \f[B]\-\-expression\f[R] options, +then bc(1) reads from \f[B]stdin\f[R]. .PP However, there are a few caveats to this. .PP @@ -412,8 +447,7 @@ Second, after an \f[B]if\f[R] statement, bc(1) doesn\[cq]t know if an \f[B]else\f[R] statement will follow, so it will not execute until it knows there will not be an \f[B]else\f[R] statement. .SH STDOUT -.PP -Any non-error output is written to \f[B]stdout\f[R]. +Any non\-error output is written to \f[B]stdout\f[R]. In addition, if history (see the \f[B]HISTORY\f[R] section) and the prompt (see the \f[B]TTY MODE\f[R] section) are enabled, both are output to \f[B]stdout\f[R]. @@ -421,7 +455,7 @@ to \f[B]stdout\f[R]. \f[B]Note\f[R]: Unlike other bc(1) implementations, this bc(1) will issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot write to \f[B]stdout\f[R], so if \f[B]stdout\f[R] is closed, as in -\f[B]bc >&-\f[R], it will quit with an error. +\f[B]bc >&\-\f[R], it will quit with an error. This is done so that bc(1) can report problems when \f[B]stdout\f[R] is redirected to a file. .PP @@ -429,13 +463,12 @@ If there are scripts that depend on the behavior of other bc(1) implementations, it is recommended that those scripts be changed to redirect \f[B]stdout\f[R] to \f[B]/dev/null\f[R]. .SH STDERR -.PP Any error output is written to \f[B]stderr\f[R]. .PP \f[B]Note\f[R]: Unlike other bc(1) implementations, this bc(1) will issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot write to \f[B]stderr\f[R], so if \f[B]stderr\f[R] is closed, as in -\f[B]bc 2>&-\f[R], it will quit with an error. +\f[B]bc 2>&\-\f[R], it will quit with an error. This is done so that bc(1) can exit with an error code when \f[B]stderr\f[R] is redirected to a file. .PP @@ -443,12 +476,10 @@ If there are scripts that depend on the behavior of other bc(1) implementations, it is recommended that those scripts be changed to redirect \f[B]stderr\f[R] to \f[B]/dev/null\f[R]. .SH SYNTAX -.PP -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. +The syntax for bc(1) programs is mostly C\-like, with some differences. +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 @@ -456,32 +487,32 @@ In the sections below, \f[B]E\f[R] means expression, \f[B]S\f[R] means statement, and \f[B]I\f[R] means identifier. .PP Identifiers (\f[B]I\f[R]) start with a lowercase letter and can be -followed by any number (up to \f[B]BC_NAME_MAX-1\f[R]) of lowercase -letters (\f[B]a-z\f[R]), digits (\f[B]0-9\f[R]), and underscores +followed by any number (up to \f[B]BC_NAME_MAX\-1\f[R]) of lowercase +letters (\f[B]a\-z\f[R]), digits (\f[B]0\-9\f[R]), and underscores (\f[B]_\f[R]). -The regex is \f[B][a-z][a-z0-9_]*\f[R]. +The regex is \f[B][a\-z][a\-z0\-9_]*\f[R]. Identifiers with more than one character (letter) are a -\f[B]non-portable extension\f[R]. +\f[B]non\-portable extension\f[R]. .PP \f[B]ibase\f[R] is a global variable determining how to interpret constant numbers. It is the \[lq]input\[rq] base, or the number base used for interpreting input numbers. \f[B]ibase\f[R] is initially \f[B]10\f[R]. -If the \f[B]-s\f[R] (\f[B]--standard\f[R]) and \f[B]-w\f[R] -(\f[B]--warn\f[R]) flags were not given on the command line, the max +If the \f[B]\-s\f[R] (\f[B]\-\-standard\f[R]) and \f[B]\-w\f[R] +(\f[B]\-\-warn\f[R]) flags were not given on the command line, the max allowable value for \f[B]ibase\f[R] is \f[B]36\f[R]. Otherwise, it is \f[B]16\f[R]. The min allowable value for \f[B]ibase\f[R] is \f[B]2\f[R]. The max allowable value for \f[B]ibase\f[R] can be queried in bc(1) -programs with the \f[B]maxibase()\f[R] built-in function. +programs with the \f[B]maxibase()\f[R] built\-in function. .PP \f[B]obase\f[R] is a global variable determining how to output results. It is the \[lq]output\[rq] base, or the number base used for outputting numbers. \f[B]obase\f[R] is initially \f[B]10\f[R]. The max allowable value for \f[B]obase\f[R] is \f[B]BC_BASE_MAX\f[R] and -can be queried in bc(1) programs with the \f[B]maxobase()\f[R] built-in +can be queried in bc(1) programs with the \f[B]maxobase()\f[R] built\-in function. The min allowable value for \f[B]obase\f[R] is \f[B]2\f[R]. Values are output in the specified base. @@ -494,7 +525,7 @@ exceptions. \f[B]scale\f[R] cannot be negative. The max allowable value for \f[B]scale\f[R] is \f[B]BC_SCALE_MAX\f[R] and can be queried in bc(1) programs with the \f[B]maxscale()\f[R] -built-in function. +built\-in function. .PP bc(1) has both \f[I]global\f[R] variables and \f[I]local\f[R] variables. All \f[I]local\f[R] variables are local to the function; they are @@ -519,20 +550,18 @@ The value that is printed is also assigned to the special variable \f[B]last\f[R]. A single dot (\f[B].\f[R]) may also be used as a synonym for \f[B]last\f[R]. -These are \f[B]non-portable extensions\f[R]. +These are \f[B]non\-portable extensions\f[R]. .PP Either semicolons or newlines may separate statements. .SS Comments -.PP There are two kinds of comments: .IP "1." 3 Block comments are enclosed in \f[B]/*\f[R] and \f[B]*/\f[R]. .IP "2." 3 Line comments go from \f[B]#\f[R] until, and not including, the next newline. -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .SS Named Expressions -.PP The following are named expressions in bc(1): .IP "1." 3 Variables: \f[B]I\f[R] @@ -547,7 +576,7 @@ Array Elements: \f[B]I[E]\f[R] .IP "6." 3 \f[B]last\f[R] or a single dot (\f[B].\f[R]) .PP -Number 6 is a \f[B]non-portable extension\f[R]. +Number 6 is a \f[B]non\-portable extension\f[R]. .PP Variables and arrays do not interfere; users can have arrays named the same as variables. @@ -561,7 +590,6 @@ Named expressions are required as the operand of of \f[B]assignment\f[R] operators (see the \f[I]Operators\f[R] subsection). .SS Operands -.PP The following are valid operands in bc(1): .IP " 1." 4 Numbers (see the \f[I]Numbers\f[R] subsection below). @@ -571,108 +599,152 @@ Array indices (\f[B]I[E]\f[R]). \f[B](E)\f[R]: The value of \f[B]E\f[R] (used to change precedence). .IP " 4." 4 \f[B]sqrt(E)\f[R]: The square root of \f[B]E\f[R]. -\f[B]E\f[R] must be non-negative. +\f[B]E\f[R] must be non\-negative. .IP " 5." 4 \f[B]length(E)\f[R]: The number of significant decimal digits in \f[B]E\f[R]. Returns \f[B]1\f[R] for \f[B]0\f[R] with no decimal places. If given a string, the length of the string is returned. -Passing a string to \f[B]length(E)\f[R] is a \f[B]non-portable +Passing a string to \f[B]length(E)\f[R] is a \f[B]non\-portable extension\f[R]. .IP " 6." 4 \f[B]length(I[])\f[R]: The number of elements in the array \f[B]I\f[R]. -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .IP " 7." 4 \f[B]scale(E)\f[R]: The \f[I]scale\f[R] of \f[B]E\f[R]. .IP " 8." 4 \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]. +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. 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 +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 "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, -which must be non-zero. +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 +This is a \f[B]non\-portable extension\f[R]. +.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 +that number as a one\-character string. +This is a \f[B]non\-portable extension\f[R]. +.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[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). The \f[B]E\f[R] argument(s) may also be arrays of the form \f[B]I[]\f[R], which will automatically be turned into array references (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 +This is a \f[B]non\-portable extension\f[R]. +.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 +This is a \f[B]non\-portable extension\f[R]. +.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 +This is a \f[B]non\-portable extension\f[R]. +.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 +This is a \f[B]non\-portable extension\f[R]. +.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 +This is a \f[B]non\-portable extension\f[R]. +.IP "21." 4 \f[B]global_stacks()\f[R]: \f[B]0\f[R] if global stacks are not enabled -with the \f[B]-g\f[R] or \f[B]--global-stacks\f[R] options, non-zero -otherwise. +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 +This is a \f[B]non\-portable extension\f[R]. +.IP "22." 4 \f[B]leading_zero()\f[R]: \f[B]0\f[R] if leading zeroes are not enabled -with the \f[B]-z\f[R] or \f[B]\[en]leading-zeroes\f[R] options, non-zero -otherwise. +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]. +This is a \f[B]non\-portable extension\f[R]. .SS Numbers -.PP 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]. -.SS Operators +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 The following arithmetic and logical operators can be used. They are listed in order of decreasing precedence. Operators in the same group have the same precedence. .TP -\f[B]++\f[R] \f[B]--\f[R] +\f[B]++\f[R] \f[B]\-\-\f[R] Type: Prefix and Postfix .RS .PP @@ -681,7 +753,7 @@ Associativity: None Description: \f[B]increment\f[R], \f[B]decrement\f[R] .RE .TP -\f[B]-\f[R] \f[B]!\f[R] +\f[B]\-\f[R] \f[B]!\f[R] Type: Prefix .RS .PP @@ -708,7 +780,7 @@ Associativity: Left Description: \f[B]multiply\f[R], \f[B]divide\f[R], \f[B]modulus\f[R] .RE .TP -\f[B]+\f[R] \f[B]-\f[R] +\f[B]+\f[R] \f[B]\-\f[R] Type: Binary .RS .PP @@ -717,7 +789,7 @@ Associativity: Left Description: \f[B]add\f[R], \f[B]subtract\f[R] .RE .TP -\f[B]=\f[R] \f[B]+=\f[R] \f[B]-=\f[R] \f[B]*=\f[R] \f[B]/=\f[R] \f[B]%=\f[R] \f[B]\[ha]=\f[R] +\f[B]=\f[R] \f[B]+=\f[R] \f[B]\-=\f[R] \f[B]*=\f[R] \f[B]/=\f[R] \f[B]%=\f[R] \f[B]\[ha]=\f[R] Type: Binary .RS .PP @@ -755,18 +827,18 @@ Description: \f[B]boolean or\f[R] .PP The operators will be described in more detail below. .TP -\f[B]++\f[R] \f[B]--\f[R] +\f[B]++\f[R] \f[B]\-\-\f[R] The prefix and postfix \f[B]increment\f[R] and \f[B]decrement\f[R] -operators behave exactly like they would in C. -They require a named expression (see the \f[I]Named Expressions\f[R] -subsection) as an operand. +operators behave exactly like they would in C. They require a named +expression (see the \f[I]Named Expressions\f[R] subsection) as an +operand. .RS .PP The prefix versions of these operators are more efficient; use them where possible. .RE .TP -\f[B]-\f[R] +\f[B]\-\f[R] The \f[B]negation\f[R] operator returns \f[B]0\f[R] if a user attempts to negate any expression with the value \f[B]0\f[R]. Otherwise, a copy of the expression with its sign flipped is returned. @@ -776,7 +848,11 @@ The \f[B]boolean not\f[R] operator returns \f[B]1\f[R] if the expression is \f[B]0\f[R], or \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +\f[B]Warning\f[R]: This operator has a \f[B]different precedence\f[R] +than the equivalent operator in GNU bc(1) and other bc(1) +implementations! +.PP +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]\[ha]\f[R] @@ -787,7 +863,7 @@ The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R]. .RS .PP The second expression must be an integer (no \f[I]scale\f[R]), and if it -is negative, the first value must be non-zero. +is negative, the first value must be non\-zero. .RE .TP \f[B]*\f[R] @@ -805,18 +881,18 @@ returns the quotient. The \f[I]scale\f[R] of the result shall be the value of \f[B]scale\f[R]. .RS .PP -The second expression must be non-zero. +The second expression must be non\-zero. .RE .TP \f[B]%\f[R] The \f[B]modulus\f[R] operator takes two expressions, \f[B]a\f[R] and \f[B]b\f[R], and evaluates them by 1) Computing \f[B]a/b\f[R] to current \f[B]scale\f[R] and 2) Using the result of step 1 to calculate -\f[B]a-(a/b)*b\f[R] to \f[I]scale\f[R] +\f[B]a\-(a/b)*b\f[R] to \f[I]scale\f[R] \f[B]max(scale+scale(b),scale(a))\f[R]. .RS .PP -The second expression must be non-zero. +The second expression must be non\-zero. .RE .TP \f[B]+\f[R] @@ -824,12 +900,12 @@ The \f[B]add\f[R] operator takes two expressions, \f[B]a\f[R] and \f[B]b\f[R], and returns the sum, with a \f[I]scale\f[R] equal to the max of the \f[I]scale\f[R]s of \f[B]a\f[R] and \f[B]b\f[R]. .TP -\f[B]-\f[R] +\f[B]\-\f[R] The \f[B]subtract\f[R] operator takes two expressions, \f[B]a\f[R] and \f[B]b\f[R], and returns the difference, with a \f[I]scale\f[R] equal to the max of the \f[I]scale\f[R]s of \f[B]a\f[R] and \f[B]b\f[R]. .TP -\f[B]=\f[R] \f[B]+=\f[R] \f[B]-=\f[R] \f[B]*=\f[R] \f[B]/=\f[R] \f[B]%=\f[R] \f[B]\[ha]=\f[R] +\f[B]=\f[R] \f[B]+=\f[R] \f[B]\-=\f[R] \f[B]*=\f[R] \f[B]/=\f[R] \f[B]%=\f[R] \f[B]\[ha]=\f[R] The \f[B]assignment\f[R] operators take two expressions, \f[B]a\f[R] and \f[B]b\f[R] where \f[B]a\f[R] is a named expression (see the \f[I]Named Expressions\f[R] subsection). @@ -853,41 +929,39 @@ 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]. +This allowance is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]&&\f[R] The \f[B]boolean and\f[R] operator takes two expressions and returns -\f[B]1\f[R] if both expressions are non-zero, \f[B]0\f[R] otherwise. +\f[B]1\f[R] if both expressions are non\-zero, \f[B]0\f[R] otherwise. .RS .PP -This is \f[I]not\f[R] a short-circuit operator. +This is \f[I]not\f[R] a short\-circuit operator. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]||\f[R] The \f[B]boolean or\f[R] operator takes two expressions and returns -\f[B]1\f[R] if one of the expressions is non-zero, \f[B]0\f[R] +\f[B]1\f[R] if one of the expressions is non\-zero, \f[B]0\f[R] otherwise. .RS .PP -This is \f[I]not\f[R] a short-circuit operator. +This is \f[I]not\f[R] a short\-circuit operator. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .SS Statements -.PP 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 +987,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 @@ -926,10 +1002,10 @@ The \f[B]E\f[R] argument(s) may also be arrays of the form \f[B]FUNCTIONS\f[R] section) if the corresponding parameter in the function definition is an array reference. .PP -Numbers 4, 9, 11, 12, 14, 15, and 16 are \f[B]non-portable +Numbers 4, 9, 11, 12, 14, 15, and 16 are \f[B]non\-portable extensions\f[R]. .PP -Also, as a \f[B]non-portable extension\f[R], any or all of the +Also, as a \f[B]non\-portable extension\f[R], any or all of the expressions in the header of a for loop may be omitted. If the condition (second expression) is omitted, it is assumed to be a constant \f[B]1\f[R]. @@ -946,7 +1022,24 @@ This is only allowed in loops. The \f[B]if\f[R] \f[B]else\f[R] statement does the same thing as in C. .PP 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). +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 +.EX +for (i = 0; i < 3; ++i) i; quit +.EE +.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 @@ -954,12 +1047,11 @@ that is not executed, bc(1) does not quit.) .PP The \f[B]limits\f[R] statement prints the limits that this bc(1) is subject to. -This is like the \f[B]quit\f[R] statement in that it is a compile-time +This is like the \f[B]quit\f[R] statement in that it is a compile\-time command. .PP An expression by itself is evaluated and printed, followed by a newline. .SS Strings -.PP If strings appear as a statement by themselves, they are printed without a trailing newline. .PP @@ -976,9 +1068,8 @@ element that has been assigned a string, an error is raised, and bc(1) resets (see the \f[B]RESET\f[R] section). .PP Assigning strings to variables and array elements and passing them to -functions are \f[B]non-portable extensions\f[R]. +functions are \f[B]non\-portable extensions\f[R]. .SS Print Statement -.PP The \[lq]expressions\[rq] in a \f[B]print\f[R] statement may also be strings. If they are, there are backslash escape sequences that are interpreted @@ -1005,14 +1096,12 @@ below: \f[B]\[rs]t\f[R]: \f[B]\[rs]t\f[R] .PP Any other character following a backslash causes the backslash and -character to be printed as-is. +character to be printed as\-is. .PP -Any non-string expression in a print statement shall be assigned to +Any non\-string expression in a print statement shall be assigned to \f[B]last\f[R], like any other expression that is printed. .SS Stream Statement -.PP -The \[lq]expressions in a \f[B]stream\f[R] statement may also be -strings. +The expressions in a \f[B]stream\f[R] statement may also be strings. .PP If a \f[B]stream\f[R] statement is given a string, it prints the string as though the string had appeared as its own statement. @@ -1022,20 +1111,17 @@ without a newline. If a \f[B]stream\f[R] statement is given a number, a copy of it is truncated and its absolute value is calculated. The result is then printed as though \f[B]obase\f[R] is \f[B]256\f[R] -and each digit is interpreted as an 8-bit ASCII character, making it a +and each digit is interpreted as an 8\-bit ASCII character, making it a byte stream. .SS Order of Evaluation -.PP All expressions in a statment are evaluated left to right, except as necessary to maintain order of operations. This means, for example, assuming that \f[B]i\f[R] is equal to \f[B]0\f[R], in the expression .IP -.nf -\f[C] +.EX a[i++] = i++ -\f[R] -.fi +.EE .PP the first (or 0th) element of \f[B]a\f[R] is set to \f[B]1\f[R], and \f[B]i\f[R] is equal to \f[B]2\f[R] at the end of the expression. @@ -1044,28 +1130,23 @@ This includes function arguments. Thus, assuming \f[B]i\f[R] is equal to \f[B]0\f[R], this means that in the expression .IP -.nf -\f[C] +.EX x(i++, i++) -\f[R] -.fi +.EE .PP the first argument passed to \f[B]x()\f[R] is \f[B]0\f[R], and the second argument is \f[B]1\f[R], while \f[B]i\f[R] is equal to \f[B]2\f[R] before the function starts executing. .SH FUNCTIONS -.PP Function definitions are as follows: .IP -.nf -\f[C] +.EX define I(I,...,I){ auto I,...,I S;...;S return(E) } -\f[R] -.fi +.EE .PP Any \f[B]I\f[R] in the parameter list or \f[B]auto\f[R] list may be replaced with \f[B]I[]\f[R] to make a parameter or \f[B]auto\f[R] var an @@ -1076,10 +1157,10 @@ asterisk in the call; they must be called with just \f[B]I[]\f[R] like normal array parameters and will be automatically converted into references. .PP -As a \f[B]non-portable extension\f[R], the opening brace of a +As a \f[B]non\-portable extension\f[R], the opening brace of a \f[B]define\f[R] statement may appear on the next line. .PP -As a \f[B]non-portable extension\f[R], the return statement may also be +As a \f[B]non\-portable extension\f[R], the return statement may also be in one of the following forms: .IP "1." 3 \f[B]return\f[R] @@ -1093,18 +1174,15 @@ equivalent to \f[B]return (0)\f[R], unless the function is a \f[B]void\f[R] function (see the \f[I]Void Functions\f[R] subsection below). .SS Void Functions -.PP Functions can also be \f[B]void\f[R] functions, defined as follows: .IP -.nf -\f[C] +.EX define void I(I,...,I){ auto I,...,I S;...;S return } -\f[R] -.fi +.EE .PP They can only be used as standalone expressions, where such an expression would be printed alone, except in a print statement. @@ -1118,17 +1196,14 @@ possible to have variables, arrays, and functions named \f[B]void\f[R]. The word \[lq]void\[rq] is only treated specially right after the \f[B]define\f[R] keyword. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .SS Array References -.PP For any array in the parameter list, if the array is declared in the form .IP -.nf -\f[C] +.EX *I[] -\f[R] -.fi +.EE .PP it is a \f[B]reference\f[R]. Any changes to the array in the function are reflected, when the @@ -1136,16 +1211,13 @@ function returns, to the array that was passed in. .PP Other than this, all function arguments are passed by value. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .SH LIBRARY -.PP -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. +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. @@ -1196,7 +1268,6 @@ This is a transcendental function (see the \f[I]Transcendental Functions\f[R] subsection below). .RE .SS Transcendental Functions -.PP All transcendental functions can return slightly inaccurate results, up to 1 ULP (https://en.wikipedia.org/wiki/Unit_in_the_last_place). This is unavoidable, and the article at @@ -1224,8 +1295,7 @@ The transcendental functions in the standard math library are: .IP \[bu] 2 \f[B]j(x, n)\f[R] .SH RESET -.PP -When bc(1) encounters an error or a signal that it has a non-default +When bc(1) encounters an error or a signal that it has a non\-default handler for, it resets. This means that several things happen. .PP @@ -1245,7 +1315,6 @@ Note that this reset behavior is different from the GNU bc(1), which attempts to start executing the statement right after the one that caused an error. .SH PERFORMANCE -.PP Most bc(1) implementations use \f[B]char\f[R] types to calculate the value of \f[B]1\f[R] decimal digit at a time, but that can be slow. This bc(1) does something different. @@ -1268,7 +1337,6 @@ checking. This integer type depends on the value of \f[B]BC_LONG_BIT\f[R], but is always at least twice as large as the integer type used to store digits. .SH LIMITS -.PP The following are the limits on bc(1): .TP \f[B]BC_LONG_BIT\f[R] @@ -1298,24 +1366,24 @@ Set at \f[B]BC_BASE_POW\f[R]. .TP \f[B]BC_DIM_MAX\f[R] The maximum size of arrays. -Set at \f[B]SIZE_MAX-1\f[R]. +Set at \f[B]SIZE_MAX\-1\f[R]. .TP \f[B]BC_SCALE_MAX\f[R] The maximum \f[B]scale\f[R]. -Set at \f[B]BC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]BC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]BC_STRING_MAX\f[R] The maximum length of strings. -Set at \f[B]BC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]BC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]BC_NAME_MAX\f[R] The maximum length of identifiers. -Set at \f[B]BC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]BC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]BC_NUM_MAX\f[R] The maximum length of a number (in decimal digits), which includes digits after the decimal point. -Set at \f[B]BC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]BC_OVERFLOW_MAX\-1\f[R]. .TP Exponent The maximum allowable exponent (positive or negative). @@ -1323,28 +1391,28 @@ Set at \f[B]BC_OVERFLOW_MAX\f[R]. .TP Number of vars The maximum number of vars/arrays. -Set at \f[B]SIZE_MAX-1\f[R]. +Set at \f[B]SIZE_MAX\-1\f[R]. .PP The actual values can be queried with the \f[B]limits\f[R] statement. .PP -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. +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 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 -the \f[B]-s\f[R] option was given. +the \f[B]\-s\f[R] option was given. .TP \f[B]BC_ENV_ARGS\f[R] -This is another way to give command-line arguments to bc(1). -They should be in the same format as all other command-line arguments. +This is another way to give command\-line arguments to bc(1). +They should be in the same format as all other command\-line arguments. These are always processed first, so any files given in \f[B]BC_ENV_ARGS\f[R] will be processed before arguments and files given -on the command-line. +on the command\-line. This gives the user the ability to set up \[lq]standard\[rq] options and files to be used at every invocation. The most useful thing for such files to contain would be useful @@ -1365,14 +1433,14 @@ you can use double quotes as the outside quotes, as in \f[B]\[lq]some quotes. However, handling a file with both kinds of quotes in \f[B]BC_ENV_ARGS\f[R] is not supported due to the complexity of the -parsing, though such files are still supported on the command-line where -the parsing is done by the shell. +parsing, though such files are still supported on the command\-line +where the parsing is done by the shell. .RE .TP \f[B]BC_LINE_LENGTH\f[R] If this environment variable exists and contains an integer that is greater than \f[B]1\f[R] and is less than \f[B]UINT16_MAX\f[R] -(\f[B]2\[ha]16-1\f[R]), bc(1) will output lines to that length, +(\f[B]2\[ha]16\-1\f[R]), bc(1) will output lines to that length, including the backslash (\f[B]\[rs]\f[R]). The default line length is \f[B]70\f[R]. .RS @@ -1384,7 +1452,7 @@ newlines. .TP \f[B]BC_BANNER\f[R] If this environment variable exists and contains an integer, then a -non-zero value activates the copyright banner when bc(1) is in +non\-zero value activates the copyright banner when bc(1) is in interactive mode, while zero deactivates it. .RS .PP @@ -1393,7 +1461,7 @@ section), then this environment variable has no effect because bc(1) does not print the banner when not in interactive mode. .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. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]BC_SIGINT_RESET\f[R] @@ -1403,13 +1471,13 @@ exits on \f[B]SIGINT\f[R] when not in interactive mode. .RS .PP However, when bc(1) is in interactive mode, then if this environment -variable exists and contains an integer, a non-zero value makes bc(1) +variable exists and contains an integer, a non\-zero value makes bc(1) reset on \f[B]SIGINT\f[R], rather than exit, and zero makes bc(1) exit. If this environment variable exists and is \f[I]not\f[R] an integer, then bc(1) will exit on \f[B]SIGINT\f[R]. .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. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]BC_TTY_MODE\f[R] @@ -1418,11 +1486,11 @@ section), then this environment variable has no effect. .RS .PP However, when TTY mode is available, then if this environment variable -exists and contains an integer, then a non-zero value makes bc(1) use +exists and contains an integer, then a non\-zero value makes bc(1) use TTY mode, and zero makes bc(1) not use TTY mode. .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. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]BC_PROMPT\f[R] @@ -1431,30 +1499,46 @@ section), then this environment variable has no effect. .RS .PP However, when TTY mode is available, then if this environment variable -exists and contains an integer, a non-zero value makes bc(1) use a -prompt, and zero or a non-integer makes bc(1) not use a prompt. +exists and contains an integer, a non\-zero value makes bc(1) use a +prompt, and zero or a non\-integer makes bc(1) not use a prompt. If this environment variable does not exist and \f[B]BC_TTY_MODE\f[R] does, then the value of the \f[B]BC_TTY_MODE\f[R] environment variable is used. .PP This environment variable and the \f[B]BC_TTY_MODE\f[R] environment variable override the default, which can be queried with the -\f[B]-h\f[R] or \f[B]--help\f[R] options. +\f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]BC_EXPR_EXIT\f[R] -If any expressions or expression files are given on the command-line -with \f[B]-e\f[R], \f[B]--expression\f[R], \f[B]-f\f[R], or -\f[B]--file\f[R], then if this environment variable exists and contains -an integer, a non-zero value makes bc(1) exit after executing the -expressions and expression files, and a zero value makes bc(1) not exit. +If any expressions or expression files are given on the command\-line +with \f[B]\-e\f[R], \f[B]\-\-expression\f[R], \f[B]\-f\f[R], or +\f[B]\-\-file\f[R], then if this environment variable exists and +contains an integer, a non\-zero value makes bc(1) exit after executing +the expressions and expression files, and a zero value makes bc(1) not +exit. .RS .PP This environment variable overrides the default, which can be queried -with the \f[B]-h\f[R] or \f[B]--help\f[R] options. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE -.SH EXIT STATUS +.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 bc(1) returns the following exit statuses: .TP \f[B]0\f[R] @@ -1470,7 +1554,7 @@ Math errors include divide by \f[B]0\f[R], taking the square root of a negative number, attempting to convert a negative number to a hardware integer, overflow when converting a number to a hardware integer, overflow when calculating the size of a number, and attempting to use a -non-integer where an integer is required. +non\-integer where an integer is required. .PP Converting to a hardware integer happens for the second operand of the power (\f[B]\[ha]\f[R]) operator and the corresponding assignment @@ -1491,7 +1575,7 @@ giving an invalid \f[B]auto\f[R] list, having a duplicate \f[B]auto\f[R]/function parameter, failing to find the end of a code block, attempting to return a value from a \f[B]void\f[R] function, attempting to use a variable as a reference, and using any extensions -when the option \f[B]-s\f[R] or any equivalents were given. +when the option \f[B]\-s\f[R] or any equivalents were given. .RE .TP \f[B]3\f[R] @@ -1514,7 +1598,7 @@ A fatal error occurred. Fatal errors include memory allocation errors, I/O errors, failing to open files, attempting to use files that do not have only ASCII characters (bc(1) only accepts ASCII characters), attempting to open a -directory as a file, and giving invalid command-line options. +directory as a file, and giving invalid command\-line options. .RE .PP The exit status \f[B]4\f[R] is special; when a fatal error occurs, bc(1) @@ -1525,19 +1609,18 @@ interactive mode (see the \f[B]INTERACTIVE MODE\f[R] section), since bc(1) resets its state (see the \f[B]RESET\f[R] section) and accepts more input when one of those errors occurs in interactive mode. This is also the case when interactive mode is forced by the -\f[B]-i\f[R] flag or \f[B]--interactive\f[R] option. +\f[B]\-i\f[R] flag or \f[B]\-\-interactive\f[R] option. .PP These exit statuses allow bc(1) to be used in shell scripting with error checking, and its normal behavior can be forced by using the -\f[B]-i\f[R] flag or \f[B]--interactive\f[R] option. +\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. +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. .PP In interactive mode, bc(1) attempts to recover from errors (see the \f[B]RESET\f[R] section), and in normal execution, flushes @@ -1546,7 +1629,6 @@ bc(1) may also reset on \f[B]SIGINT\f[R] instead of exit, depending on the contents of, or default for, the \f[B]BC_SIGINT_RESET\f[R] environment variable (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). .SH TTY MODE -.PP If \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all connected to a TTY, then \[lq]TTY mode\[rq] is considered to be available, and thus, bc(1) can turn on TTY mode, subject to some @@ -1554,45 +1636,42 @@ settings. .PP If there is the environment variable \f[B]BC_TTY_MODE\f[R] in the environment (see the \f[B]ENVIRONMENT VARIABLES\f[R] section), then if -that environment variable contains a non-zero integer, bc(1) will turn +that environment variable contains a non\-zero integer, bc(1) will turn on TTY mode when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all connected to a TTY. If the \f[B]BC_TTY_MODE\f[R] environment variable exists but is -\f[I]not\f[R] a non-zero integer, then bc(1) will not turn TTY mode on. +\f[I]not\f[R] a non\-zero integer, then bc(1) will not turn TTY mode on. .PP If the environment variable \f[B]BC_TTY_MODE\f[R] does \f[I]not\f[R] exist, the default setting is used. -The default setting can be queried with the \f[B]-h\f[R] or -\f[B]--help\f[R] options. +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 -.PP If TTY mode is available, then a prompt can be enabled. Like TTY mode itself, it can be turned on or off with an environment variable: \f[B]BC_PROMPT\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). .PP -If the environment variable \f[B]BC_PROMPT\f[R] exists and is a non-zero -integer, then the prompt is turned on when \f[B]stdin\f[R], +If the environment variable \f[B]BC_PROMPT\f[R] exists and is a +non\-zero integer, then the prompt is turned on when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are connected to a TTY and the -\f[B]-P\f[R] and \f[B]--no-prompt\f[R] options were not used. +\f[B]\-P\f[R] and \f[B]\-\-no\-prompt\f[R] options were not used. The read prompt will be turned on under the same conditions, except that -the \f[B]-R\f[R] and \f[B]--no-read-prompt\f[R] options must also not be -used. +the \f[B]\-R\f[R] and \f[B]\-\-no\-read\-prompt\f[R] options must also +not be used. .PP However, if \f[B]BC_PROMPT\f[R] does not exist, the prompt can be enabled or disabled with the \f[B]BC_TTY_MODE\f[R] environment variable, -the \f[B]-P\f[R] and \f[B]--no-prompt\f[R] options, and the \f[B]-R\f[R] -and \f[B]--no-read-prompt\f[R] options. +the \f[B]\-P\f[R] and \f[B]\-\-no\-prompt\f[R] options, and the +\f[B]\-R\f[R] and \f[B]\-\-no\-read\-prompt\f[R] options. See the \f[B]ENVIRONMENT VARIABLES\f[R] and \f[B]OPTIONS\f[R] sections for more details. .SH SIGNAL HANDLING -.PP Sending a \f[B]SIGINT\f[R] will cause bc(1) to do one of two things. .PP If bc(1) is not in interactive mode (see the \f[B]INTERACTIVE MODE\f[R] @@ -1601,7 +1680,7 @@ section), or the \f[B]BC_SIGINT_RESET\f[R] environment variable (see the an integer or it is zero, bc(1) will exit. .PP However, if bc(1) is in interactive mode, and the -\f[B]BC_SIGINT_RESET\f[R] or its default is an integer and non-zero, +\f[B]BC_SIGINT_RESET\f[R] or its default is an integer and non\-zero, then bc(1) will stop executing the current input and reset (see the \f[B]RESET\f[R] section) upon receiving a \f[B]SIGINT\f[R]. .PP @@ -1624,20 +1703,23 @@ the user to continue. \f[B]SIGTERM\f[R] and \f[B]SIGQUIT\f[R] cause bc(1) to clean up and exit, and it uses the default handler for all other signals. .SH LOCALES -.PP This bc(1) ships with support for adding error messages for different locales and thus, supports \f[B]LC_MESSAGES\f[R]. .SH SEE ALSO -.PP dc(1) .SH STANDARDS -.PP -bc(1) is compliant with the IEEE Std 1003.1-2017 -(\[lq]POSIX.1-2017\[rq]) specification at +bc(1) is compliant with the IEEE Std 1003.1\-2017 +(\[lq]POSIX.1\-2017\[rq]) specification at https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html . -The flags \f[B]-efghiqsvVw\f[R], all long options, and the extensions +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]. @@ -1645,10 +1727,13 @@ the value of \f[B]LC_NUMERIC\f[R]. This bc(1) supports error messages for different locales, and thus, it supports \f[B]LC_MESSAGES\f[R]. .SH BUGS +Before version \f[B]6.1.0\f[R], this bc(1) had incorrect behavior for +the \f[B]quit\f[R] statement. .PP -None are known. -Report bugs at https://git.yzena.com/gavin/bc. +No other bugs are known. +Report bugs at https://git.gavinhoward.com/gavin/bc . .SH AUTHORS -.PP -Gavin D. -Howard <gavin@yzena.com> and contributors. +Gavin D. Howard \c +.MT gavin@gavinhoward.com +.ME \c +\ and contributors. diff --git a/contrib/bc/manuals/bc/EH.1.md b/contrib/bc/manuals/bc/EH.1.md index 82c3d6c36159..7e682058234c 100644 --- a/contrib/bc/manuals/bc/EH.1.md +++ b/contrib/bc/manuals/bc/EH.1.md @@ -2,7 +2,7 @@ SPDX-License-Identifier: BSD-2-Clause -Copyright (c) 2018-2021 Gavin D. Howard and contributors. +Copyright (c) 2018-2024 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**. @@ -248,71 +344,12 @@ The following are the options that bc(1) accepts. : Makes bc(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)**, + 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**. -**-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**. - -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**. +letters are equal to **9** plus their position in the alphabet, starting from +**1** (i.e., **A** equals **10**, or **9+1**). + +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 @@ -618,6 +688,9 @@ The operators will be described in more detail below. : The **boolean not** operator returns **1** if the expression is **0**, or **0** otherwise. + **Warning**: This operator has a **different precedence** than the + equivalent operator in GNU bc(1) and other bc(1) implementations! + This is a **non-portable extension**. **\^** @@ -683,10 +756,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 +822,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.) @@ -810,7 +895,7 @@ like any other expression that is printed. ## Stream Statement -The "expressions in a **stream** statement may also be strings. +The expressions in a **stream** statement may also be strings. If a **stream** statement is given a string, it prints the string as though the string had appeared as its own statement. In other words, the **stream** @@ -919,9 +1004,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 +1177,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 +1284,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 +1372,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 +1401,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 +1467,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,8 +1480,11 @@ 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.gavinhoward.com/gavin/bc . # AUTHORS -Gavin D. Howard <gavin@yzena.com> and contributors. +Gavin D. Howard <gavin@gavinhoward.com> and contributors. diff --git a/contrib/bc/manuals/bc/EHN.1 b/contrib/bc/manuals/bc/EHN.1 index ca88115a5864..e3395b1cc20d 100644 --- a/contrib/bc/manuals/bc/EHN.1 +++ b/contrib/bc/manuals/bc/EHN.1 @@ -1,7 +1,7 @@ .\" .\" SPDX-License-Identifier: BSD-2-Clause .\" -.\" Copyright (c) 2018-2021 Gavin D. Howard and contributors. +.\" Copyright (c) 2018-2024 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,55 +25,139 @@ .\" 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" "August 2024" "Gavin D. Howard" "General Commands Manual" .nh .ad l .SH NAME -.PP -bc - arbitrary-precision decimal arithmetic language and calculator +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]--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]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]\&...] .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. +somewhat C\-like, but there are differences. Such differences will be noted in this document. .PP After parsing and handling options, this bc(1) reads any files given on 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 +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 bc(1) reserves as a keyword is used as the name of a function, variable, or array. -To fix that, use the command-line option \f[B]-r\f[R] \f[I]keyword\f[R], -where \f[I]keyword\f[R] is the keyword that is used as a name in the -script. +To fix that, use the command\-line option \f[B]\-r\f[R] +\f[I]keyword\f[R], where \f[I]keyword\f[R] is the keyword that is used +as a name in the script. For more information, see the \f[B]OPTIONS\f[R] section. .PP If parsing scripts meant for other bc(1) implementations still does not work, that is a bug and should be reported. See the \f[B]BUGS\f[R] section. .SH OPTIONS -.PP The following are the options that bc(1) accepts. .TP -\f[B]-g\f[R], \f[B]--global-stacks\f[R] +\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. .RS @@ -86,19 +170,16 @@ without worrying that the change will affect other functions. Thus, a hypothetical function named \f[B]output(x,b)\f[R] that simply printed \f[B]x\f[R] in base \f[B]b\f[R] could be written like this: .IP -.nf -\f[C] +.EX define void output(x, b) { obase=b x } -\f[R] -.fi +.EE .PP instead of like this: .IP -.nf -\f[C] +.EX define void output(x, b) { auto c c=obase @@ -106,8 +187,7 @@ define void output(x, b) { x obase=c } -\f[R] -.fi +.EE .PP This makes writing functions much easier. .PP @@ -121,12 +201,10 @@ converter, it is possible to replace that capability with various shell aliases. Examples: .IP -.nf -\f[C] -alias d2o=\[dq]bc -e ibase=A -e obase=8\[dq] -alias h2b=\[dq]bc -e ibase=G -e obase=2\[dq] -\f[R] -.fi +.EX +alias d2o=\[dq]bc \-e ibase=A \-e obase=8\[dq] +alias h2b=\[dq]bc \-e ibase=G \-e obase=2\[dq] +.EE .PP Second, if the purpose of a function is to set \f[B]ibase\f[R], \f[B]obase\f[R], or \f[B]scale\f[R] globally for any other purpose, it @@ -139,34 +217,45 @@ users could make sure to define \f[B]BC_ENV_ARGS\f[R] and include this option (see the \f[B]ENVIRONMENT VARIABLES\f[R] section for more details). .PP -If \f[B]-s\f[R], \f[B]-w\f[R], or any equivalents are used, this option -is ignored. +If \f[B]\-s\f[R], \f[B]\-w\f[R], or any equivalents are used, this +option is ignored. .PP -This is a \f[B]non-portable extension\f[R]. +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. +\f[B]\-h\f[R], \f[B]\-\-help\f[R] +Prints a usage message and exits. .TP -\f[B]-i\f[R], \f[B]--interactive\f[R] +\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. (See the \f[B]INTERACTIVE MODE\f[R] section.) .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-L\f[R], \f[B]--no-line-length\f[R] +\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]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-l\f[R], \f[B]--mathlib\f[R] +\f[B]\-l\f[R], \f[B]\-\-mathlib\f[R] Sets \f[B]scale\f[R] (see the \f[B]SYNTAX\f[R] section) to \f[B]20\f[R] and loads the included math library before running any code, including any expressions or files specified on the command line. @@ -175,11 +264,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]-P\f[R], \f[B]--no-prompt\f[R] +\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 @@ -187,14 +288,31 @@ Most of those users would want to put this option in These options override the \f[B]BC_PROMPT\f[R] and \f[B]BC_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]. +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] +\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 @@ -202,16 +320,16 @@ 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]read()\f[R] built-in function is called. +is only used when the \f[B]read()\f[R] built\-in function is called. .PP These options \f[I]do\f[R] override the \f[B]BC_PROMPT\f[R] and \f[B]BC_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]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-r\f[R] \f[I]keyword\f[R], \f[B]--redefine\f[R]=\f[I]keyword\f[R] +\f[B]\-r\f[R] \f[I]keyword\f[R], \f[B]\-\-redefine\f[R]=\f[I]keyword\f[R] Redefines \f[I]keyword\f[R] in order to allow it to be used as a function, variable, or array name. This is useful when this bc(1) gives parse errors when parsing scripts @@ -259,146 +377,63 @@ 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 -This is a \f[B]non-portable extension\f[R]. +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. +\f[B]\-s\f[R], \f[B]\-\-standard\f[R] +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]. +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. +\f[B]\-v\f[R], \f[B]\-V\f[R], \f[B]\-\-version\f[R] +Print the version information (copyright header) and exits. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-w\f[R], \f[B]--warn\f[R] -Like \f[B]-s\f[R] and \f[B]--standard\f[R], except that warnings (and -not errors) are printed for non-standard extensions and execution +\f[B]\-w\f[R], \f[B]\-\-warn\f[R] +Like \f[B]\-s\f[R] and \f[B]\-\-standard\f[R], except that warnings (and +not errors) are printed for non\-standard extensions and execution continues normally. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-z\f[R], \f[B]--leading-zeroes\f[R] -Makes bc(1) print all numbers greater than \f[B]-1\f[R] and less than +\f[B]\-z\f[R], \f[B]\-\-leading\-zeroes\f[R] +Makes bc(1) print all numbers greater than \f[B]\-1\f[R] and less than \f[B]1\f[R], and not equal to \f[B]0\f[R], with a leading zero. .RS .PP This can be set for individual numbers with the \f[B]plz(x)\f[R], -plznl(x)**, \f[B]pnlz(x)\f[R], and \f[B]pnlznl(x)\f[R] functions in the -extended math library (see the \f[B]LIBRARY\f[R] section). -.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. +\f[B]plznl(x)\f[R], \f[B]pnlz(x)\f[R], and \f[B]pnlznl(x)\f[R] functions +in the extended math library (see the \f[B]LIBRARY\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +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]. +All long options are \f[B]non\-portable extensions\f[R]. .SH STDIN -.PP -If no files or expressions are given by the \f[B]-f\f[R], -\f[B]--file\f[R], \f[B]-e\f[R], or \f[B]--expression\f[R] options, then -bc(1) reads from \f[B]stdin\f[R]. +If no files or expressions are given by the \f[B]\-f\f[R], +\f[B]\-\-file\f[R], \f[B]\-e\f[R], or \f[B]\-\-expression\f[R] options, +then bc(1) reads from \f[B]stdin\f[R]. .PP However, there are a few caveats to this. .PP @@ -412,8 +447,7 @@ Second, after an \f[B]if\f[R] statement, bc(1) doesn\[cq]t know if an \f[B]else\f[R] statement will follow, so it will not execute until it knows there will not be an \f[B]else\f[R] statement. .SH STDOUT -.PP -Any non-error output is written to \f[B]stdout\f[R]. +Any non\-error output is written to \f[B]stdout\f[R]. In addition, if history (see the \f[B]HISTORY\f[R] section) and the prompt (see the \f[B]TTY MODE\f[R] section) are enabled, both are output to \f[B]stdout\f[R]. @@ -421,7 +455,7 @@ to \f[B]stdout\f[R]. \f[B]Note\f[R]: Unlike other bc(1) implementations, this bc(1) will issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot write to \f[B]stdout\f[R], so if \f[B]stdout\f[R] is closed, as in -\f[B]bc >&-\f[R], it will quit with an error. +\f[B]bc >&\-\f[R], it will quit with an error. This is done so that bc(1) can report problems when \f[B]stdout\f[R] is redirected to a file. .PP @@ -429,13 +463,12 @@ If there are scripts that depend on the behavior of other bc(1) implementations, it is recommended that those scripts be changed to redirect \f[B]stdout\f[R] to \f[B]/dev/null\f[R]. .SH STDERR -.PP Any error output is written to \f[B]stderr\f[R]. .PP \f[B]Note\f[R]: Unlike other bc(1) implementations, this bc(1) will issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot write to \f[B]stderr\f[R], so if \f[B]stderr\f[R] is closed, as in -\f[B]bc 2>&-\f[R], it will quit with an error. +\f[B]bc 2>&\-\f[R], it will quit with an error. This is done so that bc(1) can exit with an error code when \f[B]stderr\f[R] is redirected to a file. .PP @@ -443,12 +476,10 @@ If there are scripts that depend on the behavior of other bc(1) implementations, it is recommended that those scripts be changed to redirect \f[B]stderr\f[R] to \f[B]/dev/null\f[R]. .SH SYNTAX -.PP -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. +The syntax for bc(1) programs is mostly C\-like, with some differences. +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 @@ -456,32 +487,32 @@ In the sections below, \f[B]E\f[R] means expression, \f[B]S\f[R] means statement, and \f[B]I\f[R] means identifier. .PP Identifiers (\f[B]I\f[R]) start with a lowercase letter and can be -followed by any number (up to \f[B]BC_NAME_MAX-1\f[R]) of lowercase -letters (\f[B]a-z\f[R]), digits (\f[B]0-9\f[R]), and underscores +followed by any number (up to \f[B]BC_NAME_MAX\-1\f[R]) of lowercase +letters (\f[B]a\-z\f[R]), digits (\f[B]0\-9\f[R]), and underscores (\f[B]_\f[R]). -The regex is \f[B][a-z][a-z0-9_]*\f[R]. +The regex is \f[B][a\-z][a\-z0\-9_]*\f[R]. Identifiers with more than one character (letter) are a -\f[B]non-portable extension\f[R]. +\f[B]non\-portable extension\f[R]. .PP \f[B]ibase\f[R] is a global variable determining how to interpret constant numbers. It is the \[lq]input\[rq] base, or the number base used for interpreting input numbers. \f[B]ibase\f[R] is initially \f[B]10\f[R]. -If the \f[B]-s\f[R] (\f[B]--standard\f[R]) and \f[B]-w\f[R] -(\f[B]--warn\f[R]) flags were not given on the command line, the max +If the \f[B]\-s\f[R] (\f[B]\-\-standard\f[R]) and \f[B]\-w\f[R] +(\f[B]\-\-warn\f[R]) flags were not given on the command line, the max allowable value for \f[B]ibase\f[R] is \f[B]36\f[R]. Otherwise, it is \f[B]16\f[R]. The min allowable value for \f[B]ibase\f[R] is \f[B]2\f[R]. The max allowable value for \f[B]ibase\f[R] can be queried in bc(1) -programs with the \f[B]maxibase()\f[R] built-in function. +programs with the \f[B]maxibase()\f[R] built\-in function. .PP \f[B]obase\f[R] is a global variable determining how to output results. It is the \[lq]output\[rq] base, or the number base used for outputting numbers. \f[B]obase\f[R] is initially \f[B]10\f[R]. The max allowable value for \f[B]obase\f[R] is \f[B]BC_BASE_MAX\f[R] and -can be queried in bc(1) programs with the \f[B]maxobase()\f[R] built-in +can be queried in bc(1) programs with the \f[B]maxobase()\f[R] built\-in function. The min allowable value for \f[B]obase\f[R] is \f[B]2\f[R]. Values are output in the specified base. @@ -494,7 +525,7 @@ exceptions. \f[B]scale\f[R] cannot be negative. The max allowable value for \f[B]scale\f[R] is \f[B]BC_SCALE_MAX\f[R] and can be queried in bc(1) programs with the \f[B]maxscale()\f[R] -built-in function. +built\-in function. .PP bc(1) has both \f[I]global\f[R] variables and \f[I]local\f[R] variables. All \f[I]local\f[R] variables are local to the function; they are @@ -519,20 +550,18 @@ The value that is printed is also assigned to the special variable \f[B]last\f[R]. A single dot (\f[B].\f[R]) may also be used as a synonym for \f[B]last\f[R]. -These are \f[B]non-portable extensions\f[R]. +These are \f[B]non\-portable extensions\f[R]. .PP Either semicolons or newlines may separate statements. .SS Comments -.PP There are two kinds of comments: .IP "1." 3 Block comments are enclosed in \f[B]/*\f[R] and \f[B]*/\f[R]. .IP "2." 3 Line comments go from \f[B]#\f[R] until, and not including, the next newline. -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .SS Named Expressions -.PP The following are named expressions in bc(1): .IP "1." 3 Variables: \f[B]I\f[R] @@ -547,7 +576,7 @@ Array Elements: \f[B]I[E]\f[R] .IP "6." 3 \f[B]last\f[R] or a single dot (\f[B].\f[R]) .PP -Number 6 is a \f[B]non-portable extension\f[R]. +Number 6 is a \f[B]non\-portable extension\f[R]. .PP Variables and arrays do not interfere; users can have arrays named the same as variables. @@ -561,7 +590,6 @@ Named expressions are required as the operand of of \f[B]assignment\f[R] operators (see the \f[I]Operators\f[R] subsection). .SS Operands -.PP The following are valid operands in bc(1): .IP " 1." 4 Numbers (see the \f[I]Numbers\f[R] subsection below). @@ -571,108 +599,152 @@ Array indices (\f[B]I[E]\f[R]). \f[B](E)\f[R]: The value of \f[B]E\f[R] (used to change precedence). .IP " 4." 4 \f[B]sqrt(E)\f[R]: The square root of \f[B]E\f[R]. -\f[B]E\f[R] must be non-negative. +\f[B]E\f[R] must be non\-negative. .IP " 5." 4 \f[B]length(E)\f[R]: The number of significant decimal digits in \f[B]E\f[R]. Returns \f[B]1\f[R] for \f[B]0\f[R] with no decimal places. If given a string, the length of the string is returned. -Passing a string to \f[B]length(E)\f[R] is a \f[B]non-portable +Passing a string to \f[B]length(E)\f[R] is a \f[B]non\-portable extension\f[R]. .IP " 6." 4 \f[B]length(I[])\f[R]: The number of elements in the array \f[B]I\f[R]. -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .IP " 7." 4 \f[B]scale(E)\f[R]: The \f[I]scale\f[R] of \f[B]E\f[R]. .IP " 8." 4 \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]. +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. 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 +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 "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, -which must be non-zero. +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 +This is a \f[B]non\-portable extension\f[R]. +.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 +that number as a one\-character string. +This is a \f[B]non\-portable extension\f[R]. +.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[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). The \f[B]E\f[R] argument(s) may also be arrays of the form \f[B]I[]\f[R], which will automatically be turned into array references (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 +This is a \f[B]non\-portable extension\f[R]. +.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 +This is a \f[B]non\-portable extension\f[R]. +.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 +This is a \f[B]non\-portable extension\f[R]. +.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 +This is a \f[B]non\-portable extension\f[R]. +.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 +This is a \f[B]non\-portable extension\f[R]. +.IP "21." 4 \f[B]global_stacks()\f[R]: \f[B]0\f[R] if global stacks are not enabled -with the \f[B]-g\f[R] or \f[B]--global-stacks\f[R] options, non-zero -otherwise. +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 +This is a \f[B]non\-portable extension\f[R]. +.IP "22." 4 \f[B]leading_zero()\f[R]: \f[B]0\f[R] if leading zeroes are not enabled -with the \f[B]-z\f[R] or \f[B]\[en]leading-zeroes\f[R] options, non-zero -otherwise. +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]. +This is a \f[B]non\-portable extension\f[R]. .SS Numbers -.PP 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]. -.SS Operators +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 The following arithmetic and logical operators can be used. They are listed in order of decreasing precedence. Operators in the same group have the same precedence. .TP -\f[B]++\f[R] \f[B]--\f[R] +\f[B]++\f[R] \f[B]\-\-\f[R] Type: Prefix and Postfix .RS .PP @@ -681,7 +753,7 @@ Associativity: None Description: \f[B]increment\f[R], \f[B]decrement\f[R] .RE .TP -\f[B]-\f[R] \f[B]!\f[R] +\f[B]\-\f[R] \f[B]!\f[R] Type: Prefix .RS .PP @@ -708,7 +780,7 @@ Associativity: Left Description: \f[B]multiply\f[R], \f[B]divide\f[R], \f[B]modulus\f[R] .RE .TP -\f[B]+\f[R] \f[B]-\f[R] +\f[B]+\f[R] \f[B]\-\f[R] Type: Binary .RS .PP @@ -717,7 +789,7 @@ Associativity: Left Description: \f[B]add\f[R], \f[B]subtract\f[R] .RE .TP -\f[B]=\f[R] \f[B]+=\f[R] \f[B]-=\f[R] \f[B]*=\f[R] \f[B]/=\f[R] \f[B]%=\f[R] \f[B]\[ha]=\f[R] +\f[B]=\f[R] \f[B]+=\f[R] \f[B]\-=\f[R] \f[B]*=\f[R] \f[B]/=\f[R] \f[B]%=\f[R] \f[B]\[ha]=\f[R] Type: Binary .RS .PP @@ -755,18 +827,18 @@ Description: \f[B]boolean or\f[R] .PP The operators will be described in more detail below. .TP -\f[B]++\f[R] \f[B]--\f[R] +\f[B]++\f[R] \f[B]\-\-\f[R] The prefix and postfix \f[B]increment\f[R] and \f[B]decrement\f[R] -operators behave exactly like they would in C. -They require a named expression (see the \f[I]Named Expressions\f[R] -subsection) as an operand. +operators behave exactly like they would in C. They require a named +expression (see the \f[I]Named Expressions\f[R] subsection) as an +operand. .RS .PP The prefix versions of these operators are more efficient; use them where possible. .RE .TP -\f[B]-\f[R] +\f[B]\-\f[R] The \f[B]negation\f[R] operator returns \f[B]0\f[R] if a user attempts to negate any expression with the value \f[B]0\f[R]. Otherwise, a copy of the expression with its sign flipped is returned. @@ -776,7 +848,11 @@ The \f[B]boolean not\f[R] operator returns \f[B]1\f[R] if the expression is \f[B]0\f[R], or \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +\f[B]Warning\f[R]: This operator has a \f[B]different precedence\f[R] +than the equivalent operator in GNU bc(1) and other bc(1) +implementations! +.PP +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]\[ha]\f[R] @@ -787,7 +863,7 @@ The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R]. .RS .PP The second expression must be an integer (no \f[I]scale\f[R]), and if it -is negative, the first value must be non-zero. +is negative, the first value must be non\-zero. .RE .TP \f[B]*\f[R] @@ -805,18 +881,18 @@ returns the quotient. The \f[I]scale\f[R] of the result shall be the value of \f[B]scale\f[R]. .RS .PP -The second expression must be non-zero. +The second expression must be non\-zero. .RE .TP \f[B]%\f[R] The \f[B]modulus\f[R] operator takes two expressions, \f[B]a\f[R] and \f[B]b\f[R], and evaluates them by 1) Computing \f[B]a/b\f[R] to current \f[B]scale\f[R] and 2) Using the result of step 1 to calculate -\f[B]a-(a/b)*b\f[R] to \f[I]scale\f[R] +\f[B]a\-(a/b)*b\f[R] to \f[I]scale\f[R] \f[B]max(scale+scale(b),scale(a))\f[R]. .RS .PP -The second expression must be non-zero. +The second expression must be non\-zero. .RE .TP \f[B]+\f[R] @@ -824,12 +900,12 @@ The \f[B]add\f[R] operator takes two expressions, \f[B]a\f[R] and \f[B]b\f[R], and returns the sum, with a \f[I]scale\f[R] equal to the max of the \f[I]scale\f[R]s of \f[B]a\f[R] and \f[B]b\f[R]. .TP -\f[B]-\f[R] +\f[B]\-\f[R] The \f[B]subtract\f[R] operator takes two expressions, \f[B]a\f[R] and \f[B]b\f[R], and returns the difference, with a \f[I]scale\f[R] equal to the max of the \f[I]scale\f[R]s of \f[B]a\f[R] and \f[B]b\f[R]. .TP -\f[B]=\f[R] \f[B]+=\f[R] \f[B]-=\f[R] \f[B]*=\f[R] \f[B]/=\f[R] \f[B]%=\f[R] \f[B]\[ha]=\f[R] +\f[B]=\f[R] \f[B]+=\f[R] \f[B]\-=\f[R] \f[B]*=\f[R] \f[B]/=\f[R] \f[B]%=\f[R] \f[B]\[ha]=\f[R] The \f[B]assignment\f[R] operators take two expressions, \f[B]a\f[R] and \f[B]b\f[R] where \f[B]a\f[R] is a named expression (see the \f[I]Named Expressions\f[R] subsection). @@ -853,41 +929,39 @@ 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]. +This allowance is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]&&\f[R] The \f[B]boolean and\f[R] operator takes two expressions and returns -\f[B]1\f[R] if both expressions are non-zero, \f[B]0\f[R] otherwise. +\f[B]1\f[R] if both expressions are non\-zero, \f[B]0\f[R] otherwise. .RS .PP -This is \f[I]not\f[R] a short-circuit operator. +This is \f[I]not\f[R] a short\-circuit operator. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]||\f[R] The \f[B]boolean or\f[R] operator takes two expressions and returns -\f[B]1\f[R] if one of the expressions is non-zero, \f[B]0\f[R] +\f[B]1\f[R] if one of the expressions is non\-zero, \f[B]0\f[R] otherwise. .RS .PP -This is \f[I]not\f[R] a short-circuit operator. +This is \f[I]not\f[R] a short\-circuit operator. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .SS Statements -.PP 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 +987,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 @@ -926,10 +1002,10 @@ The \f[B]E\f[R] argument(s) may also be arrays of the form \f[B]FUNCTIONS\f[R] section) if the corresponding parameter in the function definition is an array reference. .PP -Numbers 4, 9, 11, 12, 14, 15, and 16 are \f[B]non-portable +Numbers 4, 9, 11, 12, 14, 15, and 16 are \f[B]non\-portable extensions\f[R]. .PP -Also, as a \f[B]non-portable extension\f[R], any or all of the +Also, as a \f[B]non\-portable extension\f[R], any or all of the expressions in the header of a for loop may be omitted. If the condition (second expression) is omitted, it is assumed to be a constant \f[B]1\f[R]. @@ -946,7 +1022,24 @@ This is only allowed in loops. The \f[B]if\f[R] \f[B]else\f[R] statement does the same thing as in C. .PP 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). +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 +.EX +for (i = 0; i < 3; ++i) i; quit +.EE +.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 @@ -954,12 +1047,11 @@ that is not executed, bc(1) does not quit.) .PP The \f[B]limits\f[R] statement prints the limits that this bc(1) is subject to. -This is like the \f[B]quit\f[R] statement in that it is a compile-time +This is like the \f[B]quit\f[R] statement in that it is a compile\-time command. .PP An expression by itself is evaluated and printed, followed by a newline. .SS Strings -.PP If strings appear as a statement by themselves, they are printed without a trailing newline. .PP @@ -976,9 +1068,8 @@ element that has been assigned a string, an error is raised, and bc(1) resets (see the \f[B]RESET\f[R] section). .PP Assigning strings to variables and array elements and passing them to -functions are \f[B]non-portable extensions\f[R]. +functions are \f[B]non\-portable extensions\f[R]. .SS Print Statement -.PP The \[lq]expressions\[rq] in a \f[B]print\f[R] statement may also be strings. If they are, there are backslash escape sequences that are interpreted @@ -1005,14 +1096,12 @@ below: \f[B]\[rs]t\f[R]: \f[B]\[rs]t\f[R] .PP Any other character following a backslash causes the backslash and -character to be printed as-is. +character to be printed as\-is. .PP -Any non-string expression in a print statement shall be assigned to +Any non\-string expression in a print statement shall be assigned to \f[B]last\f[R], like any other expression that is printed. .SS Stream Statement -.PP -The \[lq]expressions in a \f[B]stream\f[R] statement may also be -strings. +The expressions in a \f[B]stream\f[R] statement may also be strings. .PP If a \f[B]stream\f[R] statement is given a string, it prints the string as though the string had appeared as its own statement. @@ -1022,20 +1111,17 @@ without a newline. If a \f[B]stream\f[R] statement is given a number, a copy of it is truncated and its absolute value is calculated. The result is then printed as though \f[B]obase\f[R] is \f[B]256\f[R] -and each digit is interpreted as an 8-bit ASCII character, making it a +and each digit is interpreted as an 8\-bit ASCII character, making it a byte stream. .SS Order of Evaluation -.PP All expressions in a statment are evaluated left to right, except as necessary to maintain order of operations. This means, for example, assuming that \f[B]i\f[R] is equal to \f[B]0\f[R], in the expression .IP -.nf -\f[C] +.EX a[i++] = i++ -\f[R] -.fi +.EE .PP the first (or 0th) element of \f[B]a\f[R] is set to \f[B]1\f[R], and \f[B]i\f[R] is equal to \f[B]2\f[R] at the end of the expression. @@ -1044,28 +1130,23 @@ This includes function arguments. Thus, assuming \f[B]i\f[R] is equal to \f[B]0\f[R], this means that in the expression .IP -.nf -\f[C] +.EX x(i++, i++) -\f[R] -.fi +.EE .PP the first argument passed to \f[B]x()\f[R] is \f[B]0\f[R], and the second argument is \f[B]1\f[R], while \f[B]i\f[R] is equal to \f[B]2\f[R] before the function starts executing. .SH FUNCTIONS -.PP Function definitions are as follows: .IP -.nf -\f[C] +.EX define I(I,...,I){ auto I,...,I S;...;S return(E) } -\f[R] -.fi +.EE .PP Any \f[B]I\f[R] in the parameter list or \f[B]auto\f[R] list may be replaced with \f[B]I[]\f[R] to make a parameter or \f[B]auto\f[R] var an @@ -1076,10 +1157,10 @@ asterisk in the call; they must be called with just \f[B]I[]\f[R] like normal array parameters and will be automatically converted into references. .PP -As a \f[B]non-portable extension\f[R], the opening brace of a +As a \f[B]non\-portable extension\f[R], the opening brace of a \f[B]define\f[R] statement may appear on the next line. .PP -As a \f[B]non-portable extension\f[R], the return statement may also be +As a \f[B]non\-portable extension\f[R], the return statement may also be in one of the following forms: .IP "1." 3 \f[B]return\f[R] @@ -1093,18 +1174,15 @@ equivalent to \f[B]return (0)\f[R], unless the function is a \f[B]void\f[R] function (see the \f[I]Void Functions\f[R] subsection below). .SS Void Functions -.PP Functions can also be \f[B]void\f[R] functions, defined as follows: .IP -.nf -\f[C] +.EX define void I(I,...,I){ auto I,...,I S;...;S return } -\f[R] -.fi +.EE .PP They can only be used as standalone expressions, where such an expression would be printed alone, except in a print statement. @@ -1118,17 +1196,14 @@ possible to have variables, arrays, and functions named \f[B]void\f[R]. The word \[lq]void\[rq] is only treated specially right after the \f[B]define\f[R] keyword. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .SS Array References -.PP For any array in the parameter list, if the array is declared in the form .IP -.nf -\f[C] +.EX *I[] -\f[R] -.fi +.EE .PP it is a \f[B]reference\f[R]. Any changes to the array in the function are reflected, when the @@ -1136,16 +1211,13 @@ function returns, to the array that was passed in. .PP Other than this, all function arguments are passed by value. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .SH LIBRARY -.PP -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. +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. @@ -1196,7 +1268,6 @@ This is a transcendental function (see the \f[I]Transcendental Functions\f[R] subsection below). .RE .SS Transcendental Functions -.PP All transcendental functions can return slightly inaccurate results, up to 1 ULP (https://en.wikipedia.org/wiki/Unit_in_the_last_place). This is unavoidable, and the article at @@ -1224,8 +1295,7 @@ The transcendental functions in the standard math library are: .IP \[bu] 2 \f[B]j(x, n)\f[R] .SH RESET -.PP -When bc(1) encounters an error or a signal that it has a non-default +When bc(1) encounters an error or a signal that it has a non\-default handler for, it resets. This means that several things happen. .PP @@ -1245,7 +1315,6 @@ Note that this reset behavior is different from the GNU bc(1), which attempts to start executing the statement right after the one that caused an error. .SH PERFORMANCE -.PP Most bc(1) implementations use \f[B]char\f[R] types to calculate the value of \f[B]1\f[R] decimal digit at a time, but that can be slow. This bc(1) does something different. @@ -1268,7 +1337,6 @@ checking. This integer type depends on the value of \f[B]BC_LONG_BIT\f[R], but is always at least twice as large as the integer type used to store digits. .SH LIMITS -.PP The following are the limits on bc(1): .TP \f[B]BC_LONG_BIT\f[R] @@ -1298,24 +1366,24 @@ Set at \f[B]BC_BASE_POW\f[R]. .TP \f[B]BC_DIM_MAX\f[R] The maximum size of arrays. -Set at \f[B]SIZE_MAX-1\f[R]. +Set at \f[B]SIZE_MAX\-1\f[R]. .TP \f[B]BC_SCALE_MAX\f[R] The maximum \f[B]scale\f[R]. -Set at \f[B]BC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]BC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]BC_STRING_MAX\f[R] The maximum length of strings. -Set at \f[B]BC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]BC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]BC_NAME_MAX\f[R] The maximum length of identifiers. -Set at \f[B]BC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]BC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]BC_NUM_MAX\f[R] The maximum length of a number (in decimal digits), which includes digits after the decimal point. -Set at \f[B]BC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]BC_OVERFLOW_MAX\-1\f[R]. .TP Exponent The maximum allowable exponent (positive or negative). @@ -1323,28 +1391,28 @@ Set at \f[B]BC_OVERFLOW_MAX\f[R]. .TP Number of vars The maximum number of vars/arrays. -Set at \f[B]SIZE_MAX-1\f[R]. +Set at \f[B]SIZE_MAX\-1\f[R]. .PP The actual values can be queried with the \f[B]limits\f[R] statement. .PP -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. +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 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 -the \f[B]-s\f[R] option was given. +the \f[B]\-s\f[R] option was given. .TP \f[B]BC_ENV_ARGS\f[R] -This is another way to give command-line arguments to bc(1). -They should be in the same format as all other command-line arguments. +This is another way to give command\-line arguments to bc(1). +They should be in the same format as all other command\-line arguments. These are always processed first, so any files given in \f[B]BC_ENV_ARGS\f[R] will be processed before arguments and files given -on the command-line. +on the command\-line. This gives the user the ability to set up \[lq]standard\[rq] options and files to be used at every invocation. The most useful thing for such files to contain would be useful @@ -1365,14 +1433,14 @@ you can use double quotes as the outside quotes, as in \f[B]\[lq]some quotes. However, handling a file with both kinds of quotes in \f[B]BC_ENV_ARGS\f[R] is not supported due to the complexity of the -parsing, though such files are still supported on the command-line where -the parsing is done by the shell. +parsing, though such files are still supported on the command\-line +where the parsing is done by the shell. .RE .TP \f[B]BC_LINE_LENGTH\f[R] If this environment variable exists and contains an integer that is greater than \f[B]1\f[R] and is less than \f[B]UINT16_MAX\f[R] -(\f[B]2\[ha]16-1\f[R]), bc(1) will output lines to that length, +(\f[B]2\[ha]16\-1\f[R]), bc(1) will output lines to that length, including the backslash (\f[B]\[rs]\f[R]). The default line length is \f[B]70\f[R]. .RS @@ -1384,7 +1452,7 @@ newlines. .TP \f[B]BC_BANNER\f[R] If this environment variable exists and contains an integer, then a -non-zero value activates the copyright banner when bc(1) is in +non\-zero value activates the copyright banner when bc(1) is in interactive mode, while zero deactivates it. .RS .PP @@ -1393,7 +1461,7 @@ section), then this environment variable has no effect because bc(1) does not print the banner when not in interactive mode. .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. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]BC_SIGINT_RESET\f[R] @@ -1403,13 +1471,13 @@ exits on \f[B]SIGINT\f[R] when not in interactive mode. .RS .PP However, when bc(1) is in interactive mode, then if this environment -variable exists and contains an integer, a non-zero value makes bc(1) +variable exists and contains an integer, a non\-zero value makes bc(1) reset on \f[B]SIGINT\f[R], rather than exit, and zero makes bc(1) exit. If this environment variable exists and is \f[I]not\f[R] an integer, then bc(1) will exit on \f[B]SIGINT\f[R]. .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. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]BC_TTY_MODE\f[R] @@ -1418,11 +1486,11 @@ section), then this environment variable has no effect. .RS .PP However, when TTY mode is available, then if this environment variable -exists and contains an integer, then a non-zero value makes bc(1) use +exists and contains an integer, then a non\-zero value makes bc(1) use TTY mode, and zero makes bc(1) not use TTY mode. .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. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]BC_PROMPT\f[R] @@ -1431,30 +1499,46 @@ section), then this environment variable has no effect. .RS .PP However, when TTY mode is available, then if this environment variable -exists and contains an integer, a non-zero value makes bc(1) use a -prompt, and zero or a non-integer makes bc(1) not use a prompt. +exists and contains an integer, a non\-zero value makes bc(1) use a +prompt, and zero or a non\-integer makes bc(1) not use a prompt. If this environment variable does not exist and \f[B]BC_TTY_MODE\f[R] does, then the value of the \f[B]BC_TTY_MODE\f[R] environment variable is used. .PP This environment variable and the \f[B]BC_TTY_MODE\f[R] environment variable override the default, which can be queried with the -\f[B]-h\f[R] or \f[B]--help\f[R] options. +\f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]BC_EXPR_EXIT\f[R] -If any expressions or expression files are given on the command-line -with \f[B]-e\f[R], \f[B]--expression\f[R], \f[B]-f\f[R], or -\f[B]--file\f[R], then if this environment variable exists and contains -an integer, a non-zero value makes bc(1) exit after executing the -expressions and expression files, and a zero value makes bc(1) not exit. +If any expressions or expression files are given on the command\-line +with \f[B]\-e\f[R], \f[B]\-\-expression\f[R], \f[B]\-f\f[R], or +\f[B]\-\-file\f[R], then if this environment variable exists and +contains an integer, a non\-zero value makes bc(1) exit after executing +the expressions and expression files, and a zero value makes bc(1) not +exit. .RS .PP This environment variable overrides the default, which can be queried -with the \f[B]-h\f[R] or \f[B]--help\f[R] options. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE -.SH EXIT STATUS +.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 bc(1) returns the following exit statuses: .TP \f[B]0\f[R] @@ -1470,7 +1554,7 @@ Math errors include divide by \f[B]0\f[R], taking the square root of a negative number, attempting to convert a negative number to a hardware integer, overflow when converting a number to a hardware integer, overflow when calculating the size of a number, and attempting to use a -non-integer where an integer is required. +non\-integer where an integer is required. .PP Converting to a hardware integer happens for the second operand of the power (\f[B]\[ha]\f[R]) operator and the corresponding assignment @@ -1491,7 +1575,7 @@ giving an invalid \f[B]auto\f[R] list, having a duplicate \f[B]auto\f[R]/function parameter, failing to find the end of a code block, attempting to return a value from a \f[B]void\f[R] function, attempting to use a variable as a reference, and using any extensions -when the option \f[B]-s\f[R] or any equivalents were given. +when the option \f[B]\-s\f[R] or any equivalents were given. .RE .TP \f[B]3\f[R] @@ -1514,7 +1598,7 @@ A fatal error occurred. Fatal errors include memory allocation errors, I/O errors, failing to open files, attempting to use files that do not have only ASCII characters (bc(1) only accepts ASCII characters), attempting to open a -directory as a file, and giving invalid command-line options. +directory as a file, and giving invalid command\-line options. .RE .PP The exit status \f[B]4\f[R] is special; when a fatal error occurs, bc(1) @@ -1525,19 +1609,18 @@ interactive mode (see the \f[B]INTERACTIVE MODE\f[R] section), since bc(1) resets its state (see the \f[B]RESET\f[R] section) and accepts more input when one of those errors occurs in interactive mode. This is also the case when interactive mode is forced by the -\f[B]-i\f[R] flag or \f[B]--interactive\f[R] option. +\f[B]\-i\f[R] flag or \f[B]\-\-interactive\f[R] option. .PP These exit statuses allow bc(1) to be used in shell scripting with error checking, and its normal behavior can be forced by using the -\f[B]-i\f[R] flag or \f[B]--interactive\f[R] option. +\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. +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. .PP In interactive mode, bc(1) attempts to recover from errors (see the \f[B]RESET\f[R] section), and in normal execution, flushes @@ -1546,7 +1629,6 @@ bc(1) may also reset on \f[B]SIGINT\f[R] instead of exit, depending on the contents of, or default for, the \f[B]BC_SIGINT_RESET\f[R] environment variable (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). .SH TTY MODE -.PP If \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all connected to a TTY, then \[lq]TTY mode\[rq] is considered to be available, and thus, bc(1) can turn on TTY mode, subject to some @@ -1554,45 +1636,42 @@ settings. .PP If there is the environment variable \f[B]BC_TTY_MODE\f[R] in the environment (see the \f[B]ENVIRONMENT VARIABLES\f[R] section), then if -that environment variable contains a non-zero integer, bc(1) will turn +that environment variable contains a non\-zero integer, bc(1) will turn on TTY mode when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all connected to a TTY. If the \f[B]BC_TTY_MODE\f[R] environment variable exists but is -\f[I]not\f[R] a non-zero integer, then bc(1) will not turn TTY mode on. +\f[I]not\f[R] a non\-zero integer, then bc(1) will not turn TTY mode on. .PP If the environment variable \f[B]BC_TTY_MODE\f[R] does \f[I]not\f[R] exist, the default setting is used. -The default setting can be queried with the \f[B]-h\f[R] or -\f[B]--help\f[R] options. +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 -.PP If TTY mode is available, then a prompt can be enabled. Like TTY mode itself, it can be turned on or off with an environment variable: \f[B]BC_PROMPT\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). .PP -If the environment variable \f[B]BC_PROMPT\f[R] exists and is a non-zero -integer, then the prompt is turned on when \f[B]stdin\f[R], +If the environment variable \f[B]BC_PROMPT\f[R] exists and is a +non\-zero integer, then the prompt is turned on when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are connected to a TTY and the -\f[B]-P\f[R] and \f[B]--no-prompt\f[R] options were not used. +\f[B]\-P\f[R] and \f[B]\-\-no\-prompt\f[R] options were not used. The read prompt will be turned on under the same conditions, except that -the \f[B]-R\f[R] and \f[B]--no-read-prompt\f[R] options must also not be -used. +the \f[B]\-R\f[R] and \f[B]\-\-no\-read\-prompt\f[R] options must also +not be used. .PP However, if \f[B]BC_PROMPT\f[R] does not exist, the prompt can be enabled or disabled with the \f[B]BC_TTY_MODE\f[R] environment variable, -the \f[B]-P\f[R] and \f[B]--no-prompt\f[R] options, and the \f[B]-R\f[R] -and \f[B]--no-read-prompt\f[R] options. +the \f[B]\-P\f[R] and \f[B]\-\-no\-prompt\f[R] options, and the +\f[B]\-R\f[R] and \f[B]\-\-no\-read\-prompt\f[R] options. See the \f[B]ENVIRONMENT VARIABLES\f[R] and \f[B]OPTIONS\f[R] sections for more details. .SH SIGNAL HANDLING -.PP Sending a \f[B]SIGINT\f[R] will cause bc(1) to do one of two things. .PP If bc(1) is not in interactive mode (see the \f[B]INTERACTIVE MODE\f[R] @@ -1601,7 +1680,7 @@ section), or the \f[B]BC_SIGINT_RESET\f[R] environment variable (see the an integer or it is zero, bc(1) will exit. .PP However, if bc(1) is in interactive mode, and the -\f[B]BC_SIGINT_RESET\f[R] or its default is an integer and non-zero, +\f[B]BC_SIGINT_RESET\f[R] or its default is an integer and non\-zero, then bc(1) will stop executing the current input and reset (see the \f[B]RESET\f[R] section) upon receiving a \f[B]SIGINT\f[R]. .PP @@ -1624,24 +1703,31 @@ the user to continue. \f[B]SIGTERM\f[R] and \f[B]SIGQUIT\f[R] cause bc(1) to clean up and exit, and it uses the default handler for all other signals. .SH SEE ALSO -.PP dc(1) .SH STANDARDS -.PP -bc(1) is compliant with the IEEE Std 1003.1-2017 -(\[lq]POSIX.1-2017\[rq]) specification at +bc(1) is compliant with the IEEE Std 1003.1\-2017 +(\[lq]POSIX.1\-2017\[rq]) specification at https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html . -The flags \f[B]-efghiqsvVw\f[R], all long options, and the extensions +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 +Before version \f[B]6.1.0\f[R], this bc(1) had incorrect behavior for +the \f[B]quit\f[R] statement. .PP -None are known. -Report bugs at https://git.yzena.com/gavin/bc. +No other bugs are known. +Report bugs at https://git.gavinhoward.com/gavin/bc . .SH AUTHORS -.PP -Gavin D. -Howard <gavin@yzena.com> and contributors. +Gavin D. Howard \c +.MT gavin@gavinhoward.com +.ME \c +\ and contributors. diff --git a/contrib/bc/manuals/bc/EHN.1.md b/contrib/bc/manuals/bc/EHN.1.md index d3873ba6ac97..9578d2ab7720 100644 --- a/contrib/bc/manuals/bc/EHN.1.md +++ b/contrib/bc/manuals/bc/EHN.1.md @@ -2,7 +2,7 @@ SPDX-License-Identifier: BSD-2-Clause -Copyright (c) 2018-2021 Gavin D. Howard and contributors. +Copyright (c) 2018-2024 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**. @@ -248,71 +344,12 @@ The following are the options that bc(1) accepts. : Makes bc(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)**, + 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**. -**-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**. - -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**. +letters are equal to **9** plus their position in the alphabet, starting from +**1** (i.e., **A** equals **10**, or **9+1**). + +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 @@ -618,6 +688,9 @@ The operators will be described in more detail below. : The **boolean not** operator returns **1** if the expression is **0**, or **0** otherwise. + **Warning**: This operator has a **different precedence** than the + equivalent operator in GNU bc(1) and other bc(1) implementations! + This is a **non-portable extension**. **\^** @@ -683,10 +756,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 +822,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.) @@ -810,7 +895,7 @@ like any other expression that is printed. ## Stream Statement -The "expressions in a **stream** statement may also be strings. +The expressions in a **stream** statement may also be strings. If a **stream** statement is given a string, it prints the string as though the string had appeared as its own statement. In other words, the **stream** @@ -919,9 +1004,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 +1177,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 +1284,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 +1372,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 +1401,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,14 +1462,21 @@ 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.gavinhoward.com/gavin/bc . # AUTHORS -Gavin D. Howard <gavin@yzena.com> and contributors. +Gavin D. Howard <gavin@gavinhoward.com> and contributors. diff --git a/contrib/bc/manuals/bc/EN.1 b/contrib/bc/manuals/bc/EN.1 index 1f1e60aad093..c1ccbec567ec 100644 --- a/contrib/bc/manuals/bc/EN.1 +++ b/contrib/bc/manuals/bc/EN.1 @@ -1,7 +1,7 @@ .\" .\" SPDX-License-Identifier: BSD-2-Clause .\" -.\" Copyright (c) 2018-2021 Gavin D. Howard and contributors. +.\" Copyright (c) 2018-2024 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,55 +25,139 @@ .\" 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" "August 2024" "Gavin D. Howard" "General Commands Manual" .nh .ad l .SH NAME -.PP -bc - arbitrary-precision decimal arithmetic language and calculator +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]--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]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]\&...] .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. +somewhat C\-like, but there are differences. Such differences will be noted in this document. .PP After parsing and handling options, this bc(1) reads any files given on 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 +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 bc(1) reserves as a keyword is used as the name of a function, variable, or array. -To fix that, use the command-line option \f[B]-r\f[R] \f[I]keyword\f[R], -where \f[I]keyword\f[R] is the keyword that is used as a name in the -script. +To fix that, use the command\-line option \f[B]\-r\f[R] +\f[I]keyword\f[R], where \f[I]keyword\f[R] is the keyword that is used +as a name in the script. For more information, see the \f[B]OPTIONS\f[R] section. .PP If parsing scripts meant for other bc(1) implementations still does not work, that is a bug and should be reported. See the \f[B]BUGS\f[R] section. .SH OPTIONS -.PP The following are the options that bc(1) accepts. .TP -\f[B]-g\f[R], \f[B]--global-stacks\f[R] +\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. .RS @@ -86,19 +170,16 @@ without worrying that the change will affect other functions. Thus, a hypothetical function named \f[B]output(x,b)\f[R] that simply printed \f[B]x\f[R] in base \f[B]b\f[R] could be written like this: .IP -.nf -\f[C] +.EX define void output(x, b) { obase=b x } -\f[R] -.fi +.EE .PP instead of like this: .IP -.nf -\f[C] +.EX define void output(x, b) { auto c c=obase @@ -106,8 +187,7 @@ define void output(x, b) { x obase=c } -\f[R] -.fi +.EE .PP This makes writing functions much easier. .PP @@ -121,12 +201,10 @@ converter, it is possible to replace that capability with various shell aliases. Examples: .IP -.nf -\f[C] -alias d2o=\[dq]bc -e ibase=A -e obase=8\[dq] -alias h2b=\[dq]bc -e ibase=G -e obase=2\[dq] -\f[R] -.fi +.EX +alias d2o=\[dq]bc \-e ibase=A \-e obase=8\[dq] +alias h2b=\[dq]bc \-e ibase=G \-e obase=2\[dq] +.EE .PP Second, if the purpose of a function is to set \f[B]ibase\f[R], \f[B]obase\f[R], or \f[B]scale\f[R] globally for any other purpose, it @@ -139,34 +217,45 @@ users could make sure to define \f[B]BC_ENV_ARGS\f[R] and include this option (see the \f[B]ENVIRONMENT VARIABLES\f[R] section for more details). .PP -If \f[B]-s\f[R], \f[B]-w\f[R], or any equivalents are used, this option -is ignored. +If \f[B]\-s\f[R], \f[B]\-w\f[R], or any equivalents are used, this +option is ignored. .PP -This is a \f[B]non-portable extension\f[R]. +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. +\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. +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] +\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]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-L\f[R], \f[B]--no-line-length\f[R] +\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]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-l\f[R], \f[B]--mathlib\f[R] +\f[B]\-l\f[R], \f[B]\-\-mathlib\f[R] Sets \f[B]scale\f[R] (see the \f[B]SYNTAX\f[R] section) to \f[B]20\f[R] and loads the included math library before running any code, including any expressions or files specified on the command line. @@ -175,11 +264,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]-P\f[R], \f[B]--no-prompt\f[R] +\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 @@ -187,14 +288,31 @@ Most of those users would want to put this option in These options override the \f[B]BC_PROMPT\f[R] and \f[B]BC_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]. +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] +\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 @@ -202,16 +320,16 @@ 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]read()\f[R] built-in function is called. +is only used when the \f[B]read()\f[R] built\-in function is called. .PP These options \f[I]do\f[R] override the \f[B]BC_PROMPT\f[R] and \f[B]BC_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]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-r\f[R] \f[I]keyword\f[R], \f[B]--redefine\f[R]=\f[I]keyword\f[R] +\f[B]\-r\f[R] \f[I]keyword\f[R], \f[B]\-\-redefine\f[R]=\f[I]keyword\f[R] Redefines \f[I]keyword\f[R] in order to allow it to be used as a function, variable, or array name. This is useful when this bc(1) gives parse errors when parsing scripts @@ -259,146 +377,63 @@ 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 -This is a \f[B]non-portable extension\f[R]. +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. +\f[B]\-s\f[R], \f[B]\-\-standard\f[R] +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]. +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. +\f[B]\-v\f[R], \f[B]\-V\f[R], \f[B]\-\-version\f[R] +Print the version information (copyright header) and exits. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-w\f[R], \f[B]--warn\f[R] -Like \f[B]-s\f[R] and \f[B]--standard\f[R], except that warnings (and -not errors) are printed for non-standard extensions and execution +\f[B]\-w\f[R], \f[B]\-\-warn\f[R] +Like \f[B]\-s\f[R] and \f[B]\-\-standard\f[R], except that warnings (and +not errors) are printed for non\-standard extensions and execution continues normally. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-z\f[R], \f[B]--leading-zeroes\f[R] -Makes bc(1) print all numbers greater than \f[B]-1\f[R] and less than +\f[B]\-z\f[R], \f[B]\-\-leading\-zeroes\f[R] +Makes bc(1) print all numbers greater than \f[B]\-1\f[R] and less than \f[B]1\f[R], and not equal to \f[B]0\f[R], with a leading zero. .RS .PP This can be set for individual numbers with the \f[B]plz(x)\f[R], -plznl(x)**, \f[B]pnlz(x)\f[R], and \f[B]pnlznl(x)\f[R] functions in the -extended math library (see the \f[B]LIBRARY\f[R] section). -.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. +\f[B]plznl(x)\f[R], \f[B]pnlz(x)\f[R], and \f[B]pnlznl(x)\f[R] functions +in the extended math library (see the \f[B]LIBRARY\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .PP -All long options are \f[B]non-portable extensions\f[R]. +All long options are \f[B]non\-portable extensions\f[R]. .SH STDIN -.PP -If no files or expressions are given by the \f[B]-f\f[R], -\f[B]--file\f[R], \f[B]-e\f[R], or \f[B]--expression\f[R] options, then -bc(1) reads from \f[B]stdin\f[R]. +If no files or expressions are given by the \f[B]\-f\f[R], +\f[B]\-\-file\f[R], \f[B]\-e\f[R], or \f[B]\-\-expression\f[R] options, +then bc(1) reads from \f[B]stdin\f[R]. .PP However, there are a few caveats to this. .PP @@ -412,8 +447,7 @@ Second, after an \f[B]if\f[R] statement, bc(1) doesn\[cq]t know if an \f[B]else\f[R] statement will follow, so it will not execute until it knows there will not be an \f[B]else\f[R] statement. .SH STDOUT -.PP -Any non-error output is written to \f[B]stdout\f[R]. +Any non\-error output is written to \f[B]stdout\f[R]. In addition, if history (see the \f[B]HISTORY\f[R] section) and the prompt (see the \f[B]TTY MODE\f[R] section) are enabled, both are output to \f[B]stdout\f[R]. @@ -421,7 +455,7 @@ to \f[B]stdout\f[R]. \f[B]Note\f[R]: Unlike other bc(1) implementations, this bc(1) will issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot write to \f[B]stdout\f[R], so if \f[B]stdout\f[R] is closed, as in -\f[B]bc >&-\f[R], it will quit with an error. +\f[B]bc >&\-\f[R], it will quit with an error. This is done so that bc(1) can report problems when \f[B]stdout\f[R] is redirected to a file. .PP @@ -429,13 +463,12 @@ If there are scripts that depend on the behavior of other bc(1) implementations, it is recommended that those scripts be changed to redirect \f[B]stdout\f[R] to \f[B]/dev/null\f[R]. .SH STDERR -.PP Any error output is written to \f[B]stderr\f[R]. .PP \f[B]Note\f[R]: Unlike other bc(1) implementations, this bc(1) will issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot write to \f[B]stderr\f[R], so if \f[B]stderr\f[R] is closed, as in -\f[B]bc 2>&-\f[R], it will quit with an error. +\f[B]bc 2>&\-\f[R], it will quit with an error. This is done so that bc(1) can exit with an error code when \f[B]stderr\f[R] is redirected to a file. .PP @@ -443,12 +476,10 @@ If there are scripts that depend on the behavior of other bc(1) implementations, it is recommended that those scripts be changed to redirect \f[B]stderr\f[R] to \f[B]/dev/null\f[R]. .SH SYNTAX -.PP -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. +The syntax for bc(1) programs is mostly C\-like, with some differences. +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 @@ -456,32 +487,32 @@ In the sections below, \f[B]E\f[R] means expression, \f[B]S\f[R] means statement, and \f[B]I\f[R] means identifier. .PP Identifiers (\f[B]I\f[R]) start with a lowercase letter and can be -followed by any number (up to \f[B]BC_NAME_MAX-1\f[R]) of lowercase -letters (\f[B]a-z\f[R]), digits (\f[B]0-9\f[R]), and underscores +followed by any number (up to \f[B]BC_NAME_MAX\-1\f[R]) of lowercase +letters (\f[B]a\-z\f[R]), digits (\f[B]0\-9\f[R]), and underscores (\f[B]_\f[R]). -The regex is \f[B][a-z][a-z0-9_]*\f[R]. +The regex is \f[B][a\-z][a\-z0\-9_]*\f[R]. Identifiers with more than one character (letter) are a -\f[B]non-portable extension\f[R]. +\f[B]non\-portable extension\f[R]. .PP \f[B]ibase\f[R] is a global variable determining how to interpret constant numbers. It is the \[lq]input\[rq] base, or the number base used for interpreting input numbers. \f[B]ibase\f[R] is initially \f[B]10\f[R]. -If the \f[B]-s\f[R] (\f[B]--standard\f[R]) and \f[B]-w\f[R] -(\f[B]--warn\f[R]) flags were not given on the command line, the max +If the \f[B]\-s\f[R] (\f[B]\-\-standard\f[R]) and \f[B]\-w\f[R] +(\f[B]\-\-warn\f[R]) flags were not given on the command line, the max allowable value for \f[B]ibase\f[R] is \f[B]36\f[R]. Otherwise, it is \f[B]16\f[R]. The min allowable value for \f[B]ibase\f[R] is \f[B]2\f[R]. The max allowable value for \f[B]ibase\f[R] can be queried in bc(1) -programs with the \f[B]maxibase()\f[R] built-in function. +programs with the \f[B]maxibase()\f[R] built\-in function. .PP \f[B]obase\f[R] is a global variable determining how to output results. It is the \[lq]output\[rq] base, or the number base used for outputting numbers. \f[B]obase\f[R] is initially \f[B]10\f[R]. The max allowable value for \f[B]obase\f[R] is \f[B]BC_BASE_MAX\f[R] and -can be queried in bc(1) programs with the \f[B]maxobase()\f[R] built-in +can be queried in bc(1) programs with the \f[B]maxobase()\f[R] built\-in function. The min allowable value for \f[B]obase\f[R] is \f[B]2\f[R]. Values are output in the specified base. @@ -494,7 +525,7 @@ exceptions. \f[B]scale\f[R] cannot be negative. The max allowable value for \f[B]scale\f[R] is \f[B]BC_SCALE_MAX\f[R] and can be queried in bc(1) programs with the \f[B]maxscale()\f[R] -built-in function. +built\-in function. .PP bc(1) has both \f[I]global\f[R] variables and \f[I]local\f[R] variables. All \f[I]local\f[R] variables are local to the function; they are @@ -519,20 +550,18 @@ The value that is printed is also assigned to the special variable \f[B]last\f[R]. A single dot (\f[B].\f[R]) may also be used as a synonym for \f[B]last\f[R]. -These are \f[B]non-portable extensions\f[R]. +These are \f[B]non\-portable extensions\f[R]. .PP Either semicolons or newlines may separate statements. .SS Comments -.PP There are two kinds of comments: .IP "1." 3 Block comments are enclosed in \f[B]/*\f[R] and \f[B]*/\f[R]. .IP "2." 3 Line comments go from \f[B]#\f[R] until, and not including, the next newline. -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .SS Named Expressions -.PP The following are named expressions in bc(1): .IP "1." 3 Variables: \f[B]I\f[R] @@ -547,7 +576,7 @@ Array Elements: \f[B]I[E]\f[R] .IP "6." 3 \f[B]last\f[R] or a single dot (\f[B].\f[R]) .PP -Number 6 is a \f[B]non-portable extension\f[R]. +Number 6 is a \f[B]non\-portable extension\f[R]. .PP Variables and arrays do not interfere; users can have arrays named the same as variables. @@ -561,7 +590,6 @@ Named expressions are required as the operand of of \f[B]assignment\f[R] operators (see the \f[I]Operators\f[R] subsection). .SS Operands -.PP The following are valid operands in bc(1): .IP " 1." 4 Numbers (see the \f[I]Numbers\f[R] subsection below). @@ -571,108 +599,152 @@ Array indices (\f[B]I[E]\f[R]). \f[B](E)\f[R]: The value of \f[B]E\f[R] (used to change precedence). .IP " 4." 4 \f[B]sqrt(E)\f[R]: The square root of \f[B]E\f[R]. -\f[B]E\f[R] must be non-negative. +\f[B]E\f[R] must be non\-negative. .IP " 5." 4 \f[B]length(E)\f[R]: The number of significant decimal digits in \f[B]E\f[R]. Returns \f[B]1\f[R] for \f[B]0\f[R] with no decimal places. If given a string, the length of the string is returned. -Passing a string to \f[B]length(E)\f[R] is a \f[B]non-portable +Passing a string to \f[B]length(E)\f[R] is a \f[B]non\-portable extension\f[R]. .IP " 6." 4 \f[B]length(I[])\f[R]: The number of elements in the array \f[B]I\f[R]. -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .IP " 7." 4 \f[B]scale(E)\f[R]: The \f[I]scale\f[R] of \f[B]E\f[R]. .IP " 8." 4 \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]. +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. 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 +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 "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, -which must be non-zero. +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 +This is a \f[B]non\-portable extension\f[R]. +.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 +that number as a one\-character string. +This is a \f[B]non\-portable extension\f[R]. +.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[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). The \f[B]E\f[R] argument(s) may also be arrays of the form \f[B]I[]\f[R], which will automatically be turned into array references (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 +This is a \f[B]non\-portable extension\f[R]. +.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 +This is a \f[B]non\-portable extension\f[R]. +.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 +This is a \f[B]non\-portable extension\f[R]. +.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 +This is a \f[B]non\-portable extension\f[R]. +.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 +This is a \f[B]non\-portable extension\f[R]. +.IP "21." 4 \f[B]global_stacks()\f[R]: \f[B]0\f[R] if global stacks are not enabled -with the \f[B]-g\f[R] or \f[B]--global-stacks\f[R] options, non-zero -otherwise. +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 +This is a \f[B]non\-portable extension\f[R]. +.IP "22." 4 \f[B]leading_zero()\f[R]: \f[B]0\f[R] if leading zeroes are not enabled -with the \f[B]-z\f[R] or \f[B]\[en]leading-zeroes\f[R] options, non-zero -otherwise. +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]. +This is a \f[B]non\-portable extension\f[R]. .SS Numbers -.PP 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]. -.SS Operators +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 The following arithmetic and logical operators can be used. They are listed in order of decreasing precedence. Operators in the same group have the same precedence. .TP -\f[B]++\f[R] \f[B]--\f[R] +\f[B]++\f[R] \f[B]\-\-\f[R] Type: Prefix and Postfix .RS .PP @@ -681,7 +753,7 @@ Associativity: None Description: \f[B]increment\f[R], \f[B]decrement\f[R] .RE .TP -\f[B]-\f[R] \f[B]!\f[R] +\f[B]\-\f[R] \f[B]!\f[R] Type: Prefix .RS .PP @@ -708,7 +780,7 @@ Associativity: Left Description: \f[B]multiply\f[R], \f[B]divide\f[R], \f[B]modulus\f[R] .RE .TP -\f[B]+\f[R] \f[B]-\f[R] +\f[B]+\f[R] \f[B]\-\f[R] Type: Binary .RS .PP @@ -717,7 +789,7 @@ Associativity: Left Description: \f[B]add\f[R], \f[B]subtract\f[R] .RE .TP -\f[B]=\f[R] \f[B]+=\f[R] \f[B]-=\f[R] \f[B]*=\f[R] \f[B]/=\f[R] \f[B]%=\f[R] \f[B]\[ha]=\f[R] +\f[B]=\f[R] \f[B]+=\f[R] \f[B]\-=\f[R] \f[B]*=\f[R] \f[B]/=\f[R] \f[B]%=\f[R] \f[B]\[ha]=\f[R] Type: Binary .RS .PP @@ -755,18 +827,18 @@ Description: \f[B]boolean or\f[R] .PP The operators will be described in more detail below. .TP -\f[B]++\f[R] \f[B]--\f[R] +\f[B]++\f[R] \f[B]\-\-\f[R] The prefix and postfix \f[B]increment\f[R] and \f[B]decrement\f[R] -operators behave exactly like they would in C. -They require a named expression (see the \f[I]Named Expressions\f[R] -subsection) as an operand. +operators behave exactly like they would in C. They require a named +expression (see the \f[I]Named Expressions\f[R] subsection) as an +operand. .RS .PP The prefix versions of these operators are more efficient; use them where possible. .RE .TP -\f[B]-\f[R] +\f[B]\-\f[R] The \f[B]negation\f[R] operator returns \f[B]0\f[R] if a user attempts to negate any expression with the value \f[B]0\f[R]. Otherwise, a copy of the expression with its sign flipped is returned. @@ -776,7 +848,11 @@ The \f[B]boolean not\f[R] operator returns \f[B]1\f[R] if the expression is \f[B]0\f[R], or \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +\f[B]Warning\f[R]: This operator has a \f[B]different precedence\f[R] +than the equivalent operator in GNU bc(1) and other bc(1) +implementations! +.PP +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]\[ha]\f[R] @@ -787,7 +863,7 @@ The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R]. .RS .PP The second expression must be an integer (no \f[I]scale\f[R]), and if it -is negative, the first value must be non-zero. +is negative, the first value must be non\-zero. .RE .TP \f[B]*\f[R] @@ -805,18 +881,18 @@ returns the quotient. The \f[I]scale\f[R] of the result shall be the value of \f[B]scale\f[R]. .RS .PP -The second expression must be non-zero. +The second expression must be non\-zero. .RE .TP \f[B]%\f[R] The \f[B]modulus\f[R] operator takes two expressions, \f[B]a\f[R] and \f[B]b\f[R], and evaluates them by 1) Computing \f[B]a/b\f[R] to current \f[B]scale\f[R] and 2) Using the result of step 1 to calculate -\f[B]a-(a/b)*b\f[R] to \f[I]scale\f[R] +\f[B]a\-(a/b)*b\f[R] to \f[I]scale\f[R] \f[B]max(scale+scale(b),scale(a))\f[R]. .RS .PP -The second expression must be non-zero. +The second expression must be non\-zero. .RE .TP \f[B]+\f[R] @@ -824,12 +900,12 @@ The \f[B]add\f[R] operator takes two expressions, \f[B]a\f[R] and \f[B]b\f[R], and returns the sum, with a \f[I]scale\f[R] equal to the max of the \f[I]scale\f[R]s of \f[B]a\f[R] and \f[B]b\f[R]. .TP -\f[B]-\f[R] +\f[B]\-\f[R] The \f[B]subtract\f[R] operator takes two expressions, \f[B]a\f[R] and \f[B]b\f[R], and returns the difference, with a \f[I]scale\f[R] equal to the max of the \f[I]scale\f[R]s of \f[B]a\f[R] and \f[B]b\f[R]. .TP -\f[B]=\f[R] \f[B]+=\f[R] \f[B]-=\f[R] \f[B]*=\f[R] \f[B]/=\f[R] \f[B]%=\f[R] \f[B]\[ha]=\f[R] +\f[B]=\f[R] \f[B]+=\f[R] \f[B]\-=\f[R] \f[B]*=\f[R] \f[B]/=\f[R] \f[B]%=\f[R] \f[B]\[ha]=\f[R] The \f[B]assignment\f[R] operators take two expressions, \f[B]a\f[R] and \f[B]b\f[R] where \f[B]a\f[R] is a named expression (see the \f[I]Named Expressions\f[R] subsection). @@ -853,41 +929,39 @@ 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]. +This allowance is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]&&\f[R] The \f[B]boolean and\f[R] operator takes two expressions and returns -\f[B]1\f[R] if both expressions are non-zero, \f[B]0\f[R] otherwise. +\f[B]1\f[R] if both expressions are non\-zero, \f[B]0\f[R] otherwise. .RS .PP -This is \f[I]not\f[R] a short-circuit operator. +This is \f[I]not\f[R] a short\-circuit operator. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]||\f[R] The \f[B]boolean or\f[R] operator takes two expressions and returns -\f[B]1\f[R] if one of the expressions is non-zero, \f[B]0\f[R] +\f[B]1\f[R] if one of the expressions is non\-zero, \f[B]0\f[R] otherwise. .RS .PP -This is \f[I]not\f[R] a short-circuit operator. +This is \f[I]not\f[R] a short\-circuit operator. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .SS Statements -.PP 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 +987,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 @@ -926,10 +1002,10 @@ The \f[B]E\f[R] argument(s) may also be arrays of the form \f[B]FUNCTIONS\f[R] section) if the corresponding parameter in the function definition is an array reference. .PP -Numbers 4, 9, 11, 12, 14, 15, and 16 are \f[B]non-portable +Numbers 4, 9, 11, 12, 14, 15, and 16 are \f[B]non\-portable extensions\f[R]. .PP -Also, as a \f[B]non-portable extension\f[R], any or all of the +Also, as a \f[B]non\-portable extension\f[R], any or all of the expressions in the header of a for loop may be omitted. If the condition (second expression) is omitted, it is assumed to be a constant \f[B]1\f[R]. @@ -946,7 +1022,24 @@ This is only allowed in loops. The \f[B]if\f[R] \f[B]else\f[R] statement does the same thing as in C. .PP 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). +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 +.EX +for (i = 0; i < 3; ++i) i; quit +.EE +.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 @@ -954,12 +1047,11 @@ that is not executed, bc(1) does not quit.) .PP The \f[B]limits\f[R] statement prints the limits that this bc(1) is subject to. -This is like the \f[B]quit\f[R] statement in that it is a compile-time +This is like the \f[B]quit\f[R] statement in that it is a compile\-time command. .PP An expression by itself is evaluated and printed, followed by a newline. .SS Strings -.PP If strings appear as a statement by themselves, they are printed without a trailing newline. .PP @@ -976,9 +1068,8 @@ element that has been assigned a string, an error is raised, and bc(1) resets (see the \f[B]RESET\f[R] section). .PP Assigning strings to variables and array elements and passing them to -functions are \f[B]non-portable extensions\f[R]. +functions are \f[B]non\-portable extensions\f[R]. .SS Print Statement -.PP The \[lq]expressions\[rq] in a \f[B]print\f[R] statement may also be strings. If they are, there are backslash escape sequences that are interpreted @@ -1005,14 +1096,12 @@ below: \f[B]\[rs]t\f[R]: \f[B]\[rs]t\f[R] .PP Any other character following a backslash causes the backslash and -character to be printed as-is. +character to be printed as\-is. .PP -Any non-string expression in a print statement shall be assigned to +Any non\-string expression in a print statement shall be assigned to \f[B]last\f[R], like any other expression that is printed. .SS Stream Statement -.PP -The \[lq]expressions in a \f[B]stream\f[R] statement may also be -strings. +The expressions in a \f[B]stream\f[R] statement may also be strings. .PP If a \f[B]stream\f[R] statement is given a string, it prints the string as though the string had appeared as its own statement. @@ -1022,20 +1111,17 @@ without a newline. If a \f[B]stream\f[R] statement is given a number, a copy of it is truncated and its absolute value is calculated. The result is then printed as though \f[B]obase\f[R] is \f[B]256\f[R] -and each digit is interpreted as an 8-bit ASCII character, making it a +and each digit is interpreted as an 8\-bit ASCII character, making it a byte stream. .SS Order of Evaluation -.PP All expressions in a statment are evaluated left to right, except as necessary to maintain order of operations. This means, for example, assuming that \f[B]i\f[R] is equal to \f[B]0\f[R], in the expression .IP -.nf -\f[C] +.EX a[i++] = i++ -\f[R] -.fi +.EE .PP the first (or 0th) element of \f[B]a\f[R] is set to \f[B]1\f[R], and \f[B]i\f[R] is equal to \f[B]2\f[R] at the end of the expression. @@ -1044,28 +1130,23 @@ This includes function arguments. Thus, assuming \f[B]i\f[R] is equal to \f[B]0\f[R], this means that in the expression .IP -.nf -\f[C] +.EX x(i++, i++) -\f[R] -.fi +.EE .PP the first argument passed to \f[B]x()\f[R] is \f[B]0\f[R], and the second argument is \f[B]1\f[R], while \f[B]i\f[R] is equal to \f[B]2\f[R] before the function starts executing. .SH FUNCTIONS -.PP Function definitions are as follows: .IP -.nf -\f[C] +.EX define I(I,...,I){ auto I,...,I S;...;S return(E) } -\f[R] -.fi +.EE .PP Any \f[B]I\f[R] in the parameter list or \f[B]auto\f[R] list may be replaced with \f[B]I[]\f[R] to make a parameter or \f[B]auto\f[R] var an @@ -1076,10 +1157,10 @@ asterisk in the call; they must be called with just \f[B]I[]\f[R] like normal array parameters and will be automatically converted into references. .PP -As a \f[B]non-portable extension\f[R], the opening brace of a +As a \f[B]non\-portable extension\f[R], the opening brace of a \f[B]define\f[R] statement may appear on the next line. .PP -As a \f[B]non-portable extension\f[R], the return statement may also be +As a \f[B]non\-portable extension\f[R], the return statement may also be in one of the following forms: .IP "1." 3 \f[B]return\f[R] @@ -1093,18 +1174,15 @@ equivalent to \f[B]return (0)\f[R], unless the function is a \f[B]void\f[R] function (see the \f[I]Void Functions\f[R] subsection below). .SS Void Functions -.PP Functions can also be \f[B]void\f[R] functions, defined as follows: .IP -.nf -\f[C] +.EX define void I(I,...,I){ auto I,...,I S;...;S return } -\f[R] -.fi +.EE .PP They can only be used as standalone expressions, where such an expression would be printed alone, except in a print statement. @@ -1118,17 +1196,14 @@ possible to have variables, arrays, and functions named \f[B]void\f[R]. The word \[lq]void\[rq] is only treated specially right after the \f[B]define\f[R] keyword. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .SS Array References -.PP For any array in the parameter list, if the array is declared in the form .IP -.nf -\f[C] +.EX *I[] -\f[R] -.fi +.EE .PP it is a \f[B]reference\f[R]. Any changes to the array in the function are reflected, when the @@ -1136,16 +1211,13 @@ function returns, to the array that was passed in. .PP Other than this, all function arguments are passed by value. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .SH LIBRARY -.PP -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. +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. @@ -1196,7 +1268,6 @@ This is a transcendental function (see the \f[I]Transcendental Functions\f[R] subsection below). .RE .SS Transcendental Functions -.PP All transcendental functions can return slightly inaccurate results, up to 1 ULP (https://en.wikipedia.org/wiki/Unit_in_the_last_place). This is unavoidable, and the article at @@ -1224,8 +1295,7 @@ The transcendental functions in the standard math library are: .IP \[bu] 2 \f[B]j(x, n)\f[R] .SH RESET -.PP -When bc(1) encounters an error or a signal that it has a non-default +When bc(1) encounters an error or a signal that it has a non\-default handler for, it resets. This means that several things happen. .PP @@ -1245,7 +1315,6 @@ Note that this reset behavior is different from the GNU bc(1), which attempts to start executing the statement right after the one that caused an error. .SH PERFORMANCE -.PP Most bc(1) implementations use \f[B]char\f[R] types to calculate the value of \f[B]1\f[R] decimal digit at a time, but that can be slow. This bc(1) does something different. @@ -1268,7 +1337,6 @@ checking. This integer type depends on the value of \f[B]BC_LONG_BIT\f[R], but is always at least twice as large as the integer type used to store digits. .SH LIMITS -.PP The following are the limits on bc(1): .TP \f[B]BC_LONG_BIT\f[R] @@ -1298,24 +1366,24 @@ Set at \f[B]BC_BASE_POW\f[R]. .TP \f[B]BC_DIM_MAX\f[R] The maximum size of arrays. -Set at \f[B]SIZE_MAX-1\f[R]. +Set at \f[B]SIZE_MAX\-1\f[R]. .TP \f[B]BC_SCALE_MAX\f[R] The maximum \f[B]scale\f[R]. -Set at \f[B]BC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]BC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]BC_STRING_MAX\f[R] The maximum length of strings. -Set at \f[B]BC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]BC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]BC_NAME_MAX\f[R] The maximum length of identifiers. -Set at \f[B]BC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]BC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]BC_NUM_MAX\f[R] The maximum length of a number (in decimal digits), which includes digits after the decimal point. -Set at \f[B]BC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]BC_OVERFLOW_MAX\-1\f[R]. .TP Exponent The maximum allowable exponent (positive or negative). @@ -1323,28 +1391,28 @@ Set at \f[B]BC_OVERFLOW_MAX\f[R]. .TP Number of vars The maximum number of vars/arrays. -Set at \f[B]SIZE_MAX-1\f[R]. +Set at \f[B]SIZE_MAX\-1\f[R]. .PP The actual values can be queried with the \f[B]limits\f[R] statement. .PP -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. +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 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 -the \f[B]-s\f[R] option was given. +the \f[B]\-s\f[R] option was given. .TP \f[B]BC_ENV_ARGS\f[R] -This is another way to give command-line arguments to bc(1). -They should be in the same format as all other command-line arguments. +This is another way to give command\-line arguments to bc(1). +They should be in the same format as all other command\-line arguments. These are always processed first, so any files given in \f[B]BC_ENV_ARGS\f[R] will be processed before arguments and files given -on the command-line. +on the command\-line. This gives the user the ability to set up \[lq]standard\[rq] options and files to be used at every invocation. The most useful thing for such files to contain would be useful @@ -1365,14 +1433,14 @@ you can use double quotes as the outside quotes, as in \f[B]\[lq]some quotes. However, handling a file with both kinds of quotes in \f[B]BC_ENV_ARGS\f[R] is not supported due to the complexity of the -parsing, though such files are still supported on the command-line where -the parsing is done by the shell. +parsing, though such files are still supported on the command\-line +where the parsing is done by the shell. .RE .TP \f[B]BC_LINE_LENGTH\f[R] If this environment variable exists and contains an integer that is greater than \f[B]1\f[R] and is less than \f[B]UINT16_MAX\f[R] -(\f[B]2\[ha]16-1\f[R]), bc(1) will output lines to that length, +(\f[B]2\[ha]16\-1\f[R]), bc(1) will output lines to that length, including the backslash (\f[B]\[rs]\f[R]). The default line length is \f[B]70\f[R]. .RS @@ -1384,7 +1452,7 @@ newlines. .TP \f[B]BC_BANNER\f[R] If this environment variable exists and contains an integer, then a -non-zero value activates the copyright banner when bc(1) is in +non\-zero value activates the copyright banner when bc(1) is in interactive mode, while zero deactivates it. .RS .PP @@ -1393,7 +1461,7 @@ section), then this environment variable has no effect because bc(1) does not print the banner when not in interactive mode. .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. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]BC_SIGINT_RESET\f[R] @@ -1403,13 +1471,13 @@ exits on \f[B]SIGINT\f[R] when not in interactive mode. .RS .PP However, when bc(1) is in interactive mode, then if this environment -variable exists and contains an integer, a non-zero value makes bc(1) +variable exists and contains an integer, a non\-zero value makes bc(1) reset on \f[B]SIGINT\f[R], rather than exit, and zero makes bc(1) exit. If this environment variable exists and is \f[I]not\f[R] an integer, then bc(1) will exit on \f[B]SIGINT\f[R]. .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. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]BC_TTY_MODE\f[R] @@ -1418,11 +1486,11 @@ section), then this environment variable has no effect. .RS .PP However, when TTY mode is available, then if this environment variable -exists and contains an integer, then a non-zero value makes bc(1) use +exists and contains an integer, then a non\-zero value makes bc(1) use TTY mode, and zero makes bc(1) not use TTY mode. .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. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]BC_PROMPT\f[R] @@ -1431,30 +1499,46 @@ section), then this environment variable has no effect. .RS .PP However, when TTY mode is available, then if this environment variable -exists and contains an integer, a non-zero value makes bc(1) use a -prompt, and zero or a non-integer makes bc(1) not use a prompt. +exists and contains an integer, a non\-zero value makes bc(1) use a +prompt, and zero or a non\-integer makes bc(1) not use a prompt. If this environment variable does not exist and \f[B]BC_TTY_MODE\f[R] does, then the value of the \f[B]BC_TTY_MODE\f[R] environment variable is used. .PP This environment variable and the \f[B]BC_TTY_MODE\f[R] environment variable override the default, which can be queried with the -\f[B]-h\f[R] or \f[B]--help\f[R] options. +\f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]BC_EXPR_EXIT\f[R] -If any expressions or expression files are given on the command-line -with \f[B]-e\f[R], \f[B]--expression\f[R], \f[B]-f\f[R], or -\f[B]--file\f[R], then if this environment variable exists and contains -an integer, a non-zero value makes bc(1) exit after executing the -expressions and expression files, and a zero value makes bc(1) not exit. +If any expressions or expression files are given on the command\-line +with \f[B]\-e\f[R], \f[B]\-\-expression\f[R], \f[B]\-f\f[R], or +\f[B]\-\-file\f[R], then if this environment variable exists and +contains an integer, a non\-zero value makes bc(1) exit after executing +the expressions and expression files, and a zero value makes bc(1) not +exit. .RS .PP This environment variable overrides the default, which can be queried -with the \f[B]-h\f[R] or \f[B]--help\f[R] options. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE -.SH EXIT STATUS +.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 bc(1) returns the following exit statuses: .TP \f[B]0\f[R] @@ -1470,7 +1554,7 @@ Math errors include divide by \f[B]0\f[R], taking the square root of a negative number, attempting to convert a negative number to a hardware integer, overflow when converting a number to a hardware integer, overflow when calculating the size of a number, and attempting to use a -non-integer where an integer is required. +non\-integer where an integer is required. .PP Converting to a hardware integer happens for the second operand of the power (\f[B]\[ha]\f[R]) operator and the corresponding assignment @@ -1491,7 +1575,7 @@ giving an invalid \f[B]auto\f[R] list, having a duplicate \f[B]auto\f[R]/function parameter, failing to find the end of a code block, attempting to return a value from a \f[B]void\f[R] function, attempting to use a variable as a reference, and using any extensions -when the option \f[B]-s\f[R] or any equivalents were given. +when the option \f[B]\-s\f[R] or any equivalents were given. .RE .TP \f[B]3\f[R] @@ -1514,7 +1598,7 @@ A fatal error occurred. Fatal errors include memory allocation errors, I/O errors, failing to open files, attempting to use files that do not have only ASCII characters (bc(1) only accepts ASCII characters), attempting to open a -directory as a file, and giving invalid command-line options. +directory as a file, and giving invalid command\-line options. .RE .PP The exit status \f[B]4\f[R] is special; when a fatal error occurs, bc(1) @@ -1525,19 +1609,18 @@ interactive mode (see the \f[B]INTERACTIVE MODE\f[R] section), since bc(1) resets its state (see the \f[B]RESET\f[R] section) and accepts more input when one of those errors occurs in interactive mode. This is also the case when interactive mode is forced by the -\f[B]-i\f[R] flag or \f[B]--interactive\f[R] option. +\f[B]\-i\f[R] flag or \f[B]\-\-interactive\f[R] option. .PP These exit statuses allow bc(1) to be used in shell scripting with error checking, and its normal behavior can be forced by using the -\f[B]-i\f[R] flag or \f[B]--interactive\f[R] option. +\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. +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. .PP In interactive mode, bc(1) attempts to recover from errors (see the \f[B]RESET\f[R] section), and in normal execution, flushes @@ -1546,7 +1629,6 @@ bc(1) may also reset on \f[B]SIGINT\f[R] instead of exit, depending on the contents of, or default for, the \f[B]BC_SIGINT_RESET\f[R] environment variable (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). .SH TTY MODE -.PP If \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all connected to a TTY, then \[lq]TTY mode\[rq] is considered to be available, and thus, bc(1) can turn on TTY mode, subject to some @@ -1554,53 +1636,49 @@ settings. .PP If there is the environment variable \f[B]BC_TTY_MODE\f[R] in the environment (see the \f[B]ENVIRONMENT VARIABLES\f[R] section), then if -that environment variable contains a non-zero integer, bc(1) will turn +that environment variable contains a non\-zero integer, bc(1) will turn on TTY mode when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all connected to a TTY. If the \f[B]BC_TTY_MODE\f[R] environment variable exists but is -\f[I]not\f[R] a non-zero integer, then bc(1) will not turn TTY mode on. +\f[I]not\f[R] a non\-zero integer, then bc(1) will not turn TTY mode on. .PP If the environment variable \f[B]BC_TTY_MODE\f[R] does \f[I]not\f[R] exist, the default setting is used. -The default setting can be queried with the \f[B]-h\f[R] or -\f[B]--help\f[R] options. +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 -.PP -Command-line history is only enabled if TTY mode is, i.e., that +.SS Command\-Line History +Command\-line history is only enabled if TTY mode is, i.e., that \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are connected to a TTY and the \f[B]BC_TTY_MODE\f[R] environment variable (see the \f[B]ENVIRONMENT VARIABLES\f[R] section) and its default do not disable TTY mode. See the \f[B]COMMAND LINE HISTORY\f[R] section for more information. .SS Prompt -.PP If TTY mode is available, then a prompt can be enabled. Like TTY mode itself, it can be turned on or off with an environment variable: \f[B]BC_PROMPT\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). .PP -If the environment variable \f[B]BC_PROMPT\f[R] exists and is a non-zero -integer, then the prompt is turned on when \f[B]stdin\f[R], +If the environment variable \f[B]BC_PROMPT\f[R] exists and is a +non\-zero integer, then the prompt is turned on when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are connected to a TTY and the -\f[B]-P\f[R] and \f[B]--no-prompt\f[R] options were not used. +\f[B]\-P\f[R] and \f[B]\-\-no\-prompt\f[R] options were not used. The read prompt will be turned on under the same conditions, except that -the \f[B]-R\f[R] and \f[B]--no-read-prompt\f[R] options must also not be -used. +the \f[B]\-R\f[R] and \f[B]\-\-no\-read\-prompt\f[R] options must also +not be used. .PP However, if \f[B]BC_PROMPT\f[R] does not exist, the prompt can be enabled or disabled with the \f[B]BC_TTY_MODE\f[R] environment variable, -the \f[B]-P\f[R] and \f[B]--no-prompt\f[R] options, and the \f[B]-R\f[R] -and \f[B]--no-read-prompt\f[R] options. +the \f[B]\-P\f[R] and \f[B]\-\-no\-prompt\f[R] options, and the +\f[B]\-R\f[R] and \f[B]\-\-no\-read\-prompt\f[R] options. See the \f[B]ENVIRONMENT VARIABLES\f[R] and \f[B]OPTIONS\f[R] sections for more details. .SH SIGNAL HANDLING -.PP Sending a \f[B]SIGINT\f[R] will cause bc(1) to do one of two things. .PP If bc(1) is not in interactive mode (see the \f[B]INTERACTIVE MODE\f[R] @@ -1609,7 +1687,7 @@ section), or the \f[B]BC_SIGINT_RESET\f[R] environment variable (see the an integer or it is zero, bc(1) will exit. .PP However, if bc(1) is in interactive mode, and the -\f[B]BC_SIGINT_RESET\f[R] or its default is an integer and non-zero, +\f[B]BC_SIGINT_RESET\f[R] or its default is an integer and non\-zero, then bc(1) will stop executing the current input and reset (see the \f[B]RESET\f[R] section) upon receiving a \f[B]SIGINT\f[R]. .PP @@ -1635,12 +1713,11 @@ The one exception is \f[B]SIGHUP\f[R]; in that case, and only when bc(1) is in TTY mode (see the \f[B]TTY MODE\f[R] section), a \f[B]SIGHUP\f[R] will cause bc(1) to clean up and exit. .SH COMMAND LINE HISTORY -.PP -bc(1) supports interactive command-line editing. +bc(1) supports interactive command\-line editing. .PP If bc(1) can be in TTY mode (see the \f[B]TTY MODE\f[R] section), history can be enabled. -This means that command-line history can only be enabled when +This means that command\-line history can only be enabled when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all connected to a TTY. .PP @@ -1653,24 +1730,31 @@ the arrow keys. .PP \f[B]Note\f[R]: tabs are converted to 8 spaces. .SH SEE ALSO -.PP dc(1) .SH STANDARDS -.PP -bc(1) is compliant with the IEEE Std 1003.1-2017 -(\[lq]POSIX.1-2017\[rq]) specification at +bc(1) is compliant with the IEEE Std 1003.1\-2017 +(\[lq]POSIX.1\-2017\[rq]) specification at https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html . -The flags \f[B]-efghiqsvVw\f[R], all long options, and the extensions +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 +Before version \f[B]6.1.0\f[R], this bc(1) had incorrect behavior for +the \f[B]quit\f[R] statement. .PP -None are known. -Report bugs at https://git.yzena.com/gavin/bc. +No other bugs are known. +Report bugs at https://git.gavinhoward.com/gavin/bc . .SH AUTHORS -.PP -Gavin D. -Howard <gavin@yzena.com> and contributors. +Gavin D. Howard \c +.MT gavin@gavinhoward.com +.ME \c +\ and contributors. diff --git a/contrib/bc/manuals/bc/EN.1.md b/contrib/bc/manuals/bc/EN.1.md index 3ebd10f8ecb5..f6ad00930902 100644 --- a/contrib/bc/manuals/bc/EN.1.md +++ b/contrib/bc/manuals/bc/EN.1.md @@ -2,7 +2,7 @@ SPDX-License-Identifier: BSD-2-Clause -Copyright (c) 2018-2021 Gavin D. Howard and contributors. +Copyright (c) 2018-2024 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**. @@ -248,71 +344,12 @@ The following are the options that bc(1) accepts. : Makes bc(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)**, + 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**. -**-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**. - -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**. +letters are equal to **9** plus their position in the alphabet, starting from +**1** (i.e., **A** equals **10**, or **9+1**). + +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 @@ -618,6 +688,9 @@ The operators will be described in more detail below. : The **boolean not** operator returns **1** if the expression is **0**, or **0** otherwise. + **Warning**: This operator has a **different precedence** than the + equivalent operator in GNU bc(1) and other bc(1) implementations! + This is a **non-portable extension**. **\^** @@ -683,10 +756,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 +822,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.) @@ -810,7 +895,7 @@ like any other expression that is printed. ## Stream Statement -The "expressions in a **stream** statement may also be strings. +The expressions in a **stream** statement may also be strings. If a **stream** statement is given a string, it prints the string as though the string had appeared as its own statement. In other words, the **stream** @@ -919,9 +1004,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 +1177,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 +1284,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 +1372,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 +1401,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,14 +1488,21 @@ 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.gavinhoward.com/gavin/bc . # AUTHORS -Gavin D. Howard <gavin@yzena.com> and contributors. +Gavin D. Howard <gavin@gavinhoward.com> and contributors. diff --git a/contrib/bc/manuals/bc/H.1 b/contrib/bc/manuals/bc/H.1 index b3e3880b0723..9dc46ee50dee 100644 --- a/contrib/bc/manuals/bc/H.1 +++ b/contrib/bc/manuals/bc/H.1 @@ -1,7 +1,7 @@ .\" .\" SPDX-License-Identifier: BSD-2-Clause .\" -.\" Copyright (c) 2018-2021 Gavin D. Howard and contributors. +.\" Copyright (c) 2018-2024 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,40 +25,38 @@ .\" 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" "August 2024" "Gavin D. Howard" "General Commands Manual" .nh .ad l .SH NAME -.PP -bc - arbitrary-precision decimal arithmetic language and calculator +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]--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]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]] .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. +somewhat C\-like, but there are differences. Such differences will be noted in this document. .PP After parsing and handling options, this bc(1) reads any files given on 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 +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. @@ -67,19 +65,114 @@ implementations. another bc(1) gives a parse error, it is probably because a word this bc(1) reserves as a keyword is used as the name of a function, variable, or array. -To fix that, use the command-line option \f[B]-r\f[R] \f[I]keyword\f[R], -where \f[I]keyword\f[R] is the keyword that is used as a name in the -script. +To fix that, use the command\-line option \f[B]\-r\f[R] +\f[I]keyword\f[R], where \f[I]keyword\f[R] is the keyword that is used +as a name in the script. For more information, see the \f[B]OPTIONS\f[R] section. .PP If parsing scripts meant for other bc(1) implementations still does not work, that is a bug and should be reported. See the \f[B]BUGS\f[R] section. .SH OPTIONS -.PP The following are the options that bc(1) accepts. .TP -\f[B]-g\f[R], \f[B]--global-stacks\f[R] +\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. .RS @@ -92,19 +185,16 @@ without worrying that the change will affect other functions. Thus, a hypothetical function named \f[B]output(x,b)\f[R] that simply printed \f[B]x\f[R] in base \f[B]b\f[R] could be written like this: .IP -.nf -\f[C] +.EX define void output(x, b) { obase=b x } -\f[R] -.fi +.EE .PP instead of like this: .IP -.nf -\f[C] +.EX define void output(x, b) { auto c c=obase @@ -112,8 +202,7 @@ define void output(x, b) { x obase=c } -\f[R] -.fi +.EE .PP This makes writing functions much easier. .PP @@ -131,12 +220,10 @@ converter, it is possible to replace that capability with various shell aliases. Examples: .IP -.nf -\f[C] -alias d2o=\[dq]bc -e ibase=A -e obase=8\[dq] -alias h2b=\[dq]bc -e ibase=G -e obase=2\[dq] -\f[R] -.fi +.EX +alias d2o=\[dq]bc \-e ibase=A \-e obase=8\[dq] +alias h2b=\[dq]bc \-e ibase=G \-e obase=2\[dq] +.EE .PP Second, if the purpose of a function is to set \f[B]ibase\f[R], \f[B]obase\f[R], \f[B]scale\f[R], or \f[B]seed\f[R] globally for any @@ -146,53 +233,63 @@ desired value for a global. .PP For functions that set \f[B]seed\f[R], the value assigned to \f[B]seed\f[R] is not propagated to parent functions. -This means that the sequence of pseudo-random numbers that they see will -not be the same sequence of pseudo-random numbers that any parent sees. +This means that the sequence of pseudo\-random numbers that they see +will not be the same sequence of pseudo\-random numbers that any parent +sees. This is only the case once \f[B]seed\f[R] has been set. .PP -If a function desires to not affect the sequence of pseudo-random +If a function desires to not affect the sequence of pseudo\-random numbers of its parents, but wants to use the same \f[B]seed\f[R], it can use the following line: .IP -.nf -\f[C] +.EX seed = seed -\f[R] -.fi +.EE .PP If the behavior of this option is desired for every run of bc(1), then users could make sure to define \f[B]BC_ENV_ARGS\f[R] and include this option (see the \f[B]ENVIRONMENT VARIABLES\f[R] section for more details). .PP -If \f[B]-s\f[R], \f[B]-w\f[R], or any equivalents are used, this option -is ignored. +If \f[B]\-s\f[R], \f[B]\-w\f[R], or any equivalents are used, this +option is ignored. .PP -This is a \f[B]non-portable extension\f[R]. +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. +\f[B]\-h\f[R], \f[B]\-\-help\f[R] +Prints a usage message and exits. .TP -\f[B]-i\f[R], \f[B]--interactive\f[R] +\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. (See the \f[B]INTERACTIVE MODE\f[R] section.) .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-L\f[R], \f[B]--no-line-length\f[R] +\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]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-l\f[R], \f[B]--mathlib\f[R] +\f[B]\-l\f[R], \f[B]\-\-mathlib\f[R] Sets \f[B]scale\f[R] (see the \f[B]SYNTAX\f[R] section) to \f[B]20\f[R] and loads the included math library and the extended math library before running any code, including any expressions or files specified on the @@ -202,11 +299,23 @@ command line. To learn what is in the libraries, see the \f[B]LIBRARY\f[R] section. .RE .TP -\f[B]-P\f[R], \f[B]--no-prompt\f[R] +\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 @@ -214,14 +323,31 @@ Most of those users would want to put this option in These options override the \f[B]BC_PROMPT\f[R] and \f[B]BC_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]. +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] +\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 @@ -229,16 +355,16 @@ 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]read()\f[R] built-in function is called. +is only used when the \f[B]read()\f[R] built\-in function is called. .PP These options \f[I]do\f[R] override the \f[B]BC_PROMPT\f[R] and \f[B]BC_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]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-r\f[R] \f[I]keyword\f[R], \f[B]--redefine\f[R]=\f[I]keyword\f[R] +\f[B]\-r\f[R] \f[I]keyword\f[R], \f[B]\-\-redefine\f[R]=\f[I]keyword\f[R] Redefines \f[I]keyword\f[R] in order to allow it to be used as a function, variable, or array name. This is useful when this bc(1) gives parse errors when parsing scripts @@ -294,157 +420,63 @@ 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 -This is a \f[B]non-portable extension\f[R]. +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. +\f[B]\-s\f[R], \f[B]\-\-standard\f[R] +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]. +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. +\f[B]\-v\f[R], \f[B]\-V\f[R], \f[B]\-\-version\f[R] +Print the version information (copyright header) and exits. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-w\f[R], \f[B]--warn\f[R] -Like \f[B]-s\f[R] and \f[B]--standard\f[R], except that warnings (and -not errors) are printed for non-standard extensions and execution +\f[B]\-w\f[R], \f[B]\-\-warn\f[R] +Like \f[B]\-s\f[R] and \f[B]\-\-standard\f[R], except that warnings (and +not errors) are printed for non\-standard extensions and execution continues normally. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-z\f[R], \f[B]--leading-zeroes\f[R] -Makes bc(1) print all numbers greater than \f[B]-1\f[R] and less than +\f[B]\-z\f[R], \f[B]\-\-leading\-zeroes\f[R] +Makes bc(1) print all numbers greater than \f[B]\-1\f[R] and less than \f[B]1\f[R], and not equal to \f[B]0\f[R], with a leading zero. .RS .PP This can be set for individual numbers with the \f[B]plz(x)\f[R], -plznl(x)**, \f[B]pnlz(x)\f[R], and \f[B]pnlznl(x)\f[R] functions in the -extended math library (see the \f[B]LIBRARY\f[R] section). -.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. +\f[B]plznl(x)\f[R], \f[B]pnlz(x)\f[R], and \f[B]pnlznl(x)\f[R] functions +in the extended math library (see the \f[B]LIBRARY\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +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]. +All long options are \f[B]non\-portable extensions\f[R]. .SH STDIN -.PP -If no files or expressions are given by the \f[B]-f\f[R], -\f[B]--file\f[R], \f[B]-e\f[R], or \f[B]--expression\f[R] options, then -bc(1) reads from \f[B]stdin\f[R]. +If no files or expressions are given by the \f[B]\-f\f[R], +\f[B]\-\-file\f[R], \f[B]\-e\f[R], or \f[B]\-\-expression\f[R] options, +then bc(1) reads from \f[B]stdin\f[R]. .PP However, there are a few caveats to this. .PP @@ -458,8 +490,7 @@ Second, after an \f[B]if\f[R] statement, bc(1) doesn\[cq]t know if an \f[B]else\f[R] statement will follow, so it will not execute until it knows there will not be an \f[B]else\f[R] statement. .SH STDOUT -.PP -Any non-error output is written to \f[B]stdout\f[R]. +Any non\-error output is written to \f[B]stdout\f[R]. In addition, if history (see the \f[B]HISTORY\f[R] section) and the prompt (see the \f[B]TTY MODE\f[R] section) are enabled, both are output to \f[B]stdout\f[R]. @@ -467,7 +498,7 @@ to \f[B]stdout\f[R]. \f[B]Note\f[R]: Unlike other bc(1) implementations, this bc(1) will issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot write to \f[B]stdout\f[R], so if \f[B]stdout\f[R] is closed, as in -\f[B]bc >&-\f[R], it will quit with an error. +\f[B]bc >&\-\f[R], it will quit with an error. This is done so that bc(1) can report problems when \f[B]stdout\f[R] is redirected to a file. .PP @@ -475,13 +506,12 @@ If there are scripts that depend on the behavior of other bc(1) implementations, it is recommended that those scripts be changed to redirect \f[B]stdout\f[R] to \f[B]/dev/null\f[R]. .SH STDERR -.PP Any error output is written to \f[B]stderr\f[R]. .PP \f[B]Note\f[R]: Unlike other bc(1) implementations, this bc(1) will issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot write to \f[B]stderr\f[R], so if \f[B]stderr\f[R] is closed, as in -\f[B]bc 2>&-\f[R], it will quit with an error. +\f[B]bc 2>&\-\f[R], it will quit with an error. This is done so that bc(1) can exit with an error code when \f[B]stderr\f[R] is redirected to a file. .PP @@ -489,12 +519,10 @@ If there are scripts that depend on the behavior of other bc(1) implementations, it is recommended that those scripts be changed to redirect \f[B]stderr\f[R] to \f[B]/dev/null\f[R]. .SH SYNTAX -.PP -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. +The syntax for bc(1) programs is mostly C\-like, with some differences. +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 @@ -502,32 +530,32 @@ In the sections below, \f[B]E\f[R] means expression, \f[B]S\f[R] means statement, and \f[B]I\f[R] means identifier. .PP Identifiers (\f[B]I\f[R]) start with a lowercase letter and can be -followed by any number (up to \f[B]BC_NAME_MAX-1\f[R]) of lowercase -letters (\f[B]a-z\f[R]), digits (\f[B]0-9\f[R]), and underscores +followed by any number (up to \f[B]BC_NAME_MAX\-1\f[R]) of lowercase +letters (\f[B]a\-z\f[R]), digits (\f[B]0\-9\f[R]), and underscores (\f[B]_\f[R]). -The regex is \f[B][a-z][a-z0-9_]*\f[R]. +The regex is \f[B][a\-z][a\-z0\-9_]*\f[R]. Identifiers with more than one character (letter) are a -\f[B]non-portable extension\f[R]. +\f[B]non\-portable extension\f[R]. .PP \f[B]ibase\f[R] is a global variable determining how to interpret constant numbers. It is the \[lq]input\[rq] base, or the number base used for interpreting input numbers. \f[B]ibase\f[R] is initially \f[B]10\f[R]. -If the \f[B]-s\f[R] (\f[B]--standard\f[R]) and \f[B]-w\f[R] -(\f[B]--warn\f[R]) flags were not given on the command line, the max +If the \f[B]\-s\f[R] (\f[B]\-\-standard\f[R]) and \f[B]\-w\f[R] +(\f[B]\-\-warn\f[R]) flags were not given on the command line, the max allowable value for \f[B]ibase\f[R] is \f[B]36\f[R]. Otherwise, it is \f[B]16\f[R]. The min allowable value for \f[B]ibase\f[R] is \f[B]2\f[R]. The max allowable value for \f[B]ibase\f[R] can be queried in bc(1) -programs with the \f[B]maxibase()\f[R] built-in function. +programs with the \f[B]maxibase()\f[R] built\-in function. .PP \f[B]obase\f[R] is a global variable determining how to output results. It is the \[lq]output\[rq] base, or the number base used for outputting numbers. \f[B]obase\f[R] is initially \f[B]10\f[R]. The max allowable value for \f[B]obase\f[R] is \f[B]BC_BASE_MAX\f[R] and -can be queried in bc(1) programs with the \f[B]maxobase()\f[R] built-in +can be queried in bc(1) programs with the \f[B]maxobase()\f[R] built\-in function. The min allowable value for \f[B]obase\f[R] is \f[B]0\f[R]. If \f[B]obase\f[R] is \f[B]0\f[R], values are output in scientific @@ -535,8 +563,8 @@ notation, and if \f[B]obase\f[R] is \f[B]1\f[R], values are output in engineering notation. Otherwise, values are output in the specified base. .PP -Outputting in scientific and engineering notations are \f[B]non-portable -extensions\f[R]. +Outputting in scientific and engineering notations are +\f[B]non\-portable extensions\f[R]. .PP The \f[I]scale\f[R] of an expression is the number of digits in the result of the expression right of the decimal point, and \f[B]scale\f[R] @@ -546,7 +574,7 @@ exceptions. \f[B]scale\f[R] cannot be negative. The max allowable value for \f[B]scale\f[R] is \f[B]BC_SCALE_MAX\f[R] and can be queried in bc(1) programs with the \f[B]maxscale()\f[R] -built-in function. +built\-in function. .PP bc(1) has both \f[I]global\f[R] variables and \f[I]local\f[R] variables. All \f[I]local\f[R] variables are local to the function; they are @@ -571,20 +599,18 @@ The value that is printed is also assigned to the special variable \f[B]last\f[R]. A single dot (\f[B].\f[R]) may also be used as a synonym for \f[B]last\f[R]. -These are \f[B]non-portable extensions\f[R]. +These are \f[B]non\-portable extensions\f[R]. .PP Either semicolons or newlines may separate statements. .SS Comments -.PP There are two kinds of comments: .IP "1." 3 Block comments are enclosed in \f[B]/*\f[R] and \f[B]*/\f[R]. .IP "2." 3 Line comments go from \f[B]#\f[R] until, and not including, the next newline. -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .SS Named Expressions -.PP The following are named expressions in bc(1): .IP "1." 3 Variables: \f[B]I\f[R] @@ -601,26 +627,26 @@ Array Elements: \f[B]I[E]\f[R] .IP "7." 3 \f[B]last\f[R] or a single dot (\f[B].\f[R]) .PP -Numbers 6 and 7 are \f[B]non-portable extensions\f[R]. +Numbers 6 and 7 are \f[B]non\-portable extensions\f[R]. .PP -The meaning of \f[B]seed\f[R] is dependent on the current pseudo-random +The meaning of \f[B]seed\f[R] is dependent on the current pseudo\-random number generator but is guaranteed to not change except for new major versions. .PP The \f[I]scale\f[R] and sign of the value may be significant. .PP If a previously used \f[B]seed\f[R] value is assigned to \f[B]seed\f[R] -and used again, the pseudo-random number generator is guaranteed to -produce the same sequence of pseudo-random numbers as it did when the +and used again, the pseudo\-random number generator is guaranteed to +produce the same sequence of pseudo\-random numbers as it did when the \f[B]seed\f[R] value was previously used. .PP The exact value assigned to \f[B]seed\f[R] is not guaranteed to be returned if \f[B]seed\f[R] is queried again immediately. However, if \f[B]seed\f[R] \f[I]does\f[R] return a different value, both values, when assigned to \f[B]seed\f[R], are guaranteed to produce the -same sequence of pseudo-random numbers. +same sequence of pseudo\-random numbers. This means that certain values assigned to \f[B]seed\f[R] will -\f[I]not\f[R] produce unique sequences of pseudo-random numbers. +\f[I]not\f[R] produce unique sequences of pseudo\-random numbers. The value of \f[B]seed\f[R] will change after any use of the \f[B]rand()\f[R] and \f[B]irand(E)\f[R] operands (see the \f[I]Operands\f[R] subsection below), except if the parameter passed to @@ -641,7 +667,6 @@ Named expressions are required as the operand of of \f[B]assignment\f[R] operators (see the \f[I]Operators\f[R] subsection). .SS Operands -.PP The following are valid operands in bc(1): .IP " 1." 4 Numbers (see the \f[I]Numbers\f[R] subsection below). @@ -651,99 +676,113 @@ Array indices (\f[B]I[E]\f[R]). \f[B](E)\f[R]: The value of \f[B]E\f[R] (used to change precedence). .IP " 4." 4 \f[B]sqrt(E)\f[R]: The square root of \f[B]E\f[R]. -\f[B]E\f[R] must be non-negative. +\f[B]E\f[R] must be non\-negative. .IP " 5." 4 \f[B]length(E)\f[R]: The number of significant decimal digits in \f[B]E\f[R]. Returns \f[B]1\f[R] for \f[B]0\f[R] with no decimal places. If given a string, the length of the string is returned. -Passing a string to \f[B]length(E)\f[R] is a \f[B]non-portable +Passing a string to \f[B]length(E)\f[R] is a \f[B]non\-portable extension\f[R]. .IP " 6." 4 \f[B]length(I[])\f[R]: The number of elements in the array \f[B]I\f[R]. -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .IP " 7." 4 \f[B]scale(E)\f[R]: The \f[I]scale\f[R] of \f[B]E\f[R]. .IP " 8." 4 \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]. +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. 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 +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 "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, -which must be non-zero. +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 +This is a \f[B]non\-portable extension\f[R]. +.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 +that number as a one\-character string. +This is a \f[B]non\-portable extension\f[R]. +.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[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). The \f[B]E\f[R] argument(s) may also be arrays of the form \f[B]I[]\f[R], which will automatically be turned into array references (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 +This is a \f[B]non\-portable extension\f[R]. +.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 +This is a \f[B]non\-portable extension\f[R]. +.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 +This is a \f[B]non\-portable extension\f[R]. +.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 +This is a \f[B]non\-portable extension\f[R]. +.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 +This is a \f[B]non\-portable extension\f[R]. +.IP "21." 4 \f[B]global_stacks()\f[R]: \f[B]0\f[R] if global stacks are not enabled -with the \f[B]-g\f[R] or \f[B]--global-stacks\f[R] options, non-zero -otherwise. +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 +This is a \f[B]non\-portable extension\f[R]. +.IP "22." 4 \f[B]leading_zero()\f[R]: \f[B]0\f[R] if leading zeroes are not enabled -with the \f[B]-z\f[R] or \f[B]\[en]leading-zeroes\f[R] options, non-zero -otherwise. +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 -\f[B]rand()\f[R]: A pseudo-random integer between \f[B]0\f[R] +This is a \f[B]non\-portable extension\f[R]. +.IP "23." 4 +\f[B]rand()\f[R]: A pseudo\-random integer between \f[B]0\f[R] (inclusive) and \f[B]BC_RAND_MAX\f[R] (inclusive). Using this operand will change the value of \f[B]seed\f[R]. -This is a \f[B]non-portable extension\f[R]. -.IP "21." 4 -\f[B]irand(E)\f[R]: A pseudo-random integer between \f[B]0\f[R] +This is a \f[B]non\-portable extension\f[R]. +.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 +If \f[B]E\f[R] is negative or is a non\-integer (\f[B]E\f[R]\[cq]s \f[I]scale\f[R] is not \f[B]0\f[R]), an error is raised, and bc(1) resets (see the \f[B]RESET\f[R] section) while \f[B]seed\f[R] remains unchanged. If \f[B]E\f[R] is larger than \f[B]BC_RAND_MAX\f[R], the higher bound is -honored by generating several pseudo-random integers, multiplying them +honored by generating several pseudo\-random integers, multiplying them by appropriate powers of \f[B]BC_RAND_MAX+1\f[R], and adding them together. Thus, the size of integer that can be generated with this operand is @@ -752,52 +791,83 @@ Using this operand will change the value of \f[B]seed\f[R], unless the 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 +This is a \f[B]non\-portable extension\f[R]. +.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]. +This is a \f[B]non\-portable extension\f[R]. .PP The integers generated by \f[B]rand()\f[R] and \f[B]irand(E)\f[R] are guaranteed to be as unbiased as possible, subject to the limitations of -the pseudo-random number generator. +the pseudo\-random number generator. .PP -\f[B]Note\f[R]: The values returned by the pseudo-random number +\f[B]Note\f[R]: The values returned by the pseudo\-random number generator with \f[B]rand()\f[R] and \f[B]irand(E)\f[R] are guaranteed to \f[I]NOT\f[R] be cryptographically secure. -This is a consequence of using a seeded pseudo-random number generator. +This is a consequence of using a seeded pseudo\-random number generator. However, they \f[I]are\f[R] guaranteed to be reproducible with identical \f[B]seed\f[R] values. -This means that the pseudo-random values from bc(1) should only be used -where a reproducible stream of pseudo-random numbers is +This means that the pseudo\-random values from bc(1) should only be used +where a reproducible stream of pseudo\-random numbers is \f[I]ESSENTIAL\f[R]. -In any other case, use a non-seeded pseudo-random number generator. +In any other case, use a non\-seeded pseudo\-random number generator. .SS Numbers -.PP 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]. The exponent (the portion after the \f[B]e\f[R]) must be an integer. An example is \f[B]1.89237e9\f[R], which is equal to \f[B]1892370000\f[R]. -Negative exponents are also allowed, so \f[B]4.2890e-3\f[R] is equal to +Negative exponents are also allowed, so \f[B]4.2890e\-3\f[R] is equal to \f[B]0.0042890\f[R]. .PP -Using scientific notation is an error or warning if the \f[B]-s\f[R] or -\f[B]-w\f[R], respectively, command-line options (or equivalents) are +Using scientific notation is an error or warning if the \f[B]\-s\f[R] or +\f[B]\-w\f[R], respectively, command\-line options (or equivalents) are given. .PP \f[B]WARNING\f[R]: Both the number and the exponent in scientific @@ -807,17 +877,16 @@ of the current \f[B]ibase\f[R]. For example, if \f[B]ibase\f[R] is \f[B]16\f[R] and bc(1) is given the number string \f[B]FFeA\f[R], the resulting decimal number will be \f[B]2550000000000\f[R], and if bc(1) is given the number string -\f[B]10e-4\f[R], the resulting decimal number will be \f[B]0.0016\f[R]. +\f[B]10e\-4\f[R], the resulting decimal number will be \f[B]0.0016\f[R]. .PP -Accepting input as scientific notation is a \f[B]non-portable +Accepting input as scientific notation is a \f[B]non\-portable extension\f[R]. .SS Operators -.PP The following arithmetic and logical operators can be used. They are listed in order of decreasing precedence. Operators in the same group have the same precedence. .TP -\f[B]++\f[R] \f[B]--\f[R] +\f[B]++\f[R] \f[B]\-\-\f[R] Type: Prefix and Postfix .RS .PP @@ -826,7 +895,7 @@ Associativity: None Description: \f[B]increment\f[R], \f[B]decrement\f[R] .RE .TP -\f[B]-\f[R] \f[B]!\f[R] +\f[B]\-\f[R] \f[B]!\f[R] Type: Prefix .RS .PP @@ -871,7 +940,7 @@ Associativity: Left Description: \f[B]multiply\f[R], \f[B]divide\f[R], \f[B]modulus\f[R] .RE .TP -\f[B]+\f[R] \f[B]-\f[R] +\f[B]+\f[R] \f[B]\-\f[R] Type: Binary .RS .PP @@ -889,7 +958,7 @@ Associativity: Left Description: \f[B]shift left\f[R], \f[B]shift right\f[R] .RE .TP -\f[B]=\f[R] \f[B]<<=\f[R] \f[B]>>=\f[R] \f[B]+=\f[R] \f[B]-=\f[R] \f[B]*=\f[R] \f[B]/=\f[R] \f[B]%=\f[R] \f[B]\[ha]=\f[R] \f[B]\[at]=\f[R] +\f[B]=\f[R] \f[B]<<=\f[R] \f[B]>>=\f[R] \f[B]+=\f[R] \f[B]\-=\f[R] \f[B]*=\f[R] \f[B]/=\f[R] \f[B]%=\f[R] \f[B]\[ha]=\f[R] \f[B]\[at]=\f[R] Type: Binary .RS .PP @@ -927,18 +996,18 @@ Description: \f[B]boolean or\f[R] .PP The operators will be described in more detail below. .TP -\f[B]++\f[R] \f[B]--\f[R] +\f[B]++\f[R] \f[B]\-\-\f[R] The prefix and postfix \f[B]increment\f[R] and \f[B]decrement\f[R] -operators behave exactly like they would in C. -They require a named expression (see the \f[I]Named Expressions\f[R] -subsection) as an operand. +operators behave exactly like they would in C. They require a named +expression (see the \f[I]Named Expressions\f[R] subsection) as an +operand. .RS .PP The prefix versions of these operators are more efficient; use them where possible. .RE .TP -\f[B]-\f[R] +\f[B]\-\f[R] The \f[B]negation\f[R] operator returns \f[B]0\f[R] if a user attempts to negate any expression with the value \f[B]0\f[R]. Otherwise, a copy of the expression with its sign flipped is returned. @@ -948,7 +1017,11 @@ The \f[B]boolean not\f[R] operator returns \f[B]1\f[R] if the expression is \f[B]0\f[R], or \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +\f[B]Warning\f[R]: This operator has a \f[B]different precedence\f[R] +than the equivalent operator in GNU bc(1) and other bc(1) +implementations! +.PP +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]$\f[R] @@ -956,7 +1029,7 @@ The \f[B]truncation\f[R] operator returns a copy of the given expression with all of its \f[I]scale\f[R] removed. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]\[at]\f[R] @@ -970,9 +1043,9 @@ more). .RS .PP The second expression must be an integer (no \f[I]scale\f[R]) and -non-negative. +non\-negative. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]\[ha]\f[R] @@ -983,7 +1056,7 @@ The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R]. .RS .PP The second expression must be an integer (no \f[I]scale\f[R]), and if it -is negative, the first value must be non-zero. +is negative, the first value must be non\-zero. .RE .TP \f[B]*\f[R] @@ -1001,18 +1074,18 @@ returns the quotient. The \f[I]scale\f[R] of the result shall be the value of \f[B]scale\f[R]. .RS .PP -The second expression must be non-zero. +The second expression must be non\-zero. .RE .TP \f[B]%\f[R] The \f[B]modulus\f[R] operator takes two expressions, \f[B]a\f[R] and \f[B]b\f[R], and evaluates them by 1) Computing \f[B]a/b\f[R] to current \f[B]scale\f[R] and 2) Using the result of step 1 to calculate -\f[B]a-(a/b)*b\f[R] to \f[I]scale\f[R] +\f[B]a\-(a/b)*b\f[R] to \f[I]scale\f[R] \f[B]max(scale+scale(b),scale(a))\f[R]. .RS .PP -The second expression must be non-zero. +The second expression must be non\-zero. .RE .TP \f[B]+\f[R] @@ -1020,7 +1093,7 @@ The \f[B]add\f[R] operator takes two expressions, \f[B]a\f[R] and \f[B]b\f[R], and returns the sum, with a \f[I]scale\f[R] equal to the max of the \f[I]scale\f[R]s of \f[B]a\f[R] and \f[B]b\f[R]. .TP -\f[B]-\f[R] +\f[B]\-\f[R] The \f[B]subtract\f[R] operator takes two expressions, \f[B]a\f[R] and \f[B]b\f[R], and returns the difference, with a \f[I]scale\f[R] equal to the max of the \f[I]scale\f[R]s of \f[B]a\f[R] and \f[B]b\f[R]. @@ -1032,9 +1105,9 @@ decimal point moved \f[B]b\f[R] places to the right. .RS .PP The second expression must be an integer (no \f[I]scale\f[R]) and -non-negative. +non\-negative. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]>>\f[R] @@ -1044,12 +1117,12 @@ decimal point moved \f[B]b\f[R] places to the left. .RS .PP The second expression must be an integer (no \f[I]scale\f[R]) and -non-negative. +non\-negative. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]=\f[R] \f[B]<<=\f[R] \f[B]>>=\f[R] \f[B]+=\f[R] \f[B]-=\f[R] \f[B]*=\f[R] \f[B]/=\f[R] \f[B]%=\f[R] \f[B]\[ha]=\f[R] \f[B]\[at]=\f[R] +\f[B]=\f[R] \f[B]<<=\f[R] \f[B]>>=\f[R] \f[B]+=\f[R] \f[B]\-=\f[R] \f[B]*=\f[R] \f[B]/=\f[R] \f[B]%=\f[R] \f[B]\[ha]=\f[R] \f[B]\[at]=\f[R] The \f[B]assignment\f[R] operators take two expressions, \f[B]a\f[R] and \f[B]b\f[R] where \f[B]a\f[R] is a named expression (see the \f[I]Named Expressions\f[R] subsection). @@ -1062,7 +1135,7 @@ the corresponding arithmetic operator and the result is assigned to \f[B]a\f[R]. .PP The \f[B]assignment\f[R] operators that correspond to operators that are -extensions are themselves \f[B]non-portable extensions\f[R]. +extensions are themselves \f[B]non\-portable extensions\f[R]. .RE .TP \f[B]==\f[R] \f[B]<=\f[R] \f[B]>=\f[R] \f[B]!=\f[R] \f[B]<\f[R] \f[B]>\f[R] @@ -1076,41 +1149,39 @@ 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]. +This allowance is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]&&\f[R] The \f[B]boolean and\f[R] operator takes two expressions and returns -\f[B]1\f[R] if both expressions are non-zero, \f[B]0\f[R] otherwise. +\f[B]1\f[R] if both expressions are non\-zero, \f[B]0\f[R] otherwise. .RS .PP -This is \f[I]not\f[R] a short-circuit operator. +This is \f[I]not\f[R] a short\-circuit operator. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]||\f[R] The \f[B]boolean or\f[R] operator takes two expressions and returns -\f[B]1\f[R] if one of the expressions is non-zero, \f[B]0\f[R] +\f[B]1\f[R] if one of the expressions is non\-zero, \f[B]0\f[R] otherwise. .RS .PP -This is \f[I]not\f[R] a short-circuit operator. +This is \f[I]not\f[R] a short\-circuit operator. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .SS Statements -.PP 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 +1207,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 @@ -1149,10 +1222,10 @@ The \f[B]E\f[R] argument(s) may also be arrays of the form \f[B]FUNCTIONS\f[R] section) if the corresponding parameter in the function definition is an array reference. .PP -Numbers 4, 9, 11, 12, 14, 15, and 16 are \f[B]non-portable +Numbers 4, 9, 11, 12, 14, 15, and 16 are \f[B]non\-portable extensions\f[R]. .PP -Also, as a \f[B]non-portable extension\f[R], any or all of the +Also, as a \f[B]non\-portable extension\f[R], any or all of the expressions in the header of a for loop may be omitted. If the condition (second expression) is omitted, it is assumed to be a constant \f[B]1\f[R]. @@ -1169,7 +1242,24 @@ This is only allowed in loops. The \f[B]if\f[R] \f[B]else\f[R] statement does the same thing as in C. .PP 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). +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 +.EX +for (i = 0; i < 3; ++i) i; quit +.EE +.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 @@ -1177,7 +1267,7 @@ that is not executed, bc(1) does not quit.) .PP The \f[B]limits\f[R] statement prints the limits that this bc(1) is subject to. -This is like the \f[B]quit\f[R] statement in that it is a compile-time +This is like the \f[B]quit\f[R] statement in that it is a compile\-time command. .PP An expression by itself is evaluated and printed, followed by a newline. @@ -1190,13 +1280,12 @@ Scientific notation is activated by assigning \f[B]0\f[R] to To deactivate them, just assign a different value to \f[B]obase\f[R]. .PP Scientific notation and engineering notation are disabled if bc(1) is -run with either the \f[B]-s\f[R] or \f[B]-w\f[R] command-line options +run with either the \f[B]\-s\f[R] or \f[B]\-w\f[R] command\-line options (or equivalents). .PP Printing numbers in scientific notation and/or engineering notation is a -\f[B]non-portable extension\f[R]. +\f[B]non\-portable extension\f[R]. .SS Strings -.PP If strings appear as a statement by themselves, they are printed without a trailing newline. .PP @@ -1213,9 +1302,8 @@ element that has been assigned a string, an error is raised, and bc(1) resets (see the \f[B]RESET\f[R] section). .PP Assigning strings to variables and array elements and passing them to -functions are \f[B]non-portable extensions\f[R]. +functions are \f[B]non\-portable extensions\f[R]. .SS Print Statement -.PP The \[lq]expressions\[rq] in a \f[B]print\f[R] statement may also be strings. If they are, there are backslash escape sequences that are interpreted @@ -1242,14 +1330,12 @@ below: \f[B]\[rs]t\f[R]: \f[B]\[rs]t\f[R] .PP Any other character following a backslash causes the backslash and -character to be printed as-is. +character to be printed as\-is. .PP -Any non-string expression in a print statement shall be assigned to +Any non\-string expression in a print statement shall be assigned to \f[B]last\f[R], like any other expression that is printed. .SS Stream Statement -.PP -The \[lq]expressions in a \f[B]stream\f[R] statement may also be -strings. +The expressions in a \f[B]stream\f[R] statement may also be strings. .PP If a \f[B]stream\f[R] statement is given a string, it prints the string as though the string had appeared as its own statement. @@ -1259,20 +1345,17 @@ without a newline. If a \f[B]stream\f[R] statement is given a number, a copy of it is truncated and its absolute value is calculated. The result is then printed as though \f[B]obase\f[R] is \f[B]256\f[R] -and each digit is interpreted as an 8-bit ASCII character, making it a +and each digit is interpreted as an 8\-bit ASCII character, making it a byte stream. .SS Order of Evaluation -.PP All expressions in a statment are evaluated left to right, except as necessary to maintain order of operations. This means, for example, assuming that \f[B]i\f[R] is equal to \f[B]0\f[R], in the expression .IP -.nf -\f[C] +.EX a[i++] = i++ -\f[R] -.fi +.EE .PP the first (or 0th) element of \f[B]a\f[R] is set to \f[B]1\f[R], and \f[B]i\f[R] is equal to \f[B]2\f[R] at the end of the expression. @@ -1281,28 +1364,23 @@ This includes function arguments. Thus, assuming \f[B]i\f[R] is equal to \f[B]0\f[R], this means that in the expression .IP -.nf -\f[C] +.EX x(i++, i++) -\f[R] -.fi +.EE .PP the first argument passed to \f[B]x()\f[R] is \f[B]0\f[R], and the second argument is \f[B]1\f[R], while \f[B]i\f[R] is equal to \f[B]2\f[R] before the function starts executing. .SH FUNCTIONS -.PP Function definitions are as follows: .IP -.nf -\f[C] +.EX define I(I,...,I){ auto I,...,I S;...;S return(E) } -\f[R] -.fi +.EE .PP Any \f[B]I\f[R] in the parameter list or \f[B]auto\f[R] list may be replaced with \f[B]I[]\f[R] to make a parameter or \f[B]auto\f[R] var an @@ -1313,10 +1391,10 @@ asterisk in the call; they must be called with just \f[B]I[]\f[R] like normal array parameters and will be automatically converted into references. .PP -As a \f[B]non-portable extension\f[R], the opening brace of a +As a \f[B]non\-portable extension\f[R], the opening brace of a \f[B]define\f[R] statement may appear on the next line. .PP -As a \f[B]non-portable extension\f[R], the return statement may also be +As a \f[B]non\-portable extension\f[R], the return statement may also be in one of the following forms: .IP "1." 3 \f[B]return\f[R] @@ -1330,18 +1408,15 @@ equivalent to \f[B]return (0)\f[R], unless the function is a \f[B]void\f[R] function (see the \f[I]Void Functions\f[R] subsection below). .SS Void Functions -.PP Functions can also be \f[B]void\f[R] functions, defined as follows: .IP -.nf -\f[C] +.EX define void I(I,...,I){ auto I,...,I S;...;S return } -\f[R] -.fi +.EE .PP They can only be used as standalone expressions, where such an expression would be printed alone, except in a print statement. @@ -1355,17 +1430,14 @@ possible to have variables, arrays, and functions named \f[B]void\f[R]. The word \[lq]void\[rq] is only treated specially right after the \f[B]define\f[R] keyword. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .SS Array References -.PP For any array in the parameter list, if the array is declared in the form .IP -.nf -\f[C] +.EX *I[] -\f[R] -.fi +.EE .PP it is a \f[B]reference\f[R]. Any changes to the array in the function are reflected, when the @@ -1373,20 +1445,17 @@ function returns, to the array that was passed in. .PP Other than this, all function arguments are passed by value. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .SH LIBRARY -.PP All of the functions below, including the functions in the extended math library (see the \f[I]Extended Library\f[R] subsection below), are -available when the \f[B]-l\f[R] or \f[B]--mathlib\f[R] command-line +available when the \f[B]\-l\f[R] or \f[B]\-\-mathlib\f[R] command\-line flags are given, except that the extended math library is not available -when the \f[B]-s\f[R] option, the \f[B]-w\f[R] option, or equivalents +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. @@ -1437,14 +1506,12 @@ This is a transcendental function (see the \f[I]Transcendental Functions\f[R] subsection below). .RE .SS Extended Library -.PP 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] +\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]. +The extended library is a \f[B]non\-portable extension\f[R]. .TP \f[B]p(x, y)\f[R] Calculates \f[B]x\f[R] to the power of \f[B]y\f[R], even if \f[B]y\f[R] @@ -1472,6 +1539,14 @@ the rounding mode round away from \f[B]0\f[R] \f[B]f(x)\f[R] Returns the factorial of the truncated absolute value of \f[B]x\f[R]. .TP +\f[B]max(a, b)\f[R] +Returns \f[B]a\f[R] if \f[B]a\f[R] is greater than \f[B]b\f[R]; +otherwise, returns \f[B]b\f[R]. +.TP +\f[B]min(a, b)\f[R] +Returns \f[B]a\f[R] if \f[B]a\f[R] is less than \f[B]b\f[R]; otherwise, +returns \f[B]b\f[R]. +.TP \f[B]perm(n, k)\f[R] Returns the permutation of the truncated absolute value of \f[B]n\f[R] of the truncated absolute value of \f[B]k\f[R], if \f[B]k <= n\f[R]. @@ -1482,6 +1557,10 @@ Returns the combination of the truncated absolute value of \f[B]n\f[R] of the truncated absolute value of \f[B]k\f[R], if \f[B]k <= n\f[R]. If not, it returns \f[B]0\f[R]. .TP +\f[B]fib(n)\f[R] +Returns the Fibonacci number of the truncated absolute value of +\f[B]n\f[R]. +.TP \f[B]l2(x)\f[R] Returns the logarithm base \f[B]2\f[R] of \f[B]x\f[R]. .RS @@ -1553,11 +1632,11 @@ Otherwise, if \f[B]x\f[R] is greater than \f[B]0\f[R], it returns If \f[B]x\f[R] is less than \f[B]0\f[R], and \f[B]y\f[R] is greater than or equal to \f[B]0\f[R], it returns \f[B]a(y/x)+pi\f[R]. If \f[B]x\f[R] is less than \f[B]0\f[R], and \f[B]y\f[R] is less than -\f[B]0\f[R], it returns \f[B]a(y/x)-pi\f[R]. +\f[B]0\f[R], it returns \f[B]a(y/x)\-pi\f[R]. If \f[B]x\f[R] is equal to \f[B]0\f[R], and \f[B]y\f[R] is greater than \f[B]0\f[R], it returns \f[B]pi/2\f[R]. If \f[B]x\f[R] is equal to \f[B]0\f[R], and \f[B]y\f[R] is less than -\f[B]0\f[R], it returns \f[B]-pi/2\f[R]. +\f[B]0\f[R], it returns \f[B]\-pi/2\f[R]. .RS .PP This function is the same as the \f[B]atan2()\f[R] function in many @@ -1591,7 +1670,7 @@ Functions\f[R] subsection below). Returns the tangent of \f[B]x\f[R], which is assumed to be in radians. .RS .PP -If \f[B]x\f[R] is equal to \f[B]1\f[R] or \f[B]-1\f[R], this raises an +If \f[B]x\f[R] is equal to \f[B]1\f[R] or \f[B]\-1\f[R], this raises an error and causes bc(1) to reset (see the \f[B]RESET\f[R] section). .PP This is an alias of \f[B]t(x)\f[R]. @@ -1619,11 +1698,11 @@ Otherwise, if \f[B]x\f[R] is greater than \f[B]0\f[R], it returns If \f[B]x\f[R] is less than \f[B]0\f[R], and \f[B]y\f[R] is greater than or equal to \f[B]0\f[R], it returns \f[B]a(y/x)+pi\f[R]. If \f[B]x\f[R] is less than \f[B]0\f[R], and \f[B]y\f[R] is less than -\f[B]0\f[R], it returns \f[B]a(y/x)-pi\f[R]. +\f[B]0\f[R], it returns \f[B]a(y/x)\-pi\f[R]. If \f[B]x\f[R] is equal to \f[B]0\f[R], and \f[B]y\f[R] is greater than \f[B]0\f[R], it returns \f[B]pi/2\f[R]. If \f[B]x\f[R] is equal to \f[B]0\f[R], and \f[B]y\f[R] is less than -\f[B]0\f[R], it returns \f[B]-pi/2\f[R]. +\f[B]0\f[R], it returns \f[B]\-pi/2\f[R]. .RS .PP This function is the same as the \f[B]atan2()\f[R] function in many @@ -1652,7 +1731,7 @@ Functions\f[R] subsection below). .RE .TP \f[B]frand(p)\f[R] -Generates a pseudo-random number between \f[B]0\f[R] (inclusive) and +Generates a pseudo\-random number between \f[B]0\f[R] (inclusive) and \f[B]1\f[R] (exclusive) with the number of decimal digits after the decimal point equal to the truncated absolute value of \f[B]p\f[R]. If \f[B]p\f[R] is not \f[B]0\f[R], then calling this function will @@ -1661,14 +1740,22 @@ If \f[B]p\f[R] is \f[B]0\f[R], then \f[B]0\f[R] is returned, and \f[B]seed\f[R] is \f[I]not\f[R] changed. .TP \f[B]ifrand(i, p)\f[R] -Generates a pseudo-random number that is between \f[B]0\f[R] (inclusive) -and the truncated absolute value of \f[B]i\f[R] (exclusive) with the -number of decimal digits after the decimal point equal to the truncated -absolute value of \f[B]p\f[R]. +Generates a pseudo\-random number that is between \f[B]0\f[R] +(inclusive) and the truncated absolute value of \f[B]i\f[R] (exclusive) +with the number of decimal digits after the decimal point equal to the +truncated absolute value of \f[B]p\f[R]. If the absolute value of \f[B]i\f[R] is greater than or equal to \f[B]2\f[R], and \f[B]p\f[R] is not \f[B]0\f[R], then calling this function will change the value of \f[B]seed\f[R]; otherwise, \f[B]0\f[R] -is returned and \f[B]seed\f[R] is not changed. +is returned, and \f[B]seed\f[R] is not changed. +.TP +\f[B]i2rand(a, b)\f[R] +Takes the truncated value of \f[B]a\f[R] and \f[B]b\f[R] and uses them +as inclusive bounds to enerate a pseudo\-random integer. +If the difference of the truncated values of \f[B]a\f[R] and \f[B]b\f[R] +is \f[B]0\f[R], then the truncated value is returned, and \f[B]seed\f[R] +is \f[I]not\f[R] changed. +Otherwise, this function will change the value of \f[B]seed\f[R]. .TP \f[B]srand(x)\f[R] Returns \f[B]x\f[R] with its sign flipped with probability @@ -1710,8 +1797,8 @@ If you want to use signed two\[cq]s complement arguments, use .TP \f[B]bshl(a, b)\f[R] Takes the truncated absolute value of both \f[B]a\f[R] and \f[B]b\f[R] -and calculates and returns the result of \f[B]a\f[R] bit-shifted left by -\f[B]b\f[R] places. +and calculates and returns the result of \f[B]a\f[R] bit\-shifted left +by \f[B]b\f[R] places. .RS .PP If you want to use signed two\[cq]s complement arguments, use @@ -1721,7 +1808,7 @@ If you want to use signed two\[cq]s complement arguments, use \f[B]bshr(a, b)\f[R] Takes the truncated absolute value of both \f[B]a\f[R] and \f[B]b\f[R] and calculates and returns the truncated result of \f[B]a\f[R] -bit-shifted right by \f[B]b\f[R] places. +bit\-shifted right by \f[B]b\f[R] places. .RS .PP If you want to use signed two\[cq]s complement arguments, use @@ -1740,7 +1827,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]bnot8(x)\f[R] Does a bitwise not of the truncated absolute value of \f[B]x\f[R] as -though it has \f[B]8\f[R] binary digits (1 unsigned byte). +though it has \f[B]8\f[R] binary digits (\f[B]1\f[R] unsigned byte). .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1749,7 +1836,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]bnot16(x)\f[R] Does a bitwise not of the truncated absolute value of \f[B]x\f[R] as -though it has \f[B]16\f[R] binary digits (2 unsigned bytes). +though it has \f[B]16\f[R] binary digits (\f[B]2\f[R] unsigned bytes). .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1758,7 +1845,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]bnot32(x)\f[R] Does a bitwise not of the truncated absolute value of \f[B]x\f[R] as -though it has \f[B]32\f[R] binary digits (4 unsigned bytes). +though it has \f[B]32\f[R] binary digits (\f[B]4\f[R] unsigned bytes). .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1767,7 +1854,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]bnot64(x)\f[R] Does a bitwise not of the truncated absolute value of \f[B]x\f[R] as -though it has \f[B]64\f[R] binary digits (8 unsigned bytes). +though it has \f[B]64\f[R] binary digits (\f[B]8\f[R] unsigned bytes). .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1785,7 +1872,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]brevn(x, n)\f[R] Runs a bit reversal on the truncated absolute value of \f[B]x\f[R] as -though it has the same number of 8-bit bytes as the truncated absolute +though it has the same number of 8\-bit bytes as the truncated absolute value of \f[B]n\f[R]. .RS .PP @@ -1795,7 +1882,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]brev8(x)\f[R] Runs a bit reversal on the truncated absolute value of \f[B]x\f[R] as -though it has 8 binary digits (1 unsigned byte). +though it has 8 binary digits (\f[B]1\f[R] unsigned byte). .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1804,7 +1891,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]brev16(x)\f[R] Runs a bit reversal on the truncated absolute value of \f[B]x\f[R] as -though it has 16 binary digits (2 unsigned bytes). +though it has 16 binary digits (\f[B]2\f[R] unsigned bytes). .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1813,7 +1900,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]brev32(x)\f[R] Runs a bit reversal on the truncated absolute value of \f[B]x\f[R] as -though it has 32 binary digits (4 unsigned bytes). +though it has 32 binary digits (\f[B]4\f[R] unsigned bytes). .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1822,7 +1909,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]brev64(x)\f[R] Runs a bit reversal on the truncated absolute value of \f[B]x\f[R] as -though it has 64 binary digits (8 unsigned bytes). +though it has 64 binary digits (\f[B]8\f[R] unsigned bytes). .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1840,11 +1927,11 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]broln(x, p, n)\f[R] Does a left bitwise rotatation of the truncated absolute value of -\f[B]x\f[R], as though it has the same number of unsigned 8-bit bytes as -the truncated absolute value of \f[B]n\f[R], by the number of places +\f[B]x\f[R], as though it has the same number of unsigned 8\-bit bytes +as the truncated absolute value of \f[B]n\f[R], by the number of places equal to the truncated absolute value of \f[B]p\f[R] modded by the \f[B]2\f[R] to the power of the number of binary digits in \f[B]n\f[R] -8-bit bytes. +8\-bit bytes. .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1875,7 +1962,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]brol32(x, p)\f[R] Does a left bitwise rotatation of the truncated absolute value of -\f[B]x\f[R], as though it has \f[B]32\f[R] binary digits (\f[B]2\f[R] +\f[B]x\f[R], as though it has \f[B]32\f[R] binary digits (\f[B]4\f[R] unsigned bytes), by the number of places equal to the truncated absolute value of \f[B]p\f[R] modded by \f[B]2\f[R] to the power of \f[B]32\f[R]. .RS @@ -1886,7 +1973,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]brol64(x, p)\f[R] Does a left bitwise rotatation of the truncated absolute value of -\f[B]x\f[R], as though it has \f[B]64\f[R] binary digits (\f[B]2\f[R] +\f[B]x\f[R], as though it has \f[B]64\f[R] binary digits (\f[B]8\f[R] unsigned bytes), by the number of places equal to the truncated absolute value of \f[B]p\f[R] modded by \f[B]2\f[R] to the power of \f[B]64\f[R]. .RS @@ -1898,9 +1985,9 @@ If you want to a use signed two\[cq]s complement argument, use \f[B]brol(x, p)\f[R] Does a left bitwise rotatation of the truncated absolute value of \f[B]x\f[R], as though it has the minimum number of power of two -unsigned 8-bit bytes, by the number of places equal to the truncated +unsigned 8\-bit bytes, by the number of places equal to the truncated absolute value of \f[B]p\f[R] modded by 2 to the power of the number of -binary digits in the minimum number of 8-bit bytes. +binary digits in the minimum number of 8\-bit bytes. .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1909,11 +1996,11 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]brorn(x, p, n)\f[R] Does a right bitwise rotatation of the truncated absolute value of -\f[B]x\f[R], as though it has the same number of unsigned 8-bit bytes as -the truncated absolute value of \f[B]n\f[R], by the number of places +\f[B]x\f[R], as though it has the same number of unsigned 8\-bit bytes +as the truncated absolute value of \f[B]n\f[R], by the number of places equal to the truncated absolute value of \f[B]p\f[R] modded by the \f[B]2\f[R] to the power of the number of binary digits in \f[B]n\f[R] -8-bit bytes. +8\-bit bytes. .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1967,9 +2054,9 @@ If you want to a use signed two\[cq]s complement argument, use \f[B]bror(x, p)\f[R] Does a right bitwise rotatation of the truncated absolute value of \f[B]x\f[R], as though it has the minimum number of power of two -unsigned 8-bit bytes, by the number of places equal to the truncated +unsigned 8\-bit bytes, by the number of places equal to the truncated absolute value of \f[B]p\f[R] modded by 2 to the power of the number of -binary digits in the minimum number of 8-bit bytes. +binary digits in the minimum number of 8\-bit bytes. .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -2023,7 +2110,7 @@ If you want to a use signed two\[cq]s complement argument, use .RE .TP \f[B]bunrev(t)\f[R] -Assumes \f[B]t\f[R] is a bitwise-reversed number with an extra set bit +Assumes \f[B]t\f[R] is a bitwise\-reversed number with an extra set bit one place more significant than the real most significant bit (which was the least significant bit in the original number). This number is reversed and returned without the extra set bit. @@ -2034,29 +2121,29 @@ meant to be used by users, but it can be. .RE .TP \f[B]plz(x)\f[R] -If \f[B]x\f[R] is not equal to \f[B]0\f[R] and greater that \f[B]-1\f[R] -and less than \f[B]1\f[R], it is printed with a leading zero, regardless -of the use of the \f[B]-z\f[R] option (see the \f[B]OPTIONS\f[R] -section) and without a trailing newline. +If \f[B]x\f[R] is not equal to \f[B]0\f[R] and greater that +\f[B]\-1\f[R] and less than \f[B]1\f[R], it is printed with a leading +zero, regardless of the use of the \f[B]\-z\f[R] option (see the +\f[B]OPTIONS\f[R] section) and without a trailing newline. .RS .PP Otherwise, \f[B]x\f[R] is printed normally, without a trailing newline. .RE .TP \f[B]plznl(x)\f[R] -If \f[B]x\f[R] is not equal to \f[B]0\f[R] and greater that \f[B]-1\f[R] -and less than \f[B]1\f[R], it is printed with a leading zero, regardless -of the use of the \f[B]-z\f[R] option (see the \f[B]OPTIONS\f[R] -section) and with a trailing newline. +If \f[B]x\f[R] is not equal to \f[B]0\f[R] and greater that +\f[B]\-1\f[R] and less than \f[B]1\f[R], it is printed with a leading +zero, regardless of the use of the \f[B]\-z\f[R] option (see the +\f[B]OPTIONS\f[R] section) and with a trailing newline. .RS .PP Otherwise, \f[B]x\f[R] is printed normally, with a trailing newline. .RE .TP \f[B]pnlz(x)\f[R] -If \f[B]x\f[R] is not equal to \f[B]0\f[R] and greater that \f[B]-1\f[R] -and less than \f[B]1\f[R], it is printed without a leading zero, -regardless of the use of the \f[B]-z\f[R] option (see the +If \f[B]x\f[R] is not equal to \f[B]0\f[R] and greater that +\f[B]\-1\f[R] and less than \f[B]1\f[R], it is printed without a leading +zero, regardless of the use of the \f[B]\-z\f[R] option (see the \f[B]OPTIONS\f[R] section) and without a trailing newline. .RS .PP @@ -2064,9 +2151,9 @@ Otherwise, \f[B]x\f[R] is printed normally, without a trailing newline. .RE .TP \f[B]pnlznl(x)\f[R] -If \f[B]x\f[R] is not equal to \f[B]0\f[R] and greater that \f[B]-1\f[R] -and less than \f[B]1\f[R], it is printed without a leading zero, -regardless of the use of the \f[B]-z\f[R] option (see the +If \f[B]x\f[R] is not equal to \f[B]0\f[R] and greater that +\f[B]\-1\f[R] and less than \f[B]1\f[R], it is printed without a leading +zero, regardless of the use of the \f[B]\-z\f[R] option (see the \f[B]OPTIONS\f[R] section) and with a trailing newline. .RS .PP @@ -2078,22 +2165,22 @@ Returns the numbers of unsigned integer bytes required to hold the truncated absolute value of \f[B]x\f[R]. .TP \f[B]sbytes(x)\f[R] -Returns the numbers of signed, two\[cq]s-complement integer bytes +Returns the numbers of signed, two\[cq]s\-complement integer bytes required to hold the truncated value of \f[B]x\f[R]. .TP \f[B]s2u(x)\f[R] -Returns \f[B]x\f[R] if it is non-negative. +Returns \f[B]x\f[R] if it is non\-negative. If it \f[I]is\f[R] negative, then it calculates what \f[B]x\f[R] would -be as a 2\[cq]s-complement signed integer and returns the non-negative +be as a 2\[cq]s\-complement signed integer and returns the non\-negative integer that would have the same representation in binary. .TP \f[B]s2un(x,n)\f[R] -Returns \f[B]x\f[R] if it is non-negative. +Returns \f[B]x\f[R] if it is non\-negative. If it \f[I]is\f[R] negative, then it calculates what \f[B]x\f[R] would -be as a 2\[cq]s-complement signed integer with \f[B]n\f[R] bytes and -returns the non-negative integer that would have the same representation -in binary. -If \f[B]x\f[R] cannot fit into \f[B]n\f[R] 2\[cq]s-complement signed +be as a 2\[cq]s\-complement signed integer with \f[B]n\f[R] bytes and +returns the non\-negative integer that would have the same +representation in binary. +If \f[B]x\f[R] cannot fit into \f[B]n\f[R] 2\[cq]s\-complement signed bytes, it is truncated to fit. .TP \f[B]hex(x)\f[R] @@ -2137,7 +2224,7 @@ subsection of the \f[B]FUNCTIONS\f[R] section). .TP \f[B]int(x)\f[R] Outputs the representation, in binary and hexadecimal, of \f[B]x\f[R] as -a signed, two\[cq]s-complement integer in as few power of two bytes as +a signed, two\[cq]s\-complement integer in as few power of two bytes as possible. Both outputs are split into bytes separated by spaces. .RS @@ -2165,7 +2252,7 @@ subsection of the \f[B]FUNCTIONS\f[R] section). .TP \f[B]intn(x, n)\f[R] Outputs the representation, in binary and hexadecimal, of \f[B]x\f[R] as -a signed, two\[cq]s-complement integer in \f[B]n\f[R] bytes. +a signed, two\[cq]s\-complement integer in \f[B]n\f[R] bytes. Both outputs are split into bytes separated by spaces. .RS .PP @@ -2193,7 +2280,7 @@ subsection of the \f[B]FUNCTIONS\f[R] section). .TP \f[B]int8(x)\f[R] Outputs the representation, in binary and hexadecimal, of \f[B]x\f[R] as -a signed, two\[cq]s-complement integer in \f[B]1\f[R] byte. +a signed, two\[cq]s\-complement integer in \f[B]1\f[R] byte. Both outputs are split into bytes separated by spaces. .RS .PP @@ -2221,7 +2308,7 @@ subsection of the \f[B]FUNCTIONS\f[R] section). .TP \f[B]int16(x)\f[R] Outputs the representation, in binary and hexadecimal, of \f[B]x\f[R] as -a signed, two\[cq]s-complement integer in \f[B]2\f[R] bytes. +a signed, two\[cq]s\-complement integer in \f[B]2\f[R] bytes. Both outputs are split into bytes separated by spaces. .RS .PP @@ -2249,7 +2336,7 @@ subsection of the \f[B]FUNCTIONS\f[R] section). .TP \f[B]int32(x)\f[R] Outputs the representation, in binary and hexadecimal, of \f[B]x\f[R] as -a signed, two\[cq]s-complement integer in \f[B]4\f[R] bytes. +a signed, two\[cq]s\-complement integer in \f[B]4\f[R] bytes. Both outputs are split into bytes separated by spaces. .RS .PP @@ -2277,7 +2364,7 @@ subsection of the \f[B]FUNCTIONS\f[R] section). .TP \f[B]int64(x)\f[R] Outputs the representation, in binary and hexadecimal, of \f[B]x\f[R] as -a signed, two\[cq]s-complement integer in \f[B]8\f[R] bytes. +a signed, two\[cq]s\-complement integer in \f[B]8\f[R] bytes. Both outputs are split into bytes separated by spaces. .RS .PP @@ -2324,14 +2411,13 @@ subsection of the \f[B]FUNCTIONS\f[R] section). \f[B]output_byte(x, i)\f[R] Outputs byte \f[B]i\f[R] of the truncated absolute value of \f[B]x\f[R], where \f[B]0\f[R] is the least significant byte and \f[B]number_of_bytes -- 1\f[R] is the most significant byte. +\- 1\f[R] is the most significant byte. .RS .PP This is a \f[B]void\f[R] function (see the \f[I]Void Functions\f[R] subsection of the \f[B]FUNCTIONS\f[R] section). .RE .SS Transcendental Functions -.PP All transcendental functions can return slightly inaccurate results, up to 1 ULP (https://en.wikipedia.org/wiki/Unit_in_the_last_place). This is unavoidable, and the article at @@ -2387,8 +2473,7 @@ The transcendental functions in the extended math library are: .IP \[bu] 2 \f[B]d2r(x)\f[R] .SH RESET -.PP -When bc(1) encounters an error or a signal that it has a non-default +When bc(1) encounters an error or a signal that it has a non\-default handler for, it resets. This means that several things happen. .PP @@ -2408,7 +2493,6 @@ Note that this reset behavior is different from the GNU bc(1), which attempts to start executing the statement right after the one that caused an error. .SH PERFORMANCE -.PP Most bc(1) implementations use \f[B]char\f[R] types to calculate the value of \f[B]1\f[R] decimal digit at a time, but that can be slow. This bc(1) does something different. @@ -2431,7 +2515,6 @@ checking. This integer type depends on the value of \f[B]BC_LONG_BIT\f[R], but is always at least twice as large as the integer type used to store digits. .SH LIMITS -.PP The following are the limits on bc(1): .TP \f[B]BC_LONG_BIT\f[R] @@ -2461,29 +2544,29 @@ Set at \f[B]BC_BASE_POW\f[R]. .TP \f[B]BC_DIM_MAX\f[R] The maximum size of arrays. -Set at \f[B]SIZE_MAX-1\f[R]. +Set at \f[B]SIZE_MAX\-1\f[R]. .TP \f[B]BC_SCALE_MAX\f[R] The maximum \f[B]scale\f[R]. -Set at \f[B]BC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]BC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]BC_STRING_MAX\f[R] The maximum length of strings. -Set at \f[B]BC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]BC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]BC_NAME_MAX\f[R] The maximum length of identifiers. -Set at \f[B]BC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]BC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]BC_NUM_MAX\f[R] The maximum length of a number (in decimal digits), which includes digits after the decimal point. -Set at \f[B]BC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]BC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]BC_RAND_MAX\f[R] The maximum integer (inclusive) returned by the \f[B]rand()\f[R] operand. -Set at \f[B]2\[ha]BC_LONG_BIT-1\f[R]. +Set at \f[B]2\[ha]BC_LONG_BIT\-1\f[R]. .TP Exponent The maximum allowable exponent (positive or negative). @@ -2491,28 +2574,28 @@ Set at \f[B]BC_OVERFLOW_MAX\f[R]. .TP Number of vars The maximum number of vars/arrays. -Set at \f[B]SIZE_MAX-1\f[R]. +Set at \f[B]SIZE_MAX\-1\f[R]. .PP The actual values can be queried with the \f[B]limits\f[R] statement. .PP -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. +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 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 -the \f[B]-s\f[R] option was given. +the \f[B]\-s\f[R] option was given. .TP \f[B]BC_ENV_ARGS\f[R] -This is another way to give command-line arguments to bc(1). -They should be in the same format as all other command-line arguments. +This is another way to give command\-line arguments to bc(1). +They should be in the same format as all other command\-line arguments. These are always processed first, so any files given in \f[B]BC_ENV_ARGS\f[R] will be processed before arguments and files given -on the command-line. +on the command\-line. This gives the user the ability to set up \[lq]standard\[rq] options and files to be used at every invocation. The most useful thing for such files to contain would be useful @@ -2533,14 +2616,14 @@ you can use double quotes as the outside quotes, as in \f[B]\[lq]some quotes. However, handling a file with both kinds of quotes in \f[B]BC_ENV_ARGS\f[R] is not supported due to the complexity of the -parsing, though such files are still supported on the command-line where -the parsing is done by the shell. +parsing, though such files are still supported on the command\-line +where the parsing is done by the shell. .RE .TP \f[B]BC_LINE_LENGTH\f[R] If this environment variable exists and contains an integer that is greater than \f[B]1\f[R] and is less than \f[B]UINT16_MAX\f[R] -(\f[B]2\[ha]16-1\f[R]), bc(1) will output lines to that length, +(\f[B]2\[ha]16\-1\f[R]), bc(1) will output lines to that length, including the backslash (\f[B]\[rs]\f[R]). The default line length is \f[B]70\f[R]. .RS @@ -2552,7 +2635,7 @@ newlines. .TP \f[B]BC_BANNER\f[R] If this environment variable exists and contains an integer, then a -non-zero value activates the copyright banner when bc(1) is in +non\-zero value activates the copyright banner when bc(1) is in interactive mode, while zero deactivates it. .RS .PP @@ -2561,7 +2644,7 @@ section), then this environment variable has no effect because bc(1) does not print the banner when not in interactive mode. .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. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]BC_SIGINT_RESET\f[R] @@ -2571,13 +2654,13 @@ exits on \f[B]SIGINT\f[R] when not in interactive mode. .RS .PP However, when bc(1) is in interactive mode, then if this environment -variable exists and contains an integer, a non-zero value makes bc(1) +variable exists and contains an integer, a non\-zero value makes bc(1) reset on \f[B]SIGINT\f[R], rather than exit, and zero makes bc(1) exit. If this environment variable exists and is \f[I]not\f[R] an integer, then bc(1) will exit on \f[B]SIGINT\f[R]. .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. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]BC_TTY_MODE\f[R] @@ -2586,11 +2669,11 @@ section), then this environment variable has no effect. .RS .PP However, when TTY mode is available, then if this environment variable -exists and contains an integer, then a non-zero value makes bc(1) use +exists and contains an integer, then a non\-zero value makes bc(1) use TTY mode, and zero makes bc(1) not use TTY mode. .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. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]BC_PROMPT\f[R] @@ -2599,30 +2682,46 @@ section), then this environment variable has no effect. .RS .PP However, when TTY mode is available, then if this environment variable -exists and contains an integer, a non-zero value makes bc(1) use a -prompt, and zero or a non-integer makes bc(1) not use a prompt. +exists and contains an integer, a non\-zero value makes bc(1) use a +prompt, and zero or a non\-integer makes bc(1) not use a prompt. If this environment variable does not exist and \f[B]BC_TTY_MODE\f[R] does, then the value of the \f[B]BC_TTY_MODE\f[R] environment variable is used. .PP This environment variable and the \f[B]BC_TTY_MODE\f[R] environment variable override the default, which can be queried with the -\f[B]-h\f[R] or \f[B]--help\f[R] options. +\f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]BC_EXPR_EXIT\f[R] -If any expressions or expression files are given on the command-line -with \f[B]-e\f[R], \f[B]--expression\f[R], \f[B]-f\f[R], or -\f[B]--file\f[R], then if this environment variable exists and contains -an integer, a non-zero value makes bc(1) exit after executing the -expressions and expression files, and a zero value makes bc(1) not exit. +If any expressions or expression files are given on the command\-line +with \f[B]\-e\f[R], \f[B]\-\-expression\f[R], \f[B]\-f\f[R], or +\f[B]\-\-file\f[R], then if this environment variable exists and +contains an integer, a non\-zero value makes bc(1) exit after executing +the expressions and expression files, and a zero value makes bc(1) not +exit. .RS .PP This environment variable overrides the default, which can be queried -with the \f[B]-h\f[R] or \f[B]--help\f[R] options. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE -.SH EXIT STATUS +.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 bc(1) returns the following exit statuses: .TP \f[B]0\f[R] @@ -2636,10 +2735,10 @@ since math errors will happen in the process of normal execution. .PP Math errors include divide by \f[B]0\f[R], taking the square root of a negative number, using a negative number as a bound for the -pseudo-random number generator, attempting to convert a negative number +pseudo\-random number generator, attempting to convert a negative number to a hardware integer, overflow when converting a number to a hardware integer, overflow when calculating the size of a number, and attempting -to use a non-integer where an integer is required. +to use a non\-integer where an integer is required. .PP Converting to a hardware integer happens for the second operand of the power (\f[B]\[ha]\f[R]), places (\f[B]\[at]\f[R]), left shift @@ -2661,7 +2760,7 @@ giving an invalid \f[B]auto\f[R] list, having a duplicate \f[B]auto\f[R]/function parameter, failing to find the end of a code block, attempting to return a value from a \f[B]void\f[R] function, attempting to use a variable as a reference, and using any extensions -when the option \f[B]-s\f[R] or any equivalents were given. +when the option \f[B]\-s\f[R] or any equivalents were given. .RE .TP \f[B]3\f[R] @@ -2684,7 +2783,7 @@ A fatal error occurred. Fatal errors include memory allocation errors, I/O errors, failing to open files, attempting to use files that do not have only ASCII characters (bc(1) only accepts ASCII characters), attempting to open a -directory as a file, and giving invalid command-line options. +directory as a file, and giving invalid command\-line options. .RE .PP The exit status \f[B]4\f[R] is special; when a fatal error occurs, bc(1) @@ -2695,19 +2794,18 @@ interactive mode (see the \f[B]INTERACTIVE MODE\f[R] section), since bc(1) resets its state (see the \f[B]RESET\f[R] section) and accepts more input when one of those errors occurs in interactive mode. This is also the case when interactive mode is forced by the -\f[B]-i\f[R] flag or \f[B]--interactive\f[R] option. +\f[B]\-i\f[R] flag or \f[B]\-\-interactive\f[R] option. .PP These exit statuses allow bc(1) to be used in shell scripting with error checking, and its normal behavior can be forced by using the -\f[B]-i\f[R] flag or \f[B]--interactive\f[R] option. +\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. +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. .PP In interactive mode, bc(1) attempts to recover from errors (see the \f[B]RESET\f[R] section), and in normal execution, flushes @@ -2716,7 +2814,6 @@ bc(1) may also reset on \f[B]SIGINT\f[R] instead of exit, depending on the contents of, or default for, the \f[B]BC_SIGINT_RESET\f[R] environment variable (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). .SH TTY MODE -.PP If \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all connected to a TTY, then \[lq]TTY mode\[rq] is considered to be available, and thus, bc(1) can turn on TTY mode, subject to some @@ -2724,45 +2821,42 @@ settings. .PP If there is the environment variable \f[B]BC_TTY_MODE\f[R] in the environment (see the \f[B]ENVIRONMENT VARIABLES\f[R] section), then if -that environment variable contains a non-zero integer, bc(1) will turn +that environment variable contains a non\-zero integer, bc(1) will turn on TTY mode when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all connected to a TTY. If the \f[B]BC_TTY_MODE\f[R] environment variable exists but is -\f[I]not\f[R] a non-zero integer, then bc(1) will not turn TTY mode on. +\f[I]not\f[R] a non\-zero integer, then bc(1) will not turn TTY mode on. .PP If the environment variable \f[B]BC_TTY_MODE\f[R] does \f[I]not\f[R] exist, the default setting is used. -The default setting can be queried with the \f[B]-h\f[R] or -\f[B]--help\f[R] options. +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 -.PP If TTY mode is available, then a prompt can be enabled. Like TTY mode itself, it can be turned on or off with an environment variable: \f[B]BC_PROMPT\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). .PP -If the environment variable \f[B]BC_PROMPT\f[R] exists and is a non-zero -integer, then the prompt is turned on when \f[B]stdin\f[R], +If the environment variable \f[B]BC_PROMPT\f[R] exists and is a +non\-zero integer, then the prompt is turned on when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are connected to a TTY and the -\f[B]-P\f[R] and \f[B]--no-prompt\f[R] options were not used. +\f[B]\-P\f[R] and \f[B]\-\-no\-prompt\f[R] options were not used. The read prompt will be turned on under the same conditions, except that -the \f[B]-R\f[R] and \f[B]--no-read-prompt\f[R] options must also not be -used. +the \f[B]\-R\f[R] and \f[B]\-\-no\-read\-prompt\f[R] options must also +not be used. .PP However, if \f[B]BC_PROMPT\f[R] does not exist, the prompt can be enabled or disabled with the \f[B]BC_TTY_MODE\f[R] environment variable, -the \f[B]-P\f[R] and \f[B]--no-prompt\f[R] options, and the \f[B]-R\f[R] -and \f[B]--no-read-prompt\f[R] options. +the \f[B]\-P\f[R] and \f[B]\-\-no\-prompt\f[R] options, and the +\f[B]\-R\f[R] and \f[B]\-\-no\-read\-prompt\f[R] options. See the \f[B]ENVIRONMENT VARIABLES\f[R] and \f[B]OPTIONS\f[R] sections for more details. .SH SIGNAL HANDLING -.PP Sending a \f[B]SIGINT\f[R] will cause bc(1) to do one of two things. .PP If bc(1) is not in interactive mode (see the \f[B]INTERACTIVE MODE\f[R] @@ -2771,7 +2865,7 @@ section), or the \f[B]BC_SIGINT_RESET\f[R] environment variable (see the an integer or it is zero, bc(1) will exit. .PP However, if bc(1) is in interactive mode, and the -\f[B]BC_SIGINT_RESET\f[R] or its default is an integer and non-zero, +\f[B]BC_SIGINT_RESET\f[R] or its default is an integer and non\-zero, then bc(1) will stop executing the current input and reset (see the \f[B]RESET\f[R] section) upon receiving a \f[B]SIGINT\f[R]. .PP @@ -2794,20 +2888,23 @@ the user to continue. \f[B]SIGTERM\f[R] and \f[B]SIGQUIT\f[R] cause bc(1) to clean up and exit, and it uses the default handler for all other signals. .SH LOCALES -.PP This bc(1) ships with support for adding error messages for different locales and thus, supports \f[B]LC_MESSAGES\f[R]. .SH SEE ALSO -.PP dc(1) .SH STANDARDS -.PP -bc(1) is compliant with the IEEE Std 1003.1-2017 -(\[lq]POSIX.1-2017\[rq]) specification at +bc(1) is compliant with the IEEE Std 1003.1\-2017 +(\[lq]POSIX.1\-2017\[rq]) specification at https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html . -The flags \f[B]-efghiqsvVw\f[R], all long options, and the extensions +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]. @@ -2815,10 +2912,13 @@ the value of \f[B]LC_NUMERIC\f[R]. This bc(1) supports error messages for different locales, and thus, it supports \f[B]LC_MESSAGES\f[R]. .SH BUGS +Before version \f[B]6.1.0\f[R], this bc(1) had incorrect behavior for +the \f[B]quit\f[R] statement. .PP -None are known. -Report bugs at https://git.yzena.com/gavin/bc. +No other bugs are known. +Report bugs at https://git.gavinhoward.com/gavin/bc . .SH AUTHORS -.PP -Gavin D. -Howard <gavin@yzena.com> and contributors. +Gavin D. Howard \c +.MT gavin@gavinhoward.com +.ME \c +\ and contributors. diff --git a/contrib/bc/manuals/bc/H.1.md b/contrib/bc/manuals/bc/H.1.md index f494e5632967..fbc0658d8171 100644 --- a/contrib/bc/manuals/bc/H.1.md +++ b/contrib/bc/manuals/bc/H.1.md @@ -2,7 +2,7 @@ SPDX-License-Identifier: BSD-2-Clause -Copyright (c) 2018-2021 Gavin D. Howard and contributors. +Copyright (c) 2018-2024 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**. @@ -268,80 +372,12 @@ The following are the options that bc(1) accepts. : Makes bc(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)**, + 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**. -**-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**. - -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**. +letters are equal to **9** plus their position in the alphabet, starting from +**1** (i.e., **A** equals **10**, or **9+1**). + +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 @@ -742,6 +811,9 @@ The operators will be described in more detail below. : The **boolean not** operator returns **1** if the expression is **0**, or **0** otherwise. + **Warning**: This operator has a **different precedence** than the + equivalent operator in GNU bc(1) and other bc(1) implementations! + This is a **non-portable extension**. **\$** @@ -849,10 +921,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 +987,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.) @@ -987,7 +1071,7 @@ like any other expression that is printed. ## Stream Statement -The "expressions in a **stream** statement may also be strings. +The expressions in a **stream** statement may also be strings. If a **stream** statement is given a string, it prints the string as though the string had appeared as its own statement. In other words, the **stream** @@ -1099,9 +1183,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 +1232,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**. @@ -1180,6 +1262,14 @@ The extended library is a **non-portable extension**. : Returns the factorial of the truncated absolute value of **x**. +**max(a, b)** + +: Returns **a** if **a** is greater than **b**; otherwise, returns **b**. + +**min(a, b)** + +: Returns **a** if **a** is less than **b**; otherwise, returns **b**. + **perm(n, k)** : Returns the permutation of the truncated absolute value of **n** of the @@ -1190,6 +1280,10 @@ The extended library is a **non-portable extension**. : Returns the combination of the truncated absolute value of **n** of the truncated absolute value of **k**, if **k \<= n**. If not, it returns **0**. +**fib(n)** + +: Returns the Fibonacci number of the truncated absolute value of **n**. + **l2(x)** : Returns the logarithm base **2** of **x**. @@ -1352,7 +1446,15 @@ The extended library is a **non-portable extension**. digits after the decimal point equal to the truncated absolute value of **p**. If the absolute value of **i** is greater than or equal to **2**, and **p** is not **0**, then calling this function will change the value of - **seed**; otherwise, **0** is returned and **seed** is not changed. + **seed**; otherwise, **0** is returned, and **seed** is not changed. + +**i2rand(a, b)** + +: Takes the truncated value of **a** and **b** and uses them as inclusive + bounds to enerate a pseudo-random integer. If the difference of the + truncated values of **a** and **b** is **0**, then the truncated value is + returned, and **seed** is *not* changed. Otherwise, this function will + change the value of **seed**. **srand(x)** @@ -1414,7 +1516,7 @@ The extended library is a **non-portable extension**. **bnot8(x)** : Does a bitwise not of the truncated absolute value of **x** as though it has - **8** binary digits (1 unsigned byte). + **8** binary digits (**1** unsigned byte). If you want to a use signed two's complement argument, use **s2u(x)** to convert. @@ -1422,7 +1524,7 @@ The extended library is a **non-portable extension**. **bnot16(x)** : Does a bitwise not of the truncated absolute value of **x** as though it has - **16** binary digits (2 unsigned bytes). + **16** binary digits (**2** unsigned bytes). If you want to a use signed two's complement argument, use **s2u(x)** to convert. @@ -1430,7 +1532,7 @@ The extended library is a **non-portable extension**. **bnot32(x)** : Does a bitwise not of the truncated absolute value of **x** as though it has - **32** binary digits (4 unsigned bytes). + **32** binary digits (**4** unsigned bytes). If you want to a use signed two's complement argument, use **s2u(x)** to convert. @@ -1438,7 +1540,7 @@ The extended library is a **non-portable extension**. **bnot64(x)** : Does a bitwise not of the truncated absolute value of **x** as though it has - **64** binary digits (8 unsigned bytes). + **64** binary digits (**8** unsigned bytes). If you want to a use signed two's complement argument, use **s2u(x)** to convert. @@ -1462,7 +1564,7 @@ The extended library is a **non-portable extension**. **brev8(x)** : Runs a bit reversal on the truncated absolute value of **x** as though it - has 8 binary digits (1 unsigned byte). + has 8 binary digits (**1** unsigned byte). If you want to a use signed two's complement argument, use **s2u(x)** to convert. @@ -1470,7 +1572,7 @@ The extended library is a **non-portable extension**. **brev16(x)** : Runs a bit reversal on the truncated absolute value of **x** as though it - has 16 binary digits (2 unsigned bytes). + has 16 binary digits (**2** unsigned bytes). If you want to a use signed two's complement argument, use **s2u(x)** to convert. @@ -1478,7 +1580,7 @@ The extended library is a **non-portable extension**. **brev32(x)** : Runs a bit reversal on the truncated absolute value of **x** as though it - has 32 binary digits (4 unsigned bytes). + has 32 binary digits (**4** unsigned bytes). If you want to a use signed two's complement argument, use **s2u(x)** to convert. @@ -1486,7 +1588,7 @@ The extended library is a **non-portable extension**. **brev64(x)** : Runs a bit reversal on the truncated absolute value of **x** as though it - has 64 binary digits (8 unsigned bytes). + has 64 binary digits (**8** unsigned bytes). If you want to a use signed two's complement argument, use **s2u(x)** to convert. @@ -1533,7 +1635,7 @@ The extended library is a **non-portable extension**. **brol32(x, p)** : Does a left bitwise rotatation of the truncated absolute value of **x**, as - though it has **32** binary digits (**2** unsigned bytes), by the number of + though it has **32** binary digits (**4** unsigned bytes), by the number of places equal to the truncated absolute value of **p** modded by **2** to the power of **32**. @@ -1543,7 +1645,7 @@ The extended library is a **non-portable extension**. **brol64(x, p)** : Does a left bitwise rotatation of the truncated absolute value of **x**, as - though it has **64** binary digits (**2** unsigned bytes), by the number of + though it has **64** binary digits (**8** unsigned bytes), by the number of places equal to the truncated absolute value of **p** modded by **2** to the power of **64**. @@ -2085,7 +2187,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 +2294,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 +2384,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 +2413,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 +2479,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,8 +2492,11 @@ 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.gavinhoward.com/gavin/bc . # AUTHORS -Gavin D. Howard <gavin@yzena.com> and contributors. +Gavin D. Howard <gavin@gavinhoward.com> and contributors. diff --git a/contrib/bc/manuals/bc/HN.1 b/contrib/bc/manuals/bc/HN.1 index 6235a3b9931c..7b4577f2dbd3 100644 --- a/contrib/bc/manuals/bc/HN.1 +++ b/contrib/bc/manuals/bc/HN.1 @@ -1,7 +1,7 @@ .\" .\" SPDX-License-Identifier: BSD-2-Clause .\" -.\" Copyright (c) 2018-2021 Gavin D. Howard and contributors. +.\" Copyright (c) 2018-2024 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,40 +25,38 @@ .\" 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" "August 2024" "Gavin D. Howard" "General Commands Manual" .nh .ad l .SH NAME -.PP -bc - arbitrary-precision decimal arithmetic language and calculator +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]--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]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]] .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. +somewhat C\-like, but there are differences. Such differences will be noted in this document. .PP After parsing and handling options, this bc(1) reads any files given on 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 +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. @@ -67,19 +65,114 @@ implementations. another bc(1) gives a parse error, it is probably because a word this bc(1) reserves as a keyword is used as the name of a function, variable, or array. -To fix that, use the command-line option \f[B]-r\f[R] \f[I]keyword\f[R], -where \f[I]keyword\f[R] is the keyword that is used as a name in the -script. +To fix that, use the command\-line option \f[B]\-r\f[R] +\f[I]keyword\f[R], where \f[I]keyword\f[R] is the keyword that is used +as a name in the script. For more information, see the \f[B]OPTIONS\f[R] section. .PP If parsing scripts meant for other bc(1) implementations still does not work, that is a bug and should be reported. See the \f[B]BUGS\f[R] section. .SH OPTIONS -.PP The following are the options that bc(1) accepts. .TP -\f[B]-g\f[R], \f[B]--global-stacks\f[R] +\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. .RS @@ -92,19 +185,16 @@ without worrying that the change will affect other functions. Thus, a hypothetical function named \f[B]output(x,b)\f[R] that simply printed \f[B]x\f[R] in base \f[B]b\f[R] could be written like this: .IP -.nf -\f[C] +.EX define void output(x, b) { obase=b x } -\f[R] -.fi +.EE .PP instead of like this: .IP -.nf -\f[C] +.EX define void output(x, b) { auto c c=obase @@ -112,8 +202,7 @@ define void output(x, b) { x obase=c } -\f[R] -.fi +.EE .PP This makes writing functions much easier. .PP @@ -131,12 +220,10 @@ converter, it is possible to replace that capability with various shell aliases. Examples: .IP -.nf -\f[C] -alias d2o=\[dq]bc -e ibase=A -e obase=8\[dq] -alias h2b=\[dq]bc -e ibase=G -e obase=2\[dq] -\f[R] -.fi +.EX +alias d2o=\[dq]bc \-e ibase=A \-e obase=8\[dq] +alias h2b=\[dq]bc \-e ibase=G \-e obase=2\[dq] +.EE .PP Second, if the purpose of a function is to set \f[B]ibase\f[R], \f[B]obase\f[R], \f[B]scale\f[R], or \f[B]seed\f[R] globally for any @@ -146,53 +233,63 @@ desired value for a global. .PP For functions that set \f[B]seed\f[R], the value assigned to \f[B]seed\f[R] is not propagated to parent functions. -This means that the sequence of pseudo-random numbers that they see will -not be the same sequence of pseudo-random numbers that any parent sees. +This means that the sequence of pseudo\-random numbers that they see +will not be the same sequence of pseudo\-random numbers that any parent +sees. This is only the case once \f[B]seed\f[R] has been set. .PP -If a function desires to not affect the sequence of pseudo-random +If a function desires to not affect the sequence of pseudo\-random numbers of its parents, but wants to use the same \f[B]seed\f[R], it can use the following line: .IP -.nf -\f[C] +.EX seed = seed -\f[R] -.fi +.EE .PP If the behavior of this option is desired for every run of bc(1), then users could make sure to define \f[B]BC_ENV_ARGS\f[R] and include this option (see the \f[B]ENVIRONMENT VARIABLES\f[R] section for more details). .PP -If \f[B]-s\f[R], \f[B]-w\f[R], or any equivalents are used, this option -is ignored. +If \f[B]\-s\f[R], \f[B]\-w\f[R], or any equivalents are used, this +option is ignored. .PP -This is a \f[B]non-portable extension\f[R]. +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. +\f[B]\-h\f[R], \f[B]\-\-help\f[R] +Prints a usage message and exits. .TP -\f[B]-i\f[R], \f[B]--interactive\f[R] +\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. (See the \f[B]INTERACTIVE MODE\f[R] section.) .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-L\f[R], \f[B]--no-line-length\f[R] +\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]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-l\f[R], \f[B]--mathlib\f[R] +\f[B]\-l\f[R], \f[B]\-\-mathlib\f[R] Sets \f[B]scale\f[R] (see the \f[B]SYNTAX\f[R] section) to \f[B]20\f[R] and loads the included math library and the extended math library before running any code, including any expressions or files specified on the @@ -202,11 +299,23 @@ command line. To learn what is in the libraries, see the \f[B]LIBRARY\f[R] section. .RE .TP -\f[B]-P\f[R], \f[B]--no-prompt\f[R] +\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 @@ -214,14 +323,31 @@ Most of those users would want to put this option in These options override the \f[B]BC_PROMPT\f[R] and \f[B]BC_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]. +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] +\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 @@ -229,16 +355,16 @@ 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]read()\f[R] built-in function is called. +is only used when the \f[B]read()\f[R] built\-in function is called. .PP These options \f[I]do\f[R] override the \f[B]BC_PROMPT\f[R] and \f[B]BC_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]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-r\f[R] \f[I]keyword\f[R], \f[B]--redefine\f[R]=\f[I]keyword\f[R] +\f[B]\-r\f[R] \f[I]keyword\f[R], \f[B]\-\-redefine\f[R]=\f[I]keyword\f[R] Redefines \f[I]keyword\f[R] in order to allow it to be used as a function, variable, or array name. This is useful when this bc(1) gives parse errors when parsing scripts @@ -294,157 +420,63 @@ 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 -This is a \f[B]non-portable extension\f[R]. +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. +\f[B]\-s\f[R], \f[B]\-\-standard\f[R] +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]. +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. +\f[B]\-v\f[R], \f[B]\-V\f[R], \f[B]\-\-version\f[R] +Print the version information (copyright header) and exits. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-w\f[R], \f[B]--warn\f[R] -Like \f[B]-s\f[R] and \f[B]--standard\f[R], except that warnings (and -not errors) are printed for non-standard extensions and execution +\f[B]\-w\f[R], \f[B]\-\-warn\f[R] +Like \f[B]\-s\f[R] and \f[B]\-\-standard\f[R], except that warnings (and +not errors) are printed for non\-standard extensions and execution continues normally. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-z\f[R], \f[B]--leading-zeroes\f[R] -Makes bc(1) print all numbers greater than \f[B]-1\f[R] and less than +\f[B]\-z\f[R], \f[B]\-\-leading\-zeroes\f[R] +Makes bc(1) print all numbers greater than \f[B]\-1\f[R] and less than \f[B]1\f[R], and not equal to \f[B]0\f[R], with a leading zero. .RS .PP This can be set for individual numbers with the \f[B]plz(x)\f[R], -plznl(x)**, \f[B]pnlz(x)\f[R], and \f[B]pnlznl(x)\f[R] functions in the -extended math library (see the \f[B]LIBRARY\f[R] section). -.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. +\f[B]plznl(x)\f[R], \f[B]pnlz(x)\f[R], and \f[B]pnlznl(x)\f[R] functions +in the extended math library (see the \f[B]LIBRARY\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +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]. +All long options are \f[B]non\-portable extensions\f[R]. .SH STDIN -.PP -If no files or expressions are given by the \f[B]-f\f[R], -\f[B]--file\f[R], \f[B]-e\f[R], or \f[B]--expression\f[R] options, then -bc(1) reads from \f[B]stdin\f[R]. +If no files or expressions are given by the \f[B]\-f\f[R], +\f[B]\-\-file\f[R], \f[B]\-e\f[R], or \f[B]\-\-expression\f[R] options, +then bc(1) reads from \f[B]stdin\f[R]. .PP However, there are a few caveats to this. .PP @@ -458,8 +490,7 @@ Second, after an \f[B]if\f[R] statement, bc(1) doesn\[cq]t know if an \f[B]else\f[R] statement will follow, so it will not execute until it knows there will not be an \f[B]else\f[R] statement. .SH STDOUT -.PP -Any non-error output is written to \f[B]stdout\f[R]. +Any non\-error output is written to \f[B]stdout\f[R]. In addition, if history (see the \f[B]HISTORY\f[R] section) and the prompt (see the \f[B]TTY MODE\f[R] section) are enabled, both are output to \f[B]stdout\f[R]. @@ -467,7 +498,7 @@ to \f[B]stdout\f[R]. \f[B]Note\f[R]: Unlike other bc(1) implementations, this bc(1) will issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot write to \f[B]stdout\f[R], so if \f[B]stdout\f[R] is closed, as in -\f[B]bc >&-\f[R], it will quit with an error. +\f[B]bc >&\-\f[R], it will quit with an error. This is done so that bc(1) can report problems when \f[B]stdout\f[R] is redirected to a file. .PP @@ -475,13 +506,12 @@ If there are scripts that depend on the behavior of other bc(1) implementations, it is recommended that those scripts be changed to redirect \f[B]stdout\f[R] to \f[B]/dev/null\f[R]. .SH STDERR -.PP Any error output is written to \f[B]stderr\f[R]. .PP \f[B]Note\f[R]: Unlike other bc(1) implementations, this bc(1) will issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot write to \f[B]stderr\f[R], so if \f[B]stderr\f[R] is closed, as in -\f[B]bc 2>&-\f[R], it will quit with an error. +\f[B]bc 2>&\-\f[R], it will quit with an error. This is done so that bc(1) can exit with an error code when \f[B]stderr\f[R] is redirected to a file. .PP @@ -489,12 +519,10 @@ If there are scripts that depend on the behavior of other bc(1) implementations, it is recommended that those scripts be changed to redirect \f[B]stderr\f[R] to \f[B]/dev/null\f[R]. .SH SYNTAX -.PP -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. +The syntax for bc(1) programs is mostly C\-like, with some differences. +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 @@ -502,32 +530,32 @@ In the sections below, \f[B]E\f[R] means expression, \f[B]S\f[R] means statement, and \f[B]I\f[R] means identifier. .PP Identifiers (\f[B]I\f[R]) start with a lowercase letter and can be -followed by any number (up to \f[B]BC_NAME_MAX-1\f[R]) of lowercase -letters (\f[B]a-z\f[R]), digits (\f[B]0-9\f[R]), and underscores +followed by any number (up to \f[B]BC_NAME_MAX\-1\f[R]) of lowercase +letters (\f[B]a\-z\f[R]), digits (\f[B]0\-9\f[R]), and underscores (\f[B]_\f[R]). -The regex is \f[B][a-z][a-z0-9_]*\f[R]. +The regex is \f[B][a\-z][a\-z0\-9_]*\f[R]. Identifiers with more than one character (letter) are a -\f[B]non-portable extension\f[R]. +\f[B]non\-portable extension\f[R]. .PP \f[B]ibase\f[R] is a global variable determining how to interpret constant numbers. It is the \[lq]input\[rq] base, or the number base used for interpreting input numbers. \f[B]ibase\f[R] is initially \f[B]10\f[R]. -If the \f[B]-s\f[R] (\f[B]--standard\f[R]) and \f[B]-w\f[R] -(\f[B]--warn\f[R]) flags were not given on the command line, the max +If the \f[B]\-s\f[R] (\f[B]\-\-standard\f[R]) and \f[B]\-w\f[R] +(\f[B]\-\-warn\f[R]) flags were not given on the command line, the max allowable value for \f[B]ibase\f[R] is \f[B]36\f[R]. Otherwise, it is \f[B]16\f[R]. The min allowable value for \f[B]ibase\f[R] is \f[B]2\f[R]. The max allowable value for \f[B]ibase\f[R] can be queried in bc(1) -programs with the \f[B]maxibase()\f[R] built-in function. +programs with the \f[B]maxibase()\f[R] built\-in function. .PP \f[B]obase\f[R] is a global variable determining how to output results. It is the \[lq]output\[rq] base, or the number base used for outputting numbers. \f[B]obase\f[R] is initially \f[B]10\f[R]. The max allowable value for \f[B]obase\f[R] is \f[B]BC_BASE_MAX\f[R] and -can be queried in bc(1) programs with the \f[B]maxobase()\f[R] built-in +can be queried in bc(1) programs with the \f[B]maxobase()\f[R] built\-in function. The min allowable value for \f[B]obase\f[R] is \f[B]0\f[R]. If \f[B]obase\f[R] is \f[B]0\f[R], values are output in scientific @@ -535,8 +563,8 @@ notation, and if \f[B]obase\f[R] is \f[B]1\f[R], values are output in engineering notation. Otherwise, values are output in the specified base. .PP -Outputting in scientific and engineering notations are \f[B]non-portable -extensions\f[R]. +Outputting in scientific and engineering notations are +\f[B]non\-portable extensions\f[R]. .PP The \f[I]scale\f[R] of an expression is the number of digits in the result of the expression right of the decimal point, and \f[B]scale\f[R] @@ -546,7 +574,7 @@ exceptions. \f[B]scale\f[R] cannot be negative. The max allowable value for \f[B]scale\f[R] is \f[B]BC_SCALE_MAX\f[R] and can be queried in bc(1) programs with the \f[B]maxscale()\f[R] -built-in function. +built\-in function. .PP bc(1) has both \f[I]global\f[R] variables and \f[I]local\f[R] variables. All \f[I]local\f[R] variables are local to the function; they are @@ -571,20 +599,18 @@ The value that is printed is also assigned to the special variable \f[B]last\f[R]. A single dot (\f[B].\f[R]) may also be used as a synonym for \f[B]last\f[R]. -These are \f[B]non-portable extensions\f[R]. +These are \f[B]non\-portable extensions\f[R]. .PP Either semicolons or newlines may separate statements. .SS Comments -.PP There are two kinds of comments: .IP "1." 3 Block comments are enclosed in \f[B]/*\f[R] and \f[B]*/\f[R]. .IP "2." 3 Line comments go from \f[B]#\f[R] until, and not including, the next newline. -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .SS Named Expressions -.PP The following are named expressions in bc(1): .IP "1." 3 Variables: \f[B]I\f[R] @@ -601,26 +627,26 @@ Array Elements: \f[B]I[E]\f[R] .IP "7." 3 \f[B]last\f[R] or a single dot (\f[B].\f[R]) .PP -Numbers 6 and 7 are \f[B]non-portable extensions\f[R]. +Numbers 6 and 7 are \f[B]non\-portable extensions\f[R]. .PP -The meaning of \f[B]seed\f[R] is dependent on the current pseudo-random +The meaning of \f[B]seed\f[R] is dependent on the current pseudo\-random number generator but is guaranteed to not change except for new major versions. .PP The \f[I]scale\f[R] and sign of the value may be significant. .PP If a previously used \f[B]seed\f[R] value is assigned to \f[B]seed\f[R] -and used again, the pseudo-random number generator is guaranteed to -produce the same sequence of pseudo-random numbers as it did when the +and used again, the pseudo\-random number generator is guaranteed to +produce the same sequence of pseudo\-random numbers as it did when the \f[B]seed\f[R] value was previously used. .PP The exact value assigned to \f[B]seed\f[R] is not guaranteed to be returned if \f[B]seed\f[R] is queried again immediately. However, if \f[B]seed\f[R] \f[I]does\f[R] return a different value, both values, when assigned to \f[B]seed\f[R], are guaranteed to produce the -same sequence of pseudo-random numbers. +same sequence of pseudo\-random numbers. This means that certain values assigned to \f[B]seed\f[R] will -\f[I]not\f[R] produce unique sequences of pseudo-random numbers. +\f[I]not\f[R] produce unique sequences of pseudo\-random numbers. The value of \f[B]seed\f[R] will change after any use of the \f[B]rand()\f[R] and \f[B]irand(E)\f[R] operands (see the \f[I]Operands\f[R] subsection below), except if the parameter passed to @@ -641,7 +667,6 @@ Named expressions are required as the operand of of \f[B]assignment\f[R] operators (see the \f[I]Operators\f[R] subsection). .SS Operands -.PP The following are valid operands in bc(1): .IP " 1." 4 Numbers (see the \f[I]Numbers\f[R] subsection below). @@ -651,99 +676,113 @@ Array indices (\f[B]I[E]\f[R]). \f[B](E)\f[R]: The value of \f[B]E\f[R] (used to change precedence). .IP " 4." 4 \f[B]sqrt(E)\f[R]: The square root of \f[B]E\f[R]. -\f[B]E\f[R] must be non-negative. +\f[B]E\f[R] must be non\-negative. .IP " 5." 4 \f[B]length(E)\f[R]: The number of significant decimal digits in \f[B]E\f[R]. Returns \f[B]1\f[R] for \f[B]0\f[R] with no decimal places. If given a string, the length of the string is returned. -Passing a string to \f[B]length(E)\f[R] is a \f[B]non-portable +Passing a string to \f[B]length(E)\f[R] is a \f[B]non\-portable extension\f[R]. .IP " 6." 4 \f[B]length(I[])\f[R]: The number of elements in the array \f[B]I\f[R]. -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .IP " 7." 4 \f[B]scale(E)\f[R]: The \f[I]scale\f[R] of \f[B]E\f[R]. .IP " 8." 4 \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]. +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. 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 +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 "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, -which must be non-zero. +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 +This is a \f[B]non\-portable extension\f[R]. +.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 +that number as a one\-character string. +This is a \f[B]non\-portable extension\f[R]. +.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[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). The \f[B]E\f[R] argument(s) may also be arrays of the form \f[B]I[]\f[R], which will automatically be turned into array references (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 +This is a \f[B]non\-portable extension\f[R]. +.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 +This is a \f[B]non\-portable extension\f[R]. +.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 +This is a \f[B]non\-portable extension\f[R]. +.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 +This is a \f[B]non\-portable extension\f[R]. +.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 +This is a \f[B]non\-portable extension\f[R]. +.IP "21." 4 \f[B]global_stacks()\f[R]: \f[B]0\f[R] if global stacks are not enabled -with the \f[B]-g\f[R] or \f[B]--global-stacks\f[R] options, non-zero -otherwise. +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 +This is a \f[B]non\-portable extension\f[R]. +.IP "22." 4 \f[B]leading_zero()\f[R]: \f[B]0\f[R] if leading zeroes are not enabled -with the \f[B]-z\f[R] or \f[B]\[en]leading-zeroes\f[R] options, non-zero -otherwise. +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 -\f[B]rand()\f[R]: A pseudo-random integer between \f[B]0\f[R] +This is a \f[B]non\-portable extension\f[R]. +.IP "23." 4 +\f[B]rand()\f[R]: A pseudo\-random integer between \f[B]0\f[R] (inclusive) and \f[B]BC_RAND_MAX\f[R] (inclusive). Using this operand will change the value of \f[B]seed\f[R]. -This is a \f[B]non-portable extension\f[R]. -.IP "21." 4 -\f[B]irand(E)\f[R]: A pseudo-random integer between \f[B]0\f[R] +This is a \f[B]non\-portable extension\f[R]. +.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 +If \f[B]E\f[R] is negative or is a non\-integer (\f[B]E\f[R]\[cq]s \f[I]scale\f[R] is not \f[B]0\f[R]), an error is raised, and bc(1) resets (see the \f[B]RESET\f[R] section) while \f[B]seed\f[R] remains unchanged. If \f[B]E\f[R] is larger than \f[B]BC_RAND_MAX\f[R], the higher bound is -honored by generating several pseudo-random integers, multiplying them +honored by generating several pseudo\-random integers, multiplying them by appropriate powers of \f[B]BC_RAND_MAX+1\f[R], and adding them together. Thus, the size of integer that can be generated with this operand is @@ -752,52 +791,83 @@ Using this operand will change the value of \f[B]seed\f[R], unless the 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 +This is a \f[B]non\-portable extension\f[R]. +.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]. +This is a \f[B]non\-portable extension\f[R]. .PP The integers generated by \f[B]rand()\f[R] and \f[B]irand(E)\f[R] are guaranteed to be as unbiased as possible, subject to the limitations of -the pseudo-random number generator. +the pseudo\-random number generator. .PP -\f[B]Note\f[R]: The values returned by the pseudo-random number +\f[B]Note\f[R]: The values returned by the pseudo\-random number generator with \f[B]rand()\f[R] and \f[B]irand(E)\f[R] are guaranteed to \f[I]NOT\f[R] be cryptographically secure. -This is a consequence of using a seeded pseudo-random number generator. +This is a consequence of using a seeded pseudo\-random number generator. However, they \f[I]are\f[R] guaranteed to be reproducible with identical \f[B]seed\f[R] values. -This means that the pseudo-random values from bc(1) should only be used -where a reproducible stream of pseudo-random numbers is +This means that the pseudo\-random values from bc(1) should only be used +where a reproducible stream of pseudo\-random numbers is \f[I]ESSENTIAL\f[R]. -In any other case, use a non-seeded pseudo-random number generator. +In any other case, use a non\-seeded pseudo\-random number generator. .SS Numbers -.PP 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]. The exponent (the portion after the \f[B]e\f[R]) must be an integer. An example is \f[B]1.89237e9\f[R], which is equal to \f[B]1892370000\f[R]. -Negative exponents are also allowed, so \f[B]4.2890e-3\f[R] is equal to +Negative exponents are also allowed, so \f[B]4.2890e\-3\f[R] is equal to \f[B]0.0042890\f[R]. .PP -Using scientific notation is an error or warning if the \f[B]-s\f[R] or -\f[B]-w\f[R], respectively, command-line options (or equivalents) are +Using scientific notation is an error or warning if the \f[B]\-s\f[R] or +\f[B]\-w\f[R], respectively, command\-line options (or equivalents) are given. .PP \f[B]WARNING\f[R]: Both the number and the exponent in scientific @@ -807,17 +877,16 @@ of the current \f[B]ibase\f[R]. For example, if \f[B]ibase\f[R] is \f[B]16\f[R] and bc(1) is given the number string \f[B]FFeA\f[R], the resulting decimal number will be \f[B]2550000000000\f[R], and if bc(1) is given the number string -\f[B]10e-4\f[R], the resulting decimal number will be \f[B]0.0016\f[R]. +\f[B]10e\-4\f[R], the resulting decimal number will be \f[B]0.0016\f[R]. .PP -Accepting input as scientific notation is a \f[B]non-portable +Accepting input as scientific notation is a \f[B]non\-portable extension\f[R]. .SS Operators -.PP The following arithmetic and logical operators can be used. They are listed in order of decreasing precedence. Operators in the same group have the same precedence. .TP -\f[B]++\f[R] \f[B]--\f[R] +\f[B]++\f[R] \f[B]\-\-\f[R] Type: Prefix and Postfix .RS .PP @@ -826,7 +895,7 @@ Associativity: None Description: \f[B]increment\f[R], \f[B]decrement\f[R] .RE .TP -\f[B]-\f[R] \f[B]!\f[R] +\f[B]\-\f[R] \f[B]!\f[R] Type: Prefix .RS .PP @@ -871,7 +940,7 @@ Associativity: Left Description: \f[B]multiply\f[R], \f[B]divide\f[R], \f[B]modulus\f[R] .RE .TP -\f[B]+\f[R] \f[B]-\f[R] +\f[B]+\f[R] \f[B]\-\f[R] Type: Binary .RS .PP @@ -889,7 +958,7 @@ Associativity: Left Description: \f[B]shift left\f[R], \f[B]shift right\f[R] .RE .TP -\f[B]=\f[R] \f[B]<<=\f[R] \f[B]>>=\f[R] \f[B]+=\f[R] \f[B]-=\f[R] \f[B]*=\f[R] \f[B]/=\f[R] \f[B]%=\f[R] \f[B]\[ha]=\f[R] \f[B]\[at]=\f[R] +\f[B]=\f[R] \f[B]<<=\f[R] \f[B]>>=\f[R] \f[B]+=\f[R] \f[B]\-=\f[R] \f[B]*=\f[R] \f[B]/=\f[R] \f[B]%=\f[R] \f[B]\[ha]=\f[R] \f[B]\[at]=\f[R] Type: Binary .RS .PP @@ -927,18 +996,18 @@ Description: \f[B]boolean or\f[R] .PP The operators will be described in more detail below. .TP -\f[B]++\f[R] \f[B]--\f[R] +\f[B]++\f[R] \f[B]\-\-\f[R] The prefix and postfix \f[B]increment\f[R] and \f[B]decrement\f[R] -operators behave exactly like they would in C. -They require a named expression (see the \f[I]Named Expressions\f[R] -subsection) as an operand. +operators behave exactly like they would in C. They require a named +expression (see the \f[I]Named Expressions\f[R] subsection) as an +operand. .RS .PP The prefix versions of these operators are more efficient; use them where possible. .RE .TP -\f[B]-\f[R] +\f[B]\-\f[R] The \f[B]negation\f[R] operator returns \f[B]0\f[R] if a user attempts to negate any expression with the value \f[B]0\f[R]. Otherwise, a copy of the expression with its sign flipped is returned. @@ -948,7 +1017,11 @@ The \f[B]boolean not\f[R] operator returns \f[B]1\f[R] if the expression is \f[B]0\f[R], or \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +\f[B]Warning\f[R]: This operator has a \f[B]different precedence\f[R] +than the equivalent operator in GNU bc(1) and other bc(1) +implementations! +.PP +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]$\f[R] @@ -956,7 +1029,7 @@ The \f[B]truncation\f[R] operator returns a copy of the given expression with all of its \f[I]scale\f[R] removed. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]\[at]\f[R] @@ -970,9 +1043,9 @@ more). .RS .PP The second expression must be an integer (no \f[I]scale\f[R]) and -non-negative. +non\-negative. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]\[ha]\f[R] @@ -983,7 +1056,7 @@ The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R]. .RS .PP The second expression must be an integer (no \f[I]scale\f[R]), and if it -is negative, the first value must be non-zero. +is negative, the first value must be non\-zero. .RE .TP \f[B]*\f[R] @@ -1001,18 +1074,18 @@ returns the quotient. The \f[I]scale\f[R] of the result shall be the value of \f[B]scale\f[R]. .RS .PP -The second expression must be non-zero. +The second expression must be non\-zero. .RE .TP \f[B]%\f[R] The \f[B]modulus\f[R] operator takes two expressions, \f[B]a\f[R] and \f[B]b\f[R], and evaluates them by 1) Computing \f[B]a/b\f[R] to current \f[B]scale\f[R] and 2) Using the result of step 1 to calculate -\f[B]a-(a/b)*b\f[R] to \f[I]scale\f[R] +\f[B]a\-(a/b)*b\f[R] to \f[I]scale\f[R] \f[B]max(scale+scale(b),scale(a))\f[R]. .RS .PP -The second expression must be non-zero. +The second expression must be non\-zero. .RE .TP \f[B]+\f[R] @@ -1020,7 +1093,7 @@ The \f[B]add\f[R] operator takes two expressions, \f[B]a\f[R] and \f[B]b\f[R], and returns the sum, with a \f[I]scale\f[R] equal to the max of the \f[I]scale\f[R]s of \f[B]a\f[R] and \f[B]b\f[R]. .TP -\f[B]-\f[R] +\f[B]\-\f[R] The \f[B]subtract\f[R] operator takes two expressions, \f[B]a\f[R] and \f[B]b\f[R], and returns the difference, with a \f[I]scale\f[R] equal to the max of the \f[I]scale\f[R]s of \f[B]a\f[R] and \f[B]b\f[R]. @@ -1032,9 +1105,9 @@ decimal point moved \f[B]b\f[R] places to the right. .RS .PP The second expression must be an integer (no \f[I]scale\f[R]) and -non-negative. +non\-negative. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]>>\f[R] @@ -1044,12 +1117,12 @@ decimal point moved \f[B]b\f[R] places to the left. .RS .PP The second expression must be an integer (no \f[I]scale\f[R]) and -non-negative. +non\-negative. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]=\f[R] \f[B]<<=\f[R] \f[B]>>=\f[R] \f[B]+=\f[R] \f[B]-=\f[R] \f[B]*=\f[R] \f[B]/=\f[R] \f[B]%=\f[R] \f[B]\[ha]=\f[R] \f[B]\[at]=\f[R] +\f[B]=\f[R] \f[B]<<=\f[R] \f[B]>>=\f[R] \f[B]+=\f[R] \f[B]\-=\f[R] \f[B]*=\f[R] \f[B]/=\f[R] \f[B]%=\f[R] \f[B]\[ha]=\f[R] \f[B]\[at]=\f[R] The \f[B]assignment\f[R] operators take two expressions, \f[B]a\f[R] and \f[B]b\f[R] where \f[B]a\f[R] is a named expression (see the \f[I]Named Expressions\f[R] subsection). @@ -1062,7 +1135,7 @@ the corresponding arithmetic operator and the result is assigned to \f[B]a\f[R]. .PP The \f[B]assignment\f[R] operators that correspond to operators that are -extensions are themselves \f[B]non-portable extensions\f[R]. +extensions are themselves \f[B]non\-portable extensions\f[R]. .RE .TP \f[B]==\f[R] \f[B]<=\f[R] \f[B]>=\f[R] \f[B]!=\f[R] \f[B]<\f[R] \f[B]>\f[R] @@ -1076,41 +1149,39 @@ 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]. +This allowance is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]&&\f[R] The \f[B]boolean and\f[R] operator takes two expressions and returns -\f[B]1\f[R] if both expressions are non-zero, \f[B]0\f[R] otherwise. +\f[B]1\f[R] if both expressions are non\-zero, \f[B]0\f[R] otherwise. .RS .PP -This is \f[I]not\f[R] a short-circuit operator. +This is \f[I]not\f[R] a short\-circuit operator. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]||\f[R] The \f[B]boolean or\f[R] operator takes two expressions and returns -\f[B]1\f[R] if one of the expressions is non-zero, \f[B]0\f[R] +\f[B]1\f[R] if one of the expressions is non\-zero, \f[B]0\f[R] otherwise. .RS .PP -This is \f[I]not\f[R] a short-circuit operator. +This is \f[I]not\f[R] a short\-circuit operator. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .SS Statements -.PP 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 +1207,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 @@ -1149,10 +1222,10 @@ The \f[B]E\f[R] argument(s) may also be arrays of the form \f[B]FUNCTIONS\f[R] section) if the corresponding parameter in the function definition is an array reference. .PP -Numbers 4, 9, 11, 12, 14, 15, and 16 are \f[B]non-portable +Numbers 4, 9, 11, 12, 14, 15, and 16 are \f[B]non\-portable extensions\f[R]. .PP -Also, as a \f[B]non-portable extension\f[R], any or all of the +Also, as a \f[B]non\-portable extension\f[R], any or all of the expressions in the header of a for loop may be omitted. If the condition (second expression) is omitted, it is assumed to be a constant \f[B]1\f[R]. @@ -1169,7 +1242,24 @@ This is only allowed in loops. The \f[B]if\f[R] \f[B]else\f[R] statement does the same thing as in C. .PP 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). +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 +.EX +for (i = 0; i < 3; ++i) i; quit +.EE +.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 @@ -1177,7 +1267,7 @@ that is not executed, bc(1) does not quit.) .PP The \f[B]limits\f[R] statement prints the limits that this bc(1) is subject to. -This is like the \f[B]quit\f[R] statement in that it is a compile-time +This is like the \f[B]quit\f[R] statement in that it is a compile\-time command. .PP An expression by itself is evaluated and printed, followed by a newline. @@ -1190,13 +1280,12 @@ Scientific notation is activated by assigning \f[B]0\f[R] to To deactivate them, just assign a different value to \f[B]obase\f[R]. .PP Scientific notation and engineering notation are disabled if bc(1) is -run with either the \f[B]-s\f[R] or \f[B]-w\f[R] command-line options +run with either the \f[B]\-s\f[R] or \f[B]\-w\f[R] command\-line options (or equivalents). .PP Printing numbers in scientific notation and/or engineering notation is a -\f[B]non-portable extension\f[R]. +\f[B]non\-portable extension\f[R]. .SS Strings -.PP If strings appear as a statement by themselves, they are printed without a trailing newline. .PP @@ -1213,9 +1302,8 @@ element that has been assigned a string, an error is raised, and bc(1) resets (see the \f[B]RESET\f[R] section). .PP Assigning strings to variables and array elements and passing them to -functions are \f[B]non-portable extensions\f[R]. +functions are \f[B]non\-portable extensions\f[R]. .SS Print Statement -.PP The \[lq]expressions\[rq] in a \f[B]print\f[R] statement may also be strings. If they are, there are backslash escape sequences that are interpreted @@ -1242,14 +1330,12 @@ below: \f[B]\[rs]t\f[R]: \f[B]\[rs]t\f[R] .PP Any other character following a backslash causes the backslash and -character to be printed as-is. +character to be printed as\-is. .PP -Any non-string expression in a print statement shall be assigned to +Any non\-string expression in a print statement shall be assigned to \f[B]last\f[R], like any other expression that is printed. .SS Stream Statement -.PP -The \[lq]expressions in a \f[B]stream\f[R] statement may also be -strings. +The expressions in a \f[B]stream\f[R] statement may also be strings. .PP If a \f[B]stream\f[R] statement is given a string, it prints the string as though the string had appeared as its own statement. @@ -1259,20 +1345,17 @@ without a newline. If a \f[B]stream\f[R] statement is given a number, a copy of it is truncated and its absolute value is calculated. The result is then printed as though \f[B]obase\f[R] is \f[B]256\f[R] -and each digit is interpreted as an 8-bit ASCII character, making it a +and each digit is interpreted as an 8\-bit ASCII character, making it a byte stream. .SS Order of Evaluation -.PP All expressions in a statment are evaluated left to right, except as necessary to maintain order of operations. This means, for example, assuming that \f[B]i\f[R] is equal to \f[B]0\f[R], in the expression .IP -.nf -\f[C] +.EX a[i++] = i++ -\f[R] -.fi +.EE .PP the first (or 0th) element of \f[B]a\f[R] is set to \f[B]1\f[R], and \f[B]i\f[R] is equal to \f[B]2\f[R] at the end of the expression. @@ -1281,28 +1364,23 @@ This includes function arguments. Thus, assuming \f[B]i\f[R] is equal to \f[B]0\f[R], this means that in the expression .IP -.nf -\f[C] +.EX x(i++, i++) -\f[R] -.fi +.EE .PP the first argument passed to \f[B]x()\f[R] is \f[B]0\f[R], and the second argument is \f[B]1\f[R], while \f[B]i\f[R] is equal to \f[B]2\f[R] before the function starts executing. .SH FUNCTIONS -.PP Function definitions are as follows: .IP -.nf -\f[C] +.EX define I(I,...,I){ auto I,...,I S;...;S return(E) } -\f[R] -.fi +.EE .PP Any \f[B]I\f[R] in the parameter list or \f[B]auto\f[R] list may be replaced with \f[B]I[]\f[R] to make a parameter or \f[B]auto\f[R] var an @@ -1313,10 +1391,10 @@ asterisk in the call; they must be called with just \f[B]I[]\f[R] like normal array parameters and will be automatically converted into references. .PP -As a \f[B]non-portable extension\f[R], the opening brace of a +As a \f[B]non\-portable extension\f[R], the opening brace of a \f[B]define\f[R] statement may appear on the next line. .PP -As a \f[B]non-portable extension\f[R], the return statement may also be +As a \f[B]non\-portable extension\f[R], the return statement may also be in one of the following forms: .IP "1." 3 \f[B]return\f[R] @@ -1330,18 +1408,15 @@ equivalent to \f[B]return (0)\f[R], unless the function is a \f[B]void\f[R] function (see the \f[I]Void Functions\f[R] subsection below). .SS Void Functions -.PP Functions can also be \f[B]void\f[R] functions, defined as follows: .IP -.nf -\f[C] +.EX define void I(I,...,I){ auto I,...,I S;...;S return } -\f[R] -.fi +.EE .PP They can only be used as standalone expressions, where such an expression would be printed alone, except in a print statement. @@ -1355,17 +1430,14 @@ possible to have variables, arrays, and functions named \f[B]void\f[R]. The word \[lq]void\[rq] is only treated specially right after the \f[B]define\f[R] keyword. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .SS Array References -.PP For any array in the parameter list, if the array is declared in the form .IP -.nf -\f[C] +.EX *I[] -\f[R] -.fi +.EE .PP it is a \f[B]reference\f[R]. Any changes to the array in the function are reflected, when the @@ -1373,20 +1445,17 @@ function returns, to the array that was passed in. .PP Other than this, all function arguments are passed by value. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .SH LIBRARY -.PP All of the functions below, including the functions in the extended math library (see the \f[I]Extended Library\f[R] subsection below), are -available when the \f[B]-l\f[R] or \f[B]--mathlib\f[R] command-line +available when the \f[B]\-l\f[R] or \f[B]\-\-mathlib\f[R] command\-line flags are given, except that the extended math library is not available -when the \f[B]-s\f[R] option, the \f[B]-w\f[R] option, or equivalents +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. @@ -1437,14 +1506,12 @@ This is a transcendental function (see the \f[I]Transcendental Functions\f[R] subsection below). .RE .SS Extended Library -.PP 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] +\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]. +The extended library is a \f[B]non\-portable extension\f[R]. .TP \f[B]p(x, y)\f[R] Calculates \f[B]x\f[R] to the power of \f[B]y\f[R], even if \f[B]y\f[R] @@ -1472,6 +1539,14 @@ the rounding mode round away from \f[B]0\f[R] \f[B]f(x)\f[R] Returns the factorial of the truncated absolute value of \f[B]x\f[R]. .TP +\f[B]max(a, b)\f[R] +Returns \f[B]a\f[R] if \f[B]a\f[R] is greater than \f[B]b\f[R]; +otherwise, returns \f[B]b\f[R]. +.TP +\f[B]min(a, b)\f[R] +Returns \f[B]a\f[R] if \f[B]a\f[R] is less than \f[B]b\f[R]; otherwise, +returns \f[B]b\f[R]. +.TP \f[B]perm(n, k)\f[R] Returns the permutation of the truncated absolute value of \f[B]n\f[R] of the truncated absolute value of \f[B]k\f[R], if \f[B]k <= n\f[R]. @@ -1482,6 +1557,10 @@ Returns the combination of the truncated absolute value of \f[B]n\f[R] of the truncated absolute value of \f[B]k\f[R], if \f[B]k <= n\f[R]. If not, it returns \f[B]0\f[R]. .TP +\f[B]fib(n)\f[R] +Returns the Fibonacci number of the truncated absolute value of +\f[B]n\f[R]. +.TP \f[B]l2(x)\f[R] Returns the logarithm base \f[B]2\f[R] of \f[B]x\f[R]. .RS @@ -1553,11 +1632,11 @@ Otherwise, if \f[B]x\f[R] is greater than \f[B]0\f[R], it returns If \f[B]x\f[R] is less than \f[B]0\f[R], and \f[B]y\f[R] is greater than or equal to \f[B]0\f[R], it returns \f[B]a(y/x)+pi\f[R]. If \f[B]x\f[R] is less than \f[B]0\f[R], and \f[B]y\f[R] is less than -\f[B]0\f[R], it returns \f[B]a(y/x)-pi\f[R]. +\f[B]0\f[R], it returns \f[B]a(y/x)\-pi\f[R]. If \f[B]x\f[R] is equal to \f[B]0\f[R], and \f[B]y\f[R] is greater than \f[B]0\f[R], it returns \f[B]pi/2\f[R]. If \f[B]x\f[R] is equal to \f[B]0\f[R], and \f[B]y\f[R] is less than -\f[B]0\f[R], it returns \f[B]-pi/2\f[R]. +\f[B]0\f[R], it returns \f[B]\-pi/2\f[R]. .RS .PP This function is the same as the \f[B]atan2()\f[R] function in many @@ -1591,7 +1670,7 @@ Functions\f[R] subsection below). Returns the tangent of \f[B]x\f[R], which is assumed to be in radians. .RS .PP -If \f[B]x\f[R] is equal to \f[B]1\f[R] or \f[B]-1\f[R], this raises an +If \f[B]x\f[R] is equal to \f[B]1\f[R] or \f[B]\-1\f[R], this raises an error and causes bc(1) to reset (see the \f[B]RESET\f[R] section). .PP This is an alias of \f[B]t(x)\f[R]. @@ -1619,11 +1698,11 @@ Otherwise, if \f[B]x\f[R] is greater than \f[B]0\f[R], it returns If \f[B]x\f[R] is less than \f[B]0\f[R], and \f[B]y\f[R] is greater than or equal to \f[B]0\f[R], it returns \f[B]a(y/x)+pi\f[R]. If \f[B]x\f[R] is less than \f[B]0\f[R], and \f[B]y\f[R] is less than -\f[B]0\f[R], it returns \f[B]a(y/x)-pi\f[R]. +\f[B]0\f[R], it returns \f[B]a(y/x)\-pi\f[R]. If \f[B]x\f[R] is equal to \f[B]0\f[R], and \f[B]y\f[R] is greater than \f[B]0\f[R], it returns \f[B]pi/2\f[R]. If \f[B]x\f[R] is equal to \f[B]0\f[R], and \f[B]y\f[R] is less than -\f[B]0\f[R], it returns \f[B]-pi/2\f[R]. +\f[B]0\f[R], it returns \f[B]\-pi/2\f[R]. .RS .PP This function is the same as the \f[B]atan2()\f[R] function in many @@ -1652,7 +1731,7 @@ Functions\f[R] subsection below). .RE .TP \f[B]frand(p)\f[R] -Generates a pseudo-random number between \f[B]0\f[R] (inclusive) and +Generates a pseudo\-random number between \f[B]0\f[R] (inclusive) and \f[B]1\f[R] (exclusive) with the number of decimal digits after the decimal point equal to the truncated absolute value of \f[B]p\f[R]. If \f[B]p\f[R] is not \f[B]0\f[R], then calling this function will @@ -1661,14 +1740,22 @@ If \f[B]p\f[R] is \f[B]0\f[R], then \f[B]0\f[R] is returned, and \f[B]seed\f[R] is \f[I]not\f[R] changed. .TP \f[B]ifrand(i, p)\f[R] -Generates a pseudo-random number that is between \f[B]0\f[R] (inclusive) -and the truncated absolute value of \f[B]i\f[R] (exclusive) with the -number of decimal digits after the decimal point equal to the truncated -absolute value of \f[B]p\f[R]. +Generates a pseudo\-random number that is between \f[B]0\f[R] +(inclusive) and the truncated absolute value of \f[B]i\f[R] (exclusive) +with the number of decimal digits after the decimal point equal to the +truncated absolute value of \f[B]p\f[R]. If the absolute value of \f[B]i\f[R] is greater than or equal to \f[B]2\f[R], and \f[B]p\f[R] is not \f[B]0\f[R], then calling this function will change the value of \f[B]seed\f[R]; otherwise, \f[B]0\f[R] -is returned and \f[B]seed\f[R] is not changed. +is returned, and \f[B]seed\f[R] is not changed. +.TP +\f[B]i2rand(a, b)\f[R] +Takes the truncated value of \f[B]a\f[R] and \f[B]b\f[R] and uses them +as inclusive bounds to enerate a pseudo\-random integer. +If the difference of the truncated values of \f[B]a\f[R] and \f[B]b\f[R] +is \f[B]0\f[R], then the truncated value is returned, and \f[B]seed\f[R] +is \f[I]not\f[R] changed. +Otherwise, this function will change the value of \f[B]seed\f[R]. .TP \f[B]srand(x)\f[R] Returns \f[B]x\f[R] with its sign flipped with probability @@ -1710,8 +1797,8 @@ If you want to use signed two\[cq]s complement arguments, use .TP \f[B]bshl(a, b)\f[R] Takes the truncated absolute value of both \f[B]a\f[R] and \f[B]b\f[R] -and calculates and returns the result of \f[B]a\f[R] bit-shifted left by -\f[B]b\f[R] places. +and calculates and returns the result of \f[B]a\f[R] bit\-shifted left +by \f[B]b\f[R] places. .RS .PP If you want to use signed two\[cq]s complement arguments, use @@ -1721,7 +1808,7 @@ If you want to use signed two\[cq]s complement arguments, use \f[B]bshr(a, b)\f[R] Takes the truncated absolute value of both \f[B]a\f[R] and \f[B]b\f[R] and calculates and returns the truncated result of \f[B]a\f[R] -bit-shifted right by \f[B]b\f[R] places. +bit\-shifted right by \f[B]b\f[R] places. .RS .PP If you want to use signed two\[cq]s complement arguments, use @@ -1740,7 +1827,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]bnot8(x)\f[R] Does a bitwise not of the truncated absolute value of \f[B]x\f[R] as -though it has \f[B]8\f[R] binary digits (1 unsigned byte). +though it has \f[B]8\f[R] binary digits (\f[B]1\f[R] unsigned byte). .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1749,7 +1836,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]bnot16(x)\f[R] Does a bitwise not of the truncated absolute value of \f[B]x\f[R] as -though it has \f[B]16\f[R] binary digits (2 unsigned bytes). +though it has \f[B]16\f[R] binary digits (\f[B]2\f[R] unsigned bytes). .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1758,7 +1845,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]bnot32(x)\f[R] Does a bitwise not of the truncated absolute value of \f[B]x\f[R] as -though it has \f[B]32\f[R] binary digits (4 unsigned bytes). +though it has \f[B]32\f[R] binary digits (\f[B]4\f[R] unsigned bytes). .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1767,7 +1854,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]bnot64(x)\f[R] Does a bitwise not of the truncated absolute value of \f[B]x\f[R] as -though it has \f[B]64\f[R] binary digits (8 unsigned bytes). +though it has \f[B]64\f[R] binary digits (\f[B]8\f[R] unsigned bytes). .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1785,7 +1872,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]brevn(x, n)\f[R] Runs a bit reversal on the truncated absolute value of \f[B]x\f[R] as -though it has the same number of 8-bit bytes as the truncated absolute +though it has the same number of 8\-bit bytes as the truncated absolute value of \f[B]n\f[R]. .RS .PP @@ -1795,7 +1882,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]brev8(x)\f[R] Runs a bit reversal on the truncated absolute value of \f[B]x\f[R] as -though it has 8 binary digits (1 unsigned byte). +though it has 8 binary digits (\f[B]1\f[R] unsigned byte). .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1804,7 +1891,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]brev16(x)\f[R] Runs a bit reversal on the truncated absolute value of \f[B]x\f[R] as -though it has 16 binary digits (2 unsigned bytes). +though it has 16 binary digits (\f[B]2\f[R] unsigned bytes). .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1813,7 +1900,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]brev32(x)\f[R] Runs a bit reversal on the truncated absolute value of \f[B]x\f[R] as -though it has 32 binary digits (4 unsigned bytes). +though it has 32 binary digits (\f[B]4\f[R] unsigned bytes). .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1822,7 +1909,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]brev64(x)\f[R] Runs a bit reversal on the truncated absolute value of \f[B]x\f[R] as -though it has 64 binary digits (8 unsigned bytes). +though it has 64 binary digits (\f[B]8\f[R] unsigned bytes). .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1840,11 +1927,11 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]broln(x, p, n)\f[R] Does a left bitwise rotatation of the truncated absolute value of -\f[B]x\f[R], as though it has the same number of unsigned 8-bit bytes as -the truncated absolute value of \f[B]n\f[R], by the number of places +\f[B]x\f[R], as though it has the same number of unsigned 8\-bit bytes +as the truncated absolute value of \f[B]n\f[R], by the number of places equal to the truncated absolute value of \f[B]p\f[R] modded by the \f[B]2\f[R] to the power of the number of binary digits in \f[B]n\f[R] -8-bit bytes. +8\-bit bytes. .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1875,7 +1962,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]brol32(x, p)\f[R] Does a left bitwise rotatation of the truncated absolute value of -\f[B]x\f[R], as though it has \f[B]32\f[R] binary digits (\f[B]2\f[R] +\f[B]x\f[R], as though it has \f[B]32\f[R] binary digits (\f[B]4\f[R] unsigned bytes), by the number of places equal to the truncated absolute value of \f[B]p\f[R] modded by \f[B]2\f[R] to the power of \f[B]32\f[R]. .RS @@ -1886,7 +1973,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]brol64(x, p)\f[R] Does a left bitwise rotatation of the truncated absolute value of -\f[B]x\f[R], as though it has \f[B]64\f[R] binary digits (\f[B]2\f[R] +\f[B]x\f[R], as though it has \f[B]64\f[R] binary digits (\f[B]8\f[R] unsigned bytes), by the number of places equal to the truncated absolute value of \f[B]p\f[R] modded by \f[B]2\f[R] to the power of \f[B]64\f[R]. .RS @@ -1898,9 +1985,9 @@ If you want to a use signed two\[cq]s complement argument, use \f[B]brol(x, p)\f[R] Does a left bitwise rotatation of the truncated absolute value of \f[B]x\f[R], as though it has the minimum number of power of two -unsigned 8-bit bytes, by the number of places equal to the truncated +unsigned 8\-bit bytes, by the number of places equal to the truncated absolute value of \f[B]p\f[R] modded by 2 to the power of the number of -binary digits in the minimum number of 8-bit bytes. +binary digits in the minimum number of 8\-bit bytes. .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1909,11 +1996,11 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]brorn(x, p, n)\f[R] Does a right bitwise rotatation of the truncated absolute value of -\f[B]x\f[R], as though it has the same number of unsigned 8-bit bytes as -the truncated absolute value of \f[B]n\f[R], by the number of places +\f[B]x\f[R], as though it has the same number of unsigned 8\-bit bytes +as the truncated absolute value of \f[B]n\f[R], by the number of places equal to the truncated absolute value of \f[B]p\f[R] modded by the \f[B]2\f[R] to the power of the number of binary digits in \f[B]n\f[R] -8-bit bytes. +8\-bit bytes. .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1967,9 +2054,9 @@ If you want to a use signed two\[cq]s complement argument, use \f[B]bror(x, p)\f[R] Does a right bitwise rotatation of the truncated absolute value of \f[B]x\f[R], as though it has the minimum number of power of two -unsigned 8-bit bytes, by the number of places equal to the truncated +unsigned 8\-bit bytes, by the number of places equal to the truncated absolute value of \f[B]p\f[R] modded by 2 to the power of the number of -binary digits in the minimum number of 8-bit bytes. +binary digits in the minimum number of 8\-bit bytes. .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -2023,7 +2110,7 @@ If you want to a use signed two\[cq]s complement argument, use .RE .TP \f[B]bunrev(t)\f[R] -Assumes \f[B]t\f[R] is a bitwise-reversed number with an extra set bit +Assumes \f[B]t\f[R] is a bitwise\-reversed number with an extra set bit one place more significant than the real most significant bit (which was the least significant bit in the original number). This number is reversed and returned without the extra set bit. @@ -2034,29 +2121,29 @@ meant to be used by users, but it can be. .RE .TP \f[B]plz(x)\f[R] -If \f[B]x\f[R] is not equal to \f[B]0\f[R] and greater that \f[B]-1\f[R] -and less than \f[B]1\f[R], it is printed with a leading zero, regardless -of the use of the \f[B]-z\f[R] option (see the \f[B]OPTIONS\f[R] -section) and without a trailing newline. +If \f[B]x\f[R] is not equal to \f[B]0\f[R] and greater that +\f[B]\-1\f[R] and less than \f[B]1\f[R], it is printed with a leading +zero, regardless of the use of the \f[B]\-z\f[R] option (see the +\f[B]OPTIONS\f[R] section) and without a trailing newline. .RS .PP Otherwise, \f[B]x\f[R] is printed normally, without a trailing newline. .RE .TP \f[B]plznl(x)\f[R] -If \f[B]x\f[R] is not equal to \f[B]0\f[R] and greater that \f[B]-1\f[R] -and less than \f[B]1\f[R], it is printed with a leading zero, regardless -of the use of the \f[B]-z\f[R] option (see the \f[B]OPTIONS\f[R] -section) and with a trailing newline. +If \f[B]x\f[R] is not equal to \f[B]0\f[R] and greater that +\f[B]\-1\f[R] and less than \f[B]1\f[R], it is printed with a leading +zero, regardless of the use of the \f[B]\-z\f[R] option (see the +\f[B]OPTIONS\f[R] section) and with a trailing newline. .RS .PP Otherwise, \f[B]x\f[R] is printed normally, with a trailing newline. .RE .TP \f[B]pnlz(x)\f[R] -If \f[B]x\f[R] is not equal to \f[B]0\f[R] and greater that \f[B]-1\f[R] -and less than \f[B]1\f[R], it is printed without a leading zero, -regardless of the use of the \f[B]-z\f[R] option (see the +If \f[B]x\f[R] is not equal to \f[B]0\f[R] and greater that +\f[B]\-1\f[R] and less than \f[B]1\f[R], it is printed without a leading +zero, regardless of the use of the \f[B]\-z\f[R] option (see the \f[B]OPTIONS\f[R] section) and without a trailing newline. .RS .PP @@ -2064,9 +2151,9 @@ Otherwise, \f[B]x\f[R] is printed normally, without a trailing newline. .RE .TP \f[B]pnlznl(x)\f[R] -If \f[B]x\f[R] is not equal to \f[B]0\f[R] and greater that \f[B]-1\f[R] -and less than \f[B]1\f[R], it is printed without a leading zero, -regardless of the use of the \f[B]-z\f[R] option (see the +If \f[B]x\f[R] is not equal to \f[B]0\f[R] and greater that +\f[B]\-1\f[R] and less than \f[B]1\f[R], it is printed without a leading +zero, regardless of the use of the \f[B]\-z\f[R] option (see the \f[B]OPTIONS\f[R] section) and with a trailing newline. .RS .PP @@ -2078,22 +2165,22 @@ Returns the numbers of unsigned integer bytes required to hold the truncated absolute value of \f[B]x\f[R]. .TP \f[B]sbytes(x)\f[R] -Returns the numbers of signed, two\[cq]s-complement integer bytes +Returns the numbers of signed, two\[cq]s\-complement integer bytes required to hold the truncated value of \f[B]x\f[R]. .TP \f[B]s2u(x)\f[R] -Returns \f[B]x\f[R] if it is non-negative. +Returns \f[B]x\f[R] if it is non\-negative. If it \f[I]is\f[R] negative, then it calculates what \f[B]x\f[R] would -be as a 2\[cq]s-complement signed integer and returns the non-negative +be as a 2\[cq]s\-complement signed integer and returns the non\-negative integer that would have the same representation in binary. .TP \f[B]s2un(x,n)\f[R] -Returns \f[B]x\f[R] if it is non-negative. +Returns \f[B]x\f[R] if it is non\-negative. If it \f[I]is\f[R] negative, then it calculates what \f[B]x\f[R] would -be as a 2\[cq]s-complement signed integer with \f[B]n\f[R] bytes and -returns the non-negative integer that would have the same representation -in binary. -If \f[B]x\f[R] cannot fit into \f[B]n\f[R] 2\[cq]s-complement signed +be as a 2\[cq]s\-complement signed integer with \f[B]n\f[R] bytes and +returns the non\-negative integer that would have the same +representation in binary. +If \f[B]x\f[R] cannot fit into \f[B]n\f[R] 2\[cq]s\-complement signed bytes, it is truncated to fit. .TP \f[B]hex(x)\f[R] @@ -2137,7 +2224,7 @@ subsection of the \f[B]FUNCTIONS\f[R] section). .TP \f[B]int(x)\f[R] Outputs the representation, in binary and hexadecimal, of \f[B]x\f[R] as -a signed, two\[cq]s-complement integer in as few power of two bytes as +a signed, two\[cq]s\-complement integer in as few power of two bytes as possible. Both outputs are split into bytes separated by spaces. .RS @@ -2165,7 +2252,7 @@ subsection of the \f[B]FUNCTIONS\f[R] section). .TP \f[B]intn(x, n)\f[R] Outputs the representation, in binary and hexadecimal, of \f[B]x\f[R] as -a signed, two\[cq]s-complement integer in \f[B]n\f[R] bytes. +a signed, two\[cq]s\-complement integer in \f[B]n\f[R] bytes. Both outputs are split into bytes separated by spaces. .RS .PP @@ -2193,7 +2280,7 @@ subsection of the \f[B]FUNCTIONS\f[R] section). .TP \f[B]int8(x)\f[R] Outputs the representation, in binary and hexadecimal, of \f[B]x\f[R] as -a signed, two\[cq]s-complement integer in \f[B]1\f[R] byte. +a signed, two\[cq]s\-complement integer in \f[B]1\f[R] byte. Both outputs are split into bytes separated by spaces. .RS .PP @@ -2221,7 +2308,7 @@ subsection of the \f[B]FUNCTIONS\f[R] section). .TP \f[B]int16(x)\f[R] Outputs the representation, in binary and hexadecimal, of \f[B]x\f[R] as -a signed, two\[cq]s-complement integer in \f[B]2\f[R] bytes. +a signed, two\[cq]s\-complement integer in \f[B]2\f[R] bytes. Both outputs are split into bytes separated by spaces. .RS .PP @@ -2249,7 +2336,7 @@ subsection of the \f[B]FUNCTIONS\f[R] section). .TP \f[B]int32(x)\f[R] Outputs the representation, in binary and hexadecimal, of \f[B]x\f[R] as -a signed, two\[cq]s-complement integer in \f[B]4\f[R] bytes. +a signed, two\[cq]s\-complement integer in \f[B]4\f[R] bytes. Both outputs are split into bytes separated by spaces. .RS .PP @@ -2277,7 +2364,7 @@ subsection of the \f[B]FUNCTIONS\f[R] section). .TP \f[B]int64(x)\f[R] Outputs the representation, in binary and hexadecimal, of \f[B]x\f[R] as -a signed, two\[cq]s-complement integer in \f[B]8\f[R] bytes. +a signed, two\[cq]s\-complement integer in \f[B]8\f[R] bytes. Both outputs are split into bytes separated by spaces. .RS .PP @@ -2324,14 +2411,13 @@ subsection of the \f[B]FUNCTIONS\f[R] section). \f[B]output_byte(x, i)\f[R] Outputs byte \f[B]i\f[R] of the truncated absolute value of \f[B]x\f[R], where \f[B]0\f[R] is the least significant byte and \f[B]number_of_bytes -- 1\f[R] is the most significant byte. +\- 1\f[R] is the most significant byte. .RS .PP This is a \f[B]void\f[R] function (see the \f[I]Void Functions\f[R] subsection of the \f[B]FUNCTIONS\f[R] section). .RE .SS Transcendental Functions -.PP All transcendental functions can return slightly inaccurate results, up to 1 ULP (https://en.wikipedia.org/wiki/Unit_in_the_last_place). This is unavoidable, and the article at @@ -2387,8 +2473,7 @@ The transcendental functions in the extended math library are: .IP \[bu] 2 \f[B]d2r(x)\f[R] .SH RESET -.PP -When bc(1) encounters an error or a signal that it has a non-default +When bc(1) encounters an error or a signal that it has a non\-default handler for, it resets. This means that several things happen. .PP @@ -2408,7 +2493,6 @@ Note that this reset behavior is different from the GNU bc(1), which attempts to start executing the statement right after the one that caused an error. .SH PERFORMANCE -.PP Most bc(1) implementations use \f[B]char\f[R] types to calculate the value of \f[B]1\f[R] decimal digit at a time, but that can be slow. This bc(1) does something different. @@ -2431,7 +2515,6 @@ checking. This integer type depends on the value of \f[B]BC_LONG_BIT\f[R], but is always at least twice as large as the integer type used to store digits. .SH LIMITS -.PP The following are the limits on bc(1): .TP \f[B]BC_LONG_BIT\f[R] @@ -2461,29 +2544,29 @@ Set at \f[B]BC_BASE_POW\f[R]. .TP \f[B]BC_DIM_MAX\f[R] The maximum size of arrays. -Set at \f[B]SIZE_MAX-1\f[R]. +Set at \f[B]SIZE_MAX\-1\f[R]. .TP \f[B]BC_SCALE_MAX\f[R] The maximum \f[B]scale\f[R]. -Set at \f[B]BC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]BC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]BC_STRING_MAX\f[R] The maximum length of strings. -Set at \f[B]BC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]BC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]BC_NAME_MAX\f[R] The maximum length of identifiers. -Set at \f[B]BC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]BC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]BC_NUM_MAX\f[R] The maximum length of a number (in decimal digits), which includes digits after the decimal point. -Set at \f[B]BC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]BC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]BC_RAND_MAX\f[R] The maximum integer (inclusive) returned by the \f[B]rand()\f[R] operand. -Set at \f[B]2\[ha]BC_LONG_BIT-1\f[R]. +Set at \f[B]2\[ha]BC_LONG_BIT\-1\f[R]. .TP Exponent The maximum allowable exponent (positive or negative). @@ -2491,28 +2574,28 @@ Set at \f[B]BC_OVERFLOW_MAX\f[R]. .TP Number of vars The maximum number of vars/arrays. -Set at \f[B]SIZE_MAX-1\f[R]. +Set at \f[B]SIZE_MAX\-1\f[R]. .PP The actual values can be queried with the \f[B]limits\f[R] statement. .PP -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. +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 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 -the \f[B]-s\f[R] option was given. +the \f[B]\-s\f[R] option was given. .TP \f[B]BC_ENV_ARGS\f[R] -This is another way to give command-line arguments to bc(1). -They should be in the same format as all other command-line arguments. +This is another way to give command\-line arguments to bc(1). +They should be in the same format as all other command\-line arguments. These are always processed first, so any files given in \f[B]BC_ENV_ARGS\f[R] will be processed before arguments and files given -on the command-line. +on the command\-line. This gives the user the ability to set up \[lq]standard\[rq] options and files to be used at every invocation. The most useful thing for such files to contain would be useful @@ -2533,14 +2616,14 @@ you can use double quotes as the outside quotes, as in \f[B]\[lq]some quotes. However, handling a file with both kinds of quotes in \f[B]BC_ENV_ARGS\f[R] is not supported due to the complexity of the -parsing, though such files are still supported on the command-line where -the parsing is done by the shell. +parsing, though such files are still supported on the command\-line +where the parsing is done by the shell. .RE .TP \f[B]BC_LINE_LENGTH\f[R] If this environment variable exists and contains an integer that is greater than \f[B]1\f[R] and is less than \f[B]UINT16_MAX\f[R] -(\f[B]2\[ha]16-1\f[R]), bc(1) will output lines to that length, +(\f[B]2\[ha]16\-1\f[R]), bc(1) will output lines to that length, including the backslash (\f[B]\[rs]\f[R]). The default line length is \f[B]70\f[R]. .RS @@ -2552,7 +2635,7 @@ newlines. .TP \f[B]BC_BANNER\f[R] If this environment variable exists and contains an integer, then a -non-zero value activates the copyright banner when bc(1) is in +non\-zero value activates the copyright banner when bc(1) is in interactive mode, while zero deactivates it. .RS .PP @@ -2561,7 +2644,7 @@ section), then this environment variable has no effect because bc(1) does not print the banner when not in interactive mode. .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. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]BC_SIGINT_RESET\f[R] @@ -2571,13 +2654,13 @@ exits on \f[B]SIGINT\f[R] when not in interactive mode. .RS .PP However, when bc(1) is in interactive mode, then if this environment -variable exists and contains an integer, a non-zero value makes bc(1) +variable exists and contains an integer, a non\-zero value makes bc(1) reset on \f[B]SIGINT\f[R], rather than exit, and zero makes bc(1) exit. If this environment variable exists and is \f[I]not\f[R] an integer, then bc(1) will exit on \f[B]SIGINT\f[R]. .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. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]BC_TTY_MODE\f[R] @@ -2586,11 +2669,11 @@ section), then this environment variable has no effect. .RS .PP However, when TTY mode is available, then if this environment variable -exists and contains an integer, then a non-zero value makes bc(1) use +exists and contains an integer, then a non\-zero value makes bc(1) use TTY mode, and zero makes bc(1) not use TTY mode. .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. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]BC_PROMPT\f[R] @@ -2599,30 +2682,46 @@ section), then this environment variable has no effect. .RS .PP However, when TTY mode is available, then if this environment variable -exists and contains an integer, a non-zero value makes bc(1) use a -prompt, and zero or a non-integer makes bc(1) not use a prompt. +exists and contains an integer, a non\-zero value makes bc(1) use a +prompt, and zero or a non\-integer makes bc(1) not use a prompt. If this environment variable does not exist and \f[B]BC_TTY_MODE\f[R] does, then the value of the \f[B]BC_TTY_MODE\f[R] environment variable is used. .PP This environment variable and the \f[B]BC_TTY_MODE\f[R] environment variable override the default, which can be queried with the -\f[B]-h\f[R] or \f[B]--help\f[R] options. +\f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]BC_EXPR_EXIT\f[R] -If any expressions or expression files are given on the command-line -with \f[B]-e\f[R], \f[B]--expression\f[R], \f[B]-f\f[R], or -\f[B]--file\f[R], then if this environment variable exists and contains -an integer, a non-zero value makes bc(1) exit after executing the -expressions and expression files, and a zero value makes bc(1) not exit. +If any expressions or expression files are given on the command\-line +with \f[B]\-e\f[R], \f[B]\-\-expression\f[R], \f[B]\-f\f[R], or +\f[B]\-\-file\f[R], then if this environment variable exists and +contains an integer, a non\-zero value makes bc(1) exit after executing +the expressions and expression files, and a zero value makes bc(1) not +exit. .RS .PP This environment variable overrides the default, which can be queried -with the \f[B]-h\f[R] or \f[B]--help\f[R] options. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE -.SH EXIT STATUS +.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 bc(1) returns the following exit statuses: .TP \f[B]0\f[R] @@ -2636,10 +2735,10 @@ since math errors will happen in the process of normal execution. .PP Math errors include divide by \f[B]0\f[R], taking the square root of a negative number, using a negative number as a bound for the -pseudo-random number generator, attempting to convert a negative number +pseudo\-random number generator, attempting to convert a negative number to a hardware integer, overflow when converting a number to a hardware integer, overflow when calculating the size of a number, and attempting -to use a non-integer where an integer is required. +to use a non\-integer where an integer is required. .PP Converting to a hardware integer happens for the second operand of the power (\f[B]\[ha]\f[R]), places (\f[B]\[at]\f[R]), left shift @@ -2661,7 +2760,7 @@ giving an invalid \f[B]auto\f[R] list, having a duplicate \f[B]auto\f[R]/function parameter, failing to find the end of a code block, attempting to return a value from a \f[B]void\f[R] function, attempting to use a variable as a reference, and using any extensions -when the option \f[B]-s\f[R] or any equivalents were given. +when the option \f[B]\-s\f[R] or any equivalents were given. .RE .TP \f[B]3\f[R] @@ -2684,7 +2783,7 @@ A fatal error occurred. Fatal errors include memory allocation errors, I/O errors, failing to open files, attempting to use files that do not have only ASCII characters (bc(1) only accepts ASCII characters), attempting to open a -directory as a file, and giving invalid command-line options. +directory as a file, and giving invalid command\-line options. .RE .PP The exit status \f[B]4\f[R] is special; when a fatal error occurs, bc(1) @@ -2695,19 +2794,18 @@ interactive mode (see the \f[B]INTERACTIVE MODE\f[R] section), since bc(1) resets its state (see the \f[B]RESET\f[R] section) and accepts more input when one of those errors occurs in interactive mode. This is also the case when interactive mode is forced by the -\f[B]-i\f[R] flag or \f[B]--interactive\f[R] option. +\f[B]\-i\f[R] flag or \f[B]\-\-interactive\f[R] option. .PP These exit statuses allow bc(1) to be used in shell scripting with error checking, and its normal behavior can be forced by using the -\f[B]-i\f[R] flag or \f[B]--interactive\f[R] option. +\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. +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. .PP In interactive mode, bc(1) attempts to recover from errors (see the \f[B]RESET\f[R] section), and in normal execution, flushes @@ -2716,7 +2814,6 @@ bc(1) may also reset on \f[B]SIGINT\f[R] instead of exit, depending on the contents of, or default for, the \f[B]BC_SIGINT_RESET\f[R] environment variable (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). .SH TTY MODE -.PP If \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all connected to a TTY, then \[lq]TTY mode\[rq] is considered to be available, and thus, bc(1) can turn on TTY mode, subject to some @@ -2724,45 +2821,42 @@ settings. .PP If there is the environment variable \f[B]BC_TTY_MODE\f[R] in the environment (see the \f[B]ENVIRONMENT VARIABLES\f[R] section), then if -that environment variable contains a non-zero integer, bc(1) will turn +that environment variable contains a non\-zero integer, bc(1) will turn on TTY mode when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all connected to a TTY. If the \f[B]BC_TTY_MODE\f[R] environment variable exists but is -\f[I]not\f[R] a non-zero integer, then bc(1) will not turn TTY mode on. +\f[I]not\f[R] a non\-zero integer, then bc(1) will not turn TTY mode on. .PP If the environment variable \f[B]BC_TTY_MODE\f[R] does \f[I]not\f[R] exist, the default setting is used. -The default setting can be queried with the \f[B]-h\f[R] or -\f[B]--help\f[R] options. +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 -.PP If TTY mode is available, then a prompt can be enabled. Like TTY mode itself, it can be turned on or off with an environment variable: \f[B]BC_PROMPT\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). .PP -If the environment variable \f[B]BC_PROMPT\f[R] exists and is a non-zero -integer, then the prompt is turned on when \f[B]stdin\f[R], +If the environment variable \f[B]BC_PROMPT\f[R] exists and is a +non\-zero integer, then the prompt is turned on when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are connected to a TTY and the -\f[B]-P\f[R] and \f[B]--no-prompt\f[R] options were not used. +\f[B]\-P\f[R] and \f[B]\-\-no\-prompt\f[R] options were not used. The read prompt will be turned on under the same conditions, except that -the \f[B]-R\f[R] and \f[B]--no-read-prompt\f[R] options must also not be -used. +the \f[B]\-R\f[R] and \f[B]\-\-no\-read\-prompt\f[R] options must also +not be used. .PP However, if \f[B]BC_PROMPT\f[R] does not exist, the prompt can be enabled or disabled with the \f[B]BC_TTY_MODE\f[R] environment variable, -the \f[B]-P\f[R] and \f[B]--no-prompt\f[R] options, and the \f[B]-R\f[R] -and \f[B]--no-read-prompt\f[R] options. +the \f[B]\-P\f[R] and \f[B]\-\-no\-prompt\f[R] options, and the +\f[B]\-R\f[R] and \f[B]\-\-no\-read\-prompt\f[R] options. See the \f[B]ENVIRONMENT VARIABLES\f[R] and \f[B]OPTIONS\f[R] sections for more details. .SH SIGNAL HANDLING -.PP Sending a \f[B]SIGINT\f[R] will cause bc(1) to do one of two things. .PP If bc(1) is not in interactive mode (see the \f[B]INTERACTIVE MODE\f[R] @@ -2771,7 +2865,7 @@ section), or the \f[B]BC_SIGINT_RESET\f[R] environment variable (see the an integer or it is zero, bc(1) will exit. .PP However, if bc(1) is in interactive mode, and the -\f[B]BC_SIGINT_RESET\f[R] or its default is an integer and non-zero, +\f[B]BC_SIGINT_RESET\f[R] or its default is an integer and non\-zero, then bc(1) will stop executing the current input and reset (see the \f[B]RESET\f[R] section) upon receiving a \f[B]SIGINT\f[R]. .PP @@ -2794,24 +2888,31 @@ the user to continue. \f[B]SIGTERM\f[R] and \f[B]SIGQUIT\f[R] cause bc(1) to clean up and exit, and it uses the default handler for all other signals. .SH SEE ALSO -.PP dc(1) .SH STANDARDS -.PP -bc(1) is compliant with the IEEE Std 1003.1-2017 -(\[lq]POSIX.1-2017\[rq]) specification at +bc(1) is compliant with the IEEE Std 1003.1\-2017 +(\[lq]POSIX.1\-2017\[rq]) specification at https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html . -The flags \f[B]-efghiqsvVw\f[R], all long options, and the extensions +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 +Before version \f[B]6.1.0\f[R], this bc(1) had incorrect behavior for +the \f[B]quit\f[R] statement. .PP -None are known. -Report bugs at https://git.yzena.com/gavin/bc. +No other bugs are known. +Report bugs at https://git.gavinhoward.com/gavin/bc . .SH AUTHORS -.PP -Gavin D. -Howard <gavin@yzena.com> and contributors. +Gavin D. Howard \c +.MT gavin@gavinhoward.com +.ME \c +\ and contributors. diff --git a/contrib/bc/manuals/bc/HN.1.md b/contrib/bc/manuals/bc/HN.1.md index 13f085a5cca7..015035c14daf 100644 --- a/contrib/bc/manuals/bc/HN.1.md +++ b/contrib/bc/manuals/bc/HN.1.md @@ -2,7 +2,7 @@ SPDX-License-Identifier: BSD-2-Clause -Copyright (c) 2018-2021 Gavin D. Howard and contributors. +Copyright (c) 2018-2024 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**. @@ -268,80 +372,12 @@ The following are the options that bc(1) accepts. : Makes bc(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)**, + 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**. -**-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**. - -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**. +letters are equal to **9** plus their position in the alphabet, starting from +**1** (i.e., **A** equals **10**, or **9+1**). + +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 @@ -742,6 +811,9 @@ The operators will be described in more detail below. : The **boolean not** operator returns **1** if the expression is **0**, or **0** otherwise. + **Warning**: This operator has a **different precedence** than the + equivalent operator in GNU bc(1) and other bc(1) implementations! + This is a **non-portable extension**. **\$** @@ -849,10 +921,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 +987,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.) @@ -987,7 +1071,7 @@ like any other expression that is printed. ## Stream Statement -The "expressions in a **stream** statement may also be strings. +The expressions in a **stream** statement may also be strings. If a **stream** statement is given a string, it prints the string as though the string had appeared as its own statement. In other words, the **stream** @@ -1099,9 +1183,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 +1232,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**. @@ -1180,6 +1262,14 @@ The extended library is a **non-portable extension**. : Returns the factorial of the truncated absolute value of **x**. +**max(a, b)** + +: Returns **a** if **a** is greater than **b**; otherwise, returns **b**. + +**min(a, b)** + +: Returns **a** if **a** is less than **b**; otherwise, returns **b**. + **perm(n, k)** : Returns the permutation of the truncated absolute value of **n** of the @@ -1190,6 +1280,10 @@ The extended library is a **non-portable extension**. : Returns the combination of the truncated absolute value of **n** of the truncated absolute value of **k**, if **k \<= n**. If not, it returns **0**. +**fib(n)** + +: Returns the Fibonacci number of the truncated absolute value of **n**. + **l2(x)** : Returns the logarithm base **2** of **x**. @@ -1352,7 +1446,15 @@ The extended library is a **non-portable extension**. digits after the decimal point equal to the truncated absolute value of **p**. If the absolute value of **i** is greater than or equal to **2**, and **p** is not **0**, then calling this function will change the value of - **seed**; otherwise, **0** is returned and **seed** is not changed. + **seed**; otherwise, **0** is returned, and **seed** is not changed. + +**i2rand(a, b)** + +: Takes the truncated value of **a** and **b** and uses them as inclusive + bounds to enerate a pseudo-random integer. If the difference of the + truncated values of **a** and **b** is **0**, then the truncated value is + returned, and **seed** is *not* changed. Otherwise, this function will + change the value of **seed**. **srand(x)** @@ -1414,7 +1516,7 @@ The extended library is a **non-portable extension**. **bnot8(x)** : Does a bitwise not of the truncated absolute value of **x** as though it has - **8** binary digits (1 unsigned byte). + **8** binary digits (**1** unsigned byte). If you want to a use signed two's complement argument, use **s2u(x)** to convert. @@ -1422,7 +1524,7 @@ The extended library is a **non-portable extension**. **bnot16(x)** : Does a bitwise not of the truncated absolute value of **x** as though it has - **16** binary digits (2 unsigned bytes). + **16** binary digits (**2** unsigned bytes). If you want to a use signed two's complement argument, use **s2u(x)** to convert. @@ -1430,7 +1532,7 @@ The extended library is a **non-portable extension**. **bnot32(x)** : Does a bitwise not of the truncated absolute value of **x** as though it has - **32** binary digits (4 unsigned bytes). + **32** binary digits (**4** unsigned bytes). If you want to a use signed two's complement argument, use **s2u(x)** to convert. @@ -1438,7 +1540,7 @@ The extended library is a **non-portable extension**. **bnot64(x)** : Does a bitwise not of the truncated absolute value of **x** as though it has - **64** binary digits (8 unsigned bytes). + **64** binary digits (**8** unsigned bytes). If you want to a use signed two's complement argument, use **s2u(x)** to convert. @@ -1462,7 +1564,7 @@ The extended library is a **non-portable extension**. **brev8(x)** : Runs a bit reversal on the truncated absolute value of **x** as though it - has 8 binary digits (1 unsigned byte). + has 8 binary digits (**1** unsigned byte). If you want to a use signed two's complement argument, use **s2u(x)** to convert. @@ -1470,7 +1572,7 @@ The extended library is a **non-portable extension**. **brev16(x)** : Runs a bit reversal on the truncated absolute value of **x** as though it - has 16 binary digits (2 unsigned bytes). + has 16 binary digits (**2** unsigned bytes). If you want to a use signed two's complement argument, use **s2u(x)** to convert. @@ -1478,7 +1580,7 @@ The extended library is a **non-portable extension**. **brev32(x)** : Runs a bit reversal on the truncated absolute value of **x** as though it - has 32 binary digits (4 unsigned bytes). + has 32 binary digits (**4** unsigned bytes). If you want to a use signed two's complement argument, use **s2u(x)** to convert. @@ -1486,7 +1588,7 @@ The extended library is a **non-portable extension**. **brev64(x)** : Runs a bit reversal on the truncated absolute value of **x** as though it - has 64 binary digits (8 unsigned bytes). + has 64 binary digits (**8** unsigned bytes). If you want to a use signed two's complement argument, use **s2u(x)** to convert. @@ -1533,7 +1635,7 @@ The extended library is a **non-portable extension**. **brol32(x, p)** : Does a left bitwise rotatation of the truncated absolute value of **x**, as - though it has **32** binary digits (**2** unsigned bytes), by the number of + though it has **32** binary digits (**4** unsigned bytes), by the number of places equal to the truncated absolute value of **p** modded by **2** to the power of **32**. @@ -1543,7 +1645,7 @@ The extended library is a **non-portable extension**. **brol64(x, p)** : Does a left bitwise rotatation of the truncated absolute value of **x**, as - though it has **64** binary digits (**2** unsigned bytes), by the number of + though it has **64** binary digits (**8** unsigned bytes), by the number of places equal to the truncated absolute value of **p** modded by **2** to the power of **64**. @@ -2085,7 +2187,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 +2294,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 +2384,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 +2413,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,14 +2474,21 @@ 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.gavinhoward.com/gavin/bc . # AUTHORS -Gavin D. Howard <gavin@yzena.com> and contributors. +Gavin D. Howard <gavin@gavinhoward.com> and contributors. diff --git a/contrib/bc/manuals/bc/N.1 b/contrib/bc/manuals/bc/N.1 index def2aee98bbc..193e0d15f6fb 100644 --- a/contrib/bc/manuals/bc/N.1 +++ b/contrib/bc/manuals/bc/N.1 @@ -1,7 +1,7 @@ .\" .\" SPDX-License-Identifier: BSD-2-Clause .\" -.\" Copyright (c) 2018-2021 Gavin D. Howard and contributors. +.\" Copyright (c) 2018-2024 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,40 +25,38 @@ .\" 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" "August 2024" "Gavin D. Howard" "General Commands Manual" .nh .ad l .SH NAME -.PP -bc - arbitrary-precision decimal arithmetic language and calculator +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]--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]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]] .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. +somewhat C\-like, but there are differences. Such differences will be noted in this document. .PP After parsing and handling options, this bc(1) reads any files given on 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 +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. @@ -67,19 +65,114 @@ implementations. another bc(1) gives a parse error, it is probably because a word this bc(1) reserves as a keyword is used as the name of a function, variable, or array. -To fix that, use the command-line option \f[B]-r\f[R] \f[I]keyword\f[R], -where \f[I]keyword\f[R] is the keyword that is used as a name in the -script. +To fix that, use the command\-line option \f[B]\-r\f[R] +\f[I]keyword\f[R], where \f[I]keyword\f[R] is the keyword that is used +as a name in the script. For more information, see the \f[B]OPTIONS\f[R] section. .PP If parsing scripts meant for other bc(1) implementations still does not work, that is a bug and should be reported. See the \f[B]BUGS\f[R] section. .SH OPTIONS -.PP The following are the options that bc(1) accepts. .TP -\f[B]-g\f[R], \f[B]--global-stacks\f[R] +\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. .RS @@ -92,19 +185,16 @@ without worrying that the change will affect other functions. Thus, a hypothetical function named \f[B]output(x,b)\f[R] that simply printed \f[B]x\f[R] in base \f[B]b\f[R] could be written like this: .IP -.nf -\f[C] +.EX define void output(x, b) { obase=b x } -\f[R] -.fi +.EE .PP instead of like this: .IP -.nf -\f[C] +.EX define void output(x, b) { auto c c=obase @@ -112,8 +202,7 @@ define void output(x, b) { x obase=c } -\f[R] -.fi +.EE .PP This makes writing functions much easier. .PP @@ -131,12 +220,10 @@ converter, it is possible to replace that capability with various shell aliases. Examples: .IP -.nf -\f[C] -alias d2o=\[dq]bc -e ibase=A -e obase=8\[dq] -alias h2b=\[dq]bc -e ibase=G -e obase=2\[dq] -\f[R] -.fi +.EX +alias d2o=\[dq]bc \-e ibase=A \-e obase=8\[dq] +alias h2b=\[dq]bc \-e ibase=G \-e obase=2\[dq] +.EE .PP Second, if the purpose of a function is to set \f[B]ibase\f[R], \f[B]obase\f[R], \f[B]scale\f[R], or \f[B]seed\f[R] globally for any @@ -146,53 +233,63 @@ desired value for a global. .PP For functions that set \f[B]seed\f[R], the value assigned to \f[B]seed\f[R] is not propagated to parent functions. -This means that the sequence of pseudo-random numbers that they see will -not be the same sequence of pseudo-random numbers that any parent sees. +This means that the sequence of pseudo\-random numbers that they see +will not be the same sequence of pseudo\-random numbers that any parent +sees. This is only the case once \f[B]seed\f[R] has been set. .PP -If a function desires to not affect the sequence of pseudo-random +If a function desires to not affect the sequence of pseudo\-random numbers of its parents, but wants to use the same \f[B]seed\f[R], it can use the following line: .IP -.nf -\f[C] +.EX seed = seed -\f[R] -.fi +.EE .PP If the behavior of this option is desired for every run of bc(1), then users could make sure to define \f[B]BC_ENV_ARGS\f[R] and include this option (see the \f[B]ENVIRONMENT VARIABLES\f[R] section for more details). .PP -If \f[B]-s\f[R], \f[B]-w\f[R], or any equivalents are used, this option -is ignored. +If \f[B]\-s\f[R], \f[B]\-w\f[R], or any equivalents are used, this +option is ignored. .PP -This is a \f[B]non-portable extension\f[R]. +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. +\f[B]\-h\f[R], \f[B]\-\-help\f[R] +Prints a usage message and exits. .TP -\f[B]-i\f[R], \f[B]--interactive\f[R] +\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. (See the \f[B]INTERACTIVE MODE\f[R] section.) .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-L\f[R], \f[B]--no-line-length\f[R] +\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]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-l\f[R], \f[B]--mathlib\f[R] +\f[B]\-l\f[R], \f[B]\-\-mathlib\f[R] Sets \f[B]scale\f[R] (see the \f[B]SYNTAX\f[R] section) to \f[B]20\f[R] and loads the included math library and the extended math library before running any code, including any expressions or files specified on the @@ -202,11 +299,23 @@ command line. To learn what is in the libraries, see the \f[B]LIBRARY\f[R] section. .RE .TP -\f[B]-P\f[R], \f[B]--no-prompt\f[R] +\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 @@ -214,14 +323,31 @@ Most of those users would want to put this option in These options override the \f[B]BC_PROMPT\f[R] and \f[B]BC_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]. +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] +\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 @@ -229,16 +355,16 @@ 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]read()\f[R] built-in function is called. +is only used when the \f[B]read()\f[R] built\-in function is called. .PP These options \f[I]do\f[R] override the \f[B]BC_PROMPT\f[R] and \f[B]BC_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]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-r\f[R] \f[I]keyword\f[R], \f[B]--redefine\f[R]=\f[I]keyword\f[R] +\f[B]\-r\f[R] \f[I]keyword\f[R], \f[B]\-\-redefine\f[R]=\f[I]keyword\f[R] Redefines \f[I]keyword\f[R] in order to allow it to be used as a function, variable, or array name. This is useful when this bc(1) gives parse errors when parsing scripts @@ -294,157 +420,63 @@ 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 -This is a \f[B]non-portable extension\f[R]. +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. +\f[B]\-s\f[R], \f[B]\-\-standard\f[R] +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]. +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. +\f[B]\-v\f[R], \f[B]\-V\f[R], \f[B]\-\-version\f[R] +Print the version information (copyright header) and exits. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-w\f[R], \f[B]--warn\f[R] -Like \f[B]-s\f[R] and \f[B]--standard\f[R], except that warnings (and -not errors) are printed for non-standard extensions and execution +\f[B]\-w\f[R], \f[B]\-\-warn\f[R] +Like \f[B]\-s\f[R] and \f[B]\-\-standard\f[R], except that warnings (and +not errors) are printed for non\-standard extensions and execution continues normally. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-z\f[R], \f[B]--leading-zeroes\f[R] -Makes bc(1) print all numbers greater than \f[B]-1\f[R] and less than +\f[B]\-z\f[R], \f[B]\-\-leading\-zeroes\f[R] +Makes bc(1) print all numbers greater than \f[B]\-1\f[R] and less than \f[B]1\f[R], and not equal to \f[B]0\f[R], with a leading zero. .RS .PP This can be set for individual numbers with the \f[B]plz(x)\f[R], -plznl(x)**, \f[B]pnlz(x)\f[R], and \f[B]pnlznl(x)\f[R] functions in the -extended math library (see the \f[B]LIBRARY\f[R] section). -.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. +\f[B]plznl(x)\f[R], \f[B]pnlz(x)\f[R], and \f[B]pnlznl(x)\f[R] functions +in the extended math library (see the \f[B]LIBRARY\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +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]. +All long options are \f[B]non\-portable extensions\f[R]. .SH STDIN -.PP -If no files or expressions are given by the \f[B]-f\f[R], -\f[B]--file\f[R], \f[B]-e\f[R], or \f[B]--expression\f[R] options, then -bc(1) reads from \f[B]stdin\f[R]. +If no files or expressions are given by the \f[B]\-f\f[R], +\f[B]\-\-file\f[R], \f[B]\-e\f[R], or \f[B]\-\-expression\f[R] options, +then bc(1) reads from \f[B]stdin\f[R]. .PP However, there are a few caveats to this. .PP @@ -458,8 +490,7 @@ Second, after an \f[B]if\f[R] statement, bc(1) doesn\[cq]t know if an \f[B]else\f[R] statement will follow, so it will not execute until it knows there will not be an \f[B]else\f[R] statement. .SH STDOUT -.PP -Any non-error output is written to \f[B]stdout\f[R]. +Any non\-error output is written to \f[B]stdout\f[R]. In addition, if history (see the \f[B]HISTORY\f[R] section) and the prompt (see the \f[B]TTY MODE\f[R] section) are enabled, both are output to \f[B]stdout\f[R]. @@ -467,7 +498,7 @@ to \f[B]stdout\f[R]. \f[B]Note\f[R]: Unlike other bc(1) implementations, this bc(1) will issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot write to \f[B]stdout\f[R], so if \f[B]stdout\f[R] is closed, as in -\f[B]bc >&-\f[R], it will quit with an error. +\f[B]bc >&\-\f[R], it will quit with an error. This is done so that bc(1) can report problems when \f[B]stdout\f[R] is redirected to a file. .PP @@ -475,13 +506,12 @@ If there are scripts that depend on the behavior of other bc(1) implementations, it is recommended that those scripts be changed to redirect \f[B]stdout\f[R] to \f[B]/dev/null\f[R]. .SH STDERR -.PP Any error output is written to \f[B]stderr\f[R]. .PP \f[B]Note\f[R]: Unlike other bc(1) implementations, this bc(1) will issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot write to \f[B]stderr\f[R], so if \f[B]stderr\f[R] is closed, as in -\f[B]bc 2>&-\f[R], it will quit with an error. +\f[B]bc 2>&\-\f[R], it will quit with an error. This is done so that bc(1) can exit with an error code when \f[B]stderr\f[R] is redirected to a file. .PP @@ -489,12 +519,10 @@ If there are scripts that depend on the behavior of other bc(1) implementations, it is recommended that those scripts be changed to redirect \f[B]stderr\f[R] to \f[B]/dev/null\f[R]. .SH SYNTAX -.PP -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. +The syntax for bc(1) programs is mostly C\-like, with some differences. +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 @@ -502,32 +530,32 @@ In the sections below, \f[B]E\f[R] means expression, \f[B]S\f[R] means statement, and \f[B]I\f[R] means identifier. .PP Identifiers (\f[B]I\f[R]) start with a lowercase letter and can be -followed by any number (up to \f[B]BC_NAME_MAX-1\f[R]) of lowercase -letters (\f[B]a-z\f[R]), digits (\f[B]0-9\f[R]), and underscores +followed by any number (up to \f[B]BC_NAME_MAX\-1\f[R]) of lowercase +letters (\f[B]a\-z\f[R]), digits (\f[B]0\-9\f[R]), and underscores (\f[B]_\f[R]). -The regex is \f[B][a-z][a-z0-9_]*\f[R]. +The regex is \f[B][a\-z][a\-z0\-9_]*\f[R]. Identifiers with more than one character (letter) are a -\f[B]non-portable extension\f[R]. +\f[B]non\-portable extension\f[R]. .PP \f[B]ibase\f[R] is a global variable determining how to interpret constant numbers. It is the \[lq]input\[rq] base, or the number base used for interpreting input numbers. \f[B]ibase\f[R] is initially \f[B]10\f[R]. -If the \f[B]-s\f[R] (\f[B]--standard\f[R]) and \f[B]-w\f[R] -(\f[B]--warn\f[R]) flags were not given on the command line, the max +If the \f[B]\-s\f[R] (\f[B]\-\-standard\f[R]) and \f[B]\-w\f[R] +(\f[B]\-\-warn\f[R]) flags were not given on the command line, the max allowable value for \f[B]ibase\f[R] is \f[B]36\f[R]. Otherwise, it is \f[B]16\f[R]. The min allowable value for \f[B]ibase\f[R] is \f[B]2\f[R]. The max allowable value for \f[B]ibase\f[R] can be queried in bc(1) -programs with the \f[B]maxibase()\f[R] built-in function. +programs with the \f[B]maxibase()\f[R] built\-in function. .PP \f[B]obase\f[R] is a global variable determining how to output results. It is the \[lq]output\[rq] base, or the number base used for outputting numbers. \f[B]obase\f[R] is initially \f[B]10\f[R]. The max allowable value for \f[B]obase\f[R] is \f[B]BC_BASE_MAX\f[R] and -can be queried in bc(1) programs with the \f[B]maxobase()\f[R] built-in +can be queried in bc(1) programs with the \f[B]maxobase()\f[R] built\-in function. The min allowable value for \f[B]obase\f[R] is \f[B]0\f[R]. If \f[B]obase\f[R] is \f[B]0\f[R], values are output in scientific @@ -535,8 +563,8 @@ notation, and if \f[B]obase\f[R] is \f[B]1\f[R], values are output in engineering notation. Otherwise, values are output in the specified base. .PP -Outputting in scientific and engineering notations are \f[B]non-portable -extensions\f[R]. +Outputting in scientific and engineering notations are +\f[B]non\-portable extensions\f[R]. .PP The \f[I]scale\f[R] of an expression is the number of digits in the result of the expression right of the decimal point, and \f[B]scale\f[R] @@ -546,7 +574,7 @@ exceptions. \f[B]scale\f[R] cannot be negative. The max allowable value for \f[B]scale\f[R] is \f[B]BC_SCALE_MAX\f[R] and can be queried in bc(1) programs with the \f[B]maxscale()\f[R] -built-in function. +built\-in function. .PP bc(1) has both \f[I]global\f[R] variables and \f[I]local\f[R] variables. All \f[I]local\f[R] variables are local to the function; they are @@ -571,20 +599,18 @@ The value that is printed is also assigned to the special variable \f[B]last\f[R]. A single dot (\f[B].\f[R]) may also be used as a synonym for \f[B]last\f[R]. -These are \f[B]non-portable extensions\f[R]. +These are \f[B]non\-portable extensions\f[R]. .PP Either semicolons or newlines may separate statements. .SS Comments -.PP There are two kinds of comments: .IP "1." 3 Block comments are enclosed in \f[B]/*\f[R] and \f[B]*/\f[R]. .IP "2." 3 Line comments go from \f[B]#\f[R] until, and not including, the next newline. -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .SS Named Expressions -.PP The following are named expressions in bc(1): .IP "1." 3 Variables: \f[B]I\f[R] @@ -601,26 +627,26 @@ Array Elements: \f[B]I[E]\f[R] .IP "7." 3 \f[B]last\f[R] or a single dot (\f[B].\f[R]) .PP -Numbers 6 and 7 are \f[B]non-portable extensions\f[R]. +Numbers 6 and 7 are \f[B]non\-portable extensions\f[R]. .PP -The meaning of \f[B]seed\f[R] is dependent on the current pseudo-random +The meaning of \f[B]seed\f[R] is dependent on the current pseudo\-random number generator but is guaranteed to not change except for new major versions. .PP The \f[I]scale\f[R] and sign of the value may be significant. .PP If a previously used \f[B]seed\f[R] value is assigned to \f[B]seed\f[R] -and used again, the pseudo-random number generator is guaranteed to -produce the same sequence of pseudo-random numbers as it did when the +and used again, the pseudo\-random number generator is guaranteed to +produce the same sequence of pseudo\-random numbers as it did when the \f[B]seed\f[R] value was previously used. .PP The exact value assigned to \f[B]seed\f[R] is not guaranteed to be returned if \f[B]seed\f[R] is queried again immediately. However, if \f[B]seed\f[R] \f[I]does\f[R] return a different value, both values, when assigned to \f[B]seed\f[R], are guaranteed to produce the -same sequence of pseudo-random numbers. +same sequence of pseudo\-random numbers. This means that certain values assigned to \f[B]seed\f[R] will -\f[I]not\f[R] produce unique sequences of pseudo-random numbers. +\f[I]not\f[R] produce unique sequences of pseudo\-random numbers. The value of \f[B]seed\f[R] will change after any use of the \f[B]rand()\f[R] and \f[B]irand(E)\f[R] operands (see the \f[I]Operands\f[R] subsection below), except if the parameter passed to @@ -641,7 +667,6 @@ Named expressions are required as the operand of of \f[B]assignment\f[R] operators (see the \f[I]Operators\f[R] subsection). .SS Operands -.PP The following are valid operands in bc(1): .IP " 1." 4 Numbers (see the \f[I]Numbers\f[R] subsection below). @@ -651,99 +676,113 @@ Array indices (\f[B]I[E]\f[R]). \f[B](E)\f[R]: The value of \f[B]E\f[R] (used to change precedence). .IP " 4." 4 \f[B]sqrt(E)\f[R]: The square root of \f[B]E\f[R]. -\f[B]E\f[R] must be non-negative. +\f[B]E\f[R] must be non\-negative. .IP " 5." 4 \f[B]length(E)\f[R]: The number of significant decimal digits in \f[B]E\f[R]. Returns \f[B]1\f[R] for \f[B]0\f[R] with no decimal places. If given a string, the length of the string is returned. -Passing a string to \f[B]length(E)\f[R] is a \f[B]non-portable +Passing a string to \f[B]length(E)\f[R] is a \f[B]non\-portable extension\f[R]. .IP " 6." 4 \f[B]length(I[])\f[R]: The number of elements in the array \f[B]I\f[R]. -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .IP " 7." 4 \f[B]scale(E)\f[R]: The \f[I]scale\f[R] of \f[B]E\f[R]. .IP " 8." 4 \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]. +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. 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 +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 "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, -which must be non-zero. +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 +This is a \f[B]non\-portable extension\f[R]. +.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 +that number as a one\-character string. +This is a \f[B]non\-portable extension\f[R]. +.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[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). The \f[B]E\f[R] argument(s) may also be arrays of the form \f[B]I[]\f[R], which will automatically be turned into array references (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 +This is a \f[B]non\-portable extension\f[R]. +.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 +This is a \f[B]non\-portable extension\f[R]. +.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 +This is a \f[B]non\-portable extension\f[R]. +.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 +This is a \f[B]non\-portable extension\f[R]. +.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 +This is a \f[B]non\-portable extension\f[R]. +.IP "21." 4 \f[B]global_stacks()\f[R]: \f[B]0\f[R] if global stacks are not enabled -with the \f[B]-g\f[R] or \f[B]--global-stacks\f[R] options, non-zero -otherwise. +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 +This is a \f[B]non\-portable extension\f[R]. +.IP "22." 4 \f[B]leading_zero()\f[R]: \f[B]0\f[R] if leading zeroes are not enabled -with the \f[B]-z\f[R] or \f[B]\[en]leading-zeroes\f[R] options, non-zero -otherwise. +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 -\f[B]rand()\f[R]: A pseudo-random integer between \f[B]0\f[R] +This is a \f[B]non\-portable extension\f[R]. +.IP "23." 4 +\f[B]rand()\f[R]: A pseudo\-random integer between \f[B]0\f[R] (inclusive) and \f[B]BC_RAND_MAX\f[R] (inclusive). Using this operand will change the value of \f[B]seed\f[R]. -This is a \f[B]non-portable extension\f[R]. -.IP "21." 4 -\f[B]irand(E)\f[R]: A pseudo-random integer between \f[B]0\f[R] +This is a \f[B]non\-portable extension\f[R]. +.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 +If \f[B]E\f[R] is negative or is a non\-integer (\f[B]E\f[R]\[cq]s \f[I]scale\f[R] is not \f[B]0\f[R]), an error is raised, and bc(1) resets (see the \f[B]RESET\f[R] section) while \f[B]seed\f[R] remains unchanged. If \f[B]E\f[R] is larger than \f[B]BC_RAND_MAX\f[R], the higher bound is -honored by generating several pseudo-random integers, multiplying them +honored by generating several pseudo\-random integers, multiplying them by appropriate powers of \f[B]BC_RAND_MAX+1\f[R], and adding them together. Thus, the size of integer that can be generated with this operand is @@ -752,52 +791,83 @@ Using this operand will change the value of \f[B]seed\f[R], unless the 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 +This is a \f[B]non\-portable extension\f[R]. +.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]. +This is a \f[B]non\-portable extension\f[R]. .PP The integers generated by \f[B]rand()\f[R] and \f[B]irand(E)\f[R] are guaranteed to be as unbiased as possible, subject to the limitations of -the pseudo-random number generator. +the pseudo\-random number generator. .PP -\f[B]Note\f[R]: The values returned by the pseudo-random number +\f[B]Note\f[R]: The values returned by the pseudo\-random number generator with \f[B]rand()\f[R] and \f[B]irand(E)\f[R] are guaranteed to \f[I]NOT\f[R] be cryptographically secure. -This is a consequence of using a seeded pseudo-random number generator. +This is a consequence of using a seeded pseudo\-random number generator. However, they \f[I]are\f[R] guaranteed to be reproducible with identical \f[B]seed\f[R] values. -This means that the pseudo-random values from bc(1) should only be used -where a reproducible stream of pseudo-random numbers is +This means that the pseudo\-random values from bc(1) should only be used +where a reproducible stream of pseudo\-random numbers is \f[I]ESSENTIAL\f[R]. -In any other case, use a non-seeded pseudo-random number generator. +In any other case, use a non\-seeded pseudo\-random number generator. .SS Numbers -.PP 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]. The exponent (the portion after the \f[B]e\f[R]) must be an integer. An example is \f[B]1.89237e9\f[R], which is equal to \f[B]1892370000\f[R]. -Negative exponents are also allowed, so \f[B]4.2890e-3\f[R] is equal to +Negative exponents are also allowed, so \f[B]4.2890e\-3\f[R] is equal to \f[B]0.0042890\f[R]. .PP -Using scientific notation is an error or warning if the \f[B]-s\f[R] or -\f[B]-w\f[R], respectively, command-line options (or equivalents) are +Using scientific notation is an error or warning if the \f[B]\-s\f[R] or +\f[B]\-w\f[R], respectively, command\-line options (or equivalents) are given. .PP \f[B]WARNING\f[R]: Both the number and the exponent in scientific @@ -807,17 +877,16 @@ of the current \f[B]ibase\f[R]. For example, if \f[B]ibase\f[R] is \f[B]16\f[R] and bc(1) is given the number string \f[B]FFeA\f[R], the resulting decimal number will be \f[B]2550000000000\f[R], and if bc(1) is given the number string -\f[B]10e-4\f[R], the resulting decimal number will be \f[B]0.0016\f[R]. +\f[B]10e\-4\f[R], the resulting decimal number will be \f[B]0.0016\f[R]. .PP -Accepting input as scientific notation is a \f[B]non-portable +Accepting input as scientific notation is a \f[B]non\-portable extension\f[R]. .SS Operators -.PP The following arithmetic and logical operators can be used. They are listed in order of decreasing precedence. Operators in the same group have the same precedence. .TP -\f[B]++\f[R] \f[B]--\f[R] +\f[B]++\f[R] \f[B]\-\-\f[R] Type: Prefix and Postfix .RS .PP @@ -826,7 +895,7 @@ Associativity: None Description: \f[B]increment\f[R], \f[B]decrement\f[R] .RE .TP -\f[B]-\f[R] \f[B]!\f[R] +\f[B]\-\f[R] \f[B]!\f[R] Type: Prefix .RS .PP @@ -871,7 +940,7 @@ Associativity: Left Description: \f[B]multiply\f[R], \f[B]divide\f[R], \f[B]modulus\f[R] .RE .TP -\f[B]+\f[R] \f[B]-\f[R] +\f[B]+\f[R] \f[B]\-\f[R] Type: Binary .RS .PP @@ -889,7 +958,7 @@ Associativity: Left Description: \f[B]shift left\f[R], \f[B]shift right\f[R] .RE .TP -\f[B]=\f[R] \f[B]<<=\f[R] \f[B]>>=\f[R] \f[B]+=\f[R] \f[B]-=\f[R] \f[B]*=\f[R] \f[B]/=\f[R] \f[B]%=\f[R] \f[B]\[ha]=\f[R] \f[B]\[at]=\f[R] +\f[B]=\f[R] \f[B]<<=\f[R] \f[B]>>=\f[R] \f[B]+=\f[R] \f[B]\-=\f[R] \f[B]*=\f[R] \f[B]/=\f[R] \f[B]%=\f[R] \f[B]\[ha]=\f[R] \f[B]\[at]=\f[R] Type: Binary .RS .PP @@ -927,18 +996,18 @@ Description: \f[B]boolean or\f[R] .PP The operators will be described in more detail below. .TP -\f[B]++\f[R] \f[B]--\f[R] +\f[B]++\f[R] \f[B]\-\-\f[R] The prefix and postfix \f[B]increment\f[R] and \f[B]decrement\f[R] -operators behave exactly like they would in C. -They require a named expression (see the \f[I]Named Expressions\f[R] -subsection) as an operand. +operators behave exactly like they would in C. They require a named +expression (see the \f[I]Named Expressions\f[R] subsection) as an +operand. .RS .PP The prefix versions of these operators are more efficient; use them where possible. .RE .TP -\f[B]-\f[R] +\f[B]\-\f[R] The \f[B]negation\f[R] operator returns \f[B]0\f[R] if a user attempts to negate any expression with the value \f[B]0\f[R]. Otherwise, a copy of the expression with its sign flipped is returned. @@ -948,7 +1017,11 @@ The \f[B]boolean not\f[R] operator returns \f[B]1\f[R] if the expression is \f[B]0\f[R], or \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +\f[B]Warning\f[R]: This operator has a \f[B]different precedence\f[R] +than the equivalent operator in GNU bc(1) and other bc(1) +implementations! +.PP +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]$\f[R] @@ -956,7 +1029,7 @@ The \f[B]truncation\f[R] operator returns a copy of the given expression with all of its \f[I]scale\f[R] removed. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]\[at]\f[R] @@ -970,9 +1043,9 @@ more). .RS .PP The second expression must be an integer (no \f[I]scale\f[R]) and -non-negative. +non\-negative. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]\[ha]\f[R] @@ -983,7 +1056,7 @@ The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R]. .RS .PP The second expression must be an integer (no \f[I]scale\f[R]), and if it -is negative, the first value must be non-zero. +is negative, the first value must be non\-zero. .RE .TP \f[B]*\f[R] @@ -1001,18 +1074,18 @@ returns the quotient. The \f[I]scale\f[R] of the result shall be the value of \f[B]scale\f[R]. .RS .PP -The second expression must be non-zero. +The second expression must be non\-zero. .RE .TP \f[B]%\f[R] The \f[B]modulus\f[R] operator takes two expressions, \f[B]a\f[R] and \f[B]b\f[R], and evaluates them by 1) Computing \f[B]a/b\f[R] to current \f[B]scale\f[R] and 2) Using the result of step 1 to calculate -\f[B]a-(a/b)*b\f[R] to \f[I]scale\f[R] +\f[B]a\-(a/b)*b\f[R] to \f[I]scale\f[R] \f[B]max(scale+scale(b),scale(a))\f[R]. .RS .PP -The second expression must be non-zero. +The second expression must be non\-zero. .RE .TP \f[B]+\f[R] @@ -1020,7 +1093,7 @@ The \f[B]add\f[R] operator takes two expressions, \f[B]a\f[R] and \f[B]b\f[R], and returns the sum, with a \f[I]scale\f[R] equal to the max of the \f[I]scale\f[R]s of \f[B]a\f[R] and \f[B]b\f[R]. .TP -\f[B]-\f[R] +\f[B]\-\f[R] The \f[B]subtract\f[R] operator takes two expressions, \f[B]a\f[R] and \f[B]b\f[R], and returns the difference, with a \f[I]scale\f[R] equal to the max of the \f[I]scale\f[R]s of \f[B]a\f[R] and \f[B]b\f[R]. @@ -1032,9 +1105,9 @@ decimal point moved \f[B]b\f[R] places to the right. .RS .PP The second expression must be an integer (no \f[I]scale\f[R]) and -non-negative. +non\-negative. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]>>\f[R] @@ -1044,12 +1117,12 @@ decimal point moved \f[B]b\f[R] places to the left. .RS .PP The second expression must be an integer (no \f[I]scale\f[R]) and -non-negative. +non\-negative. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]=\f[R] \f[B]<<=\f[R] \f[B]>>=\f[R] \f[B]+=\f[R] \f[B]-=\f[R] \f[B]*=\f[R] \f[B]/=\f[R] \f[B]%=\f[R] \f[B]\[ha]=\f[R] \f[B]\[at]=\f[R] +\f[B]=\f[R] \f[B]<<=\f[R] \f[B]>>=\f[R] \f[B]+=\f[R] \f[B]\-=\f[R] \f[B]*=\f[R] \f[B]/=\f[R] \f[B]%=\f[R] \f[B]\[ha]=\f[R] \f[B]\[at]=\f[R] The \f[B]assignment\f[R] operators take two expressions, \f[B]a\f[R] and \f[B]b\f[R] where \f[B]a\f[R] is a named expression (see the \f[I]Named Expressions\f[R] subsection). @@ -1062,7 +1135,7 @@ the corresponding arithmetic operator and the result is assigned to \f[B]a\f[R]. .PP The \f[B]assignment\f[R] operators that correspond to operators that are -extensions are themselves \f[B]non-portable extensions\f[R]. +extensions are themselves \f[B]non\-portable extensions\f[R]. .RE .TP \f[B]==\f[R] \f[B]<=\f[R] \f[B]>=\f[R] \f[B]!=\f[R] \f[B]<\f[R] \f[B]>\f[R] @@ -1076,41 +1149,39 @@ 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]. +This allowance is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]&&\f[R] The \f[B]boolean and\f[R] operator takes two expressions and returns -\f[B]1\f[R] if both expressions are non-zero, \f[B]0\f[R] otherwise. +\f[B]1\f[R] if both expressions are non\-zero, \f[B]0\f[R] otherwise. .RS .PP -This is \f[I]not\f[R] a short-circuit operator. +This is \f[I]not\f[R] a short\-circuit operator. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]||\f[R] The \f[B]boolean or\f[R] operator takes two expressions and returns -\f[B]1\f[R] if one of the expressions is non-zero, \f[B]0\f[R] +\f[B]1\f[R] if one of the expressions is non\-zero, \f[B]0\f[R] otherwise. .RS .PP -This is \f[I]not\f[R] a short-circuit operator. +This is \f[I]not\f[R] a short\-circuit operator. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .SS Statements -.PP 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 +1207,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 @@ -1149,10 +1222,10 @@ The \f[B]E\f[R] argument(s) may also be arrays of the form \f[B]FUNCTIONS\f[R] section) if the corresponding parameter in the function definition is an array reference. .PP -Numbers 4, 9, 11, 12, 14, 15, and 16 are \f[B]non-portable +Numbers 4, 9, 11, 12, 14, 15, and 16 are \f[B]non\-portable extensions\f[R]. .PP -Also, as a \f[B]non-portable extension\f[R], any or all of the +Also, as a \f[B]non\-portable extension\f[R], any or all of the expressions in the header of a for loop may be omitted. If the condition (second expression) is omitted, it is assumed to be a constant \f[B]1\f[R]. @@ -1169,7 +1242,24 @@ This is only allowed in loops. The \f[B]if\f[R] \f[B]else\f[R] statement does the same thing as in C. .PP 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). +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 +.EX +for (i = 0; i < 3; ++i) i; quit +.EE +.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 @@ -1177,7 +1267,7 @@ that is not executed, bc(1) does not quit.) .PP The \f[B]limits\f[R] statement prints the limits that this bc(1) is subject to. -This is like the \f[B]quit\f[R] statement in that it is a compile-time +This is like the \f[B]quit\f[R] statement in that it is a compile\-time command. .PP An expression by itself is evaluated and printed, followed by a newline. @@ -1190,13 +1280,12 @@ Scientific notation is activated by assigning \f[B]0\f[R] to To deactivate them, just assign a different value to \f[B]obase\f[R]. .PP Scientific notation and engineering notation are disabled if bc(1) is -run with either the \f[B]-s\f[R] or \f[B]-w\f[R] command-line options +run with either the \f[B]\-s\f[R] or \f[B]\-w\f[R] command\-line options (or equivalents). .PP Printing numbers in scientific notation and/or engineering notation is a -\f[B]non-portable extension\f[R]. +\f[B]non\-portable extension\f[R]. .SS Strings -.PP If strings appear as a statement by themselves, they are printed without a trailing newline. .PP @@ -1213,9 +1302,8 @@ element that has been assigned a string, an error is raised, and bc(1) resets (see the \f[B]RESET\f[R] section). .PP Assigning strings to variables and array elements and passing them to -functions are \f[B]non-portable extensions\f[R]. +functions are \f[B]non\-portable extensions\f[R]. .SS Print Statement -.PP The \[lq]expressions\[rq] in a \f[B]print\f[R] statement may also be strings. If they are, there are backslash escape sequences that are interpreted @@ -1242,14 +1330,12 @@ below: \f[B]\[rs]t\f[R]: \f[B]\[rs]t\f[R] .PP Any other character following a backslash causes the backslash and -character to be printed as-is. +character to be printed as\-is. .PP -Any non-string expression in a print statement shall be assigned to +Any non\-string expression in a print statement shall be assigned to \f[B]last\f[R], like any other expression that is printed. .SS Stream Statement -.PP -The \[lq]expressions in a \f[B]stream\f[R] statement may also be -strings. +The expressions in a \f[B]stream\f[R] statement may also be strings. .PP If a \f[B]stream\f[R] statement is given a string, it prints the string as though the string had appeared as its own statement. @@ -1259,20 +1345,17 @@ without a newline. If a \f[B]stream\f[R] statement is given a number, a copy of it is truncated and its absolute value is calculated. The result is then printed as though \f[B]obase\f[R] is \f[B]256\f[R] -and each digit is interpreted as an 8-bit ASCII character, making it a +and each digit is interpreted as an 8\-bit ASCII character, making it a byte stream. .SS Order of Evaluation -.PP All expressions in a statment are evaluated left to right, except as necessary to maintain order of operations. This means, for example, assuming that \f[B]i\f[R] is equal to \f[B]0\f[R], in the expression .IP -.nf -\f[C] +.EX a[i++] = i++ -\f[R] -.fi +.EE .PP the first (or 0th) element of \f[B]a\f[R] is set to \f[B]1\f[R], and \f[B]i\f[R] is equal to \f[B]2\f[R] at the end of the expression. @@ -1281,28 +1364,23 @@ This includes function arguments. Thus, assuming \f[B]i\f[R] is equal to \f[B]0\f[R], this means that in the expression .IP -.nf -\f[C] +.EX x(i++, i++) -\f[R] -.fi +.EE .PP the first argument passed to \f[B]x()\f[R] is \f[B]0\f[R], and the second argument is \f[B]1\f[R], while \f[B]i\f[R] is equal to \f[B]2\f[R] before the function starts executing. .SH FUNCTIONS -.PP Function definitions are as follows: .IP -.nf -\f[C] +.EX define I(I,...,I){ auto I,...,I S;...;S return(E) } -\f[R] -.fi +.EE .PP Any \f[B]I\f[R] in the parameter list or \f[B]auto\f[R] list may be replaced with \f[B]I[]\f[R] to make a parameter or \f[B]auto\f[R] var an @@ -1313,10 +1391,10 @@ asterisk in the call; they must be called with just \f[B]I[]\f[R] like normal array parameters and will be automatically converted into references. .PP -As a \f[B]non-portable extension\f[R], the opening brace of a +As a \f[B]non\-portable extension\f[R], the opening brace of a \f[B]define\f[R] statement may appear on the next line. .PP -As a \f[B]non-portable extension\f[R], the return statement may also be +As a \f[B]non\-portable extension\f[R], the return statement may also be in one of the following forms: .IP "1." 3 \f[B]return\f[R] @@ -1330,18 +1408,15 @@ equivalent to \f[B]return (0)\f[R], unless the function is a \f[B]void\f[R] function (see the \f[I]Void Functions\f[R] subsection below). .SS Void Functions -.PP Functions can also be \f[B]void\f[R] functions, defined as follows: .IP -.nf -\f[C] +.EX define void I(I,...,I){ auto I,...,I S;...;S return } -\f[R] -.fi +.EE .PP They can only be used as standalone expressions, where such an expression would be printed alone, except in a print statement. @@ -1355,17 +1430,14 @@ possible to have variables, arrays, and functions named \f[B]void\f[R]. The word \[lq]void\[rq] is only treated specially right after the \f[B]define\f[R] keyword. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .SS Array References -.PP For any array in the parameter list, if the array is declared in the form .IP -.nf -\f[C] +.EX *I[] -\f[R] -.fi +.EE .PP it is a \f[B]reference\f[R]. Any changes to the array in the function are reflected, when the @@ -1373,20 +1445,17 @@ function returns, to the array that was passed in. .PP Other than this, all function arguments are passed by value. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .SH LIBRARY -.PP All of the functions below, including the functions in the extended math library (see the \f[I]Extended Library\f[R] subsection below), are -available when the \f[B]-l\f[R] or \f[B]--mathlib\f[R] command-line +available when the \f[B]\-l\f[R] or \f[B]\-\-mathlib\f[R] command\-line flags are given, except that the extended math library is not available -when the \f[B]-s\f[R] option, the \f[B]-w\f[R] option, or equivalents +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. @@ -1437,14 +1506,12 @@ This is a transcendental function (see the \f[I]Transcendental Functions\f[R] subsection below). .RE .SS Extended Library -.PP 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] +\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]. +The extended library is a \f[B]non\-portable extension\f[R]. .TP \f[B]p(x, y)\f[R] Calculates \f[B]x\f[R] to the power of \f[B]y\f[R], even if \f[B]y\f[R] @@ -1472,6 +1539,14 @@ the rounding mode round away from \f[B]0\f[R] \f[B]f(x)\f[R] Returns the factorial of the truncated absolute value of \f[B]x\f[R]. .TP +\f[B]max(a, b)\f[R] +Returns \f[B]a\f[R] if \f[B]a\f[R] is greater than \f[B]b\f[R]; +otherwise, returns \f[B]b\f[R]. +.TP +\f[B]min(a, b)\f[R] +Returns \f[B]a\f[R] if \f[B]a\f[R] is less than \f[B]b\f[R]; otherwise, +returns \f[B]b\f[R]. +.TP \f[B]perm(n, k)\f[R] Returns the permutation of the truncated absolute value of \f[B]n\f[R] of the truncated absolute value of \f[B]k\f[R], if \f[B]k <= n\f[R]. @@ -1482,6 +1557,10 @@ Returns the combination of the truncated absolute value of \f[B]n\f[R] of the truncated absolute value of \f[B]k\f[R], if \f[B]k <= n\f[R]. If not, it returns \f[B]0\f[R]. .TP +\f[B]fib(n)\f[R] +Returns the Fibonacci number of the truncated absolute value of +\f[B]n\f[R]. +.TP \f[B]l2(x)\f[R] Returns the logarithm base \f[B]2\f[R] of \f[B]x\f[R]. .RS @@ -1553,11 +1632,11 @@ Otherwise, if \f[B]x\f[R] is greater than \f[B]0\f[R], it returns If \f[B]x\f[R] is less than \f[B]0\f[R], and \f[B]y\f[R] is greater than or equal to \f[B]0\f[R], it returns \f[B]a(y/x)+pi\f[R]. If \f[B]x\f[R] is less than \f[B]0\f[R], and \f[B]y\f[R] is less than -\f[B]0\f[R], it returns \f[B]a(y/x)-pi\f[R]. +\f[B]0\f[R], it returns \f[B]a(y/x)\-pi\f[R]. If \f[B]x\f[R] is equal to \f[B]0\f[R], and \f[B]y\f[R] is greater than \f[B]0\f[R], it returns \f[B]pi/2\f[R]. If \f[B]x\f[R] is equal to \f[B]0\f[R], and \f[B]y\f[R] is less than -\f[B]0\f[R], it returns \f[B]-pi/2\f[R]. +\f[B]0\f[R], it returns \f[B]\-pi/2\f[R]. .RS .PP This function is the same as the \f[B]atan2()\f[R] function in many @@ -1591,7 +1670,7 @@ Functions\f[R] subsection below). Returns the tangent of \f[B]x\f[R], which is assumed to be in radians. .RS .PP -If \f[B]x\f[R] is equal to \f[B]1\f[R] or \f[B]-1\f[R], this raises an +If \f[B]x\f[R] is equal to \f[B]1\f[R] or \f[B]\-1\f[R], this raises an error and causes bc(1) to reset (see the \f[B]RESET\f[R] section). .PP This is an alias of \f[B]t(x)\f[R]. @@ -1619,11 +1698,11 @@ Otherwise, if \f[B]x\f[R] is greater than \f[B]0\f[R], it returns If \f[B]x\f[R] is less than \f[B]0\f[R], and \f[B]y\f[R] is greater than or equal to \f[B]0\f[R], it returns \f[B]a(y/x)+pi\f[R]. If \f[B]x\f[R] is less than \f[B]0\f[R], and \f[B]y\f[R] is less than -\f[B]0\f[R], it returns \f[B]a(y/x)-pi\f[R]. +\f[B]0\f[R], it returns \f[B]a(y/x)\-pi\f[R]. If \f[B]x\f[R] is equal to \f[B]0\f[R], and \f[B]y\f[R] is greater than \f[B]0\f[R], it returns \f[B]pi/2\f[R]. If \f[B]x\f[R] is equal to \f[B]0\f[R], and \f[B]y\f[R] is less than -\f[B]0\f[R], it returns \f[B]-pi/2\f[R]. +\f[B]0\f[R], it returns \f[B]\-pi/2\f[R]. .RS .PP This function is the same as the \f[B]atan2()\f[R] function in many @@ -1652,7 +1731,7 @@ Functions\f[R] subsection below). .RE .TP \f[B]frand(p)\f[R] -Generates a pseudo-random number between \f[B]0\f[R] (inclusive) and +Generates a pseudo\-random number between \f[B]0\f[R] (inclusive) and \f[B]1\f[R] (exclusive) with the number of decimal digits after the decimal point equal to the truncated absolute value of \f[B]p\f[R]. If \f[B]p\f[R] is not \f[B]0\f[R], then calling this function will @@ -1661,14 +1740,22 @@ If \f[B]p\f[R] is \f[B]0\f[R], then \f[B]0\f[R] is returned, and \f[B]seed\f[R] is \f[I]not\f[R] changed. .TP \f[B]ifrand(i, p)\f[R] -Generates a pseudo-random number that is between \f[B]0\f[R] (inclusive) -and the truncated absolute value of \f[B]i\f[R] (exclusive) with the -number of decimal digits after the decimal point equal to the truncated -absolute value of \f[B]p\f[R]. +Generates a pseudo\-random number that is between \f[B]0\f[R] +(inclusive) and the truncated absolute value of \f[B]i\f[R] (exclusive) +with the number of decimal digits after the decimal point equal to the +truncated absolute value of \f[B]p\f[R]. If the absolute value of \f[B]i\f[R] is greater than or equal to \f[B]2\f[R], and \f[B]p\f[R] is not \f[B]0\f[R], then calling this function will change the value of \f[B]seed\f[R]; otherwise, \f[B]0\f[R] -is returned and \f[B]seed\f[R] is not changed. +is returned, and \f[B]seed\f[R] is not changed. +.TP +\f[B]i2rand(a, b)\f[R] +Takes the truncated value of \f[B]a\f[R] and \f[B]b\f[R] and uses them +as inclusive bounds to enerate a pseudo\-random integer. +If the difference of the truncated values of \f[B]a\f[R] and \f[B]b\f[R] +is \f[B]0\f[R], then the truncated value is returned, and \f[B]seed\f[R] +is \f[I]not\f[R] changed. +Otherwise, this function will change the value of \f[B]seed\f[R]. .TP \f[B]srand(x)\f[R] Returns \f[B]x\f[R] with its sign flipped with probability @@ -1710,8 +1797,8 @@ If you want to use signed two\[cq]s complement arguments, use .TP \f[B]bshl(a, b)\f[R] Takes the truncated absolute value of both \f[B]a\f[R] and \f[B]b\f[R] -and calculates and returns the result of \f[B]a\f[R] bit-shifted left by -\f[B]b\f[R] places. +and calculates and returns the result of \f[B]a\f[R] bit\-shifted left +by \f[B]b\f[R] places. .RS .PP If you want to use signed two\[cq]s complement arguments, use @@ -1721,7 +1808,7 @@ If you want to use signed two\[cq]s complement arguments, use \f[B]bshr(a, b)\f[R] Takes the truncated absolute value of both \f[B]a\f[R] and \f[B]b\f[R] and calculates and returns the truncated result of \f[B]a\f[R] -bit-shifted right by \f[B]b\f[R] places. +bit\-shifted right by \f[B]b\f[R] places. .RS .PP If you want to use signed two\[cq]s complement arguments, use @@ -1740,7 +1827,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]bnot8(x)\f[R] Does a bitwise not of the truncated absolute value of \f[B]x\f[R] as -though it has \f[B]8\f[R] binary digits (1 unsigned byte). +though it has \f[B]8\f[R] binary digits (\f[B]1\f[R] unsigned byte). .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1749,7 +1836,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]bnot16(x)\f[R] Does a bitwise not of the truncated absolute value of \f[B]x\f[R] as -though it has \f[B]16\f[R] binary digits (2 unsigned bytes). +though it has \f[B]16\f[R] binary digits (\f[B]2\f[R] unsigned bytes). .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1758,7 +1845,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]bnot32(x)\f[R] Does a bitwise not of the truncated absolute value of \f[B]x\f[R] as -though it has \f[B]32\f[R] binary digits (4 unsigned bytes). +though it has \f[B]32\f[R] binary digits (\f[B]4\f[R] unsigned bytes). .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1767,7 +1854,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]bnot64(x)\f[R] Does a bitwise not of the truncated absolute value of \f[B]x\f[R] as -though it has \f[B]64\f[R] binary digits (8 unsigned bytes). +though it has \f[B]64\f[R] binary digits (\f[B]8\f[R] unsigned bytes). .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1785,7 +1872,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]brevn(x, n)\f[R] Runs a bit reversal on the truncated absolute value of \f[B]x\f[R] as -though it has the same number of 8-bit bytes as the truncated absolute +though it has the same number of 8\-bit bytes as the truncated absolute value of \f[B]n\f[R]. .RS .PP @@ -1795,7 +1882,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]brev8(x)\f[R] Runs a bit reversal on the truncated absolute value of \f[B]x\f[R] as -though it has 8 binary digits (1 unsigned byte). +though it has 8 binary digits (\f[B]1\f[R] unsigned byte). .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1804,7 +1891,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]brev16(x)\f[R] Runs a bit reversal on the truncated absolute value of \f[B]x\f[R] as -though it has 16 binary digits (2 unsigned bytes). +though it has 16 binary digits (\f[B]2\f[R] unsigned bytes). .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1813,7 +1900,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]brev32(x)\f[R] Runs a bit reversal on the truncated absolute value of \f[B]x\f[R] as -though it has 32 binary digits (4 unsigned bytes). +though it has 32 binary digits (\f[B]4\f[R] unsigned bytes). .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1822,7 +1909,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]brev64(x)\f[R] Runs a bit reversal on the truncated absolute value of \f[B]x\f[R] as -though it has 64 binary digits (8 unsigned bytes). +though it has 64 binary digits (\f[B]8\f[R] unsigned bytes). .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1840,11 +1927,11 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]broln(x, p, n)\f[R] Does a left bitwise rotatation of the truncated absolute value of -\f[B]x\f[R], as though it has the same number of unsigned 8-bit bytes as -the truncated absolute value of \f[B]n\f[R], by the number of places +\f[B]x\f[R], as though it has the same number of unsigned 8\-bit bytes +as the truncated absolute value of \f[B]n\f[R], by the number of places equal to the truncated absolute value of \f[B]p\f[R] modded by the \f[B]2\f[R] to the power of the number of binary digits in \f[B]n\f[R] -8-bit bytes. +8\-bit bytes. .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1875,7 +1962,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]brol32(x, p)\f[R] Does a left bitwise rotatation of the truncated absolute value of -\f[B]x\f[R], as though it has \f[B]32\f[R] binary digits (\f[B]2\f[R] +\f[B]x\f[R], as though it has \f[B]32\f[R] binary digits (\f[B]4\f[R] unsigned bytes), by the number of places equal to the truncated absolute value of \f[B]p\f[R] modded by \f[B]2\f[R] to the power of \f[B]32\f[R]. .RS @@ -1886,7 +1973,7 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]brol64(x, p)\f[R] Does a left bitwise rotatation of the truncated absolute value of -\f[B]x\f[R], as though it has \f[B]64\f[R] binary digits (\f[B]2\f[R] +\f[B]x\f[R], as though it has \f[B]64\f[R] binary digits (\f[B]8\f[R] unsigned bytes), by the number of places equal to the truncated absolute value of \f[B]p\f[R] modded by \f[B]2\f[R] to the power of \f[B]64\f[R]. .RS @@ -1898,9 +1985,9 @@ If you want to a use signed two\[cq]s complement argument, use \f[B]brol(x, p)\f[R] Does a left bitwise rotatation of the truncated absolute value of \f[B]x\f[R], as though it has the minimum number of power of two -unsigned 8-bit bytes, by the number of places equal to the truncated +unsigned 8\-bit bytes, by the number of places equal to the truncated absolute value of \f[B]p\f[R] modded by 2 to the power of the number of -binary digits in the minimum number of 8-bit bytes. +binary digits in the minimum number of 8\-bit bytes. .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1909,11 +1996,11 @@ If you want to a use signed two\[cq]s complement argument, use .TP \f[B]brorn(x, p, n)\f[R] Does a right bitwise rotatation of the truncated absolute value of -\f[B]x\f[R], as though it has the same number of unsigned 8-bit bytes as -the truncated absolute value of \f[B]n\f[R], by the number of places +\f[B]x\f[R], as though it has the same number of unsigned 8\-bit bytes +as the truncated absolute value of \f[B]n\f[R], by the number of places equal to the truncated absolute value of \f[B]p\f[R] modded by the \f[B]2\f[R] to the power of the number of binary digits in \f[B]n\f[R] -8-bit bytes. +8\-bit bytes. .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -1967,9 +2054,9 @@ If you want to a use signed two\[cq]s complement argument, use \f[B]bror(x, p)\f[R] Does a right bitwise rotatation of the truncated absolute value of \f[B]x\f[R], as though it has the minimum number of power of two -unsigned 8-bit bytes, by the number of places equal to the truncated +unsigned 8\-bit bytes, by the number of places equal to the truncated absolute value of \f[B]p\f[R] modded by 2 to the power of the number of -binary digits in the minimum number of 8-bit bytes. +binary digits in the minimum number of 8\-bit bytes. .RS .PP If you want to a use signed two\[cq]s complement argument, use @@ -2023,7 +2110,7 @@ If you want to a use signed two\[cq]s complement argument, use .RE .TP \f[B]bunrev(t)\f[R] -Assumes \f[B]t\f[R] is a bitwise-reversed number with an extra set bit +Assumes \f[B]t\f[R] is a bitwise\-reversed number with an extra set bit one place more significant than the real most significant bit (which was the least significant bit in the original number). This number is reversed and returned without the extra set bit. @@ -2034,29 +2121,29 @@ meant to be used by users, but it can be. .RE .TP \f[B]plz(x)\f[R] -If \f[B]x\f[R] is not equal to \f[B]0\f[R] and greater that \f[B]-1\f[R] -and less than \f[B]1\f[R], it is printed with a leading zero, regardless -of the use of the \f[B]-z\f[R] option (see the \f[B]OPTIONS\f[R] -section) and without a trailing newline. +If \f[B]x\f[R] is not equal to \f[B]0\f[R] and greater that +\f[B]\-1\f[R] and less than \f[B]1\f[R], it is printed with a leading +zero, regardless of the use of the \f[B]\-z\f[R] option (see the +\f[B]OPTIONS\f[R] section) and without a trailing newline. .RS .PP Otherwise, \f[B]x\f[R] is printed normally, without a trailing newline. .RE .TP \f[B]plznl(x)\f[R] -If \f[B]x\f[R] is not equal to \f[B]0\f[R] and greater that \f[B]-1\f[R] -and less than \f[B]1\f[R], it is printed with a leading zero, regardless -of the use of the \f[B]-z\f[R] option (see the \f[B]OPTIONS\f[R] -section) and with a trailing newline. +If \f[B]x\f[R] is not equal to \f[B]0\f[R] and greater that +\f[B]\-1\f[R] and less than \f[B]1\f[R], it is printed with a leading +zero, regardless of the use of the \f[B]\-z\f[R] option (see the +\f[B]OPTIONS\f[R] section) and with a trailing newline. .RS .PP Otherwise, \f[B]x\f[R] is printed normally, with a trailing newline. .RE .TP \f[B]pnlz(x)\f[R] -If \f[B]x\f[R] is not equal to \f[B]0\f[R] and greater that \f[B]-1\f[R] -and less than \f[B]1\f[R], it is printed without a leading zero, -regardless of the use of the \f[B]-z\f[R] option (see the +If \f[B]x\f[R] is not equal to \f[B]0\f[R] and greater that +\f[B]\-1\f[R] and less than \f[B]1\f[R], it is printed without a leading +zero, regardless of the use of the \f[B]\-z\f[R] option (see the \f[B]OPTIONS\f[R] section) and without a trailing newline. .RS .PP @@ -2064,9 +2151,9 @@ Otherwise, \f[B]x\f[R] is printed normally, without a trailing newline. .RE .TP \f[B]pnlznl(x)\f[R] -If \f[B]x\f[R] is not equal to \f[B]0\f[R] and greater that \f[B]-1\f[R] -and less than \f[B]1\f[R], it is printed without a leading zero, -regardless of the use of the \f[B]-z\f[R] option (see the +If \f[B]x\f[R] is not equal to \f[B]0\f[R] and greater that +\f[B]\-1\f[R] and less than \f[B]1\f[R], it is printed without a leading +zero, regardless of the use of the \f[B]\-z\f[R] option (see the \f[B]OPTIONS\f[R] section) and with a trailing newline. .RS .PP @@ -2078,22 +2165,22 @@ Returns the numbers of unsigned integer bytes required to hold the truncated absolute value of \f[B]x\f[R]. .TP \f[B]sbytes(x)\f[R] -Returns the numbers of signed, two\[cq]s-complement integer bytes +Returns the numbers of signed, two\[cq]s\-complement integer bytes required to hold the truncated value of \f[B]x\f[R]. .TP \f[B]s2u(x)\f[R] -Returns \f[B]x\f[R] if it is non-negative. +Returns \f[B]x\f[R] if it is non\-negative. If it \f[I]is\f[R] negative, then it calculates what \f[B]x\f[R] would -be as a 2\[cq]s-complement signed integer and returns the non-negative +be as a 2\[cq]s\-complement signed integer and returns the non\-negative integer that would have the same representation in binary. .TP \f[B]s2un(x,n)\f[R] -Returns \f[B]x\f[R] if it is non-negative. +Returns \f[B]x\f[R] if it is non\-negative. If it \f[I]is\f[R] negative, then it calculates what \f[B]x\f[R] would -be as a 2\[cq]s-complement signed integer with \f[B]n\f[R] bytes and -returns the non-negative integer that would have the same representation -in binary. -If \f[B]x\f[R] cannot fit into \f[B]n\f[R] 2\[cq]s-complement signed +be as a 2\[cq]s\-complement signed integer with \f[B]n\f[R] bytes and +returns the non\-negative integer that would have the same +representation in binary. +If \f[B]x\f[R] cannot fit into \f[B]n\f[R] 2\[cq]s\-complement signed bytes, it is truncated to fit. .TP \f[B]hex(x)\f[R] @@ -2137,7 +2224,7 @@ subsection of the \f[B]FUNCTIONS\f[R] section). .TP \f[B]int(x)\f[R] Outputs the representation, in binary and hexadecimal, of \f[B]x\f[R] as -a signed, two\[cq]s-complement integer in as few power of two bytes as +a signed, two\[cq]s\-complement integer in as few power of two bytes as possible. Both outputs are split into bytes separated by spaces. .RS @@ -2165,7 +2252,7 @@ subsection of the \f[B]FUNCTIONS\f[R] section). .TP \f[B]intn(x, n)\f[R] Outputs the representation, in binary and hexadecimal, of \f[B]x\f[R] as -a signed, two\[cq]s-complement integer in \f[B]n\f[R] bytes. +a signed, two\[cq]s\-complement integer in \f[B]n\f[R] bytes. Both outputs are split into bytes separated by spaces. .RS .PP @@ -2193,7 +2280,7 @@ subsection of the \f[B]FUNCTIONS\f[R] section). .TP \f[B]int8(x)\f[R] Outputs the representation, in binary and hexadecimal, of \f[B]x\f[R] as -a signed, two\[cq]s-complement integer in \f[B]1\f[R] byte. +a signed, two\[cq]s\-complement integer in \f[B]1\f[R] byte. Both outputs are split into bytes separated by spaces. .RS .PP @@ -2221,7 +2308,7 @@ subsection of the \f[B]FUNCTIONS\f[R] section). .TP \f[B]int16(x)\f[R] Outputs the representation, in binary and hexadecimal, of \f[B]x\f[R] as -a signed, two\[cq]s-complement integer in \f[B]2\f[R] bytes. +a signed, two\[cq]s\-complement integer in \f[B]2\f[R] bytes. Both outputs are split into bytes separated by spaces. .RS .PP @@ -2249,7 +2336,7 @@ subsection of the \f[B]FUNCTIONS\f[R] section). .TP \f[B]int32(x)\f[R] Outputs the representation, in binary and hexadecimal, of \f[B]x\f[R] as -a signed, two\[cq]s-complement integer in \f[B]4\f[R] bytes. +a signed, two\[cq]s\-complement integer in \f[B]4\f[R] bytes. Both outputs are split into bytes separated by spaces. .RS .PP @@ -2277,7 +2364,7 @@ subsection of the \f[B]FUNCTIONS\f[R] section). .TP \f[B]int64(x)\f[R] Outputs the representation, in binary and hexadecimal, of \f[B]x\f[R] as -a signed, two\[cq]s-complement integer in \f[B]8\f[R] bytes. +a signed, two\[cq]s\-complement integer in \f[B]8\f[R] bytes. Both outputs are split into bytes separated by spaces. .RS .PP @@ -2324,14 +2411,13 @@ subsection of the \f[B]FUNCTIONS\f[R] section). \f[B]output_byte(x, i)\f[R] Outputs byte \f[B]i\f[R] of the truncated absolute value of \f[B]x\f[R], where \f[B]0\f[R] is the least significant byte and \f[B]number_of_bytes -- 1\f[R] is the most significant byte. +\- 1\f[R] is the most significant byte. .RS .PP This is a \f[B]void\f[R] function (see the \f[I]Void Functions\f[R] subsection of the \f[B]FUNCTIONS\f[R] section). .RE .SS Transcendental Functions -.PP All transcendental functions can return slightly inaccurate results, up to 1 ULP (https://en.wikipedia.org/wiki/Unit_in_the_last_place). This is unavoidable, and the article at @@ -2387,8 +2473,7 @@ The transcendental functions in the extended math library are: .IP \[bu] 2 \f[B]d2r(x)\f[R] .SH RESET -.PP -When bc(1) encounters an error or a signal that it has a non-default +When bc(1) encounters an error or a signal that it has a non\-default handler for, it resets. This means that several things happen. .PP @@ -2408,7 +2493,6 @@ Note that this reset behavior is different from the GNU bc(1), which attempts to start executing the statement right after the one that caused an error. .SH PERFORMANCE -.PP Most bc(1) implementations use \f[B]char\f[R] types to calculate the value of \f[B]1\f[R] decimal digit at a time, but that can be slow. This bc(1) does something different. @@ -2431,7 +2515,6 @@ checking. This integer type depends on the value of \f[B]BC_LONG_BIT\f[R], but is always at least twice as large as the integer type used to store digits. .SH LIMITS -.PP The following are the limits on bc(1): .TP \f[B]BC_LONG_BIT\f[R] @@ -2461,29 +2544,29 @@ Set at \f[B]BC_BASE_POW\f[R]. .TP \f[B]BC_DIM_MAX\f[R] The maximum size of arrays. -Set at \f[B]SIZE_MAX-1\f[R]. +Set at \f[B]SIZE_MAX\-1\f[R]. .TP \f[B]BC_SCALE_MAX\f[R] The maximum \f[B]scale\f[R]. -Set at \f[B]BC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]BC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]BC_STRING_MAX\f[R] The maximum length of strings. -Set at \f[B]BC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]BC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]BC_NAME_MAX\f[R] The maximum length of identifiers. -Set at \f[B]BC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]BC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]BC_NUM_MAX\f[R] The maximum length of a number (in decimal digits), which includes digits after the decimal point. -Set at \f[B]BC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]BC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]BC_RAND_MAX\f[R] The maximum integer (inclusive) returned by the \f[B]rand()\f[R] operand. -Set at \f[B]2\[ha]BC_LONG_BIT-1\f[R]. +Set at \f[B]2\[ha]BC_LONG_BIT\-1\f[R]. .TP Exponent The maximum allowable exponent (positive or negative). @@ -2491,28 +2574,28 @@ Set at \f[B]BC_OVERFLOW_MAX\f[R]. .TP Number of vars The maximum number of vars/arrays. -Set at \f[B]SIZE_MAX-1\f[R]. +Set at \f[B]SIZE_MAX\-1\f[R]. .PP The actual values can be queried with the \f[B]limits\f[R] statement. .PP -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. +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 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 -the \f[B]-s\f[R] option was given. +the \f[B]\-s\f[R] option was given. .TP \f[B]BC_ENV_ARGS\f[R] -This is another way to give command-line arguments to bc(1). -They should be in the same format as all other command-line arguments. +This is another way to give command\-line arguments to bc(1). +They should be in the same format as all other command\-line arguments. These are always processed first, so any files given in \f[B]BC_ENV_ARGS\f[R] will be processed before arguments and files given -on the command-line. +on the command\-line. This gives the user the ability to set up \[lq]standard\[rq] options and files to be used at every invocation. The most useful thing for such files to contain would be useful @@ -2533,14 +2616,14 @@ you can use double quotes as the outside quotes, as in \f[B]\[lq]some quotes. However, handling a file with both kinds of quotes in \f[B]BC_ENV_ARGS\f[R] is not supported due to the complexity of the -parsing, though such files are still supported on the command-line where -the parsing is done by the shell. +parsing, though such files are still supported on the command\-line +where the parsing is done by the shell. .RE .TP \f[B]BC_LINE_LENGTH\f[R] If this environment variable exists and contains an integer that is greater than \f[B]1\f[R] and is less than \f[B]UINT16_MAX\f[R] -(\f[B]2\[ha]16-1\f[R]), bc(1) will output lines to that length, +(\f[B]2\[ha]16\-1\f[R]), bc(1) will output lines to that length, including the backslash (\f[B]\[rs]\f[R]). The default line length is \f[B]70\f[R]. .RS @@ -2552,7 +2635,7 @@ newlines. .TP \f[B]BC_BANNER\f[R] If this environment variable exists and contains an integer, then a -non-zero value activates the copyright banner when bc(1) is in +non\-zero value activates the copyright banner when bc(1) is in interactive mode, while zero deactivates it. .RS .PP @@ -2561,7 +2644,7 @@ section), then this environment variable has no effect because bc(1) does not print the banner when not in interactive mode. .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. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]BC_SIGINT_RESET\f[R] @@ -2571,13 +2654,13 @@ exits on \f[B]SIGINT\f[R] when not in interactive mode. .RS .PP However, when bc(1) is in interactive mode, then if this environment -variable exists and contains an integer, a non-zero value makes bc(1) +variable exists and contains an integer, a non\-zero value makes bc(1) reset on \f[B]SIGINT\f[R], rather than exit, and zero makes bc(1) exit. If this environment variable exists and is \f[I]not\f[R] an integer, then bc(1) will exit on \f[B]SIGINT\f[R]. .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. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]BC_TTY_MODE\f[R] @@ -2586,11 +2669,11 @@ section), then this environment variable has no effect. .RS .PP However, when TTY mode is available, then if this environment variable -exists and contains an integer, then a non-zero value makes bc(1) use +exists and contains an integer, then a non\-zero value makes bc(1) use TTY mode, and zero makes bc(1) not use TTY mode. .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. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]BC_PROMPT\f[R] @@ -2599,30 +2682,46 @@ section), then this environment variable has no effect. .RS .PP However, when TTY mode is available, then if this environment variable -exists and contains an integer, a non-zero value makes bc(1) use a -prompt, and zero or a non-integer makes bc(1) not use a prompt. +exists and contains an integer, a non\-zero value makes bc(1) use a +prompt, and zero or a non\-integer makes bc(1) not use a prompt. If this environment variable does not exist and \f[B]BC_TTY_MODE\f[R] does, then the value of the \f[B]BC_TTY_MODE\f[R] environment variable is used. .PP This environment variable and the \f[B]BC_TTY_MODE\f[R] environment variable override the default, which can be queried with the -\f[B]-h\f[R] or \f[B]--help\f[R] options. +\f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]BC_EXPR_EXIT\f[R] -If any expressions or expression files are given on the command-line -with \f[B]-e\f[R], \f[B]--expression\f[R], \f[B]-f\f[R], or -\f[B]--file\f[R], then if this environment variable exists and contains -an integer, a non-zero value makes bc(1) exit after executing the -expressions and expression files, and a zero value makes bc(1) not exit. +If any expressions or expression files are given on the command\-line +with \f[B]\-e\f[R], \f[B]\-\-expression\f[R], \f[B]\-f\f[R], or +\f[B]\-\-file\f[R], then if this environment variable exists and +contains an integer, a non\-zero value makes bc(1) exit after executing +the expressions and expression files, and a zero value makes bc(1) not +exit. .RS .PP This environment variable overrides the default, which can be queried -with the \f[B]-h\f[R] or \f[B]--help\f[R] options. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE -.SH EXIT STATUS +.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 bc(1) returns the following exit statuses: .TP \f[B]0\f[R] @@ -2636,10 +2735,10 @@ since math errors will happen in the process of normal execution. .PP Math errors include divide by \f[B]0\f[R], taking the square root of a negative number, using a negative number as a bound for the -pseudo-random number generator, attempting to convert a negative number +pseudo\-random number generator, attempting to convert a negative number to a hardware integer, overflow when converting a number to a hardware integer, overflow when calculating the size of a number, and attempting -to use a non-integer where an integer is required. +to use a non\-integer where an integer is required. .PP Converting to a hardware integer happens for the second operand of the power (\f[B]\[ha]\f[R]), places (\f[B]\[at]\f[R]), left shift @@ -2661,7 +2760,7 @@ giving an invalid \f[B]auto\f[R] list, having a duplicate \f[B]auto\f[R]/function parameter, failing to find the end of a code block, attempting to return a value from a \f[B]void\f[R] function, attempting to use a variable as a reference, and using any extensions -when the option \f[B]-s\f[R] or any equivalents were given. +when the option \f[B]\-s\f[R] or any equivalents were given. .RE .TP \f[B]3\f[R] @@ -2684,7 +2783,7 @@ A fatal error occurred. Fatal errors include memory allocation errors, I/O errors, failing to open files, attempting to use files that do not have only ASCII characters (bc(1) only accepts ASCII characters), attempting to open a -directory as a file, and giving invalid command-line options. +directory as a file, and giving invalid command\-line options. .RE .PP The exit status \f[B]4\f[R] is special; when a fatal error occurs, bc(1) @@ -2695,19 +2794,18 @@ interactive mode (see the \f[B]INTERACTIVE MODE\f[R] section), since bc(1) resets its state (see the \f[B]RESET\f[R] section) and accepts more input when one of those errors occurs in interactive mode. This is also the case when interactive mode is forced by the -\f[B]-i\f[R] flag or \f[B]--interactive\f[R] option. +\f[B]\-i\f[R] flag or \f[B]\-\-interactive\f[R] option. .PP These exit statuses allow bc(1) to be used in shell scripting with error checking, and its normal behavior can be forced by using the -\f[B]-i\f[R] flag or \f[B]--interactive\f[R] option. +\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. +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. .PP In interactive mode, bc(1) attempts to recover from errors (see the \f[B]RESET\f[R] section), and in normal execution, flushes @@ -2716,7 +2814,6 @@ bc(1) may also reset on \f[B]SIGINT\f[R] instead of exit, depending on the contents of, or default for, the \f[B]BC_SIGINT_RESET\f[R] environment variable (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). .SH TTY MODE -.PP If \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all connected to a TTY, then \[lq]TTY mode\[rq] is considered to be available, and thus, bc(1) can turn on TTY mode, subject to some @@ -2724,53 +2821,49 @@ settings. .PP If there is the environment variable \f[B]BC_TTY_MODE\f[R] in the environment (see the \f[B]ENVIRONMENT VARIABLES\f[R] section), then if -that environment variable contains a non-zero integer, bc(1) will turn +that environment variable contains a non\-zero integer, bc(1) will turn on TTY mode when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all connected to a TTY. If the \f[B]BC_TTY_MODE\f[R] environment variable exists but is -\f[I]not\f[R] a non-zero integer, then bc(1) will not turn TTY mode on. +\f[I]not\f[R] a non\-zero integer, then bc(1) will not turn TTY mode on. .PP If the environment variable \f[B]BC_TTY_MODE\f[R] does \f[I]not\f[R] exist, the default setting is used. -The default setting can be queried with the \f[B]-h\f[R] or -\f[B]--help\f[R] options. +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 -.PP -Command-line history is only enabled if TTY mode is, i.e., that +.SS Command\-Line History +Command\-line history is only enabled if TTY mode is, i.e., that \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are connected to a TTY and the \f[B]BC_TTY_MODE\f[R] environment variable (see the \f[B]ENVIRONMENT VARIABLES\f[R] section) and its default do not disable TTY mode. See the \f[B]COMMAND LINE HISTORY\f[R] section for more information. .SS Prompt -.PP If TTY mode is available, then a prompt can be enabled. Like TTY mode itself, it can be turned on or off with an environment variable: \f[B]BC_PROMPT\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). .PP -If the environment variable \f[B]BC_PROMPT\f[R] exists and is a non-zero -integer, then the prompt is turned on when \f[B]stdin\f[R], +If the environment variable \f[B]BC_PROMPT\f[R] exists and is a +non\-zero integer, then the prompt is turned on when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are connected to a TTY and the -\f[B]-P\f[R] and \f[B]--no-prompt\f[R] options were not used. +\f[B]\-P\f[R] and \f[B]\-\-no\-prompt\f[R] options were not used. The read prompt will be turned on under the same conditions, except that -the \f[B]-R\f[R] and \f[B]--no-read-prompt\f[R] options must also not be -used. +the \f[B]\-R\f[R] and \f[B]\-\-no\-read\-prompt\f[R] options must also +not be used. .PP However, if \f[B]BC_PROMPT\f[R] does not exist, the prompt can be enabled or disabled with the \f[B]BC_TTY_MODE\f[R] environment variable, -the \f[B]-P\f[R] and \f[B]--no-prompt\f[R] options, and the \f[B]-R\f[R] -and \f[B]--no-read-prompt\f[R] options. +the \f[B]\-P\f[R] and \f[B]\-\-no\-prompt\f[R] options, and the +\f[B]\-R\f[R] and \f[B]\-\-no\-read\-prompt\f[R] options. See the \f[B]ENVIRONMENT VARIABLES\f[R] and \f[B]OPTIONS\f[R] sections for more details. .SH SIGNAL HANDLING -.PP Sending a \f[B]SIGINT\f[R] will cause bc(1) to do one of two things. .PP If bc(1) is not in interactive mode (see the \f[B]INTERACTIVE MODE\f[R] @@ -2779,7 +2872,7 @@ section), or the \f[B]BC_SIGINT_RESET\f[R] environment variable (see the an integer or it is zero, bc(1) will exit. .PP However, if bc(1) is in interactive mode, and the -\f[B]BC_SIGINT_RESET\f[R] or its default is an integer and non-zero, +\f[B]BC_SIGINT_RESET\f[R] or its default is an integer and non\-zero, then bc(1) will stop executing the current input and reset (see the \f[B]RESET\f[R] section) upon receiving a \f[B]SIGINT\f[R]. .PP @@ -2805,12 +2898,11 @@ The one exception is \f[B]SIGHUP\f[R]; in that case, and only when bc(1) is in TTY mode (see the \f[B]TTY MODE\f[R] section), a \f[B]SIGHUP\f[R] will cause bc(1) to clean up and exit. .SH COMMAND LINE HISTORY -.PP -bc(1) supports interactive command-line editing. +bc(1) supports interactive command\-line editing. .PP If bc(1) can be in TTY mode (see the \f[B]TTY MODE\f[R] section), history can be enabled. -This means that command-line history can only be enabled when +This means that command\-line history can only be enabled when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all connected to a TTY. .PP @@ -2823,24 +2915,31 @@ the arrow keys. .PP \f[B]Note\f[R]: tabs are converted to 8 spaces. .SH SEE ALSO -.PP dc(1) .SH STANDARDS -.PP -bc(1) is compliant with the IEEE Std 1003.1-2017 -(\[lq]POSIX.1-2017\[rq]) specification at +bc(1) is compliant with the IEEE Std 1003.1\-2017 +(\[lq]POSIX.1\-2017\[rq]) specification at https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html . -The flags \f[B]-efghiqsvVw\f[R], all long options, and the extensions +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 +Before version \f[B]6.1.0\f[R], this bc(1) had incorrect behavior for +the \f[B]quit\f[R] statement. .PP -None are known. -Report bugs at https://git.yzena.com/gavin/bc. +No other bugs are known. +Report bugs at https://git.gavinhoward.com/gavin/bc . .SH AUTHORS -.PP -Gavin D. -Howard <gavin@yzena.com> and contributors. +Gavin D. Howard \c +.MT gavin@gavinhoward.com +.ME \c +\ and contributors. diff --git a/contrib/bc/manuals/bc/N.1.md b/contrib/bc/manuals/bc/N.1.md index 27cc68c8d39a..859c32e3e774 100644 --- a/contrib/bc/manuals/bc/N.1.md +++ b/contrib/bc/manuals/bc/N.1.md @@ -2,7 +2,7 @@ SPDX-License-Identifier: BSD-2-Clause -Copyright (c) 2018-2021 Gavin D. Howard and contributors. +Copyright (c) 2018-2024 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**. @@ -268,80 +372,12 @@ The following are the options that bc(1) accepts. : Makes bc(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)**, + 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**. -**-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**. - -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**. +letters are equal to **9** plus their position in the alphabet, starting from +**1** (i.e., **A** equals **10**, or **9+1**). + +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 @@ -742,6 +811,9 @@ The operators will be described in more detail below. : The **boolean not** operator returns **1** if the expression is **0**, or **0** otherwise. + **Warning**: This operator has a **different precedence** than the + equivalent operator in GNU bc(1) and other bc(1) implementations! + This is a **non-portable extension**. **\$** @@ -849,10 +921,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 +987,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.) @@ -987,7 +1071,7 @@ like any other expression that is printed. ## Stream Statement -The "expressions in a **stream** statement may also be strings. +The expressions in a **stream** statement may also be strings. If a **stream** statement is given a string, it prints the string as though the string had appeared as its own statement. In other words, the **stream** @@ -1099,9 +1183,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 +1232,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**. @@ -1180,6 +1262,14 @@ The extended library is a **non-portable extension**. : Returns the factorial of the truncated absolute value of **x**. +**max(a, b)** + +: Returns **a** if **a** is greater than **b**; otherwise, returns **b**. + +**min(a, b)** + +: Returns **a** if **a** is less than **b**; otherwise, returns **b**. + **perm(n, k)** : Returns the permutation of the truncated absolute value of **n** of the @@ -1190,6 +1280,10 @@ The extended library is a **non-portable extension**. : Returns the combination of the truncated absolute value of **n** of the truncated absolute value of **k**, if **k \<= n**. If not, it returns **0**. +**fib(n)** + +: Returns the Fibonacci number of the truncated absolute value of **n**. + **l2(x)** : Returns the logarithm base **2** of **x**. @@ -1352,7 +1446,15 @@ The extended library is a **non-portable extension**. digits after the decimal point equal to the truncated absolute value of **p**. If the absolute value of **i** is greater than or equal to **2**, and **p** is not **0**, then calling this function will change the value of - **seed**; otherwise, **0** is returned and **seed** is not changed. + **seed**; otherwise, **0** is returned, and **seed** is not changed. + +**i2rand(a, b)** + +: Takes the truncated value of **a** and **b** and uses them as inclusive + bounds to enerate a pseudo-random integer. If the difference of the + truncated values of **a** and **b** is **0**, then the truncated value is + returned, and **seed** is *not* changed. Otherwise, this function will + change the value of **seed**. **srand(x)** @@ -1414,7 +1516,7 @@ The extended library is a **non-portable extension**. **bnot8(x)** : Does a bitwise not of the truncated absolute value of **x** as though it has - **8** binary digits (1 unsigned byte). + **8** binary digits (**1** unsigned byte). If you want to a use signed two's complement argument, use **s2u(x)** to convert. @@ -1422,7 +1524,7 @@ The extended library is a **non-portable extension**. **bnot16(x)** : Does a bitwise not of the truncated absolute value of **x** as though it has - **16** binary digits (2 unsigned bytes). + **16** binary digits (**2** unsigned bytes). If you want to a use signed two's complement argument, use **s2u(x)** to convert. @@ -1430,7 +1532,7 @@ The extended library is a **non-portable extension**. **bnot32(x)** : Does a bitwise not of the truncated absolute value of **x** as though it has - **32** binary digits (4 unsigned bytes). + **32** binary digits (**4** unsigned bytes). If you want to a use signed two's complement argument, use **s2u(x)** to convert. @@ -1438,7 +1540,7 @@ The extended library is a **non-portable extension**. **bnot64(x)** : Does a bitwise not of the truncated absolute value of **x** as though it has - **64** binary digits (8 unsigned bytes). + **64** binary digits (**8** unsigned bytes). If you want to a use signed two's complement argument, use **s2u(x)** to convert. @@ -1462,7 +1564,7 @@ The extended library is a **non-portable extension**. **brev8(x)** : Runs a bit reversal on the truncated absolute value of **x** as though it - has 8 binary digits (1 unsigned byte). + has 8 binary digits (**1** unsigned byte). If you want to a use signed two's complement argument, use **s2u(x)** to convert. @@ -1470,7 +1572,7 @@ The extended library is a **non-portable extension**. **brev16(x)** : Runs a bit reversal on the truncated absolute value of **x** as though it - has 16 binary digits (2 unsigned bytes). + has 16 binary digits (**2** unsigned bytes). If you want to a use signed two's complement argument, use **s2u(x)** to convert. @@ -1478,7 +1580,7 @@ The extended library is a **non-portable extension**. **brev32(x)** : Runs a bit reversal on the truncated absolute value of **x** as though it - has 32 binary digits (4 unsigned bytes). + has 32 binary digits (**4** unsigned bytes). If you want to a use signed two's complement argument, use **s2u(x)** to convert. @@ -1486,7 +1588,7 @@ The extended library is a **non-portable extension**. **brev64(x)** : Runs a bit reversal on the truncated absolute value of **x** as though it - has 64 binary digits (8 unsigned bytes). + has 64 binary digits (**8** unsigned bytes). If you want to a use signed two's complement argument, use **s2u(x)** to convert. @@ -1533,7 +1635,7 @@ The extended library is a **non-portable extension**. **brol32(x, p)** : Does a left bitwise rotatation of the truncated absolute value of **x**, as - though it has **32** binary digits (**2** unsigned bytes), by the number of + though it has **32** binary digits (**4** unsigned bytes), by the number of places equal to the truncated absolute value of **p** modded by **2** to the power of **32**. @@ -1543,7 +1645,7 @@ The extended library is a **non-portable extension**. **brol64(x, p)** : Does a left bitwise rotatation of the truncated absolute value of **x**, as - though it has **64** binary digits (**2** unsigned bytes), by the number of + though it has **64** binary digits (**8** unsigned bytes), by the number of places equal to the truncated absolute value of **p** modded by **2** to the power of **64**. @@ -2085,7 +2187,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 +2294,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 +2384,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 +2413,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,14 +2500,21 @@ 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.gavinhoward.com/gavin/bc . # AUTHORS -Gavin D. Howard <gavin@yzena.com> and contributors. +Gavin D. Howard <gavin@gavinhoward.com> and contributors. diff --git a/contrib/bc/manuals/bcl.3 b/contrib/bc/manuals/bcl.3 index c0678722db0c..f2791624b2ca 100644 --- a/contrib/bc/manuals/bcl.3 +++ b/contrib/bc/manuals/bcl.3 @@ -1,7 +1,7 @@ .\" .\" SPDX-License-Identifier: BSD-2-Clause .\" -.\" Copyright (c) 2018-2021 Gavin D. Howard and contributors. +.\" Copyright (c) 2018-2024 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,30 +25,24 @@ .\" 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" "January 2024" "Gavin D. Howard" "Libraries Manual" .nh .ad l .SH NAME -.PP -bcl - library of arbitrary precision decimal arithmetic +bcl \- library of arbitrary precision decimal arithmetic .SH SYNOPSIS .SS Use -.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,8 +57,11 @@ 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] -.SS Contexts .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 These items will allow clients to handle contexts, which are isolated from each other. This allows more than one client to use bcl(3) in the same program. @@ -100,16 +97,14 @@ size_t\f[R] \f[I]ibase\f[R]\f[B]);\f[R] \f[B]void bcl_ctxt_setObase(BclContext\f[R] \f[I]ctxt\f[R]\f[B], size_t\f[R] \f[I]obase\f[R]\f[B]);\f[R] .SS Errors -.PP These items allow clients to handle errors. .PP \f[B]typedef enum BclError BclError;\f[R] .PP \f[B]BclError bcl_err(BclNumber\f[R] \f[I]n\f[R]\f[B]);\f[R] .SS Numbers -.PP These items allow clients to manipulate and query the -arbitrary-precision numbers managed by bcl(3). +arbitrary\-precision numbers managed by bcl(3). .PP \f[B]typedef struct { size_t i; } BclNumber;\f[R] .PP @@ -129,7 +124,6 @@ size_t\f[R] \f[I]scale\f[R]\f[B]);\f[R] .PP \f[B]size_t bcl_num_len(BclNumber\f[R] \f[I]n\f[R]\f[B]);\f[R] .SS Conversion -.PP These items allow clients to convert numbers into and from strings and integers. .PP @@ -138,48 +132,84 @@ integers. .PP \f[B]char* bcl_string(BclNumber\f[R] \f[I]n\f[R]\f[B]);\f[R] .PP +\f[B]char* bcl_string_keep(BclNumber\f[R] \f[I]n\f[R]\f[B]);\f[R] +.PP \f[B]BclError bcl_bigdig(BclNumber\f[R] \f[I]n\f[R]\f[B], BclBigDig *\f[R]\f[I]result\f[R]\f[B]);\f[R] .PP +\f[B]BclError bcl_bigdig_keep(BclNumber\f[R] \f[I]n\f[R]\f[B], BclBigDig +*\f[R]\f[I]result\f[R]\f[B]);\f[R] +.PP \f[B]BclNumber bcl_bigdig2num(BclBigDig\f[R] \f[I]val\f[R]\f[B]);\f[R] .SS Math -.PP These items allow clients to run math on numbers. .PP \f[B]BclNumber bcl_add(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] \f[I]b\f[R]\f[B]);\f[R] .PP +\f[B]BclNumber bcl_add_keep(BclNumber\f[R] \f[I]a\f[R]\f[B], +BclNumber\f[R] \f[I]b\f[R]\f[B]);\f[R] +.PP \f[B]BclNumber bcl_sub(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] \f[I]b\f[R]\f[B]);\f[R] .PP +\f[B]BclNumber bcl_sub_keep(BclNumber\f[R] \f[I]a\f[R]\f[B], +BclNumber\f[R] \f[I]b\f[R]\f[B]);\f[R] +.PP \f[B]BclNumber bcl_mul(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] \f[I]b\f[R]\f[B]);\f[R] .PP +\f[B]BclNumber bcl_mul_keep(BclNumber\f[R] \f[I]a\f[R]\f[B], +BclNumber\f[R] \f[I]b\f[R]\f[B]);\f[R] +.PP \f[B]BclNumber bcl_div(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] \f[I]b\f[R]\f[B]);\f[R] .PP +\f[B]BclNumber bcl_div_keep(BclNumber\f[R] \f[I]a\f[R]\f[B], +BclNumber\f[R] \f[I]b\f[R]\f[B]);\f[R] +.PP \f[B]BclNumber bcl_mod(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] \f[I]b\f[R]\f[B]);\f[R] .PP +\f[B]BclNumber bcl_mod_keep(BclNumber\f[R] \f[I]a\f[R]\f[B], +BclNumber\f[R] \f[I]b\f[R]\f[B]);\f[R] +.PP \f[B]BclNumber bcl_pow(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] \f[I]b\f[R]\f[B]);\f[R] .PP +\f[B]BclNumber bcl_pow_keep(BclNumber\f[R] \f[I]a\f[R]\f[B], +BclNumber\f[R] \f[I]b\f[R]\f[B]);\f[R] +.PP \f[B]BclNumber bcl_lshift(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] \f[I]b\f[R]\f[B]);\f[R] .PP +\f[B]BclNumber bcl_lshift_keep(BclNumber\f[R] \f[I]a\f[R]\f[B], +BclNumber\f[R] \f[I]b\f[R]\f[B]);\f[R] +.PP \f[B]BclNumber bcl_rshift(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] \f[I]b\f[R]\f[B]);\f[R] .PP +\f[B]BclNumber bcl_rshift_keep(BclNumber\f[R] \f[I]a\f[R]\f[B], +BclNumber\f[R] \f[I]b\f[R]\f[B]);\f[R] +.PP \f[B]BclNumber bcl_sqrt(BclNumber\f[R] \f[I]a\f[R]\f[B]);\f[R] .PP +\f[B]BclNumber bcl_sqrt_keep(BclNumber\f[R] \f[I]a\f[R]\f[B]);\f[R] +.PP \f[B]BclError bcl_divmod(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] \f[I]b\f[R]\f[B], BclNumber *\f[R]\f[I]c\f[R]\f[B], BclNumber *\f[R]\f[I]d\f[R]\f[B]);\f[R] .PP +\f[B]BclError bcl_divmod_keep(BclNumber\f[R] \f[I]a\f[R]\f[B], +BclNumber\f[R] \f[I]b\f[R]\f[B], BclNumber *\f[R]\f[I]c\f[R]\f[B], +BclNumber *\f[R]\f[I]d\f[R]\f[B]);\f[R] +.PP \f[B]BclNumber bcl_modexp(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] \f[I]b\f[R]\f[B], BclNumber\f[R] \f[I]c\f[R]\f[B]);\f[R] -.SS Miscellaneous .PP +\f[B]BclNumber bcl_modexp_keep(BclNumber\f[R] \f[I]a\f[R]\f[B], +BclNumber\f[R] \f[I]b\f[R]\f[B], BclNumber\f[R] \f[I]c\f[R]\f[B]);\f[R] +.SS Miscellaneous These items are miscellaneous. .PP \f[B]void bcl_zero(BclNumber\f[R] \f[I]n\f[R]\f[B]);\f[R] @@ -193,9 +223,8 @@ These items are miscellaneous. \f[I]s\f[R]\f[B]);\f[R] .PP \f[B]BclNumber bcl_dup(BclNumber\f[R] \f[I]s\f[R]\f[B]);\f[R] -.SS Pseudo-Random Number Generator -.PP -These items allow clients to manipulate the seeded pseudo-random number +.SS Pseudo\-Random Number Generator +These items allow clients to manipulate the seeded pseudo\-random number generator in bcl(3). .PP \f[B]#define BCL_SEED_ULONGS\f[R] @@ -208,14 +237,22 @@ generator in bcl(3). .PP \f[B]BclNumber bcl_irand(BclNumber\f[R] \f[I]a\f[R]\f[B]);\f[R] .PP +\f[B]BclNumber bcl_irand_keep(BclNumber\f[R] \f[I]a\f[R]\f[B]);\f[R] +.PP \f[B]BclNumber bcl_frand(size_t\f[R] \f[I]places\f[R]\f[B]);\f[R] .PP \f[B]BclNumber bcl_ifrand(BclNumber\f[R] \f[I]a\f[R]\f[B], size_t\f[R] \f[I]places\f[R]\f[B]);\f[R] .PP +\f[B]BclNumber bcl_ifrand_keep(BclNumber\f[R] \f[I]a\f[R]\f[B], +size_t\f[R] \f[I]places\f[R]\f[B]);\f[R] +.PP \f[B]BclError bcl_rand_seedWithNum(BclNumber\f[R] \f[I]n\f[R]\f[B]);\f[R] .PP +\f[B]BclError bcl_rand_seedWithNum_keep(BclNumber\f[R] +\f[I]n\f[R]\f[B]);\f[R] +.PP \f[B]BclError bcl_rand_seed(unsigned char\f[R] \f[I]seed\f[R]\f[B][\f[R]\f[I]BCL_SEED_SIZE\f[R]\f[B]]);\f[R] .PP @@ -228,16 +265,11 @@ generator in bcl(3). \f[B]BclRandInt bcl_rand_bounded(BclRandInt\f[R] \f[I]bound\f[R]\f[B]);\f[R] .SH DESCRIPTION -.PP -bcl(3) is a library that implements arbitrary-precision decimal math, as -standardized by POSIX +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). .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,53 +277,66 @@ 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. +.SS Setup +.TP +\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 \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 -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. +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 -See the \f[B]SIGNAL HANDLING\f[R] section. +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 first one clients call. +Calling any other function without calling this one first is undefined +behavior. .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]. +\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 -See the \f[B]SIGNAL HANDLING\f[R] section. +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 -.SS Setup .TP \f[B]BclError bcl_init(\f[R]\f[I]void\f[R]\f[B])\f[R] -Initializes this library. +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 bcl(3) without problem. +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 first one clients call. -Calling any other function without calling this one first is undefined -behavior. +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] @@ -299,9 +344,12 @@ 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 +361,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,32 +375,79 @@ 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 \f[B]bool bcl_leadingZeroes(\f[R]\f[I]void\f[R]\f[B])\f[R] Queries and returns the state of whether leading zeroes are added to strings returned 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]. +\f[B]\-1\f[R], less than \f[B]1\f[R], and not equal to \f[B]0\f[R]. 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 \f[B]void bcl_setLeadingZeroes(bool\f[R] \f[I]leadingZeroes\f[R]\f[B])\f[R] Sets the state of whether leading zeroes are added to strings returned -by \f[B]bcl_string()\f[R] when numbers are greater than \f[B]-1\f[R], +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. +Garbage collects cached instances of arbitrary\-precision numbers. This only frees the memory of numbers that are \f[I]not\f[R] in use, so it is safe to call at any time. .SS Contexts -.PP All procedures that take a \f[B]BclContext\f[R] parameter a require a valid context as an argument. .TP @@ -392,6 +490,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] @@ -468,13 +575,12 @@ If there was no error, it will return \f[B]BCL_ERROR_NONE\f[R]. There must be a valid current context. .RE .SS Numbers -.PP All procedures in this section require a valid current context. .TP \f[B]BclNumber\f[R] -A handle to an arbitrary-precision number. +A handle to an arbitrary\-precision number. The actual number type is not exposed; the \f[B]BclNumber\f[R] handle is -the only way clients can refer to instances of arbitrary-precision +the only way clients can refer to instances of arbitrary\-precision numbers. .TP \f[B]BclNumber bcl_num_create(\f[R]\f[I]void\f[R]\f[B])\f[R] @@ -532,11 +638,11 @@ Otherwise, this function can return: Returns the number of \f[I]significant decimal digits\f[R] in \f[I]n\f[R]. .SS Conversion -.PP All procedures in this section require a valid current context. .PP -All procedures in this section consume the given \f[B]BclNumber\f[R] -arguments that are not given to pointer arguments. +All procedures in this section without the \f[B]_keep\f[R] suffix in +their name consume the given \f[B]BclNumber\f[R] arguments that are not +given to pointer arguments. See the \f[B]Consumption and Propagation\f[R] subsection below. .TP \f[B]BclNumber bcl_parse(const char *restrict\f[R] \f[I]val\f[R]\f[B])\f[R] @@ -544,7 +650,7 @@ Parses a number string according to the current context\[cq]s \f[B]ibase\f[R] and returns the resulting number. .RS .PP -\f[I]val\f[R] must be non-\f[B]NULL\f[R] and a valid string. +\f[I]val\f[R] must be non\-\f[B]NULL\f[R] and a valid string. See \f[B]BCL_ERROR_PARSE_INVALID_STR\f[R] in the \f[B]ERRORS\f[R] section for more information. .PP @@ -571,6 +677,11 @@ The string is dynamically allocated and must be freed by the caller. See the \f[B]Consumption and Propagation\f[R] subsection below. .RE .TP +\f[B]char* bcl_string_keep(BclNumber\f[R] \f[I]n\f[R]\f[B])\f[R] +Returns a string representation of \f[I]n\f[R] according the the current +context\[cq]s \f[B]ibase\f[R]. +The string is dynamically allocated and must be freed by the caller. +.TP \f[B]BclError bcl_bigdig(BclNumber\f[R] \f[I]n\f[R]\f[B], BclBigDig *\f[R]\f[I]result\f[R]\f[B])\f[R] Converts \f[I]n\f[R] into a \f[B]BclBigDig\f[R] and returns the result in the space pointed to by \f[I]result\f[R]. @@ -592,6 +703,24 @@ Otherwise, this function can return: See the \f[B]Consumption and Propagation\f[R] subsection below. .RE .TP +\f[B]BclError bcl_bigdig_keep(BclNumber\f[R] \f[I]n\f[R]\f[B], BclBigDig *\f[R]\f[I]result\f[R]\f[B])\f[R] +Converts \f[I]n\f[R] into a \f[B]BclBigDig\f[R] and returns the result +in the space pointed to by \f[I]result\f[R]. +.RS +.PP +\f[I]a\f[R] must be smaller than \f[B]BC_OVERFLOW_MAX\f[R]. +See the \f[B]LIMITS\f[R] section. +.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_INVALID_NUM\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_INVALID_CONTEXT\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_MATH_OVERFLOW\f[R] +.RE +.TP \f[B]BclNumber bcl_bigdig2num(BclBigDig\f[R] \f[I]val\f[R]\f[B])\f[R] Creates a \f[B]BclNumber\f[R] from \f[I]val\f[R]. .RS @@ -605,9 +734,13 @@ Possible errors include: \f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] .RE .SS Math -.PP All procedures in this section require a valid current context. .PP +All procedures in this section without the \f[B]_keep\f[R] suffix in +their name consume the given \f[B]BclNumber\f[R] arguments that are not +given to pointer arguments. +See the \f[B]Consumption and Propagation\f[R] subsection below. +.PP All procedures in this section can return the following errors: .IP \[bu] 2 \f[B]BCL_ERROR_INVALID_NUM\f[R] @@ -639,6 +772,25 @@ Possible errors include: \f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] .RE .TP +\f[B]BclNumber bcl_add_keep(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] \f[I]b\f[R]\f[B])\f[R] +Adds \f[I]a\f[R] and \f[I]b\f[R] and returns the result. +The \f[I]scale\f[R] of the result is the max of the \f[I]scale\f[R]s of +\f[I]a\f[R] and \f[I]b\f[R]. +.RS +.PP +\f[I]a\f[R] and \f[I]b\f[R] can be the same number. +.PP +bcl(3) will encode an error in the return value, if there was one. +The error can be queried with \f[B]bcl_err(BclNumber)\f[R]. +Possible errors include: +.IP \[bu] 2 +\f[B]BCL_ERROR_INVALID_NUM\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_INVALID_CONTEXT\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] +.RE +.TP \f[B]BclNumber bcl_sub(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] \f[I]b\f[R]\f[B])\f[R] Subtracts \f[I]b\f[R] from \f[I]a\f[R] and returns the result. The \f[I]scale\f[R] of the result is the max of the \f[I]scale\f[R]s of @@ -662,6 +814,25 @@ Possible errors include: \f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] .RE .TP +\f[B]BclNumber bcl_sub_keep(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] \f[I]b\f[R]\f[B])\f[R] +Subtracts \f[I]b\f[R] from \f[I]a\f[R] and returns the result. +The \f[I]scale\f[R] of the result is the max of the \f[I]scale\f[R]s of +\f[I]a\f[R] and \f[I]b\f[R]. +.RS +.PP +\f[I]a\f[R] and \f[I]b\f[R] can be the same number. +.PP +bcl(3) will encode an error in the return value, if there was one. +The error can be queried with \f[B]bcl_err(BclNumber)\f[R]. +Possible errors include: +.IP \[bu] 2 +\f[B]BCL_ERROR_INVALID_NUM\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_INVALID_CONTEXT\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] +.RE +.TP \f[B]BclNumber bcl_mul(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] \f[I]b\f[R]\f[B])\f[R] Multiplies \f[I]a\f[R] and \f[I]b\f[R] and returns the result. If \f[I]ascale\f[R] is the \f[I]scale\f[R] of \f[I]a\f[R] and @@ -688,6 +859,28 @@ Possible errors include: \f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] .RE .TP +\f[B]BclNumber bcl_mul_keep(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] \f[I]b\f[R]\f[B])\f[R] +Multiplies \f[I]a\f[R] and \f[I]b\f[R] and returns the result. +If \f[I]ascale\f[R] is the \f[I]scale\f[R] of \f[I]a\f[R] and +\f[I]bscale\f[R] is the \f[I]scale\f[R] of \f[I]b\f[R], the +\f[I]scale\f[R] of the result is equal to +\f[B]min(ascale+bscale,max(scale,ascale,bscale))\f[R], where +\f[B]min()\f[R] and \f[B]max()\f[R] return the obvious values. +.RS +.PP +\f[I]a\f[R] and \f[I]b\f[R] can be the same number. +.PP +bcl(3) will encode an error in the return value, if there was one. +The error can be queried with \f[B]bcl_err(BclNumber)\f[R]. +Possible errors include: +.IP \[bu] 2 +\f[B]BCL_ERROR_INVALID_NUM\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_INVALID_CONTEXT\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] +.RE +.TP \f[B]BclNumber bcl_div(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] \f[I]b\f[R]\f[B])\f[R] Divides \f[I]a\f[R] by \f[I]b\f[R] and returns the result. The \f[I]scale\f[R] of the result is the \f[I]scale\f[R] of the current @@ -715,9 +908,32 @@ Possible errors include: \f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] .RE .TP +\f[B]BclNumber bcl_div_keep(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] \f[I]b\f[R]\f[B])\f[R] +Divides \f[I]a\f[R] by \f[I]b\f[R] and returns the result. +The \f[I]scale\f[R] of the result is the \f[I]scale\f[R] of the current +context. +.RS +.PP +\f[I]b\f[R] cannot be \f[B]0\f[R]. +.PP +\f[I]a\f[R] and \f[I]b\f[R] can be the same number. +.PP +bcl(3) will encode an error in the return value, if there was one. +The error can be queried with \f[B]bcl_err(BclNumber)\f[R]. +Possible errors include: +.IP \[bu] 2 +\f[B]BCL_ERROR_INVALID_NUM\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_INVALID_CONTEXT\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_MATH_DIVIDE_BY_ZERO\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] +.RE +.TP \f[B]BclNumber bcl_mod(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] \f[I]b\f[R]\f[B])\f[R] Divides \f[I]a\f[R] by \f[I]b\f[R] to the \f[I]scale\f[R] of the current -context, computes the modulus \f[B]a-(a/b)*b\f[R], and returns the +context, computes the modulus \f[B]a\-(a/b)*b\f[R], and returns the modulus. .RS .PP @@ -742,11 +958,34 @@ Possible errors include: \f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] .RE .TP +\f[B]BclNumber bcl_mod_keep(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] \f[I]b\f[R]\f[B])\f[R] +Divides \f[I]a\f[R] by \f[I]b\f[R] to the \f[I]scale\f[R] of the current +context, computes the modulus \f[B]a\-(a/b)*b\f[R], and returns the +modulus. +.RS +.PP +\f[I]b\f[R] cannot be \f[B]0\f[R]. +.PP +\f[I]a\f[R] and \f[I]b\f[R] can be the same number. +.PP +bcl(3) will encode an error in the return value, if there was one. +The error can be queried with \f[B]bcl_err(BclNumber)\f[R]. +Possible errors include: +.IP \[bu] 2 +\f[B]BCL_ERROR_INVALID_NUM\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_INVALID_CONTEXT\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_MATH_DIVIDE_BY_ZERO\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] +.RE +.TP \f[B]BclNumber bcl_pow(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] \f[I]b\f[R]\f[B])\f[R] Calculates \f[I]a\f[R] to the power of \f[I]b\f[R] to the \f[I]scale\f[R] of the current context. \f[I]b\f[R] must be an integer, but can be negative. -If it is negative, \f[I]a\f[R] must be non-zero. +If it is negative, \f[I]a\f[R] must be non\-zero. .RS .PP \f[I]b\f[R] must be an integer. @@ -778,6 +1017,38 @@ Possible errors include: \f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] .RE .TP +\f[B]BclNumber bcl_pow_keep(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] \f[I]b\f[R]\f[B])\f[R] +Calculates \f[I]a\f[R] to the power of \f[I]b\f[R] to the +\f[I]scale\f[R] of the current context. +\f[I]b\f[R] must be an integer, but can be negative. +If it is negative, \f[I]a\f[R] must be non\-zero. +.RS +.PP +\f[I]b\f[R] must be an integer. +If \f[I]b\f[R] is negative, \f[I]a\f[R] must not be \f[B]0\f[R]. +.PP +\f[I]a\f[R] must be smaller than \f[B]BC_OVERFLOW_MAX\f[R]. +See the \f[B]LIMITS\f[R] section. +.PP +\f[I]a\f[R] and \f[I]b\f[R] can be the same number. +.PP +bcl(3) will encode an error in the return value, if there was one. +The error can be queried with \f[B]bcl_err(BclNumber)\f[R]. +Possible errors include: +.IP \[bu] 2 +\f[B]BCL_ERROR_INVALID_NUM\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_INVALID_CONTEXT\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_MATH_NON_INTEGER\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_MATH_OVERFLOW\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_MATH_DIVIDE_BY_ZERO\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] +.RE +.TP \f[B]BclNumber bcl_lshift(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] \f[I]b\f[R]\f[B])\f[R] Shifts \f[I]a\f[R] left (moves the radix right) by \f[I]b\f[R] places and returns the result. @@ -806,6 +1077,30 @@ Possible errors include: \f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] .RE .TP +\f[B]BclNumber bcl_lshift_keep(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] \f[I]b\f[R]\f[B])\f[R] +Shifts \f[I]a\f[R] left (moves the radix right) by \f[I]b\f[R] places +and returns the result. +This is done in decimal. +\f[I]b\f[R] must be an integer. +.RS +.PP +\f[I]b\f[R] must be an integer. +.PP +\f[I]a\f[R] and \f[I]b\f[R] can be the same number. +.PP +bcl(3) will encode an error in the return value, if there was one. +The error can be queried with \f[B]bcl_err(BclNumber)\f[R]. +Possible errors include: +.IP \[bu] 2 +\f[B]BCL_ERROR_INVALID_NUM\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_INVALID_CONTEXT\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_MATH_NON_INTEGER\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] +.RE +.TP \f[B]BclNumber bcl_rshift(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] \f[I]b\f[R]\f[B])\f[R] Shifts \f[I]a\f[R] right (moves the radix left) by \f[I]b\f[R] places and returns the result. @@ -834,6 +1129,30 @@ Possible errors include: \f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] .RE .TP +\f[B]BclNumber bcl_rshift_keep(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] \f[I]b\f[R]\f[B])\f[R] +Shifts \f[I]a\f[R] right (moves the radix left) by \f[I]b\f[R] places +and returns the result. +This is done in decimal. +\f[I]b\f[R] must be an integer. +.RS +.PP +\f[I]b\f[R] must be an integer. +.PP +\f[I]a\f[R] and \f[I]b\f[R] can be the same number. +.PP +bcl(3) will encode an error in the return value, if there was one. +The error can be queried with \f[B]bcl_err(BclNumber)\f[R]. +Possible errors include: +.IP \[bu] 2 +\f[B]BCL_ERROR_INVALID_NUM\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_INVALID_CONTEXT\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_MATH_NON_INTEGER\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] +.RE +.TP \f[B]BclNumber bcl_sqrt(BclNumber\f[R] \f[I]a\f[R]\f[B])\f[R] Calculates the square root of \f[I]a\f[R] and returns the result. The \f[I]scale\f[R] of the result is equal to the \f[B]scale\f[R] of the @@ -858,6 +1177,27 @@ Possible errors include: \f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] .RE .TP +\f[B]BclNumber bcl_sqrt_keep(BclNumber\f[R] \f[I]a\f[R]\f[B])\f[R] +Calculates the square root of \f[I]a\f[R] and returns the result. +The \f[I]scale\f[R] of the result is equal to the \f[B]scale\f[R] of the +current context. +.RS +.PP +\f[I]a\f[R] cannot be negative. +.PP +bcl(3) will encode an error in the return value, if there was one. +The error can be queried with \f[B]bcl_err(BclNumber)\f[R]. +Possible errors include: +.IP \[bu] 2 +\f[B]BCL_ERROR_INVALID_NUM\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_INVALID_CONTEXT\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_MATH_NEGATIVE\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] +.RE +.TP \f[B]BclError bcl_divmod(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] \f[I]b\f[R]\f[B], BclNumber *\f[R]\f[I]c\f[R]\f[B], BclNumber *\f[R]\f[I]d\f[R]\f[B])\f[R] Divides \f[I]a\f[R] by \f[I]b\f[R] and returns the quotient in a new number which is put into the space pointed to by \f[I]c\f[R], and puts @@ -886,6 +1226,30 @@ Otherwise, this function can return: \f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] .RE .TP +\f[B]BclError bcl_divmod_keep(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] \f[I]b\f[R]\f[B], BclNumber *\f[R]\f[I]c\f[R]\f[B], BclNumber *\f[R]\f[I]d\f[R]\f[B])\f[R] +Divides \f[I]a\f[R] by \f[I]b\f[R] and returns the quotient in a new +number which is put into the space pointed to by \f[I]c\f[R], and puts +the modulus in a new number which is put into the space pointed to by +\f[I]d\f[R]. +.RS +.PP +\f[I]b\f[R] cannot be \f[B]0\f[R]. +.PP +\f[I]c\f[R] and \f[I]d\f[R] cannot point to the same place, nor can they +point to the space occupied by \f[I]a\f[R] or \f[I]b\f[R]. +.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_INVALID_NUM\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_INVALID_CONTEXT\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_MATH_DIVIDE_BY_ZERO\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] +.RE +.TP \f[B]BclNumber bcl_modexp(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] \f[I]b\f[R]\f[B], BclNumber\f[R] \f[I]c\f[R]\f[B])\f[R] Computes a modular exponentiation where \f[I]a\f[R] is the base, \f[I]b\f[R] is the exponent, and \f[I]c\f[R] is the modulus, and returns @@ -918,6 +1282,35 @@ Possible errors include: .IP \[bu] 2 \f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] .RE +.TP +\f[B]BclNumber bcl_modexp_keep(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] \f[I]b\f[R]\f[B], BclNumber\f[R] \f[I]c\f[R]\f[B])\f[R] +Computes a modular exponentiation where \f[I]a\f[R] is the base, +\f[I]b\f[R] is the exponent, and \f[I]c\f[R] is the modulus, and returns +the result. +The \f[I]scale\f[R] of the result is equal to the \f[B]scale\f[R] of the +current context. +.RS +.PP +\f[I]a\f[R], \f[I]b\f[R], and \f[I]c\f[R] must be integers. +\f[I]c\f[R] must not be \f[B]0\f[R]. +\f[I]b\f[R] must not be negative. +.PP +bcl(3) will encode an error in the return value, if there was one. +The error can be queried with \f[B]bcl_err(BclNumber)\f[R]. +Possible errors include: +.IP \[bu] 2 +\f[B]BCL_ERROR_INVALID_NUM\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_INVALID_CONTEXT\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_MATH_NEGATIVE\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_MATH_NON_INTEGER\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_MATH_DIVIDE_BY_ZERO\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] +.RE .SS Miscellaneous .TP \f[B]void bcl_zero(BclNumber\f[R] \f[I]n\f[R]\f[B])\f[R] @@ -961,11 +1354,11 @@ Possible errors include: .IP \[bu] 2 \f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] .RE -.SS Pseudo-Random Number Generator -.PP -The pseudo-random number generator in bcl(3) is a \f[I]seeded\f[R] PRNG. +.SS Pseudo\-Random Number Generator +The pseudo\-random number generator in bcl(3) is a \f[I]seeded\f[R] +PRNG. Given the same seed twice, it will produce the same sequence of -pseudo-random numbers twice. +pseudo\-random numbers twice. .PP By default, bcl(3) attempts to seed the PRNG with data from \f[B]/dev/urandom\f[R]. @@ -987,7 +1380,12 @@ char[\f[R]\f[I]BCL_SEED_SIZE\f[R]\f[B]])\f[R] .IP \[bu] 2 \f[B]bcl_rand_reseed(\f[R]\f[I]void\f[R]\f[B])\f[R] .PP -The following items allow clients to use the pseudo-random number +All procedures in this section without the \f[B]_keep\f[R] suffix in +their name consume the given \f[B]BclNumber\f[R] arguments that are not +given to pointer arguments. +See the \f[B]Consumption and Propagation\f[R] subsection below. +.PP +The following items allow clients to use the pseudo\-random number generator. All procedures require a valid current context. .TP @@ -1017,7 +1415,7 @@ This is done by generating as many random numbers as necessary, multiplying them by certain exponents, and adding them all together. .RS .PP -\f[I]a\f[R] must be an integer and non-negative. +\f[I]a\f[R] must be an integer and non\-negative. .PP \f[I]a\f[R] is consumed; it cannot be used after the call. See the \f[B]Consumption and Propagation\f[R] subsection below. @@ -1039,6 +1437,36 @@ Possible errors include: \f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] .RE .TP +\f[B]BclNumber bcl_irand_keep(BclNumber\f[R] \f[I]a\f[R]\f[B])\f[R] +Returns a random number that is not larger than \f[I]a\f[R] in a new +number. +If \f[I]a\f[R] is \f[B]0\f[R] or \f[B]1\f[R], the new number is equal to +\f[B]0\f[R]. +The bound is unlimited, so it is not bound to the size of +\f[B]BclRandInt\f[R]. +This is done by generating as many random numbers as necessary, +multiplying them by certain exponents, and adding them all together. +.RS +.PP +\f[I]a\f[R] must be an integer and non\-negative. +.PP +This procedure requires a valid current context. +.PP +bcl(3) will encode an error in the return value, if there was one. +The error can be queried with \f[B]bcl_err(BclNumber)\f[R]. +Possible errors include: +.IP \[bu] 2 +\f[B]BCL_ERROR_INVALID_NUM\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_INVALID_CONTEXT\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_MATH_NEGATIVE\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_MATH_NON_INTEGER\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] +.RE +.TP \f[B]BclNumber bcl_frand(size_t\f[R] \f[I]places\f[R]\f[B])\f[R] Returns a random number between \f[B]0\f[R] (inclusive) and \f[B]1\f[R] (exclusive) that has \f[I]places\f[R] decimal digits after the radix @@ -1063,7 +1491,7 @@ decimal digits after the radix (decimal point). There are no limits on \f[I]a\f[R] or \f[I]places\f[R]. .RS .PP -\f[I]a\f[R] must be an integer and non-negative. +\f[I]a\f[R] must be an integer and non\-negative. .PP \f[I]a\f[R] is consumed; it cannot be used after the call. See the \f[B]Consumption and Propagation\f[R] subsection below. @@ -1085,11 +1513,55 @@ Possible errors include: \f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] .RE .TP +\f[B]BclNumber bcl_ifrand_keep(BclNumber\f[R] \f[I]a\f[R]\f[B], size_t\f[R] \f[I]places\f[R]\f[B])\f[R] +Returns a random number less than \f[I]a\f[R] with \f[I]places\f[R] +decimal digits after the radix (decimal point). +There are no limits on \f[I]a\f[R] or \f[I]places\f[R]. +.RS +.PP +\f[I]a\f[R] must be an integer and non\-negative. +.PP +This procedure requires a valid current context. +.PP +bcl(3) will encode an error in the return value, if there was one. +The error can be queried with \f[B]bcl_err(BclNumber)\f[R]. +Possible errors include: +.IP \[bu] 2 +\f[B]BCL_ERROR_INVALID_NUM\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_INVALID_CONTEXT\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_MATH_NEGATIVE\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_MATH_NON_INTEGER\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] +.RE +.TP \f[B]BclError bcl_rand_seedWithNum(BclNumber\f[R] \f[I]n\f[R]\f[B])\f[R] Seeds the PRNG with \f[I]n\f[R]. .RS .PP -\f[I]n\f[R] is \f[I]not\f[R] consumed. +\f[I]n\f[R] is consumed. +.PP +This procedure requires a valid current context. +.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_INVALID_NUM\f[R] +.IP \[bu] 2 +\f[B]BCL_ERROR_INVALID_CONTEXT\f[R] +.PP +Note that if \f[B]bcl_rand_seed2num(\f[R]\f[I]void\f[R]\f[B])\f[R] or +\f[B]bcl_rand_seed2num_err(BclNumber)\f[R] are called right after this +function, they are not guaranteed to return a number equal to +\f[I]n\f[R]. +.RE +.TP +\f[B]BclError bcl_rand_seedWithNum_keep(BclNumber\f[R] \f[I]n\f[R]\f[B])\f[R] +Seeds the PRNG with \f[I]n\f[R]. +.RS .PP This procedure requires a valid current context. .PP @@ -1157,18 +1629,15 @@ Bias is removed before returning the integer. This procedure cannot fail. .RE .SS Consumption and Propagation -.PP Some functions are listed as consuming some or all of their arguments. This means that the arguments are freed, regardless of if there were errors or not. .PP This is to enable compact code like the following: .IP -.nf -\f[C] +.EX BclNumber n = bcl_num_add(bcl_num_mul(a, b), bcl_num_div(c, d)); -\f[R] -.fi +.EE .PP If arguments to those functions were not consumed, memory would be leaked until reclaimed with \f[B]bcl_ctxt_freeNums(BclContext)\f[R]. @@ -1177,16 +1646,13 @@ When errors occur, they are propagated through. The result should always be checked with \f[B]bcl_err(BclNumber)\f[R], so the example above should properly be: .IP -.nf -\f[C] +.EX BclNumber n = bcl_num_add(bcl_num_mul(a, b), bcl_num_div(c, d)); -if (bc_num_err(n) != BCL_ERROR_NONE) { +if (bcl_err(n) != BCL_ERROR_NONE) { // Handle the error. } -\f[R] -.fi +.EE .SH ERRORS -.PP Most functions in bcl(3) return, directly or indirectly, any one of the error codes defined in \f[B]BclError\f[R]. The complete list of codes is the following: @@ -1200,16 +1666,13 @@ 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. .TP \f[B]BCL_ERROR_MATH_NON_INTEGER\f[R] -A non-integer was given as an argument to a parameter that cannot accept -non-integer numbers, such as for the second parameter of +A non\-integer was given as an argument to a parameter that cannot +accept non\-integer numbers, such as for the second parameter of \f[B]bcl_num_pow()\f[R]. .TP \f[B]BCL_ERROR_MATH_OVERFLOW\f[R] @@ -1224,7 +1687,7 @@ An invalid number string was passed to a parsing function. .RS .PP A valid number string can only be one radix (period). -In addition, any lowercase ASCII letters, symbols, or non-ASCII +In addition, any lowercase ASCII letters, symbols, or non\-ASCII characters are invalid. It is allowed for the first character to be a dash. In that case, the number is considered to be negative. @@ -1244,7 +1707,7 @@ of the current \f[B]ibase\f[R]. For example, if \f[B]ibase\f[R] is \f[B]16\f[R] and bcl(3) is given the number string \f[B]FFeA\f[R], the resulting decimal number will be \f[B]2550000000000\f[R], and if bcl(3) is given the number string -\f[B]10e-4\f[R], the resulting decimal number will be \f[B]0.0016\f[R]. +\f[B]10e\-4\f[R], the resulting decimal number will be \f[B]0.0016\f[R]. .RE .TP \f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] @@ -1277,14 +1740,17 @@ It is highly recommended that client libraries do \f[I]not\f[R] activate 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. -.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 \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 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 value of \f[B]1\f[R] decimal digit at a time, but that can be slow. bcl(3) does something different. @@ -1304,7 +1770,6 @@ checking. This integer type depends on the value of \f[B]BC_LONG_BIT\f[R], but is always at least twice as large as the integer type used to store digits. .SH LIMITS -.PP The following are the limits on bcl(3): .TP \f[B]BC_LONG_BIT\f[R] @@ -1334,51 +1799,31 @@ Set at \f[B]BC_BASE_POW\f[R]. .TP \f[B]BC_SCALE_MAX\f[R] The maximum \f[B]scale\f[R]. -Set at \f[B]BC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]BC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]BC_NUM_MAX\f[R] The maximum length of a number (in decimal digits), which includes digits after the decimal point. -Set at \f[B]BC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]BC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]BC_RAND_MAX\f[R] The maximum integer (inclusive) returned by the \f[B]bcl_rand_int()\f[R] function. -Set at \f[B]2\[ha]BC_LONG_BIT-1\f[R]. +Set at \f[B]2\[ha]BC_LONG_BIT\-1\f[R]. .TP Exponent The maximum allowable exponent (positive or negative). Set at \f[B]BC_OVERFLOW_MAX\f[R]. .PP -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. +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) .SH STANDARDS -.PP bcl(3) is compliant with the arithmetic defined in the IEEE Std -1003.1-2017 (\[lq]POSIX.1-2017\[rq]) specification at +1003.1\-2017 (\[lq]POSIX.1\-2017\[rq]) specification at https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html for bc(1). .PP @@ -1387,10 +1832,10 @@ numbers that use a period (\f[B].\f[R]) as a radix point, regardless of the value of \f[B]LC_NUMERIC\f[R]. This is also true of bcl(3). .SH BUGS -.PP None are known. -Report bugs at https://git.yzena.com/gavin/bc. +Report bugs at https://git.gavinhoward.com/gavin/bc. .SH AUTHORS -.PP -Gavin D. -Howard <gavin@yzena.com> and contributors. +Gavin D. Howard \c +.MT gavin@gavinhoward.com +.ME \c +\ and contributors. diff --git a/contrib/bc/manuals/bcl.3.md b/contrib/bc/manuals/bcl.3.md index 1f694413f7d6..41c1c120b623 100644 --- a/contrib/bc/manuals/bcl.3.md +++ b/contrib/bc/manuals/bcl.3.md @@ -2,7 +2,7 @@ SPDX-License-Identifier: BSD-2-Clause -Copyright (c) 2018-2021 Gavin D. Howard and contributors. +Copyright (c) 2018-2024 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 @@ -137,8 +136,12 @@ These items allow clients to convert numbers into and from strings and integers. **char\* bcl_string(BclNumber** _n_**);** +**char\* bcl_string_keep(BclNumber** _n_**);** + **BclError bcl_bigdig(BclNumber** _n_**, BclBigDig \***_result_**);** +**BclError bcl_bigdig_keep(BclNumber** _n_**, BclBigDig \***_result_**);** + **BclNumber bcl_bigdig2num(BclBigDig** _val_**);** ## Math @@ -147,26 +150,48 @@ These items allow clients to run math on numbers. **BclNumber bcl_add(BclNumber** _a_**, BclNumber** _b_**);** +**BclNumber bcl_add_keep(BclNumber** _a_**, BclNumber** _b_**);** + **BclNumber bcl_sub(BclNumber** _a_**, BclNumber** _b_**);** +**BclNumber bcl_sub_keep(BclNumber** _a_**, BclNumber** _b_**);** + **BclNumber bcl_mul(BclNumber** _a_**, BclNumber** _b_**);** +**BclNumber bcl_mul_keep(BclNumber** _a_**, BclNumber** _b_**);** + **BclNumber bcl_div(BclNumber** _a_**, BclNumber** _b_**);** +**BclNumber bcl_div_keep(BclNumber** _a_**, BclNumber** _b_**);** + **BclNumber bcl_mod(BclNumber** _a_**, BclNumber** _b_**);** +**BclNumber bcl_mod_keep(BclNumber** _a_**, BclNumber** _b_**);** + **BclNumber bcl_pow(BclNumber** _a_**, BclNumber** _b_**);** +**BclNumber bcl_pow_keep(BclNumber** _a_**, BclNumber** _b_**);** + **BclNumber bcl_lshift(BclNumber** _a_**, BclNumber** _b_**);** +**BclNumber bcl_lshift_keep(BclNumber** _a_**, BclNumber** _b_**);** + **BclNumber bcl_rshift(BclNumber** _a_**, BclNumber** _b_**);** +**BclNumber bcl_rshift_keep(BclNumber** _a_**, BclNumber** _b_**);** + **BclNumber bcl_sqrt(BclNumber** _a_**);** +**BclNumber bcl_sqrt_keep(BclNumber** _a_**);** + **BclError bcl_divmod(BclNumber** _a_**, BclNumber** _b_**, BclNumber \***_c_**, BclNumber \***_d_**);** +**BclError bcl_divmod_keep(BclNumber** _a_**, BclNumber** _b_**, BclNumber \***_c_**, BclNumber \***_d_**);** + **BclNumber bcl_modexp(BclNumber** _a_**, BclNumber** _b_**, BclNumber** _c_**);** +**BclNumber bcl_modexp_keep(BclNumber** _a_**, BclNumber** _b_**, BclNumber** _c_**);** + ## Miscellaneous These items are miscellaneous. @@ -196,12 +221,18 @@ generator in bcl(3). **BclNumber bcl_irand(BclNumber** _a_**);** +**BclNumber bcl_irand_keep(BclNumber** _a_**);** + **BclNumber bcl_frand(size_t** _places_**);** **BclNumber bcl_ifrand(BclNumber** _a_**, size_t** _places_**);** +**BclNumber bcl_ifrand_keep(BclNumber** _a_**, size_t** _places_**);** + **BclError bcl_rand_seedWithNum(BclNumber** _n_**);** +**BclError bcl_rand_seedWithNum_keep(BclNumber** _n_**);** + **BclError bcl_rand_seed(unsigned char** _seed_**[**_BCL_SEED_SIZE_**]);** **void bcl_rand_reseed(**_void_**);** @@ -218,64 +249,73 @@ 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 +## Setup + +**BclError bcl_start(**_void_**)** -**void bcl_handleSignal(**_void_**)** +: Initializes this library. This function can be called multiple times, but + **bcl_end()** must only be called *once*. This is to make it possible for + multiple libraries and applications to initialize bcl(3) without problem. -: 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. + 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: - If execution *is* interrupted, **bcl_handleSignal(**_void_**)** does *not* - return to its caller. + * **BCL_ERROR_FATAL_ALLOC_ERR** - See the **SIGNAL HANDLING** section. + This function must be the first one clients call. Calling any other + function without calling this one first is undefined behavior. -**bool bcl_running(**_void_**)** +**void bcl_end(**_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**. +: Deinitializes this library. This function must only be called *once*. - See the **SIGNAL HANDLING** section. + All data must have been freed before calling this function. -## Setup + 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 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. +: 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 first one clients call. Calling any other - function without calling this one first is undefined behavior. + 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 +325,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 +336,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 +347,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 +358,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 +434,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. @@ -496,9 +580,9 @@ All procedures in this section require a valid current context. All procedures in this section require a valid current context. -All procedures in this section consume the given **BclNumber** arguments that -are not given to pointer arguments. See the **Consumption and Propagation** -subsection below. +All procedures in this section without the **_keep** suffix in their name +consume the given **BclNumber** arguments that are not given to pointer +arguments. See the **Consumption and Propagation** subsection below. **BclNumber bcl_parse(const char \*restrict** _val_**)** @@ -526,6 +610,12 @@ subsection below. *n* is consumed; it cannot be used after the call. See the **Consumption and Propagation** subsection below. +**char\* bcl_string_keep(BclNumber** _n_**)** + +: Returns a string representation of *n* according the the current context's + **ibase**. The string is dynamically allocated and must be freed by the + caller. + **BclError bcl_bigdig(BclNumber** _n_**, BclBigDig \***_result_**)** : Converts *n* into a **BclBigDig** and returns the result in the space @@ -543,6 +633,20 @@ subsection below. *n* is consumed; it cannot be used after the call. See the **Consumption and Propagation** subsection below. +**BclError bcl_bigdig_keep(BclNumber** _n_**, BclBigDig \***_result_**)** + +: Converts *n* into a **BclBigDig** and returns the result in the space + pointed to by *result*. + + *a* must be smaller than **BC_OVERFLOW_MAX**. See the **LIMITS** section. + + If there was no error, **BCL_ERROR_NONE** is returned. Otherwise, this + function can return: + + * **BCL_ERROR_INVALID_NUM** + * **BCL_ERROR_INVALID_CONTEXT** + * **BCL_ERROR_MATH_OVERFLOW** + **BclNumber bcl_bigdig2num(BclBigDig** _val_**)** : Creates a **BclNumber** from *val*. @@ -557,6 +661,10 @@ subsection below. All procedures in this section require a valid current context. +All procedures in this section without the **_keep** suffix in their name +consume the given **BclNumber** arguments that are not given to pointer +arguments. See the **Consumption and Propagation** subsection below. + All procedures in this section can return the following errors: * **BCL_ERROR_INVALID_NUM** @@ -580,6 +688,20 @@ All procedures in this section can return the following errors: * **BCL_ERROR_INVALID_CONTEXT** * **BCL_ERROR_FATAL_ALLOC_ERR** +**BclNumber bcl_add_keep(BclNumber** _a_**, BclNumber** _b_**)** + +: Adds *a* and *b* and returns the result. The *scale* of the result is the + max of the *scale*s of *a* and *b*. + + *a* and *b* can be the same number. + + bcl(3) will encode an error in the return value, if there was one. The error + can be queried with **bcl_err(BclNumber)**. Possible errors include: + + * **BCL_ERROR_INVALID_NUM** + * **BCL_ERROR_INVALID_CONTEXT** + * **BCL_ERROR_FATAL_ALLOC_ERR** + **BclNumber bcl_sub(BclNumber** _a_**, BclNumber** _b_**)** : Subtracts *b* from *a* and returns the result. The *scale* of the result is @@ -597,6 +719,20 @@ All procedures in this section can return the following errors: * **BCL_ERROR_INVALID_CONTEXT** * **BCL_ERROR_FATAL_ALLOC_ERR** +**BclNumber bcl_sub_keep(BclNumber** _a_**, BclNumber** _b_**)** + +: Subtracts *b* from *a* and returns the result. The *scale* of the result is + the max of the *scale*s of *a* and *b*. + + *a* and *b* can be the same number. + + bcl(3) will encode an error in the return value, if there was one. The error + can be queried with **bcl_err(BclNumber)**. Possible errors include: + + * **BCL_ERROR_INVALID_NUM** + * **BCL_ERROR_INVALID_CONTEXT** + * **BCL_ERROR_FATAL_ALLOC_ERR** + **BclNumber bcl_mul(BclNumber** _a_**, BclNumber** _b_**)** : Multiplies *a* and *b* and returns the result. If *ascale* is the *scale* of @@ -616,6 +752,22 @@ All procedures in this section can return the following errors: * **BCL_ERROR_INVALID_CONTEXT** * **BCL_ERROR_FATAL_ALLOC_ERR** +**BclNumber bcl_mul_keep(BclNumber** _a_**, BclNumber** _b_**)** + +: Multiplies *a* and *b* and returns the result. If *ascale* is the *scale* of + *a* and *bscale* is the *scale* of *b*, the *scale* of the result is equal + to **min(ascale+bscale,max(scale,ascale,bscale))**, where **min()** and + **max()** return the obvious values. + + *a* and *b* can be the same number. + + bcl(3) will encode an error in the return value, if there was one. The error + can be queried with **bcl_err(BclNumber)**. Possible errors include: + + * **BCL_ERROR_INVALID_NUM** + * **BCL_ERROR_INVALID_CONTEXT** + * **BCL_ERROR_FATAL_ALLOC_ERR** + **BclNumber bcl_div(BclNumber** _a_**, BclNumber** _b_**)** : Divides *a* by *b* and returns the result. The *scale* of the result is the @@ -636,6 +788,23 @@ All procedures in this section can return the following errors: * **BCL_ERROR_MATH_DIVIDE_BY_ZERO** * **BCL_ERROR_FATAL_ALLOC_ERR** +**BclNumber bcl_div_keep(BclNumber** _a_**, BclNumber** _b_**)** + +: Divides *a* by *b* and returns the result. The *scale* of the result is the + *scale* of the current context. + + *b* cannot be **0**. + + *a* and *b* can be the same number. + + bcl(3) will encode an error in the return value, if there was one. The error + can be queried with **bcl_err(BclNumber)**. Possible errors include: + + * **BCL_ERROR_INVALID_NUM** + * **BCL_ERROR_INVALID_CONTEXT** + * **BCL_ERROR_MATH_DIVIDE_BY_ZERO** + * **BCL_ERROR_FATAL_ALLOC_ERR** + **BclNumber bcl_mod(BclNumber** _a_**, BclNumber** _b_**)** : Divides *a* by *b* to the *scale* of the current context, computes the @@ -656,6 +825,23 @@ All procedures in this section can return the following errors: * **BCL_ERROR_MATH_DIVIDE_BY_ZERO** * **BCL_ERROR_FATAL_ALLOC_ERR** +**BclNumber bcl_mod_keep(BclNumber** _a_**, BclNumber** _b_**)** + +: Divides *a* by *b* to the *scale* of the current context, computes the + modulus **a-(a/b)\*b**, and returns the modulus. + + *b* cannot be **0**. + + *a* and *b* can be the same number. + + bcl(3) will encode an error in the return value, if there was one. The error + can be queried with **bcl_err(BclNumber)**. Possible errors include: + + * **BCL_ERROR_INVALID_NUM** + * **BCL_ERROR_INVALID_CONTEXT** + * **BCL_ERROR_MATH_DIVIDE_BY_ZERO** + * **BCL_ERROR_FATAL_ALLOC_ERR** + **BclNumber bcl_pow(BclNumber** _a_**, BclNumber** _b_**)** : Calculates *a* to the power of *b* to the *scale* of the current context. @@ -681,6 +867,28 @@ All procedures in this section can return the following errors: * **BCL_ERROR_MATH_DIVIDE_BY_ZERO** * **BCL_ERROR_FATAL_ALLOC_ERR** +**BclNumber bcl_pow_keep(BclNumber** _a_**, BclNumber** _b_**)** + +: Calculates *a* to the power of *b* to the *scale* of the current context. + *b* must be an integer, but can be negative. If it is negative, *a* must + be non-zero. + + *b* must be an integer. If *b* is negative, *a* must not be **0**. + + *a* must be smaller than **BC_OVERFLOW_MAX**. See the **LIMITS** section. + + *a* and *b* can be the same number. + + bcl(3) will encode an error in the return value, if there was one. The error + can be queried with **bcl_err(BclNumber)**. Possible errors include: + + * **BCL_ERROR_INVALID_NUM** + * **BCL_ERROR_INVALID_CONTEXT** + * **BCL_ERROR_MATH_NON_INTEGER** + * **BCL_ERROR_MATH_OVERFLOW** + * **BCL_ERROR_MATH_DIVIDE_BY_ZERO** + * **BCL_ERROR_FATAL_ALLOC_ERR** + **BclNumber bcl_lshift(BclNumber** _a_**, BclNumber** _b_**)** : Shifts *a* left (moves the radix right) by *b* places and returns the @@ -701,6 +909,23 @@ All procedures in this section can return the following errors: * **BCL_ERROR_MATH_NON_INTEGER** * **BCL_ERROR_FATAL_ALLOC_ERR** +**BclNumber bcl_lshift_keep(BclNumber** _a_**, BclNumber** _b_**)** + +: Shifts *a* left (moves the radix right) by *b* places and returns the + result. This is done in decimal. *b* must be an integer. + + *b* must be an integer. + + *a* and *b* can be the same number. + + bcl(3) will encode an error in the return value, if there was one. The error + can be queried with **bcl_err(BclNumber)**. Possible errors include: + + * **BCL_ERROR_INVALID_NUM** + * **BCL_ERROR_INVALID_CONTEXT** + * **BCL_ERROR_MATH_NON_INTEGER** + * **BCL_ERROR_FATAL_ALLOC_ERR** + **BclNumber bcl_rshift(BclNumber** _a_**, BclNumber** _b_**)** : Shifts *a* right (moves the radix left) by *b* places and returns the @@ -721,6 +946,23 @@ All procedures in this section can return the following errors: * **BCL_ERROR_MATH_NON_INTEGER** * **BCL_ERROR_FATAL_ALLOC_ERR** +**BclNumber bcl_rshift_keep(BclNumber** _a_**, BclNumber** _b_**)** + +: Shifts *a* right (moves the radix left) by *b* places and returns the + result. This is done in decimal. *b* must be an integer. + + *b* must be an integer. + + *a* and *b* can be the same number. + + bcl(3) will encode an error in the return value, if there was one. The error + can be queried with **bcl_err(BclNumber)**. Possible errors include: + + * **BCL_ERROR_INVALID_NUM** + * **BCL_ERROR_INVALID_CONTEXT** + * **BCL_ERROR_MATH_NON_INTEGER** + * **BCL_ERROR_FATAL_ALLOC_ERR** + **BclNumber bcl_sqrt(BclNumber** _a_**)** : Calculates the square root of *a* and returns the result. The *scale* of the @@ -739,6 +981,21 @@ All procedures in this section can return the following errors: * **BCL_ERROR_MATH_NEGATIVE** * **BCL_ERROR_FATAL_ALLOC_ERR** +**BclNumber bcl_sqrt_keep(BclNumber** _a_**)** + +: Calculates the square root of *a* and returns the result. The *scale* of the + result is equal to the **scale** of the current context. + + *a* cannot be negative. + + bcl(3) will encode an error in the return value, if there was one. The error + can be queried with **bcl_err(BclNumber)**. Possible errors include: + + * **BCL_ERROR_INVALID_NUM** + * **BCL_ERROR_INVALID_CONTEXT** + * **BCL_ERROR_MATH_NEGATIVE** + * **BCL_ERROR_FATAL_ALLOC_ERR** + **BclError bcl_divmod(BclNumber** _a_**, BclNumber** _b_**, BclNumber \***_c_**, BclNumber \***_d_**)** : Divides *a* by *b* and returns the quotient in a new number which is put @@ -761,6 +1018,25 @@ All procedures in this section can return the following errors: * **BCL_ERROR_MATH_DIVIDE_BY_ZERO** * **BCL_ERROR_FATAL_ALLOC_ERR** +**BclError bcl_divmod_keep(BclNumber** _a_**, BclNumber** _b_**, BclNumber \***_c_**, BclNumber \***_d_**)** + +: Divides *a* by *b* and returns the quotient in a new number which is put + into the space pointed to by *c*, and puts the modulus in a new number which + is put into the space pointed to by *d*. + + *b* cannot be **0**. + + *c* and *d* cannot point to the same place, nor can they point to the space + occupied by *a* or *b*. + + If there was no error, **BCL_ERROR_NONE** is returned. Otherwise, this + function can return: + + * **BCL_ERROR_INVALID_NUM** + * **BCL_ERROR_INVALID_CONTEXT** + * **BCL_ERROR_MATH_DIVIDE_BY_ZERO** + * **BCL_ERROR_FATAL_ALLOC_ERR** + **BclNumber bcl_modexp(BclNumber** _a_**, BclNumber** _b_**, BclNumber** _c_**)** : Computes a modular exponentiation where *a* is the base, *b* is the @@ -783,6 +1059,25 @@ All procedures in this section can return the following errors: * **BCL_ERROR_MATH_DIVIDE_BY_ZERO** * **BCL_ERROR_FATAL_ALLOC_ERR** +**BclNumber bcl_modexp_keep(BclNumber** _a_**, BclNumber** _b_**, BclNumber** _c_**)** + +: Computes a modular exponentiation where *a* is the base, *b* is the + exponent, and *c* is the modulus, and returns the result. The *scale* of the + result is equal to the **scale** of the current context. + + *a*, *b*, and *c* must be integers. *c* must not be **0**. *b* must not be + negative. + + bcl(3) will encode an error in the return value, if there was one. The error + can be queried with **bcl_err(BclNumber)**. Possible errors include: + + * **BCL_ERROR_INVALID_NUM** + * **BCL_ERROR_INVALID_CONTEXT** + * **BCL_ERROR_MATH_NEGATIVE** + * **BCL_ERROR_MATH_NON_INTEGER** + * **BCL_ERROR_MATH_DIVIDE_BY_ZERO** + * **BCL_ERROR_FATAL_ALLOC_ERR** + ## Miscellaneous **void bcl_zero(BclNumber** _n_**)** @@ -839,6 +1134,10 @@ If necessary, the PRNG can be reseeded with one of the following functions: * **bcl_rand_seed(unsigned char[**_BCL_SEED_SIZE_**])** * **bcl_rand_reseed(**_void_**)** +All procedures in this section without the **_keep** suffix in their name +consume the given **BclNumber** arguments that are not given to pointer +arguments. See the **Consumption and Propagation** subsection below. + The following items allow clients to use the pseudo-random number generator. All procedures require a valid current context. @@ -869,8 +1168,29 @@ procedures require a valid current context. *a* must be an integer and non-negative. - *a* is consumed; it cannot be used after the call. See the - **Consumption and Propagation** subsection below. + *a* is consumed; it cannot be used after the call. See the **Consumption and + Propagation** subsection below. + + This procedure requires a valid current context. + + bcl(3) will encode an error in the return value, if there was one. The error + can be queried with **bcl_err(BclNumber)**. Possible errors include: + + * **BCL_ERROR_INVALID_NUM** + * **BCL_ERROR_INVALID_CONTEXT** + * **BCL_ERROR_MATH_NEGATIVE** + * **BCL_ERROR_MATH_NON_INTEGER** + * **BCL_ERROR_FATAL_ALLOC_ERR** + +**BclNumber bcl_irand_keep(BclNumber** _a_**)** + +: Returns a random number that is not larger than *a* in a new number. If *a* + is **0** or **1**, the new number is equal to **0**. The bound is unlimited, + so it is not bound to the size of **BclRandInt**. This is done by generating + as many random numbers as necessary, multiplying them by certain exponents, + and adding them all together. + + *a* must be an integer and non-negative. This procedure requires a valid current context. @@ -904,8 +1224,26 @@ procedures require a valid current context. *a* must be an integer and non-negative. - *a* is consumed; it cannot be used after the call. See the - **Consumption and Propagation** subsection below. + *a* is consumed; it cannot be used after the call. See the **Consumption and + Propagation** subsection below. + + This procedure requires a valid current context. + + bcl(3) will encode an error in the return value, if there was one. The error + can be queried with **bcl_err(BclNumber)**. Possible errors include: + + * **BCL_ERROR_INVALID_NUM** + * **BCL_ERROR_INVALID_CONTEXT** + * **BCL_ERROR_MATH_NEGATIVE** + * **BCL_ERROR_MATH_NON_INTEGER** + * **BCL_ERROR_FATAL_ALLOC_ERR** + +**BclNumber bcl_ifrand_keep(BclNumber** _a_**, size_t** _places_**)** + +: Returns a random number less than *a* with *places* decimal digits after the + radix (decimal point). There are no limits on *a* or *places*. + + *a* must be an integer and non-negative. This procedure requires a valid current context. @@ -922,7 +1260,23 @@ procedures require a valid current context. : Seeds the PRNG with *n*. - *n* is *not* consumed. + *n* is consumed. + + This procedure requires a valid current context. + + If there was no error, **BCL_ERROR_NONE** is returned. Otherwise, this + function can return: + + * **BCL_ERROR_INVALID_NUM** + * **BCL_ERROR_INVALID_CONTEXT** + + Note that if **bcl_rand_seed2num(**_void_**)** or + **bcl_rand_seed2num_err(BclNumber)** are called right after this function, + they are not guaranteed to return a number equal to *n*. + +**BclError bcl_rand_seedWithNum_keep(BclNumber** _n_**)** + +: Seeds the PRNG with *n*. This procedure requires a valid current context. @@ -994,7 +1348,7 @@ checked with **bcl_err(BclNumber)**, so the example above should properly be: BclNumber n = bcl_num_add(bcl_num_mul(a, b), bcl_num_div(c, d)); - if (bc_num_err(n) != BCL_ERROR_NONE) { + if (bcl_err(n) != BCL_ERROR_NONE) { // Handle the error. } @@ -1015,10 +1369,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 +1438,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 +1516,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) @@ -1195,8 +1532,8 @@ use a period (**.**) as a radix point, regardless of the value of # BUGS -None are known. Report bugs at https://git.yzena.com/gavin/bc. +None are known. Report bugs at https://git.gavinhoward.com/gavin/bc. # AUTHORS -Gavin D. Howard <gavin@yzena.com> and contributors. +Gavin D. Howard <gavin@gavinhoward.com> and contributors. diff --git a/contrib/bc/manuals/build.md b/contrib/bc/manuals/build.md index af0b7c15e0c3..d9c46ae22602 100644 --- a/contrib/bc/manuals/build.md +++ b/contrib/bc/manuals/build.md @@ -40,7 +40,7 @@ accepted build options. ## Windows For releases, Windows builds of `bc`, `dc`, and `bcl` are available for download -from <https://git.yzena.com/gavin/bc> and GitHub. +from <https://git.gavinhoward.com/gavin/bc> and GitHub. However, if you wish to build it yourself, this `bc` can be built using Visual Studio or MSBuild. @@ -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/ diff --git a/contrib/bc/manuals/dc/A.1 b/contrib/bc/manuals/dc/A.1 index cc1ad0e7bb75..d59e0fa68a58 100644 --- a/contrib/bc/manuals/dc/A.1 +++ b/contrib/bc/manuals/dc/A.1 @@ -1,7 +1,7 @@ .\" .\" SPDX-License-Identifier: BSD-2-Clause .\" -.\" Copyright (c) 2018-2021 Gavin D. Howard and contributors. +.\" Copyright (c) 2018-2024 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,128 +25,97 @@ .\" 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" "August 2024" "Gavin D. Howard" "General Commands Manual" .nh .ad l .SH Name -.PP -dc - arbitrary-precision decimal reverse-Polish notation calculator +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. +dc(1) is an arbitrary\-precision calculator. It uses a stack (reverse Polish notation) to store numbers and results of computations. Arithmetic operations pop arguments off of the stack and push the results. .PP -If no files are given on the command-line, then dc(1) reads from +If no files are given on the command\-line, then dc(1) reads from \f[B]stdin\f[R] (see the \f[B]STDIN\f[R] section). Otherwise, those files are processed, and dc(1) will then exit. .PP If a user wants to set up a standard environment, they can use \f[B]DC_ENV_ARGS\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). For example, if a user wants the \f[B]scale\f[R] always set to -\f[B]10\f[R], they can set \f[B]DC_ENV_ARGS\f[R] to \f[B]-e 10k\f[R], +\f[B]10\f[R], they can set \f[B]DC_ENV_ARGS\f[R] to \f[B]\-e 10k\f[R], and this dc(1) will always start with a \f[B]scale\f[R] of \f[B]10\f[R]. .SH OPTIONS -.PP The following are the options that dc(1) accepts. .TP -\f[B]-h\f[R], \f[B]--help\f[R] -Prints a usage message and quits. -.TP -\f[B]-v\f[R], \f[B]-V\f[R], \f[B]--version\f[R] -Print the version information (copyright header) and exit. -.TP -\f[B]-i\f[R], \f[B]--interactive\f[R] -Forces interactive mode. -(See the \f[B]INTERACTIVE MODE\f[R] section.) +\f[B]\-C\f[R], \f[B]\-\-no\-digit\-clamp\f[R] +Disables clamping of digits greater than or equal to the current +\f[B]ibase\f[R] when parsing numbers. .RS .PP -This is a \f[B]non-portable extension\f[R]. -.RE -.TP -\f[B]-L\f[R], \f[B]--no-line-length\f[R] -Disables line length checking and prints numbers without backslashes and -newlines. -In other words, this option sets \f[B]BC_LINE_LENGTH\f[R] to \f[B]0\f[R] -(see the \f[B]ENVIRONMENT VARIABLES\f[R] section). -.RS +This means that the value added to a number from a digit is always that +digit\[cq]s value multiplied by the value of ibase raised to the power +of the digit\[cq]s position, which starts from 0 at the least +significant digit. .PP -This is a \f[B]non-portable extension\f[R]. -.RE -.TP -\f[B]-P\f[R], \f[B]--no-prompt\f[R] -Disables the prompt in TTY mode. -(The prompt is only enabled in TTY mode. -See the \f[B]TTY MODE\f[R] section.) This is mostly for those users that -do not want a prompt or are not used to having them in dc(1). -Most of those users would want to put this option in -\f[B]DC_ENV_ARGS\f[R]. -.RS +If this and/or the \f[B]\-c\f[R] or \f[B]\-\-digit\-clamp\f[R] options +are given multiple times, the last one given is used. .PP -These options override the \f[B]DC_PROMPT\f[R] and \f[B]DC_TTY_MODE\f[R] -environment variables (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). +This option overrides the \f[B]DC_DIGIT_CLAMP\f[R] environment variable +(see the \f[B]ENVIRONMENT VARIABLES\f[R] section) and the default, which +can be queried with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-R\f[R], \f[B]--no-read-prompt\f[R] -Disables the read prompt in TTY mode. -(The read prompt is only enabled in TTY mode. -See the \f[B]TTY MODE\f[R] section.) This is mostly for those users that -do not want a read prompt or are not used to having them in dc(1). -Most of those users would want to put this option in -\f[B]BC_ENV_ARGS\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). -This option is also useful in hash bang lines of dc(1) scripts that -prompt for user input. +\f[B]\-c\f[R], \f[B]\-\-digit\-clamp\f[R] +Enables clamping of digits greater than or equal to the current +\f[B]ibase\f[R] when parsing numbers. .RS .PP -This option does not disable the regular prompt because the read prompt -is only used when the \f[B]?\f[R] command is used. +This means that digits that the value added to a number from a digit +that is greater than or equal to the ibase is the value of ibase minus 1 +all multiplied by the value of ibase raised to the power of the +digit\[cq]s position, which starts from 0 at the least significant +digit. .PP -These options \f[I]do\f[R] override the \f[B]DC_PROMPT\f[R] and -\f[B]DC_TTY_MODE\f[R] environment variables (see the \f[B]ENVIRONMENT -VARIABLES\f[R] section), but only for the read prompt. +If this and/or the \f[B]\-C\f[R] or \f[B]\-\-no\-digit\-clamp\f[R] +options are given multiple times, the last one given is used. .PP -This is a \f[B]non-portable extension\f[R]. -.RE -.TP -\f[B]-x\f[R] \f[B]--extended-register\f[R] -Enables extended register mode. -See the \f[I]Extended Register Mode\f[R] subsection of the -\f[B]REGISTERS\f[R] section for more information. -.RS +This option overrides the \f[B]DC_DIGIT_CLAMP\f[R] environment variable +(see the \f[B]ENVIRONMENT VARIABLES\f[R] section) and the default, which +can be queried with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-z\f[R], \f[B]--leading-zeroes\f[R] -Makes dc(1) print all numbers greater than \f[B]-1\f[R] and less than -\f[B]1\f[R], and not equal to \f[B]0\f[R], with a leading zero. +\f[B]\-E\f[R] \f[I]seed\f[R], \f[B]\-\-seed\f[R]=\f[I]seed\f[R] +Sets the builtin variable \f[B]seed\f[R] to the value \f[I]seed\f[R] +assuming that \f[I]seed\f[R] is in base 10. +It is a fatal error if \f[I]seed\f[R] is not a valid number. .RS .PP -This can be set for individual numbers with the \f[B]plz(x)\f[R], -plznl(x)**, \f[B]pnlz(x)\f[R], and \f[B]pnlznl(x)\f[R] functions in the -extended math library (see the \f[B]LIBRARY\f[R] section). +If multiple instances of this option are given, the last is used. .PP -This is a \f[B]non-portable extension\f[R]. +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] +\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 @@ -155,41 +124,44 @@ 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 +If this option is given on the command\-line (i.e., not in \f[B]DC_ENV_ARGS\f[R], see the \f[B]ENVIRONMENT VARIABLES\f[R] section), then after processing all expressions and files, dc(1) will exit, unless -\f[B]-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to -\f[B]-f\f[R] or \f[B]--file\f[R], whether on the command-line or in +\f[B]\-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to +\f[B]\-f\f[R] or \f[B]\-\-file\f[R], whether on the command\-line or in \f[B]DC_ENV_ARGS\f[R]. -However, if any other \f[B]-e\f[R], \f[B]--expression\f[R], -\f[B]-f\f[R], or \f[B]--file\f[R] arguments are given after -\f[B]-f-\f[R] or equivalent is given, dc(1) will give a fatal error and -exit. +However, if any other \f[B]\-e\f[R], \f[B]\-\-expression\f[R], +\f[B]\-f\f[R], or \f[B]\-\-file\f[R] arguments are given after +\f[B]\-f\-\f[R] or equivalent is given, dc(1) will give a fatal error +and exit. .PP -This is a \f[B]non-portable extension\f[R]. +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] +\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 +If this option is given on the command\-line (i.e., not in \f[B]DC_ENV_ARGS\f[R], see the \f[B]ENVIRONMENT VARIABLES\f[R] section), then after processing all expressions and files, dc(1) will exit, unless -\f[B]-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to -\f[B]-f\f[R] or \f[B]--file\f[R]. -However, if any other \f[B]-e\f[R], \f[B]--expression\f[R], -\f[B]-f\f[R], or \f[B]--file\f[R] arguments are given after -\f[B]-f-\f[R] or equivalent is given, dc(1) will give a fatal error and -exit. +\f[B]\-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to +\f[B]\-f\f[R] or \f[B]\-\-file\f[R]. +However, if any other \f[B]\-e\f[R], \f[B]\-\-expression\f[R], +\f[B]\-f\f[R], or \f[B]\-\-file\f[R] arguments are given after +\f[B]\-f\-\f[R] or equivalent is given, dc(1) will give a fatal error +and exit. .PP -This is a \f[B]non-portable extension\f[R]. +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] +\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. It is a fatal error if \f[I]ibase\f[R] is not a valid number. @@ -197,10 +169,28 @@ It is a fatal error if \f[I]ibase\f[R] is not a valid number. .PP If multiple instances of this option are given, the last is used. .PP -This is a \f[B]non-portable extension\f[R]. +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] +\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. @@ -208,10 +198,48 @@ It is a fatal error if \f[I]obase\f[R] is not a valid number. .PP If multiple instances of this option are given, the last is used. .PP -This is a \f[B]non-portable extension\f[R]. +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] +\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. It is a fatal error if \f[I]scale\f[R] is not a valid number. @@ -219,26 +247,34 @@ It is a fatal error if \f[I]scale\f[R] is not a valid number. .PP If multiple instances of this option are given, the last is used. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-E\f[R] \f[I]seed\f[R], \f[B]--seed\f[R]=\f[I]seed\f[R] -Sets the builtin variable \f[B]seed\f[R] to the value \f[I]seed\f[R] -assuming that \f[I]seed\f[R] is in base 10. -It is a fatal error if \f[I]seed\f[R] is not a valid number. +\f[B]\-v\f[R], \f[B]\-V\f[R], \f[B]\-\-version\f[R] +Print the version information (copyright header) and exits. +.TP +\f[B]\-x\f[R] \f[B]\-\-extended\-register\f[R] +Enables extended register mode. +See the \f[I]Extended Register Mode\f[R] subsection of the +\f[B]REGISTERS\f[R] section for more information. .RS .PP -If multiple instances of this option are given, the last is used. +This is a \f[B]non\-portable extension\f[R]. +.RE +.TP +\f[B]\-z\f[R], \f[B]\-\-leading\-zeroes\f[R] +Makes dc(1) print all numbers greater than \f[B]\-1\f[R] and less than +\f[B]1\f[R], and not equal to \f[B]0\f[R], with a leading zero. +.RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .PP -All long options are \f[B]non-portable extensions\f[R]. +All long options are \f[B]non\-portable extensions\f[R]. .SH STDIN -.PP -If no files are given on the command-line and no files or expressions -are given by the \f[B]-f\f[R], \f[B]--file\f[R], \f[B]-e\f[R], or -\f[B]--expression\f[R] options, then dc(1) reads from \f[B]stdin\f[R]. +If no files are given on the command\-line and no files or expressions +are given by the \f[B]\-f\f[R], \f[B]\-\-file\f[R], \f[B]\-e\f[R], or +\f[B]\-\-expression\f[R] options, then dc(1) reads from \f[B]stdin\f[R]. .PP However, there is a caveat to this. .PP @@ -248,8 +284,7 @@ ended. This means that, except for escaped brackets, all brackets must be balanced before dc(1) parses and executes. .SH STDOUT -.PP -Any non-error output is written to \f[B]stdout\f[R]. +Any non\-error output is written to \f[B]stdout\f[R]. In addition, if history (see the \f[B]HISTORY\f[R] section) and the prompt (see the \f[B]TTY MODE\f[R] section) are enabled, both are output to \f[B]stdout\f[R]. @@ -257,7 +292,7 @@ to \f[B]stdout\f[R]. \f[B]Note\f[R]: Unlike other dc(1) implementations, this dc(1) will issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot write to \f[B]stdout\f[R], so if \f[B]stdout\f[R] is closed, as in -\f[B]dc >&-\f[R], it will quit with an error. +\f[B]dc >&\-\f[R], it will quit with an error. This is done so that dc(1) can report problems when \f[B]stdout\f[R] is redirected to a file. .PP @@ -265,13 +300,12 @@ If there are scripts that depend on the behavior of other dc(1) implementations, it is recommended that those scripts be changed to redirect \f[B]stdout\f[R] to \f[B]/dev/null\f[R]. .SH STDERR -.PP Any error output is written to \f[B]stderr\f[R]. .PP \f[B]Note\f[R]: Unlike other dc(1) implementations, this dc(1) will issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot write to \f[B]stderr\f[R], so if \f[B]stderr\f[R] is closed, as in -\f[B]dc 2>&-\f[R], it will quit with an error. +\f[B]dc 2>&\-\f[R], it will quit with an error. This is done so that dc(1) can exit with an error code when \f[B]stderr\f[R] is redirected to a file. .PP @@ -279,7 +313,6 @@ If there are scripts that depend on the behavior of other dc(1) implementations, it is recommended that those scripts be changed to redirect \f[B]stderr\f[R] to \f[B]/dev/null\f[R]. .SH SYNTAX -.PP Each item in the input source code, either a number (see the \f[B]NUMBERS\f[R] section) or a command (see the \f[B]COMMANDS\f[R] section), is processed and executed, in order. @@ -308,8 +341,8 @@ notation, and if \f[B]obase\f[R] is \f[B]1\f[R], values are output in engineering notation. Otherwise, values are output in the specified base. .PP -Outputting in scientific and engineering notations are \f[B]non-portable -extensions\f[R]. +Outputting in scientific and engineering notations are +\f[B]non\-portable extensions\f[R]. .PP The \f[I]scale\f[R] of an expression is the number of digits in the result of the expression right of the decimal point, and \f[B]scale\f[R] @@ -321,14 +354,14 @@ The max allowable value for \f[B]scale\f[R] can be queried in dc(1) programs with the \f[B]V\f[R] command. .PP \f[B]seed\f[R] is a register containing the current seed for the -pseudo-random number generator. +pseudo\-random number generator. If the current value of \f[B]seed\f[R] is queried and stored, then if it -is assigned to \f[B]seed\f[R] later, the pseudo-random number generator -is guaranteed to produce the same sequence of pseudo-random numbers that -were generated after the value of \f[B]seed\f[R] was first queried. +is assigned to \f[B]seed\f[R] later, the pseudo\-random number generator +is guaranteed to produce the same sequence of pseudo\-random numbers +that were generated after the value of \f[B]seed\f[R] was first queried. .PP Multiple values assigned to \f[B]seed\f[R] can produce the same sequence -of pseudo-random numbers. +of pseudo\-random numbers. Likewise, when a value is assigned to \f[B]seed\f[R], it is not guaranteed that querying \f[B]seed\f[R] immediately after will return the same value. @@ -338,39 +371,68 @@ get receive a value of \f[B]0\f[R] or \f[B]1\f[R]. The maximum integer returned by the \f[B]\[cq]\f[R] command can be queried with the \f[B]W\f[R] command. .PP -\f[B]Note\f[R]: The values returned by the pseudo-random number +\f[B]Note\f[R]: The values returned by the pseudo\-random number generator with the \f[B]\[cq]\f[R] and \f[B]\[lq]\f[R] commands are guaranteed to \f[B]NOT\f[R] be cryptographically secure. -This is a consequence of using a seeded pseudo-random number generator. +This is a consequence of using a seeded pseudo\-random number generator. However, they \f[I]are\f[R] guaranteed to be reproducible with identical \f[B]seed\f[R] values. -This means that the pseudo-random values from dc(1) should only be used -where a reproducible stream of pseudo-random numbers is +This means that the pseudo\-random values from dc(1) should only be used +where a reproducible stream of pseudo\-random numbers is \f[I]ESSENTIAL\f[R]. -In any other case, use a non-seeded pseudo-random number generator. +In any other case, use a non\-seeded pseudo\-random number generator. .PP -The pseudo-random number generator, \f[B]seed\f[R], and all associated -operations are \f[B]non-portable extensions\f[R]. +The pseudo\-random number generator, \f[B]seed\f[R], and all associated +operations are \f[B]non\-portable extensions\f[R]. .SS Comments -.PP Comments go from \f[B]#\f[R] until, and not including, the next newline. -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .SH NUMBERS -.PP Numbers are strings made up of digits, uppercase letters up to \f[B]F\f[R], and at most \f[B]1\f[R] period for a radix. Numbers can have up to \f[B]DC_NUM_MAX\f[R] digits. -Uppercase letters are equal to \f[B]9\f[R] + their position in the +Uppercase letters are equal to \f[B]9\f[R] plus their position in the alphabet (i.e., \f[B]A\f[R] equals \f[B]10\f[R], or \f[B]9+1\f[R]). -If a digit or letter makes no sense with the current value of -\f[B]ibase\f[R], they are set to the value of the highest valid digit in -\f[B]ibase\f[R]. .PP -Single-character numbers (i.e., \f[B]A\f[R] alone) take the value that -they would have if they were valid digits, regardless of the value of -\f[B]ibase\f[R]. +If a digit or letter makes no sense with the current value of +\f[B]ibase\f[R] (i.e., they are greater than or equal to the current +value of \f[B]ibase\f[R]), then the behavior depends on the existence of +the \f[B]\-c\f[R]/\f[B]\-\-digit\-clamp\f[R] or +\f[B]\-C\f[R]/\f[B]\-\-no\-digit\-clamp\f[R] options (see the +\f[B]OPTIONS\f[R] section), the existence and setting of the +\f[B]DC_DIGIT_CLAMP\f[R] environment variable (see the \f[B]ENVIRONMENT +VARIABLES\f[R] section), or the default, which can be queried with the +\f[B]\-h\f[R]/\f[B]\-\-help\f[R] option. +.PP +If clamping is off, then digits or letters that are greater than or +equal to the current value of \f[B]ibase\f[R] are not changed. +Instead, their given value is multiplied by the appropriate power of +\f[B]ibase\f[R] and added into the number. +This means that, with an \f[B]ibase\f[R] of \f[B]3\f[R], the number +\f[B]AB\f[R] is equal to \f[B]3\[ha]1*A+3\[ha]0*B\f[R], which is +\f[B]3\f[R] times \f[B]10\f[R] plus \f[B]11\f[R], or \f[B]41\f[R]. +.PP +If clamping is on, then digits or letters that are greater than or equal +to the current value of \f[B]ibase\f[R] are set to the value of the +highest valid digit in \f[B]ibase\f[R] before being multiplied by the +appropriate power of \f[B]ibase\f[R] and added into the number. +This means that, with an \f[B]ibase\f[R] of \f[B]3\f[R], the number +\f[B]AB\f[R] is equal to \f[B]3\[ha]1*2+3\[ha]0*2\f[R], which is +\f[B]3\f[R] times \f[B]2\f[R] plus \f[B]2\f[R], or \f[B]8\f[R]. +.PP +There is one exception to clamping: single\-character numbers (i.e., +\f[B]A\f[R] alone). +Such numbers are never clamped and always take the value they would have +in the highest possible \f[B]ibase\f[R]. This means that \f[B]A\f[R] alone always equals decimal \f[B]10\f[R] and -\f[B]F\f[R] alone always equals decimal \f[B]15\f[R]. +\f[B]Z\f[R] alone always equals decimal \f[B]35\f[R]. +This behavior is mandated by the standard for bc(1) (see the STANDARDS +section) and is meant to provide an easy way to set the current +\f[B]ibase\f[R] (with the \f[B]i\f[R] command) regardless of the current +value of \f[B]ibase\f[R]. +.PP +If clamping is on, and the clamped value of a character is needed, use a +leading zero, i.e., for \f[B]A\f[R], use \f[B]0A\f[R]. .PP In addition, dc(1) accepts numbers in scientific notation. These have the form \f[B]<number>e<integer>\f[R]. @@ -389,13 +451,11 @@ number string \f[B]FFeA\f[R], the resulting decimal number will be \f[B]2550000000000\f[R], and if dc(1) is given the number string \f[B]10e_4\f[R], the resulting decimal number will be \f[B]0.0016\f[R]. .PP -Accepting input as scientific notation is a \f[B]non-portable +Accepting input as scientific notation is a \f[B]non\-portable extension\f[R]. .SH COMMANDS -.PP The valid commands are listed below. .SS Printing -.PP These commands are used for printing. .PP Note that both scientific notation and engineering notation are @@ -407,7 +467,7 @@ activated by assigning \f[B]1\f[R] to \f[B]obase\f[R] using To deactivate them, just assign a different value to \f[B]obase\f[R]. .PP Printing numbers in scientific notation and/or engineering notation is a -\f[B]non-portable extension\f[R]. +\f[B]non\-portable extension\f[R]. .TP \f[B]p\f[R] Prints the value on top of the stack, whether number or string, and @@ -427,12 +487,12 @@ Pops a value off the stack. .PP If the value is a number, it is truncated and the absolute value of the result is printed as though \f[B]obase\f[R] is \f[B]256\f[R] and each -digit is interpreted as an 8-bit ASCII character, making it a byte +digit is interpreted as an 8\-bit ASCII character, making it a byte stream. .PP If the value is a string, it is printed without a trailing newline. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]f\f[R] @@ -443,7 +503,6 @@ without altering anything. Users should use this command when they get lost. .RE .SS Arithmetic -.PP These are the commands used for arithmetic. .TP \f[B]+\f[R] @@ -452,7 +511,7 @@ pushed onto the stack. The \f[I]scale\f[R] of the result is equal to the max \f[I]scale\f[R] of both operands. .TP -\f[B]-\f[R] +\f[B]\-\f[R] The top two values are popped off the stack, subtracted, and the result is pushed onto the stack. The \f[I]scale\f[R] of the result is equal to the max \f[I]scale\f[R] of @@ -473,7 +532,7 @@ pushed onto the stack. The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R]. .RS .PP -The first value popped off of the stack must be non-zero. +The first value popped off of the stack must be non\-zero. .RE .TP \f[B]%\f[R] @@ -483,10 +542,10 @@ is pushed onto the stack. .PP Remaindering is equivalent to 1) Computing \f[B]a/b\f[R] to current \f[B]scale\f[R], and 2) Using the result of step 1 to calculate -\f[B]a-(a/b)*b\f[R] to \f[I]scale\f[R] +\f[B]a\-(a/b)*b\f[R] to \f[I]scale\f[R] \f[B]max(scale+scale(b),scale(a))\f[R]. .PP -The first value popped off of the stack must be non-zero. +The first value popped off of the stack must be non\-zero. .RE .TP \f[B]\[ti]\f[R] @@ -497,9 +556,9 @@ This is equivalent to \f[B]x y / x y %\f[R] except that \f[B]x\f[R] and \f[B]y\f[R] are only evaluated once. .RS .PP -The first value popped off of the stack must be non-zero. +The first value popped off of the stack must be non\-zero. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]\[ha]\f[R] @@ -510,7 +569,7 @@ The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R]. .PP The first value popped off of the stack must be an integer, and if that value is negative, the second value popped off of the stack must be -non-zero. +non\-zero. .RE .TP \f[B]v\f[R] @@ -519,7 +578,7 @@ the result is pushed onto the stack. The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R]. .RS .PP -The value popped off of the stack must be non-negative. +The value popped off of the stack must be non\-negative. .RE .TP \f[B]_\f[R] @@ -529,7 +588,7 @@ or other commands), then that number is input as a negative number. .PP Otherwise, the top value on the stack is popped and copied, and the copy is negated and pushed onto the stack. -This behavior without a number is a \f[B]non-portable extension\f[R]. +This behavior without a number is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]b\f[R] @@ -538,7 +597,7 @@ back onto the stack. Otherwise, its absolute value is pushed onto the stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]|\f[R] @@ -547,12 +606,12 @@ is computed, and the result is pushed onto the stack. .RS .PP The first value popped is used as the reduction modulus and must be an -integer and non-zero. +integer and non\-zero. The second value popped is used as the exponent and must be an integer -and non-negative. +and non\-negative. The third value popped is the base and must be an integer. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]$\f[R] @@ -560,7 +619,7 @@ The top value is popped off the stack and copied, and the copy is truncated and pushed onto the stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]\[at]\f[R] @@ -570,9 +629,9 @@ extension. .RS .PP The first value popped off of the stack must be an integer and -non-negative. +non\-negative. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]H\f[R] @@ -581,9 +640,9 @@ left (radix shifted right) to the value of the first. .RS .PP The first value popped off of the stack must be an integer and -non-negative. +non\-negative. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]h\f[R] @@ -592,9 +651,9 @@ right (radix shifted left) to the value of the first. .RS .PP The first value popped off of the stack must be an integer and -non-negative. +non\-negative. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]G\f[R] @@ -602,7 +661,7 @@ The top two values are popped off of the stack, they are compared, and a \f[B]1\f[R] is pushed if they are equal, or \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]N\f[R] @@ -610,7 +669,7 @@ The top value is popped off of the stack, and if it a \f[B]0\f[R], a \f[B]1\f[R] is pushed; otherwise, a \f[B]0\f[R] is pushed. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B](\f[R] @@ -619,7 +678,7 @@ The top two values are popped off of the stack, they are compared, and a \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]{\f[R] @@ -628,7 +687,7 @@ The top two values are popped off of the stack, they are compared, and a or \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B])\f[R] @@ -637,7 +696,7 @@ The top two values are popped off of the stack, they are compared, and a \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]}\f[R] @@ -646,42 +705,41 @@ The top two values are popped off of the stack, they are compared, and a second, or \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]M\f[R] The top two values are popped off of the stack. -If they are both non-zero, a \f[B]1\f[R] is pushed onto the stack. +If they are both non\-zero, a \f[B]1\f[R] is pushed onto the stack. If either of them is zero, or both of them are, then a \f[B]0\f[R] is pushed onto the stack. .RS .PP This is like the \f[B]&&\f[R] operator in bc(1), and it is \f[I]not\f[R] -a short-circuit operator. +a short\-circuit operator. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]m\f[R] The top two values are popped off of the stack. -If at least one of them is non-zero, a \f[B]1\f[R] is pushed onto the +If at least one of them is non\-zero, a \f[B]1\f[R] is pushed onto the stack. If both of them are zero, then a \f[B]0\f[R] is pushed onto the stack. .RS .PP This is like the \f[B]||\f[R] operator in bc(1), and it is \f[I]not\f[R] -a short-circuit operator. +a short\-circuit operator. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE -.SS Pseudo-Random Number Generator -.PP -dc(1) has a built-in pseudo-random number generator. -These commands query the pseudo-random number generator. +.SS Pseudo\-Random Number Generator +dc(1) has a built\-in pseudo\-random number generator. +These commands query the pseudo\-random number generator. (See Parameters for more information about the \f[B]seed\f[R] value that -controls the pseudo-random number generator.) +controls the pseudo\-random number generator.) .PP -The pseudo-random number generator is guaranteed to \f[B]NOT\f[R] be +The pseudo\-random number generator is guaranteed to \f[B]NOT\f[R] be cryptographically secure. .TP \f[B]\[cq]\f[R] @@ -690,19 +748,19 @@ the \f[B]LIMITS\f[R] section). .RS .PP The generated integer is made as unbiased as possible, subject to the -limitations of the pseudo-random number generator. +limitations of the pseudo\-random number generator. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]\[lq]\f[R] Pops a value off of the stack, which is used as an \f[B]exclusive\f[R] upper bound on the integer that will be generated. -If the bound is negative or is a non-integer, an error is raised, and +If the bound is negative or is a non\-integer, an error is raised, and dc(1) resets (see the \f[B]RESET\f[R] section) while \f[B]seed\f[R] remains unchanged. If the bound is larger than \f[B]DC_RAND_MAX\f[R], the higher bound is -honored by generating several pseudo-random integers, multiplying them +honored by generating several pseudo\-random integers, multiplying them by appropriate powers of \f[B]DC_RAND_MAX+1\f[R], and adding them together. Thus, the size of integer that can be generated with this command is @@ -714,12 +772,11 @@ is \f[I]not\f[R] changed. .RS .PP The generated integer is made as unbiased as possible, subject to the -limitations of the pseudo-random number generator. +limitations of the pseudo\-random number generator. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .SS Stack Control -.PP These commands control the stack. .TP \f[B]c\f[R] @@ -735,7 +792,6 @@ Swaps (\[lq]reverses\[rq]) the two top items on the stack. \f[B]R\f[R] Pops (\[lq]removes\[rq]) the top value from the stack. .SS Register Control -.PP These commands control registers (see the \f[B]REGISTERS\f[R] section). .TP \f[B]s\f[R]\f[I]r\f[R] @@ -757,7 +813,6 @@ push it onto the main stack. The previous value in the stack for register \f[I]r\f[R], if any, is now accessible via the \f[B]l\f[R]\f[I]r\f[R] command. .SS Parameters -.PP These commands control the values of \f[B]ibase\f[R], \f[B]obase\f[R], \f[B]scale\f[R], and \f[B]seed\f[R]. Also see the \f[B]SYNTAX\f[R] section. @@ -785,7 +840,7 @@ If the value on top of the stack has any \f[I]scale\f[R], the .TP \f[B]k\f[R] Pops the value off of the top of the stack and uses it to set -\f[B]scale\f[R], which must be non-negative. +\f[B]scale\f[R], which must be non\-negative. .RS .PP If the value on top of the stack has any \f[I]scale\f[R], the @@ -795,7 +850,7 @@ If the value on top of the stack has any \f[I]scale\f[R], the \f[B]j\f[R] Pops the value off of the top of the stack and uses it to set \f[B]seed\f[R]. -The meaning of \f[B]seed\f[R] is dependent on the current pseudo-random +The meaning of \f[B]seed\f[R] is dependent on the current pseudo\-random number generator but is guaranteed to not change except for new major versions. .RS @@ -803,22 +858,22 @@ versions. The \f[I]scale\f[R] and sign of the value may be significant. .PP If a previously used \f[B]seed\f[R] value is used again, the -pseudo-random number generator is guaranteed to produce the same -sequence of pseudo-random numbers as it did when the \f[B]seed\f[R] +pseudo\-random number generator is guaranteed to produce the same +sequence of pseudo\-random numbers as it did when the \f[B]seed\f[R] value was previously used. .PP The exact value assigned to \f[B]seed\f[R] is not guaranteed to be returned if the \f[B]J\f[R] command is used. However, if \f[B]seed\f[R] \f[I]does\f[R] return a different value, both values, when assigned to \f[B]seed\f[R], are guaranteed to produce the -same sequence of pseudo-random numbers. +same sequence of pseudo\-random numbers. This means that certain values assigned to \f[B]seed\f[R] will not -produce unique sequences of pseudo-random numbers. +produce unique sequences of pseudo\-random numbers. .PP There is no limit to the length (number of significant decimal digits) or \f[I]scale\f[R] of the value that can be assigned to \f[B]seed\f[R]. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]I\f[R] @@ -834,7 +889,7 @@ Pushes the current value of \f[B]scale\f[R] onto the main stack. Pushes the current value of \f[B]seed\f[R] onto the main stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]T\f[R] @@ -842,7 +897,7 @@ Pushes the maximum allowable value of \f[B]ibase\f[R] onto the main stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]U\f[R] @@ -850,7 +905,7 @@ Pushes the maximum allowable value of \f[B]obase\f[R] onto the main stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]V\f[R] @@ -858,18 +913,17 @@ Pushes the maximum allowable value of \f[B]scale\f[R] onto the main stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]W\f[R] Pushes the maximum (inclusive) integer that can be generated with the -\f[B]\[cq]\f[R] pseudo-random number generator command. +\f[B]\[cq]\f[R] pseudo\-random number generator command. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .SS Strings -.PP The following commands control strings. .PP dc(1) can work with both numbers and strings, and registers (see the @@ -907,16 +961,16 @@ The value on top of the stack is popped. If it is a number, it is truncated and its absolute value is taken. The result mod \f[B]256\f[R] is calculated. If that result is \f[B]0\f[R], push an empty string; otherwise, push a -one-character string where the character is the result of the mod +one\-character string where the character is the result of the mod interpreted as an ASCII character. .PP If it is a string, then a new string is made. If the original string is empty, the new string is empty. If it is not, then the first character of the original string is used to -create the new string as a one-character string. +create the new string as a one\-character string. The new string is then pushed onto the stack. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]x\f[R] @@ -952,7 +1006,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]!>\f[R]\f[I]r\f[R] @@ -973,7 +1027,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]<\f[R]\f[I]r\f[R] @@ -994,7 +1048,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]!<\f[R]\f[I]r\f[R] @@ -1015,7 +1069,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]=\f[R]\f[I]r\f[R] @@ -1036,7 +1090,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]!=\f[R]\f[I]r\f[R] @@ -1057,7 +1111,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]?\f[R] @@ -1070,7 +1124,7 @@ the execution of the macro that executed it. If there are no macros, or only one macro executing, dc(1) exits. .TP \f[B]Q\f[R] -Pops a value from the stack which must be non-negative and is used the +Pops a value from the stack which must be non\-negative and is used the number of macro executions to pop off of the execution stack. If the number of levels to pop is greater than the number of executing macros, dc(1) exits. @@ -1081,8 +1135,11 @@ The execution stack is the stack of string executions. The number that is pushed onto the stack is exactly as many as is needed to make dc(1) exit with the \f[B]Q\f[R] command, so the sequence \f[B],Q\f[R] will make dc(1) exit. -.SS Status +.RS .PP +This is a \f[B]non\-portable extension\f[R]. +.RE +.SS Status These commands query status of the stack or its top value. .TP \f[B]Z\f[R] @@ -1107,6 +1164,24 @@ stack. If it is a string, pushes \f[B]0\f[R]. .RE .TP +\f[B]u\f[R] +Pops one value off of the stack. +If the value is a number, this pushes \f[B]1\f[R] onto the stack. +Otherwise (if it is a string), it pushes \f[B]0\f[R]. +.RS +.PP +This is a \f[B]non\-portable extension\f[R]. +.RE +.TP +\f[B]t\f[R] +Pops one value off of the stack. +If the value is a string, this pushes \f[B]1\f[R] onto the stack. +Otherwise (if it is a number), it pushes \f[B]0\f[R]. +.RS +.PP +This is a \f[B]non\-portable extension\f[R]. +.RE +.TP \f[B]z\f[R] Pushes the current depth of the stack (before execution of this command) onto the stack. @@ -1122,10 +1197,9 @@ register\[cq]s stack must always have at least one item; dc(1) will give an error and reset otherwise (see the \f[B]RESET\f[R] section). This means that this command will never push \f[B]0\f[R]. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .SS Arrays -.PP These commands manipulate arrays. .TP \f[B]:\f[R]\f[I]r\f[R] @@ -1142,10 +1216,9 @@ The selected value is then pushed onto the stack. Pushes the length of the array \f[I]r\f[R] onto the stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .SS Global Settings -.PP These commands retrieve global settings. These are the only commands that require multiple specific characters, and all of them begin with the letter \f[B]g\f[R]. @@ -1157,12 +1230,17 @@ section). Pushes the line length set by \f[B]DC_LINE_LENGTH\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section) onto the stack. .TP +\f[B]gx\f[R] +Pushes \f[B]1\f[R] onto the stack if extended register mode is on, +\f[B]0\f[R] otherwise. +See the \f[I]Extended Register Mode\f[R] subsection of the +\f[B]REGISTERS\f[R] section for more information. +.TP \f[B]gz\f[R] Pushes \f[B]0\f[R] onto the stack if the leading zero setting has not -been enabled with the \f[B]-z\f[R] or \f[B]--leading-zeroes\f[R] options -(see the \f[B]OPTIONS\f[R] section), non-zero otherwise. +been enabled with the \f[B]\-z\f[R] or \f[B]\-\-leading\-zeroes\f[R] +options (see the \f[B]OPTIONS\f[R] section), non\-zero otherwise. .SH REGISTERS -.PP Registers are names that can store strings, numbers, and arrays. (Number/string registers do not interfere with array registers.) .PP @@ -1172,45 +1250,45 @@ All registers, when first referenced, have one value (\f[B]0\f[R]) in their stack, and it is a runtime error to attempt to pop that item off of the register stack. .PP -In non-extended register mode, a register name is just the single +In non\-extended register mode, a register name is just the single character that follows any command that needs a register name. The only exceptions are: a newline (\f[B]`\[rs]n'\f[R]) and a left bracket (\f[B]`['\f[R]); it is a parse error for a newline or a left bracket to be used as a register name. .SS Extended Register Mode -.PP Unlike most other dc(1) implentations, this dc(1) provides nearly unlimited amounts of registers, if extended register mode is enabled. .PP -If extended register mode is enabled (\f[B]-x\f[R] or -\f[B]--extended-register\f[R] command-line arguments are given), then -normal single character registers are used \f[I]unless\f[R] the +If extended register mode is enabled (\f[B]\-x\f[R] or +\f[B]\-\-extended\-register\f[R] command\-line arguments are given), +then normal single character registers are used \f[I]unless\f[R] the character immediately following a command that needs a register name is a space (according to \f[B]isspace()\f[R]) and not a newline (\f[B]`\[rs]n'\f[R]). .PP In that case, the register name is found according to the regex -\f[B][a-z][a-z0-9_]*\f[R] (like bc(1) identifiers), and it is a parse -error if the next non-space characters do not match that regex. +\f[B][a\-z][a\-z0\-9_]*\f[R] (like bc(1) identifiers), and it is a parse +error if the next non\-space characters do not match that regex. .SH RESET -.PP -When dc(1) encounters an error or a signal that it has a non-default +When dc(1) encounters an error or a signal that it has a non\-default handler for, it resets. This means that several things happen. .PP First, any macros that are executing are stopped and popped off the -stack. +execution stack. The behavior is not unlike that of exceptions in programming languages. Then the execution point is set so that any code waiting to execute (after all macros returned) is skipped. .PP +However, the stack of values is \f[I]not\f[R] cleared; in interactive +mode, users can inspect the stack and manipulate it. +.PP Thus, when dc(1) resets, it skips any remaining code waiting to be executed. Then, if it is interactive mode, and the error was not a fatal error (see the \f[B]EXIT STATUS\f[R] section), it asks for more input; otherwise, it exits with the appropriate return code. .SH PERFORMANCE -.PP Most dc(1) implementations use \f[B]char\f[R] types to calculate the value of \f[B]1\f[R] decimal digit at a time, but that can be slow. This dc(1) does something different. @@ -1230,7 +1308,6 @@ checking. This integer type depends on the value of \f[B]DC_LONG_BIT\f[R], but is always at least twice as large as the integer type used to store digits. .SH LIMITS -.PP The following are the limits on dc(1): .TP \f[B]DC_LONG_BIT\f[R] @@ -1260,29 +1337,29 @@ Set at \f[B]DC_BASE_POW\f[R]. .TP \f[B]DC_DIM_MAX\f[R] The maximum size of arrays. -Set at \f[B]SIZE_MAX-1\f[R]. +Set at \f[B]SIZE_MAX\-1\f[R]. .TP \f[B]DC_SCALE_MAX\f[R] The maximum \f[B]scale\f[R]. -Set at \f[B]DC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]DC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]DC_STRING_MAX\f[R] The maximum length of strings. -Set at \f[B]DC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]DC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]DC_NAME_MAX\f[R] The maximum length of identifiers. -Set at \f[B]DC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]DC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]DC_NUM_MAX\f[R] The maximum length of a number (in decimal digits), which includes digits after the decimal point. -Set at \f[B]DC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]DC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]DC_RAND_MAX\f[R] The maximum integer (inclusive) returned by the \f[B]\[cq]\f[R] command, if dc(1). -Set at \f[B]2\[ha]DC_LONG_BIT-1\f[R]. +Set at \f[B]2\[ha]DC_LONG_BIT\-1\f[R]. .TP Exponent The maximum allowable exponent (positive or negative). @@ -1290,27 +1367,27 @@ Set at \f[B]DC_OVERFLOW_MAX\f[R]. .TP Number of vars The maximum number of vars/arrays. -Set at \f[B]SIZE_MAX-1\f[R]. +Set at \f[B]SIZE_MAX\-1\f[R]. .PP -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. +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 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). -They should be in the same format as all other command-line arguments. +This is another way to give command\-line arguments to dc(1). +They should be in the same format as all other command\-line arguments. These are always processed first, so any files given in \f[B]DC_ENV_ARGS\f[R] will be processed before arguments and files given -on the command-line. +on the command\-line. This gives the user the ability to set up \[lq]standard\[rq] options and files to be used at every invocation. The most useful thing for such files to contain would be useful functions that the user might want every time dc(1) runs. -Another use would be to use the \f[B]-e\f[R] option to set +Another use would be to use the \f[B]\-e\f[R] option to set \f[B]scale\f[R] to a value other than \f[B]0\f[R]. .RS .PP @@ -1328,14 +1405,14 @@ you can use double quotes as the outside quotes, as in \f[B]\[lq]some quotes. However, handling a file with both kinds of quotes in \f[B]DC_ENV_ARGS\f[R] is not supported due to the complexity of the -parsing, though such files are still supported on the command-line where -the parsing is done by the shell. +parsing, though such files are still supported on the command\-line +where the parsing is done by the shell. .RE .TP \f[B]DC_LINE_LENGTH\f[R] If this environment variable exists and contains an integer that is greater than \f[B]1\f[R] and is less than \f[B]UINT16_MAX\f[R] -(\f[B]2\[ha]16-1\f[R]), dc(1) will output lines to that length, +(\f[B]2\[ha]16\-1\f[R]), dc(1) will output lines to that length, including the backslash newline combo. The default line length is \f[B]70\f[R]. .RS @@ -1352,13 +1429,13 @@ exits on \f[B]SIGINT\f[R] when not in interactive mode. .RS .PP However, when dc(1) is in interactive mode, then if this environment -variable exists and contains an integer, a non-zero value makes dc(1) +variable exists and contains an integer, a non\-zero value makes dc(1) reset on \f[B]SIGINT\f[R], rather than exit, and zero makes dc(1) exit. If this environment variable exists and is \f[I]not\f[R] an integer, then dc(1) will exit on \f[B]SIGINT\f[R]. .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. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]DC_TTY_MODE\f[R] @@ -1367,11 +1444,11 @@ section), then this environment variable has no effect. .RS .PP However, when TTY mode is available, then if this environment variable -exists and contains an integer, then a non-zero value makes dc(1) use +exists and contains an integer, then a non\-zero value makes dc(1) use TTY mode, and zero makes dc(1) not use TTY mode. .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. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]DC_PROMPT\f[R] @@ -1380,30 +1457,46 @@ section), then this environment variable has no effect. .RS .PP However, when TTY mode is available, then if this environment variable -exists and contains an integer, a non-zero value makes dc(1) use a -prompt, and zero or a non-integer makes dc(1) not use a prompt. +exists and contains an integer, a non\-zero value makes dc(1) use a +prompt, and zero or a non\-integer makes dc(1) not use a prompt. If this environment variable does not exist and \f[B]DC_TTY_MODE\f[R] does, then the value of the \f[B]DC_TTY_MODE\f[R] environment variable is used. .PP This environment variable and the \f[B]DC_TTY_MODE\f[R] environment variable override the default, which can be queried with the -\f[B]-h\f[R] or \f[B]--help\f[R] options. +\f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]DC_EXPR_EXIT\f[R] -If any expressions or expression files are given on the command-line -with \f[B]-e\f[R], \f[B]--expression\f[R], \f[B]-f\f[R], or -\f[B]--file\f[R], then if this environment variable exists and contains -an integer, a non-zero value makes dc(1) exit after executing the -expressions and expression files, and a zero value makes dc(1) not exit. +If any expressions or expression files are given on the command\-line +with \f[B]\-e\f[R], \f[B]\-\-expression\f[R], \f[B]\-f\f[R], or +\f[B]\-\-file\f[R], then if this environment variable exists and +contains an integer, a non\-zero value makes dc(1) exit after executing +the expressions and expression files, and a zero value makes dc(1) not +exit. .RS .PP This environment variable overrides the default, which can be queried -with the \f[B]-h\f[R] or \f[B]--help\f[R] options. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE -.SH EXIT STATUS +.TP +\f[B]DC_DIGIT_CLAMP\f[R] +When parsing numbers and if this environment variable exists and +contains an integer, a non\-zero value makes dc(1) clamp digits that are +greater than or equal to the current \f[B]ibase\f[R] so that all such +digits are considered equal to the \f[B]ibase\f[R] minus 1, and a zero +value disables such clamping so that those digits are always equal to +their value, which is multiplied by the power of the \f[B]ibase\f[R]. +.RS .PP +This never applies to single\-digit numbers, as per the bc(1) standard +(see the \f[B]STANDARDS\f[R] section). +.PP +This environment variable overrides the default, which can be queried +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. +.RE +.SH EXIT STATUS dc(1) returns the following exit statuses: .TP \f[B]0\f[R] @@ -1417,10 +1510,10 @@ since math errors will happen in the process of normal execution. .PP Math errors include divide by \f[B]0\f[R], taking the square root of a negative number, using a negative number as a bound for the -pseudo-random number generator, attempting to convert a negative number +pseudo\-random number generator, attempting to convert a negative number to a hardware integer, overflow when converting a number to a hardware integer, overflow when calculating the size of a number, and attempting -to use a non-integer where an integer is required. +to use a non\-integer where an integer is required. .PP Converting to a hardware integer happens for the second operand of the power (\f[B]\[ha]\f[R]), places (\f[B]\[at]\f[R]), left shift @@ -1455,7 +1548,7 @@ A fatal error occurred. Fatal errors include memory allocation errors, I/O errors, failing to open files, attempting to use files that do not have only ASCII characters (dc(1) only accepts ASCII characters), attempting to open a -directory as a file, and giving invalid command-line options. +directory as a file, and giving invalid command\-line options. .RE .PP The exit status \f[B]4\f[R] is special; when a fatal error occurs, dc(1) @@ -1466,17 +1559,17 @@ interactive mode (see the \f[B]INTERACTIVE MODE\f[R] section), since dc(1) resets its state (see the \f[B]RESET\f[R] section) and accepts more input when one of those errors occurs in interactive mode. This is also the case when interactive mode is forced by the -\f[B]-i\f[R] flag or \f[B]--interactive\f[R] option. +\f[B]\-i\f[R] flag or \f[B]\-\-interactive\f[R] option. .PP These exit statuses allow dc(1) to be used in shell scripting with error checking, and its normal behavior can be forced by using the -\f[B]-i\f[R] flag or \f[B]--interactive\f[R] option. +\f[B]\-i\f[R] flag or \f[B]\-\-interactive\f[R] option. .SH INTERACTIVE MODE -.PP -Like bc(1), dc(1) has an interactive mode and a non-interactive mode. +Like bc(1), dc(1) has an interactive mode and a non\-interactive mode. Interactive mode is turned on automatically when both \f[B]stdin\f[R] -and \f[B]stdout\f[R] are hooked to a terminal, but the \f[B]-i\f[R] flag -and \f[B]--interactive\f[R] option can turn it on in other situations. +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. .PP In interactive mode, dc(1) attempts to recover from errors (see the \f[B]RESET\f[R] section), and in normal execution, flushes @@ -1485,7 +1578,6 @@ dc(1) may also reset on \f[B]SIGINT\f[R] instead of exit, depending on the contents of, or default for, the \f[B]DC_SIGINT_RESET\f[R] environment variable (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). .SH TTY MODE -.PP If \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all connected to a TTY, then \[lq]TTY mode\[rq] is considered to be available, and thus, dc(1) can turn on TTY mode, subject to some @@ -1493,53 +1585,49 @@ settings. .PP If there is the environment variable \f[B]DC_TTY_MODE\f[R] in the environment (see the \f[B]ENVIRONMENT VARIABLES\f[R] section), then if -that environment variable contains a non-zero integer, dc(1) will turn +that environment variable contains a non\-zero integer, dc(1) will turn on TTY mode when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all connected to a TTY. If the \f[B]DC_TTY_MODE\f[R] environment variable exists but is -\f[I]not\f[R] a non-zero integer, then dc(1) will not turn TTY mode on. +\f[I]not\f[R] a non\-zero integer, then dc(1) will not turn TTY mode on. .PP If the environment variable \f[B]DC_TTY_MODE\f[R] does \f[I]not\f[R] exist, the default setting is used. -The default setting can be queried with the \f[B]-h\f[R] or -\f[B]--help\f[R] options. +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. -.SS Command-Line History -.PP -Command-line history is only enabled if TTY mode is, i.e., that +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 +Command\-line history is only enabled if TTY mode is, i.e., that \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are connected to a TTY and the \f[B]DC_TTY_MODE\f[R] environment variable (see the \f[B]ENVIRONMENT VARIABLES\f[R] section) and its default do not disable TTY mode. See the \f[B]COMMAND LINE HISTORY\f[R] section for more information. .SS Prompt -.PP If TTY mode is available, then a prompt can be enabled. Like TTY mode itself, it can be turned on or off with an environment variable: \f[B]DC_PROMPT\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). .PP -If the environment variable \f[B]DC_PROMPT\f[R] exists and is a non-zero -integer, then the prompt is turned on when \f[B]stdin\f[R], +If the environment variable \f[B]DC_PROMPT\f[R] exists and is a +non\-zero integer, then the prompt is turned on when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are connected to a TTY and the -\f[B]-P\f[R] and \f[B]--no-prompt\f[R] options were not used. +\f[B]\-P\f[R] and \f[B]\-\-no\-prompt\f[R] options were not used. The read prompt will be turned on under the same conditions, except that -the \f[B]-R\f[R] and \f[B]--no-read-prompt\f[R] options must also not be -used. +the \f[B]\-R\f[R] and \f[B]\-\-no\-read\-prompt\f[R] options must also +not be used. .PP However, if \f[B]DC_PROMPT\f[R] does not exist, the prompt can be enabled or disabled with the \f[B]DC_TTY_MODE\f[R] environment variable, -the \f[B]-P\f[R] and \f[B]--no-prompt\f[R] options, and the \f[B]-R\f[R] -and \f[B]--no-read-prompt\f[R] options. +the \f[B]\-P\f[R] and \f[B]\-\-no\-prompt\f[R] options, and the +\f[B]\-R\f[R] and \f[B]\-\-no\-read\-prompt\f[R] options. See the \f[B]ENVIRONMENT VARIABLES\f[R] and \f[B]OPTIONS\f[R] sections for more details. .SH SIGNAL HANDLING -.PP Sending a \f[B]SIGINT\f[R] will cause dc(1) to do one of two things. .PP If dc(1) is not in interactive mode (see the \f[B]INTERACTIVE MODE\f[R] @@ -1548,7 +1636,7 @@ section), or the \f[B]DC_SIGINT_RESET\f[R] environment variable (see the an integer or it is zero, dc(1) will exit. .PP However, if dc(1) is in interactive mode, and the -\f[B]DC_SIGINT_RESET\f[R] or its default is an integer and non-zero, +\f[B]DC_SIGINT_RESET\f[R] or its default is an integer and non\-zero, then dc(1) will stop executing the current input and reset (see the \f[B]RESET\f[R] section) upon receiving a \f[B]SIGINT\f[R]. .PP @@ -1574,12 +1662,11 @@ The one exception is \f[B]SIGHUP\f[R]; in that case, and only when dc(1) is in TTY mode (see the \f[B]TTY MODE\f[R] section), a \f[B]SIGHUP\f[R] will cause dc(1) to clean up and exit. .SH COMMAND LINE HISTORY -.PP -dc(1) supports interactive command-line editing. +dc(1) supports interactive command\-line editing. .PP If dc(1) can be in TTY mode (see the \f[B]TTY MODE\f[R] section), history can be enabled. -This means that command-line history can only be enabled when +This means that command\-line history can only be enabled when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all connected to a TTY. .PP @@ -1589,23 +1676,20 @@ section). .PP \f[B]Note\f[R]: tabs are converted to 8 spaces. .SH LOCALES -.PP This dc(1) ships with support for adding error messages for different locales and thus, supports \f[B]LC_MESSAGES\f[R]. .SH SEE ALSO -.PP bc(1) .SH STANDARDS -.PP -The dc(1) utility operators are compliant with the operators in the IEEE -Std 1003.1-2017 (\[lq]POSIX.1-2017\[rq]) specification at -https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html for -bc(1). +The dc(1) utility operators and some behavior are compliant with the +operators in the IEEE Std 1003.1\-2017 (\[lq]POSIX.1\-2017\[rq]) bc(1) +specification at +https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html . .SH BUGS -.PP None are known. -Report bugs at https://git.yzena.com/gavin/bc. +Report bugs at https://git.gavinhoward.com/gavin/bc . .SH AUTHOR -.PP -Gavin D. -Howard <gavin@yzena.com> and contributors. +Gavin D. Howard \c +.MT gavin@gavinhoward.com +.ME \c +\ and contributors. diff --git a/contrib/bc/manuals/dc/A.1.md b/contrib/bc/manuals/dc/A.1.md index f678c5f5a869..ad0c59934fd1 100644 --- a/contrib/bc/manuals/dc/A.1.md +++ b/contrib/bc/manuals/dc/A.1.md @@ -2,7 +2,7 @@ SPDX-License-Identifier: BSD-2-Clause -Copyright (c) 2018-2021 Gavin D. Howard and contributors. +Copyright (c) 2018-2024 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 is a **non-portable extension**. - -**-P**, **-\-no-prompt** + 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. -: 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**. + If this and/or the **-C** or **-\-no-digit-clamp** options are given + multiple times, the last one given is used. - These options override the **DC_PROMPT** and **DC_TTY_MODE** environment - variables (see the **ENVIRONMENT VARIABLES** 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**. -**-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** +**-E** *seed*, **-\-seed**=*seed* -: Makes dc(1) print all numbers greater than **-1** and less than **1**, and - not equal to **0**, with a leading zero. +: 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. - 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,21 @@ 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 is a **non-portable extension**. @@ -302,15 +335,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**. - -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**. +Uppercase letters are equal to **9** plus 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** (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 +996,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 +1020,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) @@ -1009,6 +1083,12 @@ other character produces a parse error (see the **ERRORS** section). : Pushes the line length set by **DC_LINE_LENGTH** (see the **ENVIRONMENT VARIABLES** section) onto the stack. +**gx** + +: Pushes **1** onto the stack if extended register mode is on, **0** + otherwise. See the *Extended Register Mode* subsection of the **REGISTERS** + section for more information. + **gz** : Pushes **0** onto the stack if the leading zero setting has not been enabled @@ -1050,11 +1130,14 @@ the next non-space characters do not match that regex. When dc(1) encounters an error or a signal that it has a non-default handler for, it resets. This means that several things happen. -First, any macros that are executing are stopped and popped off the stack. -The behavior is not unlike that of exceptions in programming languages. Then -the execution point is set so that any code waiting to execute (after all +First, any macros that are executing are stopped and popped off the execution +stack. The behavior is not unlike that of exceptions in programming languages. +Then the execution point is set so that any code waiting to execute (after all macros returned) is skipped. +However, the stack of values is *not* cleared; in interactive mode, users can +inspect the stack and manipulate it. + Thus, when dc(1) resets, it skips any remaining code waiting to be executed. Then, if it is interactive mode, and the error was not a fatal error (see the **EXIT STATUS** section), it asks for more input; otherwise, it exits with the @@ -1148,7 +1231,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 +1321,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 +1432,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,14 +1516,14 @@ 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.gavinhoward.com/gavin/bc . # AUTHOR -Gavin D. Howard <gavin@yzena.com> and contributors. +Gavin D. Howard <gavin@gavinhoward.com> and contributors. diff --git a/contrib/bc/manuals/dc/E.1 b/contrib/bc/manuals/dc/E.1 index 7f90beac6b1c..a5febe44705f 100644 --- a/contrib/bc/manuals/dc/E.1 +++ b/contrib/bc/manuals/dc/E.1 @@ -1,7 +1,7 @@ .\" .\" SPDX-License-Identifier: BSD-2-Clause .\" -.\" Copyright (c) 2018-2021 Gavin D. Howard and contributors. +.\" Copyright (c) 2018-2024 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,124 +25,82 @@ .\" 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" "August 2024" "Gavin D. Howard" "General Commands Manual" .nh .ad l .SH Name -.PP -dc - arbitrary-precision decimal reverse-Polish notation calculator +dc \- arbitrary\-precision decimal reverse\-Polish notation calculator .SH SYNOPSIS -.PP -\f[B]dc\f[R] [\f[B]-hiPRvVx\f[R]] [\f[B]--version\f[R]] -[\f[B]--help\f[R]] [\f[B]--interactive\f[R]] [\f[B]--no-prompt\f[R]] -[\f[B]--no-read-prompt\f[R]] [\f[B]--extended-register\f[R]] -[\f[B]-e\f[R] \f[I]expr\f[R]] -[\f[B]--expression\f[R]=\f[I]expr\f[R]\&...] [\f[B]-f\f[R] -\f[I]file\f[R]\&...] [\f[B]--file\f[R]=\f[I]file\f[R]\&...] +\f[B]dc\f[R] [\f[B]\-cChiPRvVx\f[R]] [\f[B]\-\-version\f[R]] +[\f[B]\-\-help\f[R]] [\f[B]\-\-digit\-clamp\f[R]] +[\f[B]\-\-no\-digit\-clamp\f[R]] [\f[B]\-\-interactive\f[R]] +[\f[B]\-\-no\-prompt\f[R]] [\f[B]\-\-no\-read\-prompt\f[R]] +[\f[B]\-\-extended\-register\f[R]] [\f[B]\-e\f[R] \f[I]expr\f[R]] +[\f[B]\-\-expression\f[R]=\f[I]expr\f[R]\&...] +[\f[B]\-f\f[R] \f[I]file\f[R]\&...] +[\f[B]\-\-file\f[R]=\f[I]file\f[R]\&...] [\f[I]file\f[R]\&...] .SH DESCRIPTION -.PP -dc(1) is an arbitrary-precision calculator. +dc(1) is an arbitrary\-precision calculator. It uses a stack (reverse Polish notation) to store numbers and results of computations. Arithmetic operations pop arguments off of the stack and push the results. .PP -If no files are given on the command-line, then dc(1) reads from +If no files are given on the command\-line, then dc(1) reads from \f[B]stdin\f[R] (see the \f[B]STDIN\f[R] section). Otherwise, those files are processed, and dc(1) will then exit. .PP If a user wants to set up a standard environment, they can use \f[B]DC_ENV_ARGS\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). For example, if a user wants the \f[B]scale\f[R] always set to -\f[B]10\f[R], they can set \f[B]DC_ENV_ARGS\f[R] to \f[B]-e 10k\f[R], +\f[B]10\f[R], they can set \f[B]DC_ENV_ARGS\f[R] to \f[B]\-e 10k\f[R], and this dc(1) will always start with a \f[B]scale\f[R] of \f[B]10\f[R]. .SH OPTIONS -.PP The following are the options that dc(1) accepts. .TP -\f[B]-h\f[R], \f[B]--help\f[R] -Prints a usage message and quits. -.TP -\f[B]-v\f[R], \f[B]-V\f[R], \f[B]--version\f[R] -Print the version information (copyright header) and exit. -.TP -\f[B]-i\f[R], \f[B]--interactive\f[R] -Forces interactive mode. -(See the \f[B]INTERACTIVE MODE\f[R] section.) +\f[B]\-C\f[R], \f[B]\-\-no\-digit\-clamp\f[R] +Disables clamping of digits greater than or equal to the current +\f[B]ibase\f[R] when parsing numbers. .RS .PP -This is a \f[B]non-portable extension\f[R]. -.RE -.TP -\f[B]-L\f[R], \f[B]--no-line-length\f[R] -Disables line length checking and prints numbers without backslashes and -newlines. -In other words, this option sets \f[B]BC_LINE_LENGTH\f[R] to \f[B]0\f[R] -(see the \f[B]ENVIRONMENT VARIABLES\f[R] section). -.RS +This means that the value added to a number from a digit is always that +digit\[cq]s value multiplied by the value of ibase raised to the power +of the digit\[cq]s position, which starts from 0 at the least +significant digit. .PP -This is a \f[B]non-portable extension\f[R]. -.RE -.TP -\f[B]-P\f[R], \f[B]--no-prompt\f[R] -Disables the prompt in TTY mode. -(The prompt is only enabled in TTY mode. -See the \f[B]TTY MODE\f[R] section.) This is mostly for those users that -do not want a prompt or are not used to having them in dc(1). -Most of those users would want to put this option in -\f[B]DC_ENV_ARGS\f[R]. -.RS +If this and/or the \f[B]\-c\f[R] or \f[B]\-\-digit\-clamp\f[R] options +are given multiple times, the last one given is used. .PP -These options override the \f[B]DC_PROMPT\f[R] and \f[B]DC_TTY_MODE\f[R] -environment variables (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). +This option overrides the \f[B]DC_DIGIT_CLAMP\f[R] environment variable +(see the \f[B]ENVIRONMENT VARIABLES\f[R] section) and the default, which +can be queried with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-R\f[R], \f[B]--no-read-prompt\f[R] -Disables the read prompt in TTY mode. -(The read prompt is only enabled in TTY mode. -See the \f[B]TTY MODE\f[R] section.) This is mostly for those users that -do not want a read prompt or are not used to having them in dc(1). -Most of those users would want to put this option in -\f[B]BC_ENV_ARGS\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). -This option is also useful in hash bang lines of dc(1) scripts that -prompt for user input. +\f[B]\-c\f[R], \f[B]\-\-digit\-clamp\f[R] +Enables clamping of digits greater than or equal to the current +\f[B]ibase\f[R] when parsing numbers. .RS .PP -This option does not disable the regular prompt because the read prompt -is only used when the \f[B]?\f[R] command is used. +This means that digits that the value added to a number from a digit +that is greater than or equal to the ibase is the value of ibase minus 1 +all multiplied by the value of ibase raised to the power of the +digit\[cq]s position, which starts from 0 at the least significant +digit. .PP -These options \f[I]do\f[R] override the \f[B]DC_PROMPT\f[R] and -\f[B]DC_TTY_MODE\f[R] environment variables (see the \f[B]ENVIRONMENT -VARIABLES\f[R] section), but only for the read prompt. +If this and/or the \f[B]\-C\f[R] or \f[B]\-\-no\-digit\-clamp\f[R] +options are given multiple times, the last one given is used. .PP -This is a \f[B]non-portable extension\f[R]. -.RE -.TP -\f[B]-x\f[R] \f[B]--extended-register\f[R] -Enables extended register mode. -See the \f[I]Extended Register Mode\f[R] subsection of the -\f[B]REGISTERS\f[R] section for more information. -.RS +This option overrides the \f[B]DC_DIGIT_CLAMP\f[R] environment variable +(see the \f[B]ENVIRONMENT VARIABLES\f[R] section) and the default, which +can be queried with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .PP -This is a \f[B]non-portable extension\f[R]. +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 -.TP -\f[B]-e\f[R] \f[I]expr\f[R], \f[B]--expression\f[R]=\f[I]expr\f[R] +\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 @@ -151,41 +109,44 @@ 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 +If this option is given on the command\-line (i.e., not in \f[B]DC_ENV_ARGS\f[R], see the \f[B]ENVIRONMENT VARIABLES\f[R] section), then after processing all expressions and files, dc(1) will exit, unless -\f[B]-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to -\f[B]-f\f[R] or \f[B]--file\f[R], whether on the command-line or in +\f[B]\-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to +\f[B]\-f\f[R] or \f[B]\-\-file\f[R], whether on the command\-line or in \f[B]DC_ENV_ARGS\f[R]. -However, if any other \f[B]-e\f[R], \f[B]--expression\f[R], -\f[B]-f\f[R], or \f[B]--file\f[R] arguments are given after -\f[B]-f-\f[R] or equivalent is given, dc(1) will give a fatal error and -exit. +However, if any other \f[B]\-e\f[R], \f[B]\-\-expression\f[R], +\f[B]\-f\f[R], or \f[B]\-\-file\f[R] arguments are given after +\f[B]\-f\-\f[R] or equivalent is given, dc(1) will give a fatal error +and exit. .PP -This is a \f[B]non-portable extension\f[R]. +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] +\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 +If this option is given on the command\-line (i.e., not in \f[B]DC_ENV_ARGS\f[R], see the \f[B]ENVIRONMENT VARIABLES\f[R] section), then after processing all expressions and files, dc(1) will exit, unless -\f[B]-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to -\f[B]-f\f[R] or \f[B]--file\f[R]. -However, if any other \f[B]-e\f[R], \f[B]--expression\f[R], -\f[B]-f\f[R], or \f[B]--file\f[R] arguments are given after -\f[B]-f-\f[R] or equivalent is given, dc(1) will give a fatal error and -exit. +\f[B]\-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to +\f[B]\-f\f[R] or \f[B]\-\-file\f[R]. +However, if any other \f[B]\-e\f[R], \f[B]\-\-expression\f[R], +\f[B]\-f\f[R], or \f[B]\-\-file\f[R] arguments are given after +\f[B]\-f\-\f[R] or equivalent is given, dc(1) will give a fatal error +and exit. .PP -This is a \f[B]non-portable extension\f[R]. +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] +\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. It is a fatal error if \f[I]ibase\f[R] is not a valid number. @@ -193,10 +154,28 @@ It is a fatal error if \f[I]ibase\f[R] is not a valid number. .PP If multiple instances of this option are given, the last is used. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-O\f[R] \f[I]obase\f[R], \f[B]--obase\f[R]=\f[I]obase\f[R] +\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. It is a fatal error if \f[I]obase\f[R] is not a valid number. @@ -204,10 +183,48 @@ It is a fatal error if \f[I]obase\f[R] is not a valid number. .PP If multiple instances of this option are given, the last is used. .PP -This is a \f[B]non-portable extension\f[R]. +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]-S\f[R] \f[I]scale\f[R], \f[B]--scale\f[R]=\f[I]scale\f[R] +\f[B]\-R\f[R], \f[B]\-\-no\-read\-prompt\f[R] +Disables the read prompt in TTY mode. +(The read prompt is only enabled in TTY mode. +See the \f[B]TTY MODE\f[R] section.) +This is mostly for those users that do not want a read prompt or are not +used to having them in dc(1). +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. It is a fatal error if \f[I]scale\f[R] is not a valid number. @@ -215,15 +232,34 @@ It is a fatal error if \f[I]scale\f[R] is not a valid number. .PP If multiple instances of this option are given, the last is used. .PP -This is a \f[B]non-portable extension\f[R]. +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 -All long options are \f[B]non-portable extensions\f[R]. -.SH STDIN +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 -If no files are given on the command-line and no files or expressions -are given by the \f[B]-f\f[R], \f[B]--file\f[R], \f[B]-e\f[R], or -\f[B]--expression\f[R] options, then dc(1) reads from \f[B]stdin\f[R]. +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 +If no files are given on the command\-line and no files or expressions +are given by the \f[B]\-f\f[R], \f[B]\-\-file\f[R], \f[B]\-e\f[R], or +\f[B]\-\-expression\f[R] options, then dc(1) reads from \f[B]stdin\f[R]. .PP However, there is a caveat to this. .PP @@ -233,8 +269,7 @@ ended. This means that, except for escaped brackets, all brackets must be balanced before dc(1) parses and executes. .SH STDOUT -.PP -Any non-error output is written to \f[B]stdout\f[R]. +Any non\-error output is written to \f[B]stdout\f[R]. In addition, if history (see the \f[B]HISTORY\f[R] section) and the prompt (see the \f[B]TTY MODE\f[R] section) are enabled, both are output to \f[B]stdout\f[R]. @@ -242,7 +277,7 @@ to \f[B]stdout\f[R]. \f[B]Note\f[R]: Unlike other dc(1) implementations, this dc(1) will issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot write to \f[B]stdout\f[R], so if \f[B]stdout\f[R] is closed, as in -\f[B]dc >&-\f[R], it will quit with an error. +\f[B]dc >&\-\f[R], it will quit with an error. This is done so that dc(1) can report problems when \f[B]stdout\f[R] is redirected to a file. .PP @@ -250,13 +285,12 @@ If there are scripts that depend on the behavior of other dc(1) implementations, it is recommended that those scripts be changed to redirect \f[B]stdout\f[R] to \f[B]/dev/null\f[R]. .SH STDERR -.PP Any error output is written to \f[B]stderr\f[R]. .PP \f[B]Note\f[R]: Unlike other dc(1) implementations, this dc(1) will issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot write to \f[B]stderr\f[R], so if \f[B]stderr\f[R] is closed, as in -\f[B]dc 2>&-\f[R], it will quit with an error. +\f[B]dc 2>&\-\f[R], it will quit with an error. This is done so that dc(1) can exit with an error code when \f[B]stderr\f[R] is redirected to a file. .PP @@ -264,7 +298,6 @@ If there are scripts that depend on the behavior of other dc(1) implementations, it is recommended that those scripts be changed to redirect \f[B]stderr\f[R] to \f[B]/dev/null\f[R]. .SH SYNTAX -.PP Each item in the input source code, either a number (see the \f[B]NUMBERS\f[R] section) or a command (see the \f[B]COMMANDS\f[R] section), is processed and executed, in order. @@ -299,30 +332,57 @@ precision of any operations (with exceptions). The max allowable value for \f[B]scale\f[R] can be queried in dc(1) programs with the \f[B]V\f[R] command. .SS Comments -.PP Comments go from \f[B]#\f[R] until, and not including, the next newline. -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .SH NUMBERS -.PP Numbers are strings made up of digits, uppercase letters up to \f[B]F\f[R], and at most \f[B]1\f[R] period for a radix. Numbers can have up to \f[B]DC_NUM_MAX\f[R] digits. -Uppercase letters are equal to \f[B]9\f[R] + their position in the +Uppercase letters are equal to \f[B]9\f[R] plus their position in the alphabet (i.e., \f[B]A\f[R] equals \f[B]10\f[R], or \f[B]9+1\f[R]). -If a digit or letter makes no sense with the current value of -\f[B]ibase\f[R], they are set to the value of the highest valid digit in -\f[B]ibase\f[R]. .PP -Single-character numbers (i.e., \f[B]A\f[R] alone) take the value that -they would have if they were valid digits, regardless of the value of -\f[B]ibase\f[R]. +If a digit or letter makes no sense with the current value of +\f[B]ibase\f[R] (i.e., they are greater than or equal to the current +value of \f[B]ibase\f[R]), then the behavior depends on the existence of +the \f[B]\-c\f[R]/\f[B]\-\-digit\-clamp\f[R] or +\f[B]\-C\f[R]/\f[B]\-\-no\-digit\-clamp\f[R] options (see the +\f[B]OPTIONS\f[R] section), the existence and setting of the +\f[B]DC_DIGIT_CLAMP\f[R] environment variable (see the \f[B]ENVIRONMENT +VARIABLES\f[R] section), or the default, which can be queried with the +\f[B]\-h\f[R]/\f[B]\-\-help\f[R] option. +.PP +If clamping is off, then digits or letters that are greater than or +equal to the current value of \f[B]ibase\f[R] are not changed. +Instead, their given value is multiplied by the appropriate power of +\f[B]ibase\f[R] and added into the number. +This means that, with an \f[B]ibase\f[R] of \f[B]3\f[R], the number +\f[B]AB\f[R] is equal to \f[B]3\[ha]1*A+3\[ha]0*B\f[R], which is +\f[B]3\f[R] times \f[B]10\f[R] plus \f[B]11\f[R], or \f[B]41\f[R]. +.PP +If clamping is on, then digits or letters that are greater than or equal +to the current value of \f[B]ibase\f[R] are set to the value of the +highest valid digit in \f[B]ibase\f[R] before being multiplied by the +appropriate power of \f[B]ibase\f[R] and added into the number. +This means that, with an \f[B]ibase\f[R] of \f[B]3\f[R], the number +\f[B]AB\f[R] is equal to \f[B]3\[ha]1*2+3\[ha]0*2\f[R], which is +\f[B]3\f[R] times \f[B]2\f[R] plus \f[B]2\f[R], or \f[B]8\f[R]. +.PP +There is one exception to clamping: single\-character numbers (i.e., +\f[B]A\f[R] alone). +Such numbers are never clamped and always take the value they would have +in the highest possible \f[B]ibase\f[R]. This means that \f[B]A\f[R] alone always equals decimal \f[B]10\f[R] and -\f[B]F\f[R] alone always equals decimal \f[B]15\f[R]. +\f[B]Z\f[R] alone always equals decimal \f[B]35\f[R]. +This behavior is mandated by the standard for bc(1) (see the STANDARDS +section) and is meant to provide an easy way to set the current +\f[B]ibase\f[R] (with the \f[B]i\f[R] command) regardless of the current +value of \f[B]ibase\f[R]. +.PP +If clamping is on, and the clamped value of a character is needed, use a +leading zero, i.e., for \f[B]A\f[R], use \f[B]0A\f[R]. .SH COMMANDS -.PP The valid commands are listed below. .SS Printing -.PP These commands are used for printing. .TP \f[B]p\f[R] @@ -343,12 +403,12 @@ Pops a value off the stack. .PP If the value is a number, it is truncated and the absolute value of the result is printed as though \f[B]obase\f[R] is \f[B]256\f[R] and each -digit is interpreted as an 8-bit ASCII character, making it a byte +digit is interpreted as an 8\-bit ASCII character, making it a byte stream. .PP If the value is a string, it is printed without a trailing newline. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]f\f[R] @@ -359,7 +419,6 @@ without altering anything. Users should use this command when they get lost. .RE .SS Arithmetic -.PP These are the commands used for arithmetic. .TP \f[B]+\f[R] @@ -368,7 +427,7 @@ pushed onto the stack. The \f[I]scale\f[R] of the result is equal to the max \f[I]scale\f[R] of both operands. .TP -\f[B]-\f[R] +\f[B]\-\f[R] The top two values are popped off the stack, subtracted, and the result is pushed onto the stack. The \f[I]scale\f[R] of the result is equal to the max \f[I]scale\f[R] of @@ -389,7 +448,7 @@ pushed onto the stack. The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R]. .RS .PP -The first value popped off of the stack must be non-zero. +The first value popped off of the stack must be non\-zero. .RE .TP \f[B]%\f[R] @@ -399,10 +458,10 @@ is pushed onto the stack. .PP Remaindering is equivalent to 1) Computing \f[B]a/b\f[R] to current \f[B]scale\f[R], and 2) Using the result of step 1 to calculate -\f[B]a-(a/b)*b\f[R] to \f[I]scale\f[R] +\f[B]a\-(a/b)*b\f[R] to \f[I]scale\f[R] \f[B]max(scale+scale(b),scale(a))\f[R]. .PP -The first value popped off of the stack must be non-zero. +The first value popped off of the stack must be non\-zero. .RE .TP \f[B]\[ti]\f[R] @@ -413,9 +472,9 @@ This is equivalent to \f[B]x y / x y %\f[R] except that \f[B]x\f[R] and \f[B]y\f[R] are only evaluated once. .RS .PP -The first value popped off of the stack must be non-zero. +The first value popped off of the stack must be non\-zero. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]\[ha]\f[R] @@ -426,7 +485,7 @@ The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R]. .PP The first value popped off of the stack must be an integer, and if that value is negative, the second value popped off of the stack must be -non-zero. +non\-zero. .RE .TP \f[B]v\f[R] @@ -435,7 +494,7 @@ the result is pushed onto the stack. The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R]. .RS .PP -The value popped off of the stack must be non-negative. +The value popped off of the stack must be non\-negative. .RE .TP \f[B]_\f[R] @@ -445,7 +504,7 @@ or other commands), then that number is input as a negative number. .PP Otherwise, the top value on the stack is popped and copied, and the copy is negated and pushed onto the stack. -This behavior without a number is a \f[B]non-portable extension\f[R]. +This behavior without a number is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]b\f[R] @@ -454,7 +513,7 @@ back onto the stack. Otherwise, its absolute value is pushed onto the stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]|\f[R] @@ -463,12 +522,12 @@ is computed, and the result is pushed onto the stack. .RS .PP The first value popped is used as the reduction modulus and must be an -integer and non-zero. +integer and non\-zero. The second value popped is used as the exponent and must be an integer -and non-negative. +and non\-negative. The third value popped is the base and must be an integer. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]G\f[R] @@ -476,7 +535,7 @@ The top two values are popped off of the stack, they are compared, and a \f[B]1\f[R] is pushed if they are equal, or \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]N\f[R] @@ -484,7 +543,7 @@ The top value is popped off of the stack, and if it a \f[B]0\f[R], a \f[B]1\f[R] is pushed; otherwise, a \f[B]0\f[R] is pushed. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B](\f[R] @@ -493,7 +552,7 @@ The top two values are popped off of the stack, they are compared, and a \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]{\f[R] @@ -502,7 +561,7 @@ The top two values are popped off of the stack, they are compared, and a or \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B])\f[R] @@ -511,7 +570,7 @@ The top two values are popped off of the stack, they are compared, and a \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]}\f[R] @@ -520,36 +579,35 @@ The top two values are popped off of the stack, they are compared, and a second, or \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]M\f[R] The top two values are popped off of the stack. -If they are both non-zero, a \f[B]1\f[R] is pushed onto the stack. +If they are both non\-zero, a \f[B]1\f[R] is pushed onto the stack. If either of them is zero, or both of them are, then a \f[B]0\f[R] is pushed onto the stack. .RS .PP This is like the \f[B]&&\f[R] operator in bc(1), and it is \f[I]not\f[R] -a short-circuit operator. +a short\-circuit operator. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]m\f[R] The top two values are popped off of the stack. -If at least one of them is non-zero, a \f[B]1\f[R] is pushed onto the +If at least one of them is non\-zero, a \f[B]1\f[R] is pushed onto the stack. If both of them are zero, then a \f[B]0\f[R] is pushed onto the stack. .RS .PP This is like the \f[B]||\f[R] operator in bc(1), and it is \f[I]not\f[R] -a short-circuit operator. +a short\-circuit operator. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .SS Stack Control -.PP These commands control the stack. .TP \f[B]c\f[R] @@ -565,7 +623,6 @@ Swaps (\[lq]reverses\[rq]) the two top items on the stack. \f[B]R\f[R] Pops (\[lq]removes\[rq]) the top value from the stack. .SS Register Control -.PP These commands control registers (see the \f[B]REGISTERS\f[R] section). .TP \f[B]s\f[R]\f[I]r\f[R] @@ -587,7 +644,6 @@ push it onto the main stack. The previous value in the stack for register \f[I]r\f[R], if any, is now accessible via the \f[B]l\f[R]\f[I]r\f[R] command. .SS Parameters -.PP These commands control the values of \f[B]ibase\f[R], \f[B]obase\f[R], and \f[B]scale\f[R]. Also see the \f[B]SYNTAX\f[R] section. @@ -614,7 +670,7 @@ If the value on top of the stack has any \f[I]scale\f[R], the .TP \f[B]k\f[R] Pops the value off of the top of the stack and uses it to set -\f[B]scale\f[R], which must be non-negative. +\f[B]scale\f[R], which must be non\-negative. .RS .PP If the value on top of the stack has any \f[I]scale\f[R], the @@ -635,7 +691,7 @@ Pushes the maximum allowable value of \f[B]ibase\f[R] onto the main stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]U\f[R] @@ -643,7 +699,7 @@ Pushes the maximum allowable value of \f[B]obase\f[R] onto the main stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]V\f[R] @@ -651,10 +707,9 @@ Pushes the maximum allowable value of \f[B]scale\f[R] onto the main stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .SS Strings -.PP The following commands control strings. .PP dc(1) can work with both numbers and strings, and registers (see the @@ -692,16 +747,16 @@ The value on top of the stack is popped. If it is a number, it is truncated and its absolute value is taken. The result mod \f[B]256\f[R] is calculated. If that result is \f[B]0\f[R], push an empty string; otherwise, push a -one-character string where the character is the result of the mod +one\-character string where the character is the result of the mod interpreted as an ASCII character. .PP If it is a string, then a new string is made. If the original string is empty, the new string is empty. If it is not, then the first character of the original string is used to -create the new string as a one-character string. +create the new string as a one\-character string. The new string is then pushed onto the stack. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]x\f[R] @@ -737,7 +792,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]!>\f[R]\f[I]r\f[R] @@ -758,7 +813,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]<\f[R]\f[I]r\f[R] @@ -779,7 +834,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]!<\f[R]\f[I]r\f[R] @@ -800,7 +855,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]=\f[R]\f[I]r\f[R] @@ -821,7 +876,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]!=\f[R]\f[I]r\f[R] @@ -842,7 +897,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]?\f[R] @@ -855,7 +910,7 @@ the execution of the macro that executed it. If there are no macros, or only one macro executing, dc(1) exits. .TP \f[B]Q\f[R] -Pops a value from the stack which must be non-negative and is used the +Pops a value from the stack which must be non\-negative and is used the number of macro executions to pop off of the execution stack. If the number of levels to pop is greater than the number of executing macros, dc(1) exits. @@ -866,8 +921,11 @@ The execution stack is the stack of string executions. The number that is pushed onto the stack is exactly as many as is needed to make dc(1) exit with the \f[B]Q\f[R] command, so the sequence \f[B],Q\f[R] will make dc(1) exit. -.SS Status +.RS .PP +This is a \f[B]non\-portable extension\f[R]. +.RE +.SS Status These commands query status of the stack or its top value. .TP \f[B]Z\f[R] @@ -892,6 +950,24 @@ stack. If it is a string, pushes \f[B]0\f[R]. .RE .TP +\f[B]u\f[R] +Pops one value off of the stack. +If the value is a number, this pushes \f[B]1\f[R] onto the stack. +Otherwise (if it is a string), it pushes \f[B]0\f[R]. +.RS +.PP +This is a \f[B]non\-portable extension\f[R]. +.RE +.TP +\f[B]t\f[R] +Pops one value off of the stack. +If the value is a string, this pushes \f[B]1\f[R] onto the stack. +Otherwise (if it is a number), it pushes \f[B]0\f[R]. +.RS +.PP +This is a \f[B]non\-portable extension\f[R]. +.RE +.TP \f[B]z\f[R] Pushes the current depth of the stack (before execution of this command) onto the stack. @@ -907,10 +983,9 @@ register\[cq]s stack must always have at least one item; dc(1) will give an error and reset otherwise (see the \f[B]RESET\f[R] section). This means that this command will never push \f[B]0\f[R]. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .SS Arrays -.PP These commands manipulate arrays. .TP \f[B]:\f[R]\f[I]r\f[R] @@ -927,10 +1002,9 @@ The selected value is then pushed onto the stack. Pushes the length of the array \f[I]r\f[R] onto the stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .SS Global Settings -.PP These commands retrieve global settings. These are the only commands that require multiple specific characters, and all of them begin with the letter \f[B]g\f[R]. @@ -942,12 +1016,17 @@ section). Pushes the line length set by \f[B]DC_LINE_LENGTH\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section) onto the stack. .TP +\f[B]gx\f[R] +Pushes \f[B]1\f[R] onto the stack if extended register mode is on, +\f[B]0\f[R] otherwise. +See the \f[I]Extended Register Mode\f[R] subsection of the +\f[B]REGISTERS\f[R] section for more information. +.TP \f[B]gz\f[R] Pushes \f[B]0\f[R] onto the stack if the leading zero setting has not -been enabled with the \f[B]-z\f[R] or \f[B]--leading-zeroes\f[R] options -(see the \f[B]OPTIONS\f[R] section), non-zero otherwise. +been enabled with the \f[B]\-z\f[R] or \f[B]\-\-leading\-zeroes\f[R] +options (see the \f[B]OPTIONS\f[R] section), non\-zero otherwise. .SH REGISTERS -.PP Registers are names that can store strings, numbers, and arrays. (Number/string registers do not interfere with array registers.) .PP @@ -957,45 +1036,45 @@ All registers, when first referenced, have one value (\f[B]0\f[R]) in their stack, and it is a runtime error to attempt to pop that item off of the register stack. .PP -In non-extended register mode, a register name is just the single +In non\-extended register mode, a register name is just the single character that follows any command that needs a register name. The only exceptions are: a newline (\f[B]`\[rs]n'\f[R]) and a left bracket (\f[B]`['\f[R]); it is a parse error for a newline or a left bracket to be used as a register name. .SS Extended Register Mode -.PP Unlike most other dc(1) implentations, this dc(1) provides nearly unlimited amounts of registers, if extended register mode is enabled. .PP -If extended register mode is enabled (\f[B]-x\f[R] or -\f[B]--extended-register\f[R] command-line arguments are given), then -normal single character registers are used \f[I]unless\f[R] the +If extended register mode is enabled (\f[B]\-x\f[R] or +\f[B]\-\-extended\-register\f[R] command\-line arguments are given), +then normal single character registers are used \f[I]unless\f[R] the character immediately following a command that needs a register name is a space (according to \f[B]isspace()\f[R]) and not a newline (\f[B]`\[rs]n'\f[R]). .PP In that case, the register name is found according to the regex -\f[B][a-z][a-z0-9_]*\f[R] (like bc(1) identifiers), and it is a parse -error if the next non-space characters do not match that regex. +\f[B][a\-z][a\-z0\-9_]*\f[R] (like bc(1) identifiers), and it is a parse +error if the next non\-space characters do not match that regex. .SH RESET -.PP -When dc(1) encounters an error or a signal that it has a non-default +When dc(1) encounters an error or a signal that it has a non\-default handler for, it resets. This means that several things happen. .PP First, any macros that are executing are stopped and popped off the -stack. +execution stack. The behavior is not unlike that of exceptions in programming languages. Then the execution point is set so that any code waiting to execute (after all macros returned) is skipped. .PP +However, the stack of values is \f[I]not\f[R] cleared; in interactive +mode, users can inspect the stack and manipulate it. +.PP Thus, when dc(1) resets, it skips any remaining code waiting to be executed. Then, if it is interactive mode, and the error was not a fatal error (see the \f[B]EXIT STATUS\f[R] section), it asks for more input; otherwise, it exits with the appropriate return code. .SH PERFORMANCE -.PP Most dc(1) implementations use \f[B]char\f[R] types to calculate the value of \f[B]1\f[R] decimal digit at a time, but that can be slow. This dc(1) does something different. @@ -1015,7 +1094,6 @@ checking. This integer type depends on the value of \f[B]DC_LONG_BIT\f[R], but is always at least twice as large as the integer type used to store digits. .SH LIMITS -.PP The following are the limits on dc(1): .TP \f[B]DC_LONG_BIT\f[R] @@ -1045,24 +1123,24 @@ Set at \f[B]DC_BASE_POW\f[R]. .TP \f[B]DC_DIM_MAX\f[R] The maximum size of arrays. -Set at \f[B]SIZE_MAX-1\f[R]. +Set at \f[B]SIZE_MAX\-1\f[R]. .TP \f[B]DC_SCALE_MAX\f[R] The maximum \f[B]scale\f[R]. -Set at \f[B]DC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]DC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]DC_STRING_MAX\f[R] The maximum length of strings. -Set at \f[B]DC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]DC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]DC_NAME_MAX\f[R] The maximum length of identifiers. -Set at \f[B]DC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]DC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]DC_NUM_MAX\f[R] The maximum length of a number (in decimal digits), which includes digits after the decimal point. -Set at \f[B]DC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]DC_OVERFLOW_MAX\-1\f[R]. .TP Exponent The maximum allowable exponent (positive or negative). @@ -1070,27 +1148,27 @@ Set at \f[B]DC_OVERFLOW_MAX\f[R]. .TP Number of vars The maximum number of vars/arrays. -Set at \f[B]SIZE_MAX-1\f[R]. +Set at \f[B]SIZE_MAX\-1\f[R]. .PP -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. +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 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). -They should be in the same format as all other command-line arguments. +This is another way to give command\-line arguments to dc(1). +They should be in the same format as all other command\-line arguments. These are always processed first, so any files given in \f[B]DC_ENV_ARGS\f[R] will be processed before arguments and files given -on the command-line. +on the command\-line. This gives the user the ability to set up \[lq]standard\[rq] options and files to be used at every invocation. The most useful thing for such files to contain would be useful functions that the user might want every time dc(1) runs. -Another use would be to use the \f[B]-e\f[R] option to set +Another use would be to use the \f[B]\-e\f[R] option to set \f[B]scale\f[R] to a value other than \f[B]0\f[R]. .RS .PP @@ -1108,14 +1186,14 @@ you can use double quotes as the outside quotes, as in \f[B]\[lq]some quotes. However, handling a file with both kinds of quotes in \f[B]DC_ENV_ARGS\f[R] is not supported due to the complexity of the -parsing, though such files are still supported on the command-line where -the parsing is done by the shell. +parsing, though such files are still supported on the command\-line +where the parsing is done by the shell. .RE .TP \f[B]DC_LINE_LENGTH\f[R] If this environment variable exists and contains an integer that is greater than \f[B]1\f[R] and is less than \f[B]UINT16_MAX\f[R] -(\f[B]2\[ha]16-1\f[R]), dc(1) will output lines to that length, +(\f[B]2\[ha]16\-1\f[R]), dc(1) will output lines to that length, including the backslash newline combo. The default line length is \f[B]70\f[R]. .RS @@ -1132,13 +1210,13 @@ exits on \f[B]SIGINT\f[R] when not in interactive mode. .RS .PP However, when dc(1) is in interactive mode, then if this environment -variable exists and contains an integer, a non-zero value makes dc(1) +variable exists and contains an integer, a non\-zero value makes dc(1) reset on \f[B]SIGINT\f[R], rather than exit, and zero makes dc(1) exit. If this environment variable exists and is \f[I]not\f[R] an integer, then dc(1) will exit on \f[B]SIGINT\f[R]. .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. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]DC_TTY_MODE\f[R] @@ -1147,11 +1225,11 @@ section), then this environment variable has no effect. .RS .PP However, when TTY mode is available, then if this environment variable -exists and contains an integer, then a non-zero value makes dc(1) use +exists and contains an integer, then a non\-zero value makes dc(1) use TTY mode, and zero makes dc(1) not use TTY mode. .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. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]DC_PROMPT\f[R] @@ -1160,30 +1238,46 @@ section), then this environment variable has no effect. .RS .PP However, when TTY mode is available, then if this environment variable -exists and contains an integer, a non-zero value makes dc(1) use a -prompt, and zero or a non-integer makes dc(1) not use a prompt. +exists and contains an integer, a non\-zero value makes dc(1) use a +prompt, and zero or a non\-integer makes dc(1) not use a prompt. If this environment variable does not exist and \f[B]DC_TTY_MODE\f[R] does, then the value of the \f[B]DC_TTY_MODE\f[R] environment variable is used. .PP This environment variable and the \f[B]DC_TTY_MODE\f[R] environment variable override the default, which can be queried with the -\f[B]-h\f[R] or \f[B]--help\f[R] options. +\f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]DC_EXPR_EXIT\f[R] -If any expressions or expression files are given on the command-line -with \f[B]-e\f[R], \f[B]--expression\f[R], \f[B]-f\f[R], or -\f[B]--file\f[R], then if this environment variable exists and contains -an integer, a non-zero value makes dc(1) exit after executing the -expressions and expression files, and a zero value makes dc(1) not exit. +If any expressions or expression files are given on the command\-line +with \f[B]\-e\f[R], \f[B]\-\-expression\f[R], \f[B]\-f\f[R], or +\f[B]\-\-file\f[R], then if this environment variable exists and +contains an integer, a non\-zero value makes dc(1) exit after executing +the expressions and expression files, and a zero value makes dc(1) not +exit. .RS .PP This environment variable overrides the default, which can be queried -with the \f[B]-h\f[R] or \f[B]--help\f[R] options. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE -.SH EXIT STATUS +.TP +\f[B]DC_DIGIT_CLAMP\f[R] +When parsing numbers and if this environment variable exists and +contains an integer, a non\-zero value makes dc(1) clamp digits that are +greater than or equal to the current \f[B]ibase\f[R] so that all such +digits are considered equal to the \f[B]ibase\f[R] minus 1, and a zero +value disables such clamping so that those digits are always equal to +their value, which is multiplied by the power of the \f[B]ibase\f[R]. +.RS .PP +This never applies to single\-digit numbers, as per the bc(1) standard +(see the \f[B]STANDARDS\f[R] section). +.PP +This environment variable overrides the default, which can be queried +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. +.RE +.SH EXIT STATUS dc(1) returns the following exit statuses: .TP \f[B]0\f[R] @@ -1199,7 +1293,7 @@ Math errors include divide by \f[B]0\f[R], taking the square root of a negative number, attempting to convert a negative number to a hardware integer, overflow when converting a number to a hardware integer, overflow when calculating the size of a number, and attempting to use a -non-integer where an integer is required. +non\-integer where an integer is required. .PP Converting to a hardware integer happens for the second operand of the power (\f[B]\[ha]\f[R]) operator. @@ -1233,7 +1327,7 @@ A fatal error occurred. Fatal errors include memory allocation errors, I/O errors, failing to open files, attempting to use files that do not have only ASCII characters (dc(1) only accepts ASCII characters), attempting to open a -directory as a file, and giving invalid command-line options. +directory as a file, and giving invalid command\-line options. .RE .PP The exit status \f[B]4\f[R] is special; when a fatal error occurs, dc(1) @@ -1244,17 +1338,17 @@ interactive mode (see the \f[B]INTERACTIVE MODE\f[R] section), since dc(1) resets its state (see the \f[B]RESET\f[R] section) and accepts more input when one of those errors occurs in interactive mode. This is also the case when interactive mode is forced by the -\f[B]-i\f[R] flag or \f[B]--interactive\f[R] option. +\f[B]\-i\f[R] flag or \f[B]\-\-interactive\f[R] option. .PP These exit statuses allow dc(1) to be used in shell scripting with error checking, and its normal behavior can be forced by using the -\f[B]-i\f[R] flag or \f[B]--interactive\f[R] option. +\f[B]\-i\f[R] flag or \f[B]\-\-interactive\f[R] option. .SH INTERACTIVE MODE -.PP -Like bc(1), dc(1) has an interactive mode and a non-interactive mode. +Like bc(1), dc(1) has an interactive mode and a non\-interactive mode. Interactive mode is turned on automatically when both \f[B]stdin\f[R] -and \f[B]stdout\f[R] are hooked to a terminal, but the \f[B]-i\f[R] flag -and \f[B]--interactive\f[R] option can turn it on in other situations. +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. .PP In interactive mode, dc(1) attempts to recover from errors (see the \f[B]RESET\f[R] section), and in normal execution, flushes @@ -1263,7 +1357,6 @@ dc(1) may also reset on \f[B]SIGINT\f[R] instead of exit, depending on the contents of, or default for, the \f[B]DC_SIGINT_RESET\f[R] environment variable (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). .SH TTY MODE -.PP If \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all connected to a TTY, then \[lq]TTY mode\[rq] is considered to be available, and thus, dc(1) can turn on TTY mode, subject to some @@ -1271,53 +1364,49 @@ settings. .PP If there is the environment variable \f[B]DC_TTY_MODE\f[R] in the environment (see the \f[B]ENVIRONMENT VARIABLES\f[R] section), then if -that environment variable contains a non-zero integer, dc(1) will turn +that environment variable contains a non\-zero integer, dc(1) will turn on TTY mode when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all connected to a TTY. If the \f[B]DC_TTY_MODE\f[R] environment variable exists but is -\f[I]not\f[R] a non-zero integer, then dc(1) will not turn TTY mode on. +\f[I]not\f[R] a non\-zero integer, then dc(1) will not turn TTY mode on. .PP If the environment variable \f[B]DC_TTY_MODE\f[R] does \f[I]not\f[R] exist, the default setting is used. -The default setting can be queried with the \f[B]-h\f[R] or -\f[B]--help\f[R] options. +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. -.SS Command-Line History -.PP -Command-line history is only enabled if TTY mode is, i.e., that +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 +Command\-line history is only enabled if TTY mode is, i.e., that \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are connected to a TTY and the \f[B]DC_TTY_MODE\f[R] environment variable (see the \f[B]ENVIRONMENT VARIABLES\f[R] section) and its default do not disable TTY mode. See the \f[B]COMMAND LINE HISTORY\f[R] section for more information. .SS Prompt -.PP If TTY mode is available, then a prompt can be enabled. Like TTY mode itself, it can be turned on or off with an environment variable: \f[B]DC_PROMPT\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). .PP -If the environment variable \f[B]DC_PROMPT\f[R] exists and is a non-zero -integer, then the prompt is turned on when \f[B]stdin\f[R], +If the environment variable \f[B]DC_PROMPT\f[R] exists and is a +non\-zero integer, then the prompt is turned on when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are connected to a TTY and the -\f[B]-P\f[R] and \f[B]--no-prompt\f[R] options were not used. +\f[B]\-P\f[R] and \f[B]\-\-no\-prompt\f[R] options were not used. The read prompt will be turned on under the same conditions, except that -the \f[B]-R\f[R] and \f[B]--no-read-prompt\f[R] options must also not be -used. +the \f[B]\-R\f[R] and \f[B]\-\-no\-read\-prompt\f[R] options must also +not be used. .PP However, if \f[B]DC_PROMPT\f[R] does not exist, the prompt can be enabled or disabled with the \f[B]DC_TTY_MODE\f[R] environment variable, -the \f[B]-P\f[R] and \f[B]--no-prompt\f[R] options, and the \f[B]-R\f[R] -and \f[B]--no-read-prompt\f[R] options. +the \f[B]\-P\f[R] and \f[B]\-\-no\-prompt\f[R] options, and the +\f[B]\-R\f[R] and \f[B]\-\-no\-read\-prompt\f[R] options. See the \f[B]ENVIRONMENT VARIABLES\f[R] and \f[B]OPTIONS\f[R] sections for more details. .SH SIGNAL HANDLING -.PP Sending a \f[B]SIGINT\f[R] will cause dc(1) to do one of two things. .PP If dc(1) is not in interactive mode (see the \f[B]INTERACTIVE MODE\f[R] @@ -1326,7 +1415,7 @@ section), or the \f[B]DC_SIGINT_RESET\f[R] environment variable (see the an integer or it is zero, dc(1) will exit. .PP However, if dc(1) is in interactive mode, and the -\f[B]DC_SIGINT_RESET\f[R] or its default is an integer and non-zero, +\f[B]DC_SIGINT_RESET\f[R] or its default is an integer and non\-zero, then dc(1) will stop executing the current input and reset (see the \f[B]RESET\f[R] section) upon receiving a \f[B]SIGINT\f[R]. .PP @@ -1352,12 +1441,11 @@ The one exception is \f[B]SIGHUP\f[R]; in that case, and only when dc(1) is in TTY mode (see the \f[B]TTY MODE\f[R] section), a \f[B]SIGHUP\f[R] will cause dc(1) to clean up and exit. .SH COMMAND LINE HISTORY -.PP -dc(1) supports interactive command-line editing. +dc(1) supports interactive command\-line editing. .PP If dc(1) can be in TTY mode (see the \f[B]TTY MODE\f[R] section), history can be enabled. -This means that command-line history can only be enabled when +This means that command\-line history can only be enabled when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all connected to a TTY. .PP @@ -1367,23 +1455,20 @@ section). .PP \f[B]Note\f[R]: tabs are converted to 8 spaces. .SH LOCALES -.PP This dc(1) ships with support for adding error messages for different locales and thus, supports \f[B]LC_MESSAGES\f[R]. .SH SEE ALSO -.PP bc(1) .SH STANDARDS -.PP -The dc(1) utility operators are compliant with the operators in the IEEE -Std 1003.1-2017 (\[lq]POSIX.1-2017\[rq]) specification at -https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html for -bc(1). +The dc(1) utility operators and some behavior are compliant with the +operators in the IEEE Std 1003.1\-2017 (\[lq]POSIX.1\-2017\[rq]) bc(1) +specification at +https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html . .SH BUGS -.PP None are known. -Report bugs at https://git.yzena.com/gavin/bc. +Report bugs at https://git.gavinhoward.com/gavin/bc . .SH AUTHOR -.PP -Gavin D. -Howard <gavin@yzena.com> and contributors. +Gavin D. Howard \c +.MT gavin@gavinhoward.com +.ME \c +\ and contributors. diff --git a/contrib/bc/manuals/dc/E.1.md b/contrib/bc/manuals/dc/E.1.md index f854cbba874b..54b877999d0d 100644 --- a/contrib/bc/manuals/dc/E.1.md +++ b/contrib/bc/manuals/dc/E.1.md @@ -2,7 +2,7 @@ SPDX-License-Identifier: BSD-2-Clause -Copyright (c) 2018-2021 Gavin D. Howard and contributors. +Copyright (c) 2018-2024 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** - -: Prints a usage message and quits. - -**-v**, **-V**, **-\-version** - -: Print the version information (copyright header) and exit. - -**-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). +**-C**, **-\-no-digit-clamp** - This is a **non-portable extension**. - -**-P**, **-\-no-prompt** +: Disables clamping of digits greater than or equal to the current **ibase** + when parsing numbers. -: 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 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. - This option does not disable the regular prompt because the read prompt is - only used when the **?** command is used. + If this and/or the **-c** or **-\-digit-clamp** options are given multiple + times, the last one given 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 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**. -**-x** **-\-extended-register** - -: Enables extended register mode. See the *Extended Register Mode* subsection - of the **REGISTERS** section for more information. +**-c**, **-\-digit-clamp** - This is a **non-portable extension**. +: Enables clamping of digits greater than or equal to the current **ibase** + when parsing numbers. -**-z**, **-\-leading-zeroes** + 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. -: Makes dc(1) print all numbers greater than **-1** and less than **1**, and - not equal to **0**, with a leading zero. + If this and/or the **-C** or **-\-no-digit-clamp** options are given + multiple times, the last one given is used. - 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,24 @@ 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 is a **non-portable extension**. + All long options are **non-portable extensions**. # STDIN @@ -263,15 +296,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**. - -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**. +Uppercase letters are equal to **9** plus 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** (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 +827,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 +851,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) @@ -840,6 +914,12 @@ other character produces a parse error (see the **ERRORS** section). : Pushes the line length set by **DC_LINE_LENGTH** (see the **ENVIRONMENT VARIABLES** section) onto the stack. +**gx** + +: Pushes **1** onto the stack if extended register mode is on, **0** + otherwise. See the *Extended Register Mode* subsection of the **REGISTERS** + section for more information. + **gz** : Pushes **0** onto the stack if the leading zero setting has not been enabled @@ -881,11 +961,14 @@ the next non-space characters do not match that regex. When dc(1) encounters an error or a signal that it has a non-default handler for, it resets. This means that several things happen. -First, any macros that are executing are stopped and popped off the stack. -The behavior is not unlike that of exceptions in programming languages. Then -the execution point is set so that any code waiting to execute (after all +First, any macros that are executing are stopped and popped off the execution +stack. The behavior is not unlike that of exceptions in programming languages. +Then the execution point is set so that any code waiting to execute (after all macros returned) is skipped. +However, the stack of values is *not* cleared; in interactive mode, users can +inspect the stack and manipulate it. + Thus, when dc(1) resets, it skips any remaining code waiting to be executed. Then, if it is interactive mode, and the error was not a fatal error (see the **EXIT STATUS** section), it asks for more input; otherwise, it exits with the @@ -974,7 +1057,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 +1147,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 +1256,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,14 +1340,14 @@ 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.gavinhoward.com/gavin/bc . # AUTHOR -Gavin D. Howard <gavin@yzena.com> and contributors. +Gavin D. Howard <gavin@gavinhoward.com> and contributors. diff --git a/contrib/bc/manuals/dc/EH.1 b/contrib/bc/manuals/dc/EH.1 index 96cb156e789f..61fbaa4efe92 100644 --- a/contrib/bc/manuals/dc/EH.1 +++ b/contrib/bc/manuals/dc/EH.1 @@ -1,7 +1,7 @@ .\" .\" SPDX-License-Identifier: BSD-2-Clause .\" -.\" Copyright (c) 2018-2021 Gavin D. Howard and contributors. +.\" Copyright (c) 2018-2024 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,124 +25,82 @@ .\" 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" "August 2024" "Gavin D. Howard" "General Commands Manual" .nh .ad l .SH Name -.PP -dc - arbitrary-precision decimal reverse-Polish notation calculator +dc \- arbitrary\-precision decimal reverse\-Polish notation calculator .SH SYNOPSIS -.PP -\f[B]dc\f[R] [\f[B]-hiPRvVx\f[R]] [\f[B]--version\f[R]] -[\f[B]--help\f[R]] [\f[B]--interactive\f[R]] [\f[B]--no-prompt\f[R]] -[\f[B]--no-read-prompt\f[R]] [\f[B]--extended-register\f[R]] -[\f[B]-e\f[R] \f[I]expr\f[R]] -[\f[B]--expression\f[R]=\f[I]expr\f[R]\&...] [\f[B]-f\f[R] -\f[I]file\f[R]\&...] [\f[B]--file\f[R]=\f[I]file\f[R]\&...] +\f[B]dc\f[R] [\f[B]\-cChiPRvVx\f[R]] [\f[B]\-\-version\f[R]] +[\f[B]\-\-help\f[R]] [\f[B]\-\-digit\-clamp\f[R]] +[\f[B]\-\-no\-digit\-clamp\f[R]] [\f[B]\-\-interactive\f[R]] +[\f[B]\-\-no\-prompt\f[R]] [\f[B]\-\-no\-read\-prompt\f[R]] +[\f[B]\-\-extended\-register\f[R]] [\f[B]\-e\f[R] \f[I]expr\f[R]] +[\f[B]\-\-expression\f[R]=\f[I]expr\f[R]\&...] +[\f[B]\-f\f[R] \f[I]file\f[R]\&...] +[\f[B]\-\-file\f[R]=\f[I]file\f[R]\&...] [\f[I]file\f[R]\&...] .SH DESCRIPTION -.PP -dc(1) is an arbitrary-precision calculator. +dc(1) is an arbitrary\-precision calculator. It uses a stack (reverse Polish notation) to store numbers and results of computations. Arithmetic operations pop arguments off of the stack and push the results. .PP -If no files are given on the command-line, then dc(1) reads from +If no files are given on the command\-line, then dc(1) reads from \f[B]stdin\f[R] (see the \f[B]STDIN\f[R] section). Otherwise, those files are processed, and dc(1) will then exit. .PP If a user wants to set up a standard environment, they can use \f[B]DC_ENV_ARGS\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). For example, if a user wants the \f[B]scale\f[R] always set to -\f[B]10\f[R], they can set \f[B]DC_ENV_ARGS\f[R] to \f[B]-e 10k\f[R], +\f[B]10\f[R], they can set \f[B]DC_ENV_ARGS\f[R] to \f[B]\-e 10k\f[R], and this dc(1) will always start with a \f[B]scale\f[R] of \f[B]10\f[R]. .SH OPTIONS -.PP The following are the options that dc(1) accepts. .TP -\f[B]-h\f[R], \f[B]--help\f[R] -Prints a usage message and quits. -.TP -\f[B]-v\f[R], \f[B]-V\f[R], \f[B]--version\f[R] -Print the version information (copyright header) and exit. -.TP -\f[B]-i\f[R], \f[B]--interactive\f[R] -Forces interactive mode. -(See the \f[B]INTERACTIVE MODE\f[R] section.) +\f[B]\-C\f[R], \f[B]\-\-no\-digit\-clamp\f[R] +Disables clamping of digits greater than or equal to the current +\f[B]ibase\f[R] when parsing numbers. .RS .PP -This is a \f[B]non-portable extension\f[R]. -.RE -.TP -\f[B]-L\f[R], \f[B]--no-line-length\f[R] -Disables line length checking and prints numbers without backslashes and -newlines. -In other words, this option sets \f[B]BC_LINE_LENGTH\f[R] to \f[B]0\f[R] -(see the \f[B]ENVIRONMENT VARIABLES\f[R] section). -.RS +This means that the value added to a number from a digit is always that +digit\[cq]s value multiplied by the value of ibase raised to the power +of the digit\[cq]s position, which starts from 0 at the least +significant digit. .PP -This is a \f[B]non-portable extension\f[R]. -.RE -.TP -\f[B]-P\f[R], \f[B]--no-prompt\f[R] -Disables the prompt in TTY mode. -(The prompt is only enabled in TTY mode. -See the \f[B]TTY MODE\f[R] section.) This is mostly for those users that -do not want a prompt or are not used to having them in dc(1). -Most of those users would want to put this option in -\f[B]DC_ENV_ARGS\f[R]. -.RS +If this and/or the \f[B]\-c\f[R] or \f[B]\-\-digit\-clamp\f[R] options +are given multiple times, the last one given is used. .PP -These options override the \f[B]DC_PROMPT\f[R] and \f[B]DC_TTY_MODE\f[R] -environment variables (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). +This option overrides the \f[B]DC_DIGIT_CLAMP\f[R] environment variable +(see the \f[B]ENVIRONMENT VARIABLES\f[R] section) and the default, which +can be queried with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-R\f[R], \f[B]--no-read-prompt\f[R] -Disables the read prompt in TTY mode. -(The read prompt is only enabled in TTY mode. -See the \f[B]TTY MODE\f[R] section.) This is mostly for those users that -do not want a read prompt or are not used to having them in dc(1). -Most of those users would want to put this option in -\f[B]BC_ENV_ARGS\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). -This option is also useful in hash bang lines of dc(1) scripts that -prompt for user input. +\f[B]\-c\f[R], \f[B]\-\-digit\-clamp\f[R] +Enables clamping of digits greater than or equal to the current +\f[B]ibase\f[R] when parsing numbers. .RS .PP -This option does not disable the regular prompt because the read prompt -is only used when the \f[B]?\f[R] command is used. -.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 +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 -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 +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 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]. +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] +\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 @@ -151,41 +109,44 @@ 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 +If this option is given on the command\-line (i.e., not in \f[B]DC_ENV_ARGS\f[R], see the \f[B]ENVIRONMENT VARIABLES\f[R] section), then after processing all expressions and files, dc(1) will exit, unless -\f[B]-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to -\f[B]-f\f[R] or \f[B]--file\f[R], whether on the command-line or in +\f[B]\-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to +\f[B]\-f\f[R] or \f[B]\-\-file\f[R], whether on the command\-line or in \f[B]DC_ENV_ARGS\f[R]. -However, if any other \f[B]-e\f[R], \f[B]--expression\f[R], -\f[B]-f\f[R], or \f[B]--file\f[R] arguments are given after -\f[B]-f-\f[R] or equivalent is given, dc(1) will give a fatal error and -exit. +However, if any other \f[B]\-e\f[R], \f[B]\-\-expression\f[R], +\f[B]\-f\f[R], or \f[B]\-\-file\f[R] arguments are given after +\f[B]\-f\-\f[R] or equivalent is given, dc(1) will give a fatal error +and exit. .PP -This is a \f[B]non-portable extension\f[R]. +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] +\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 +If this option is given on the command\-line (i.e., not in \f[B]DC_ENV_ARGS\f[R], see the \f[B]ENVIRONMENT VARIABLES\f[R] section), then after processing all expressions and files, dc(1) will exit, unless -\f[B]-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to -\f[B]-f\f[R] or \f[B]--file\f[R]. -However, if any other \f[B]-e\f[R], \f[B]--expression\f[R], -\f[B]-f\f[R], or \f[B]--file\f[R] arguments are given after -\f[B]-f-\f[R] or equivalent is given, dc(1) will give a fatal error and -exit. +\f[B]\-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to +\f[B]\-f\f[R] or \f[B]\-\-file\f[R]. +However, if any other \f[B]\-e\f[R], \f[B]\-\-expression\f[R], +\f[B]\-f\f[R], or \f[B]\-\-file\f[R] arguments are given after +\f[B]\-f\-\f[R] or equivalent is given, dc(1) will give a fatal error +and exit. .PP -This is a \f[B]non-portable extension\f[R]. +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] +\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. It is a fatal error if \f[I]ibase\f[R] is not a valid number. @@ -193,10 +154,28 @@ It is a fatal error if \f[I]ibase\f[R] is not a valid number. .PP If multiple instances of this option are given, the last is used. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-O\f[R] \f[I]obase\f[R], \f[B]--obase\f[R]=\f[I]obase\f[R] +\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. It is a fatal error if \f[I]obase\f[R] is not a valid number. @@ -204,10 +183,48 @@ It is a fatal error if \f[I]obase\f[R] is not a valid number. .PP If multiple instances of this option are given, the last is used. .PP -This is a \f[B]non-portable extension\f[R]. +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]-S\f[R] \f[I]scale\f[R], \f[B]--scale\f[R]=\f[I]scale\f[R] +\f[B]\-R\f[R], \f[B]\-\-no\-read\-prompt\f[R] +Disables the read prompt in TTY mode. +(The read prompt is only enabled in TTY mode. +See the \f[B]TTY MODE\f[R] section.) +This is mostly for those users that do not want a read prompt or are not +used to having them in dc(1). +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. It is a fatal error if \f[I]scale\f[R] is not a valid number. @@ -215,15 +232,34 @@ It is a fatal error if \f[I]scale\f[R] is not a valid number. .PP If multiple instances of this option are given, the last is used. .PP -This is a \f[B]non-portable extension\f[R]. +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 -All long options are \f[B]non-portable extensions\f[R]. -.SH STDIN +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 -If no files are given on the command-line and no files or expressions -are given by the \f[B]-f\f[R], \f[B]--file\f[R], \f[B]-e\f[R], or -\f[B]--expression\f[R] options, then dc(1) reads from \f[B]stdin\f[R]. +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 +If no files are given on the command\-line and no files or expressions +are given by the \f[B]\-f\f[R], \f[B]\-\-file\f[R], \f[B]\-e\f[R], or +\f[B]\-\-expression\f[R] options, then dc(1) reads from \f[B]stdin\f[R]. .PP However, there is a caveat to this. .PP @@ -233,8 +269,7 @@ ended. This means that, except for escaped brackets, all brackets must be balanced before dc(1) parses and executes. .SH STDOUT -.PP -Any non-error output is written to \f[B]stdout\f[R]. +Any non\-error output is written to \f[B]stdout\f[R]. In addition, if history (see the \f[B]HISTORY\f[R] section) and the prompt (see the \f[B]TTY MODE\f[R] section) are enabled, both are output to \f[B]stdout\f[R]. @@ -242,7 +277,7 @@ to \f[B]stdout\f[R]. \f[B]Note\f[R]: Unlike other dc(1) implementations, this dc(1) will issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot write to \f[B]stdout\f[R], so if \f[B]stdout\f[R] is closed, as in -\f[B]dc >&-\f[R], it will quit with an error. +\f[B]dc >&\-\f[R], it will quit with an error. This is done so that dc(1) can report problems when \f[B]stdout\f[R] is redirected to a file. .PP @@ -250,13 +285,12 @@ If there are scripts that depend on the behavior of other dc(1) implementations, it is recommended that those scripts be changed to redirect \f[B]stdout\f[R] to \f[B]/dev/null\f[R]. .SH STDERR -.PP Any error output is written to \f[B]stderr\f[R]. .PP \f[B]Note\f[R]: Unlike other dc(1) implementations, this dc(1) will issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot write to \f[B]stderr\f[R], so if \f[B]stderr\f[R] is closed, as in -\f[B]dc 2>&-\f[R], it will quit with an error. +\f[B]dc 2>&\-\f[R], it will quit with an error. This is done so that dc(1) can exit with an error code when \f[B]stderr\f[R] is redirected to a file. .PP @@ -264,7 +298,6 @@ If there are scripts that depend on the behavior of other dc(1) implementations, it is recommended that those scripts be changed to redirect \f[B]stderr\f[R] to \f[B]/dev/null\f[R]. .SH SYNTAX -.PP Each item in the input source code, either a number (see the \f[B]NUMBERS\f[R] section) or a command (see the \f[B]COMMANDS\f[R] section), is processed and executed, in order. @@ -299,30 +332,57 @@ precision of any operations (with exceptions). The max allowable value for \f[B]scale\f[R] can be queried in dc(1) programs with the \f[B]V\f[R] command. .SS Comments -.PP Comments go from \f[B]#\f[R] until, and not including, the next newline. -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .SH NUMBERS -.PP Numbers are strings made up of digits, uppercase letters up to \f[B]F\f[R], and at most \f[B]1\f[R] period for a radix. Numbers can have up to \f[B]DC_NUM_MAX\f[R] digits. -Uppercase letters are equal to \f[B]9\f[R] + their position in the +Uppercase letters are equal to \f[B]9\f[R] plus their position in the alphabet (i.e., \f[B]A\f[R] equals \f[B]10\f[R], or \f[B]9+1\f[R]). -If a digit or letter makes no sense with the current value of -\f[B]ibase\f[R], they are set to the value of the highest valid digit in -\f[B]ibase\f[R]. .PP -Single-character numbers (i.e., \f[B]A\f[R] alone) take the value that -they would have if they were valid digits, regardless of the value of -\f[B]ibase\f[R]. +If a digit or letter makes no sense with the current value of +\f[B]ibase\f[R] (i.e., they are greater than or equal to the current +value of \f[B]ibase\f[R]), then the behavior depends on the existence of +the \f[B]\-c\f[R]/\f[B]\-\-digit\-clamp\f[R] or +\f[B]\-C\f[R]/\f[B]\-\-no\-digit\-clamp\f[R] options (see the +\f[B]OPTIONS\f[R] section), the existence and setting of the +\f[B]DC_DIGIT_CLAMP\f[R] environment variable (see the \f[B]ENVIRONMENT +VARIABLES\f[R] section), or the default, which can be queried with the +\f[B]\-h\f[R]/\f[B]\-\-help\f[R] option. +.PP +If clamping is off, then digits or letters that are greater than or +equal to the current value of \f[B]ibase\f[R] are not changed. +Instead, their given value is multiplied by the appropriate power of +\f[B]ibase\f[R] and added into the number. +This means that, with an \f[B]ibase\f[R] of \f[B]3\f[R], the number +\f[B]AB\f[R] is equal to \f[B]3\[ha]1*A+3\[ha]0*B\f[R], which is +\f[B]3\f[R] times \f[B]10\f[R] plus \f[B]11\f[R], or \f[B]41\f[R]. +.PP +If clamping is on, then digits or letters that are greater than or equal +to the current value of \f[B]ibase\f[R] are set to the value of the +highest valid digit in \f[B]ibase\f[R] before being multiplied by the +appropriate power of \f[B]ibase\f[R] and added into the number. +This means that, with an \f[B]ibase\f[R] of \f[B]3\f[R], the number +\f[B]AB\f[R] is equal to \f[B]3\[ha]1*2+3\[ha]0*2\f[R], which is +\f[B]3\f[R] times \f[B]2\f[R] plus \f[B]2\f[R], or \f[B]8\f[R]. +.PP +There is one exception to clamping: single\-character numbers (i.e., +\f[B]A\f[R] alone). +Such numbers are never clamped and always take the value they would have +in the highest possible \f[B]ibase\f[R]. This means that \f[B]A\f[R] alone always equals decimal \f[B]10\f[R] and -\f[B]F\f[R] alone always equals decimal \f[B]15\f[R]. +\f[B]Z\f[R] alone always equals decimal \f[B]35\f[R]. +This behavior is mandated by the standard for bc(1) (see the STANDARDS +section) and is meant to provide an easy way to set the current +\f[B]ibase\f[R] (with the \f[B]i\f[R] command) regardless of the current +value of \f[B]ibase\f[R]. +.PP +If clamping is on, and the clamped value of a character is needed, use a +leading zero, i.e., for \f[B]A\f[R], use \f[B]0A\f[R]. .SH COMMANDS -.PP The valid commands are listed below. .SS Printing -.PP These commands are used for printing. .TP \f[B]p\f[R] @@ -343,12 +403,12 @@ Pops a value off the stack. .PP If the value is a number, it is truncated and the absolute value of the result is printed as though \f[B]obase\f[R] is \f[B]256\f[R] and each -digit is interpreted as an 8-bit ASCII character, making it a byte +digit is interpreted as an 8\-bit ASCII character, making it a byte stream. .PP If the value is a string, it is printed without a trailing newline. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]f\f[R] @@ -359,7 +419,6 @@ without altering anything. Users should use this command when they get lost. .RE .SS Arithmetic -.PP These are the commands used for arithmetic. .TP \f[B]+\f[R] @@ -368,7 +427,7 @@ pushed onto the stack. The \f[I]scale\f[R] of the result is equal to the max \f[I]scale\f[R] of both operands. .TP -\f[B]-\f[R] +\f[B]\-\f[R] The top two values are popped off the stack, subtracted, and the result is pushed onto the stack. The \f[I]scale\f[R] of the result is equal to the max \f[I]scale\f[R] of @@ -389,7 +448,7 @@ pushed onto the stack. The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R]. .RS .PP -The first value popped off of the stack must be non-zero. +The first value popped off of the stack must be non\-zero. .RE .TP \f[B]%\f[R] @@ -399,10 +458,10 @@ is pushed onto the stack. .PP Remaindering is equivalent to 1) Computing \f[B]a/b\f[R] to current \f[B]scale\f[R], and 2) Using the result of step 1 to calculate -\f[B]a-(a/b)*b\f[R] to \f[I]scale\f[R] +\f[B]a\-(a/b)*b\f[R] to \f[I]scale\f[R] \f[B]max(scale+scale(b),scale(a))\f[R]. .PP -The first value popped off of the stack must be non-zero. +The first value popped off of the stack must be non\-zero. .RE .TP \f[B]\[ti]\f[R] @@ -413,9 +472,9 @@ This is equivalent to \f[B]x y / x y %\f[R] except that \f[B]x\f[R] and \f[B]y\f[R] are only evaluated once. .RS .PP -The first value popped off of the stack must be non-zero. +The first value popped off of the stack must be non\-zero. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]\[ha]\f[R] @@ -426,7 +485,7 @@ The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R]. .PP The first value popped off of the stack must be an integer, and if that value is negative, the second value popped off of the stack must be -non-zero. +non\-zero. .RE .TP \f[B]v\f[R] @@ -435,7 +494,7 @@ the result is pushed onto the stack. The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R]. .RS .PP -The value popped off of the stack must be non-negative. +The value popped off of the stack must be non\-negative. .RE .TP \f[B]_\f[R] @@ -445,7 +504,7 @@ or other commands), then that number is input as a negative number. .PP Otherwise, the top value on the stack is popped and copied, and the copy is negated and pushed onto the stack. -This behavior without a number is a \f[B]non-portable extension\f[R]. +This behavior without a number is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]b\f[R] @@ -454,7 +513,7 @@ back onto the stack. Otherwise, its absolute value is pushed onto the stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]|\f[R] @@ -463,12 +522,12 @@ is computed, and the result is pushed onto the stack. .RS .PP The first value popped is used as the reduction modulus and must be an -integer and non-zero. +integer and non\-zero. The second value popped is used as the exponent and must be an integer -and non-negative. +and non\-negative. The third value popped is the base and must be an integer. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]G\f[R] @@ -476,7 +535,7 @@ The top two values are popped off of the stack, they are compared, and a \f[B]1\f[R] is pushed if they are equal, or \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]N\f[R] @@ -484,7 +543,7 @@ The top value is popped off of the stack, and if it a \f[B]0\f[R], a \f[B]1\f[R] is pushed; otherwise, a \f[B]0\f[R] is pushed. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B](\f[R] @@ -493,7 +552,7 @@ The top two values are popped off of the stack, they are compared, and a \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]{\f[R] @@ -502,7 +561,7 @@ The top two values are popped off of the stack, they are compared, and a or \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B])\f[R] @@ -511,7 +570,7 @@ The top two values are popped off of the stack, they are compared, and a \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]}\f[R] @@ -520,36 +579,35 @@ The top two values are popped off of the stack, they are compared, and a second, or \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]M\f[R] The top two values are popped off of the stack. -If they are both non-zero, a \f[B]1\f[R] is pushed onto the stack. +If they are both non\-zero, a \f[B]1\f[R] is pushed onto the stack. If either of them is zero, or both of them are, then a \f[B]0\f[R] is pushed onto the stack. .RS .PP This is like the \f[B]&&\f[R] operator in bc(1), and it is \f[I]not\f[R] -a short-circuit operator. +a short\-circuit operator. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]m\f[R] The top two values are popped off of the stack. -If at least one of them is non-zero, a \f[B]1\f[R] is pushed onto the +If at least one of them is non\-zero, a \f[B]1\f[R] is pushed onto the stack. If both of them are zero, then a \f[B]0\f[R] is pushed onto the stack. .RS .PP This is like the \f[B]||\f[R] operator in bc(1), and it is \f[I]not\f[R] -a short-circuit operator. +a short\-circuit operator. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .SS Stack Control -.PP These commands control the stack. .TP \f[B]c\f[R] @@ -565,7 +623,6 @@ Swaps (\[lq]reverses\[rq]) the two top items on the stack. \f[B]R\f[R] Pops (\[lq]removes\[rq]) the top value from the stack. .SS Register Control -.PP These commands control registers (see the \f[B]REGISTERS\f[R] section). .TP \f[B]s\f[R]\f[I]r\f[R] @@ -587,7 +644,6 @@ push it onto the main stack. The previous value in the stack for register \f[I]r\f[R], if any, is now accessible via the \f[B]l\f[R]\f[I]r\f[R] command. .SS Parameters -.PP These commands control the values of \f[B]ibase\f[R], \f[B]obase\f[R], and \f[B]scale\f[R]. Also see the \f[B]SYNTAX\f[R] section. @@ -614,7 +670,7 @@ If the value on top of the stack has any \f[I]scale\f[R], the .TP \f[B]k\f[R] Pops the value off of the top of the stack and uses it to set -\f[B]scale\f[R], which must be non-negative. +\f[B]scale\f[R], which must be non\-negative. .RS .PP If the value on top of the stack has any \f[I]scale\f[R], the @@ -635,7 +691,7 @@ Pushes the maximum allowable value of \f[B]ibase\f[R] onto the main stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]U\f[R] @@ -643,7 +699,7 @@ Pushes the maximum allowable value of \f[B]obase\f[R] onto the main stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]V\f[R] @@ -651,10 +707,9 @@ Pushes the maximum allowable value of \f[B]scale\f[R] onto the main stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .SS Strings -.PP The following commands control strings. .PP dc(1) can work with both numbers and strings, and registers (see the @@ -692,16 +747,16 @@ The value on top of the stack is popped. If it is a number, it is truncated and its absolute value is taken. The result mod \f[B]256\f[R] is calculated. If that result is \f[B]0\f[R], push an empty string; otherwise, push a -one-character string where the character is the result of the mod +one\-character string where the character is the result of the mod interpreted as an ASCII character. .PP If it is a string, then a new string is made. If the original string is empty, the new string is empty. If it is not, then the first character of the original string is used to -create the new string as a one-character string. +create the new string as a one\-character string. The new string is then pushed onto the stack. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]x\f[R] @@ -737,7 +792,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]!>\f[R]\f[I]r\f[R] @@ -758,7 +813,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]<\f[R]\f[I]r\f[R] @@ -779,7 +834,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]!<\f[R]\f[I]r\f[R] @@ -800,7 +855,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]=\f[R]\f[I]r\f[R] @@ -821,7 +876,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]!=\f[R]\f[I]r\f[R] @@ -842,7 +897,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]?\f[R] @@ -855,7 +910,7 @@ the execution of the macro that executed it. If there are no macros, or only one macro executing, dc(1) exits. .TP \f[B]Q\f[R] -Pops a value from the stack which must be non-negative and is used the +Pops a value from the stack which must be non\-negative and is used the number of macro executions to pop off of the execution stack. If the number of levels to pop is greater than the number of executing macros, dc(1) exits. @@ -866,8 +921,11 @@ The execution stack is the stack of string executions. The number that is pushed onto the stack is exactly as many as is needed to make dc(1) exit with the \f[B]Q\f[R] command, so the sequence \f[B],Q\f[R] will make dc(1) exit. -.SS Status +.RS .PP +This is a \f[B]non\-portable extension\f[R]. +.RE +.SS Status These commands query status of the stack or its top value. .TP \f[B]Z\f[R] @@ -892,6 +950,24 @@ stack. If it is a string, pushes \f[B]0\f[R]. .RE .TP +\f[B]u\f[R] +Pops one value off of the stack. +If the value is a number, this pushes \f[B]1\f[R] onto the stack. +Otherwise (if it is a string), it pushes \f[B]0\f[R]. +.RS +.PP +This is a \f[B]non\-portable extension\f[R]. +.RE +.TP +\f[B]t\f[R] +Pops one value off of the stack. +If the value is a string, this pushes \f[B]1\f[R] onto the stack. +Otherwise (if it is a number), it pushes \f[B]0\f[R]. +.RS +.PP +This is a \f[B]non\-portable extension\f[R]. +.RE +.TP \f[B]z\f[R] Pushes the current depth of the stack (before execution of this command) onto the stack. @@ -907,10 +983,9 @@ register\[cq]s stack must always have at least one item; dc(1) will give an error and reset otherwise (see the \f[B]RESET\f[R] section). This means that this command will never push \f[B]0\f[R]. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .SS Arrays -.PP These commands manipulate arrays. .TP \f[B]:\f[R]\f[I]r\f[R] @@ -927,10 +1002,9 @@ The selected value is then pushed onto the stack. Pushes the length of the array \f[I]r\f[R] onto the stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .SS Global Settings -.PP These commands retrieve global settings. These are the only commands that require multiple specific characters, and all of them begin with the letter \f[B]g\f[R]. @@ -942,12 +1016,17 @@ section). Pushes the line length set by \f[B]DC_LINE_LENGTH\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section) onto the stack. .TP +\f[B]gx\f[R] +Pushes \f[B]1\f[R] onto the stack if extended register mode is on, +\f[B]0\f[R] otherwise. +See the \f[I]Extended Register Mode\f[R] subsection of the +\f[B]REGISTERS\f[R] section for more information. +.TP \f[B]gz\f[R] Pushes \f[B]0\f[R] onto the stack if the leading zero setting has not -been enabled with the \f[B]-z\f[R] or \f[B]--leading-zeroes\f[R] options -(see the \f[B]OPTIONS\f[R] section), non-zero otherwise. +been enabled with the \f[B]\-z\f[R] or \f[B]\-\-leading\-zeroes\f[R] +options (see the \f[B]OPTIONS\f[R] section), non\-zero otherwise. .SH REGISTERS -.PP Registers are names that can store strings, numbers, and arrays. (Number/string registers do not interfere with array registers.) .PP @@ -957,45 +1036,45 @@ All registers, when first referenced, have one value (\f[B]0\f[R]) in their stack, and it is a runtime error to attempt to pop that item off of the register stack. .PP -In non-extended register mode, a register name is just the single +In non\-extended register mode, a register name is just the single character that follows any command that needs a register name. The only exceptions are: a newline (\f[B]`\[rs]n'\f[R]) and a left bracket (\f[B]`['\f[R]); it is a parse error for a newline or a left bracket to be used as a register name. .SS Extended Register Mode -.PP Unlike most other dc(1) implentations, this dc(1) provides nearly unlimited amounts of registers, if extended register mode is enabled. .PP -If extended register mode is enabled (\f[B]-x\f[R] or -\f[B]--extended-register\f[R] command-line arguments are given), then -normal single character registers are used \f[I]unless\f[R] the +If extended register mode is enabled (\f[B]\-x\f[R] or +\f[B]\-\-extended\-register\f[R] command\-line arguments are given), +then normal single character registers are used \f[I]unless\f[R] the character immediately following a command that needs a register name is a space (according to \f[B]isspace()\f[R]) and not a newline (\f[B]`\[rs]n'\f[R]). .PP In that case, the register name is found according to the regex -\f[B][a-z][a-z0-9_]*\f[R] (like bc(1) identifiers), and it is a parse -error if the next non-space characters do not match that regex. +\f[B][a\-z][a\-z0\-9_]*\f[R] (like bc(1) identifiers), and it is a parse +error if the next non\-space characters do not match that regex. .SH RESET -.PP -When dc(1) encounters an error or a signal that it has a non-default +When dc(1) encounters an error or a signal that it has a non\-default handler for, it resets. This means that several things happen. .PP First, any macros that are executing are stopped and popped off the -stack. +execution stack. The behavior is not unlike that of exceptions in programming languages. Then the execution point is set so that any code waiting to execute (after all macros returned) is skipped. .PP +However, the stack of values is \f[I]not\f[R] cleared; in interactive +mode, users can inspect the stack and manipulate it. +.PP Thus, when dc(1) resets, it skips any remaining code waiting to be executed. Then, if it is interactive mode, and the error was not a fatal error (see the \f[B]EXIT STATUS\f[R] section), it asks for more input; otherwise, it exits with the appropriate return code. .SH PERFORMANCE -.PP Most dc(1) implementations use \f[B]char\f[R] types to calculate the value of \f[B]1\f[R] decimal digit at a time, but that can be slow. This dc(1) does something different. @@ -1015,7 +1094,6 @@ checking. This integer type depends on the value of \f[B]DC_LONG_BIT\f[R], but is always at least twice as large as the integer type used to store digits. .SH LIMITS -.PP The following are the limits on dc(1): .TP \f[B]DC_LONG_BIT\f[R] @@ -1045,24 +1123,24 @@ Set at \f[B]DC_BASE_POW\f[R]. .TP \f[B]DC_DIM_MAX\f[R] The maximum size of arrays. -Set at \f[B]SIZE_MAX-1\f[R]. +Set at \f[B]SIZE_MAX\-1\f[R]. .TP \f[B]DC_SCALE_MAX\f[R] The maximum \f[B]scale\f[R]. -Set at \f[B]DC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]DC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]DC_STRING_MAX\f[R] The maximum length of strings. -Set at \f[B]DC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]DC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]DC_NAME_MAX\f[R] The maximum length of identifiers. -Set at \f[B]DC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]DC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]DC_NUM_MAX\f[R] The maximum length of a number (in decimal digits), which includes digits after the decimal point. -Set at \f[B]DC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]DC_OVERFLOW_MAX\-1\f[R]. .TP Exponent The maximum allowable exponent (positive or negative). @@ -1070,27 +1148,27 @@ Set at \f[B]DC_OVERFLOW_MAX\f[R]. .TP Number of vars The maximum number of vars/arrays. -Set at \f[B]SIZE_MAX-1\f[R]. +Set at \f[B]SIZE_MAX\-1\f[R]. .PP -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. +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 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). -They should be in the same format as all other command-line arguments. +This is another way to give command\-line arguments to dc(1). +They should be in the same format as all other command\-line arguments. These are always processed first, so any files given in \f[B]DC_ENV_ARGS\f[R] will be processed before arguments and files given -on the command-line. +on the command\-line. This gives the user the ability to set up \[lq]standard\[rq] options and files to be used at every invocation. The most useful thing for such files to contain would be useful functions that the user might want every time dc(1) runs. -Another use would be to use the \f[B]-e\f[R] option to set +Another use would be to use the \f[B]\-e\f[R] option to set \f[B]scale\f[R] to a value other than \f[B]0\f[R]. .RS .PP @@ -1108,14 +1186,14 @@ you can use double quotes as the outside quotes, as in \f[B]\[lq]some quotes. However, handling a file with both kinds of quotes in \f[B]DC_ENV_ARGS\f[R] is not supported due to the complexity of the -parsing, though such files are still supported on the command-line where -the parsing is done by the shell. +parsing, though such files are still supported on the command\-line +where the parsing is done by the shell. .RE .TP \f[B]DC_LINE_LENGTH\f[R] If this environment variable exists and contains an integer that is greater than \f[B]1\f[R] and is less than \f[B]UINT16_MAX\f[R] -(\f[B]2\[ha]16-1\f[R]), dc(1) will output lines to that length, +(\f[B]2\[ha]16\-1\f[R]), dc(1) will output lines to that length, including the backslash newline combo. The default line length is \f[B]70\f[R]. .RS @@ -1132,13 +1210,13 @@ exits on \f[B]SIGINT\f[R] when not in interactive mode. .RS .PP However, when dc(1) is in interactive mode, then if this environment -variable exists and contains an integer, a non-zero value makes dc(1) +variable exists and contains an integer, a non\-zero value makes dc(1) reset on \f[B]SIGINT\f[R], rather than exit, and zero makes dc(1) exit. If this environment variable exists and is \f[I]not\f[R] an integer, then dc(1) will exit on \f[B]SIGINT\f[R]. .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. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]DC_TTY_MODE\f[R] @@ -1147,11 +1225,11 @@ section), then this environment variable has no effect. .RS .PP However, when TTY mode is available, then if this environment variable -exists and contains an integer, then a non-zero value makes dc(1) use +exists and contains an integer, then a non\-zero value makes dc(1) use TTY mode, and zero makes dc(1) not use TTY mode. .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. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]DC_PROMPT\f[R] @@ -1160,30 +1238,46 @@ section), then this environment variable has no effect. .RS .PP However, when TTY mode is available, then if this environment variable -exists and contains an integer, a non-zero value makes dc(1) use a -prompt, and zero or a non-integer makes dc(1) not use a prompt. +exists and contains an integer, a non\-zero value makes dc(1) use a +prompt, and zero or a non\-integer makes dc(1) not use a prompt. If this environment variable does not exist and \f[B]DC_TTY_MODE\f[R] does, then the value of the \f[B]DC_TTY_MODE\f[R] environment variable is used. .PP This environment variable and the \f[B]DC_TTY_MODE\f[R] environment variable override the default, which can be queried with the -\f[B]-h\f[R] or \f[B]--help\f[R] options. +\f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]DC_EXPR_EXIT\f[R] -If any expressions or expression files are given on the command-line -with \f[B]-e\f[R], \f[B]--expression\f[R], \f[B]-f\f[R], or -\f[B]--file\f[R], then if this environment variable exists and contains -an integer, a non-zero value makes dc(1) exit after executing the -expressions and expression files, and a zero value makes dc(1) not exit. +If any expressions or expression files are given on the command\-line +with \f[B]\-e\f[R], \f[B]\-\-expression\f[R], \f[B]\-f\f[R], or +\f[B]\-\-file\f[R], then if this environment variable exists and +contains an integer, a non\-zero value makes dc(1) exit after executing +the expressions and expression files, and a zero value makes dc(1) not +exit. .RS .PP This environment variable overrides the default, which can be queried -with the \f[B]-h\f[R] or \f[B]--help\f[R] options. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE -.SH EXIT STATUS +.TP +\f[B]DC_DIGIT_CLAMP\f[R] +When parsing numbers and if this environment variable exists and +contains an integer, a non\-zero value makes dc(1) clamp digits that are +greater than or equal to the current \f[B]ibase\f[R] so that all such +digits are considered equal to the \f[B]ibase\f[R] minus 1, and a zero +value disables such clamping so that those digits are always equal to +their value, which is multiplied by the power of the \f[B]ibase\f[R]. +.RS +.PP +This never applies to single\-digit numbers, as per the bc(1) standard +(see the \f[B]STANDARDS\f[R] section). .PP +This environment variable overrides the default, which can be queried +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. +.RE +.SH EXIT STATUS dc(1) returns the following exit statuses: .TP \f[B]0\f[R] @@ -1199,7 +1293,7 @@ Math errors include divide by \f[B]0\f[R], taking the square root of a negative number, attempting to convert a negative number to a hardware integer, overflow when converting a number to a hardware integer, overflow when calculating the size of a number, and attempting to use a -non-integer where an integer is required. +non\-integer where an integer is required. .PP Converting to a hardware integer happens for the second operand of the power (\f[B]\[ha]\f[R]) operator. @@ -1233,7 +1327,7 @@ A fatal error occurred. Fatal errors include memory allocation errors, I/O errors, failing to open files, attempting to use files that do not have only ASCII characters (dc(1) only accepts ASCII characters), attempting to open a -directory as a file, and giving invalid command-line options. +directory as a file, and giving invalid command\-line options. .RE .PP The exit status \f[B]4\f[R] is special; when a fatal error occurs, dc(1) @@ -1244,17 +1338,17 @@ interactive mode (see the \f[B]INTERACTIVE MODE\f[R] section), since dc(1) resets its state (see the \f[B]RESET\f[R] section) and accepts more input when one of those errors occurs in interactive mode. This is also the case when interactive mode is forced by the -\f[B]-i\f[R] flag or \f[B]--interactive\f[R] option. +\f[B]\-i\f[R] flag or \f[B]\-\-interactive\f[R] option. .PP These exit statuses allow dc(1) to be used in shell scripting with error checking, and its normal behavior can be forced by using the -\f[B]-i\f[R] flag or \f[B]--interactive\f[R] option. +\f[B]\-i\f[R] flag or \f[B]\-\-interactive\f[R] option. .SH INTERACTIVE MODE -.PP -Like bc(1), dc(1) has an interactive mode and a non-interactive mode. +Like bc(1), dc(1) has an interactive mode and a non\-interactive mode. Interactive mode is turned on automatically when both \f[B]stdin\f[R] -and \f[B]stdout\f[R] are hooked to a terminal, but the \f[B]-i\f[R] flag -and \f[B]--interactive\f[R] option can turn it on in other situations. +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. .PP In interactive mode, dc(1) attempts to recover from errors (see the \f[B]RESET\f[R] section), and in normal execution, flushes @@ -1263,7 +1357,6 @@ dc(1) may also reset on \f[B]SIGINT\f[R] instead of exit, depending on the contents of, or default for, the \f[B]DC_SIGINT_RESET\f[R] environment variable (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). .SH TTY MODE -.PP If \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all connected to a TTY, then \[lq]TTY mode\[rq] is considered to be available, and thus, dc(1) can turn on TTY mode, subject to some @@ -1271,45 +1364,42 @@ settings. .PP If there is the environment variable \f[B]DC_TTY_MODE\f[R] in the environment (see the \f[B]ENVIRONMENT VARIABLES\f[R] section), then if -that environment variable contains a non-zero integer, dc(1) will turn +that environment variable contains a non\-zero integer, dc(1) will turn on TTY mode when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all connected to a TTY. If the \f[B]DC_TTY_MODE\f[R] environment variable exists but is -\f[I]not\f[R] a non-zero integer, then dc(1) will not turn TTY mode on. +\f[I]not\f[R] a non\-zero integer, then dc(1) will not turn TTY mode on. .PP If the environment variable \f[B]DC_TTY_MODE\f[R] does \f[I]not\f[R] exist, the default setting is used. -The default setting can be queried with the \f[B]-h\f[R] or -\f[B]--help\f[R] options. +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. Like TTY mode itself, it can be turned on or off with an environment variable: \f[B]DC_PROMPT\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). .PP -If the environment variable \f[B]DC_PROMPT\f[R] exists and is a non-zero -integer, then the prompt is turned on when \f[B]stdin\f[R], +If the environment variable \f[B]DC_PROMPT\f[R] exists and is a +non\-zero integer, then the prompt is turned on when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are connected to a TTY and the -\f[B]-P\f[R] and \f[B]--no-prompt\f[R] options were not used. +\f[B]\-P\f[R] and \f[B]\-\-no\-prompt\f[R] options were not used. The read prompt will be turned on under the same conditions, except that -the \f[B]-R\f[R] and \f[B]--no-read-prompt\f[R] options must also not be -used. +the \f[B]\-R\f[R] and \f[B]\-\-no\-read\-prompt\f[R] options must also +not be used. .PP However, if \f[B]DC_PROMPT\f[R] does not exist, the prompt can be enabled or disabled with the \f[B]DC_TTY_MODE\f[R] environment variable, -the \f[B]-P\f[R] and \f[B]--no-prompt\f[R] options, and the \f[B]-R\f[R] -and \f[B]--no-read-prompt\f[R] options. +the \f[B]\-P\f[R] and \f[B]\-\-no\-prompt\f[R] options, and the +\f[B]\-R\f[R] and \f[B]\-\-no\-read\-prompt\f[R] options. See the \f[B]ENVIRONMENT VARIABLES\f[R] and \f[B]OPTIONS\f[R] sections for more details. .SH SIGNAL HANDLING -.PP Sending a \f[B]SIGINT\f[R] will cause dc(1) to do one of two things. .PP If dc(1) is not in interactive mode (see the \f[B]INTERACTIVE MODE\f[R] @@ -1318,7 +1408,7 @@ section), or the \f[B]DC_SIGINT_RESET\f[R] environment variable (see the an integer or it is zero, dc(1) will exit. .PP However, if dc(1) is in interactive mode, and the -\f[B]DC_SIGINT_RESET\f[R] or its default is an integer and non-zero, +\f[B]DC_SIGINT_RESET\f[R] or its default is an integer and non\-zero, then dc(1) will stop executing the current input and reset (see the \f[B]RESET\f[R] section) upon receiving a \f[B]SIGINT\f[R]. .PP @@ -1341,23 +1431,20 @@ the user to continue. \f[B]SIGTERM\f[R] and \f[B]SIGQUIT\f[R] cause dc(1) to clean up and exit, and it uses the default handler for all other signals. .SH LOCALES -.PP This dc(1) ships with support for adding error messages for different locales and thus, supports \f[B]LC_MESSAGES\f[R]. .SH SEE ALSO -.PP bc(1) .SH STANDARDS -.PP -The dc(1) utility operators are compliant with the operators in the IEEE -Std 1003.1-2017 (\[lq]POSIX.1-2017\[rq]) specification at -https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html for -bc(1). +The dc(1) utility operators and some behavior are compliant with the +operators in the IEEE Std 1003.1\-2017 (\[lq]POSIX.1\-2017\[rq]) bc(1) +specification at +https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html . .SH BUGS -.PP None are known. -Report bugs at https://git.yzena.com/gavin/bc. +Report bugs at https://git.gavinhoward.com/gavin/bc . .SH AUTHOR -.PP -Gavin D. -Howard <gavin@yzena.com> and contributors. +Gavin D. Howard \c +.MT gavin@gavinhoward.com +.ME \c +\ and contributors. diff --git a/contrib/bc/manuals/dc/EH.1.md b/contrib/bc/manuals/dc/EH.1.md index 50850226ddbe..6398477a84dd 100644 --- a/contrib/bc/manuals/dc/EH.1.md +++ b/contrib/bc/manuals/dc/EH.1.md @@ -2,7 +2,7 @@ SPDX-License-Identifier: BSD-2-Clause -Copyright (c) 2018-2021 Gavin D. Howard and contributors. +Copyright (c) 2018-2024 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** - -: Prints a usage message and quits. - -**-v**, **-V**, **-\-version** - -: Print the version information (copyright header) and exit. - -**-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). +**-C**, **-\-no-digit-clamp** - This is a **non-portable extension**. - -**-P**, **-\-no-prompt** +: Disables clamping of digits greater than or equal to the current **ibase** + when parsing numbers. -: 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 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. - This option does not disable the regular prompt because the read prompt is - only used when the **?** command is used. + If this and/or the **-c** or **-\-digit-clamp** options are given multiple + times, the last one given 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 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**. -**-x** **-\-extended-register** - -: Enables extended register mode. See the *Extended Register Mode* subsection - of the **REGISTERS** section for more information. +**-c**, **-\-digit-clamp** - This is a **non-portable extension**. +: Enables clamping of digits greater than or equal to the current **ibase** + when parsing numbers. -**-z**, **-\-leading-zeroes** + 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. -: Makes dc(1) print all numbers greater than **-1** and less than **1**, and - not equal to **0**, with a leading zero. + If this and/or the **-C** or **-\-no-digit-clamp** options are given + multiple times, the last one given is used. - 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,24 @@ 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 is a **non-portable extension**. + All long options are **non-portable extensions**. # STDIN @@ -263,15 +296,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**. - -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**. +Uppercase letters are equal to **9** plus 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** (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 +827,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 +851,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) @@ -840,6 +914,12 @@ other character produces a parse error (see the **ERRORS** section). : Pushes the line length set by **DC_LINE_LENGTH** (see the **ENVIRONMENT VARIABLES** section) onto the stack. +**gx** + +: Pushes **1** onto the stack if extended register mode is on, **0** + otherwise. See the *Extended Register Mode* subsection of the **REGISTERS** + section for more information. + **gz** : Pushes **0** onto the stack if the leading zero setting has not been enabled @@ -881,11 +961,14 @@ the next non-space characters do not match that regex. When dc(1) encounters an error or a signal that it has a non-default handler for, it resets. This means that several things happen. -First, any macros that are executing are stopped and popped off the stack. -The behavior is not unlike that of exceptions in programming languages. Then -the execution point is set so that any code waiting to execute (after all +First, any macros that are executing are stopped and popped off the execution +stack. The behavior is not unlike that of exceptions in programming languages. +Then the execution point is set so that any code waiting to execute (after all macros returned) is skipped. +However, the stack of values is *not* cleared; in interactive mode, users can +inspect the stack and manipulate it. + Thus, when dc(1) resets, it skips any remaining code waiting to be executed. Then, if it is interactive mode, and the error was not a fatal error (see the **EXIT STATUS** section), it asks for more input; otherwise, it exits with the @@ -974,7 +1057,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 +1147,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 +1256,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,14 +1317,14 @@ 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.gavinhoward.com/gavin/bc . # AUTHOR -Gavin D. Howard <gavin@yzena.com> and contributors. +Gavin D. Howard <gavin@gavinhoward.com> and contributors. diff --git a/contrib/bc/manuals/dc/EHN.1 b/contrib/bc/manuals/dc/EHN.1 index 31e60102b971..974cb3c86791 100644 --- a/contrib/bc/manuals/dc/EHN.1 +++ b/contrib/bc/manuals/dc/EHN.1 @@ -1,7 +1,7 @@ .\" .\" SPDX-License-Identifier: BSD-2-Clause .\" -.\" Copyright (c) 2018-2021 Gavin D. Howard and contributors. +.\" Copyright (c) 2018-2024 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,124 +25,82 @@ .\" 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" "August 2024" "Gavin D. Howard" "General Commands Manual" .nh .ad l .SH Name -.PP -dc - arbitrary-precision decimal reverse-Polish notation calculator +dc \- arbitrary\-precision decimal reverse\-Polish notation calculator .SH SYNOPSIS -.PP -\f[B]dc\f[R] [\f[B]-hiPRvVx\f[R]] [\f[B]--version\f[R]] -[\f[B]--help\f[R]] [\f[B]--interactive\f[R]] [\f[B]--no-prompt\f[R]] -[\f[B]--no-read-prompt\f[R]] [\f[B]--extended-register\f[R]] -[\f[B]-e\f[R] \f[I]expr\f[R]] -[\f[B]--expression\f[R]=\f[I]expr\f[R]\&...] [\f[B]-f\f[R] -\f[I]file\f[R]\&...] [\f[B]--file\f[R]=\f[I]file\f[R]\&...] +\f[B]dc\f[R] [\f[B]\-cChiPRvVx\f[R]] [\f[B]\-\-version\f[R]] +[\f[B]\-\-help\f[R]] [\f[B]\-\-digit\-clamp\f[R]] +[\f[B]\-\-no\-digit\-clamp\f[R]] [\f[B]\-\-interactive\f[R]] +[\f[B]\-\-no\-prompt\f[R]] [\f[B]\-\-no\-read\-prompt\f[R]] +[\f[B]\-\-extended\-register\f[R]] [\f[B]\-e\f[R] \f[I]expr\f[R]] +[\f[B]\-\-expression\f[R]=\f[I]expr\f[R]\&...] +[\f[B]\-f\f[R] \f[I]file\f[R]\&...] +[\f[B]\-\-file\f[R]=\f[I]file\f[R]\&...] [\f[I]file\f[R]\&...] .SH DESCRIPTION -.PP -dc(1) is an arbitrary-precision calculator. +dc(1) is an arbitrary\-precision calculator. It uses a stack (reverse Polish notation) to store numbers and results of computations. Arithmetic operations pop arguments off of the stack and push the results. .PP -If no files are given on the command-line, then dc(1) reads from +If no files are given on the command\-line, then dc(1) reads from \f[B]stdin\f[R] (see the \f[B]STDIN\f[R] section). Otherwise, those files are processed, and dc(1) will then exit. .PP If a user wants to set up a standard environment, they can use \f[B]DC_ENV_ARGS\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). For example, if a user wants the \f[B]scale\f[R] always set to -\f[B]10\f[R], they can set \f[B]DC_ENV_ARGS\f[R] to \f[B]-e 10k\f[R], +\f[B]10\f[R], they can set \f[B]DC_ENV_ARGS\f[R] to \f[B]\-e 10k\f[R], and this dc(1) will always start with a \f[B]scale\f[R] of \f[B]10\f[R]. .SH OPTIONS -.PP The following are the options that dc(1) accepts. .TP -\f[B]-h\f[R], \f[B]--help\f[R] -Prints a usage message and quits. -.TP -\f[B]-v\f[R], \f[B]-V\f[R], \f[B]--version\f[R] -Print the version information (copyright header) and exit. -.TP -\f[B]-i\f[R], \f[B]--interactive\f[R] -Forces interactive mode. -(See the \f[B]INTERACTIVE MODE\f[R] section.) +\f[B]\-C\f[R], \f[B]\-\-no\-digit\-clamp\f[R] +Disables clamping of digits greater than or equal to the current +\f[B]ibase\f[R] when parsing numbers. .RS .PP -This is a \f[B]non-portable extension\f[R]. -.RE -.TP -\f[B]-L\f[R], \f[B]--no-line-length\f[R] -Disables line length checking and prints numbers without backslashes and -newlines. -In other words, this option sets \f[B]BC_LINE_LENGTH\f[R] to \f[B]0\f[R] -(see the \f[B]ENVIRONMENT VARIABLES\f[R] section). -.RS +This means that the value added to a number from a digit is always that +digit\[cq]s value multiplied by the value of ibase raised to the power +of the digit\[cq]s position, which starts from 0 at the least +significant digit. .PP -This is a \f[B]non-portable extension\f[R]. -.RE -.TP -\f[B]-P\f[R], \f[B]--no-prompt\f[R] -Disables the prompt in TTY mode. -(The prompt is only enabled in TTY mode. -See the \f[B]TTY MODE\f[R] section.) This is mostly for those users that -do not want a prompt or are not used to having them in dc(1). -Most of those users would want to put this option in -\f[B]DC_ENV_ARGS\f[R]. -.RS +If this and/or the \f[B]\-c\f[R] or \f[B]\-\-digit\-clamp\f[R] options +are given multiple times, the last one given is used. .PP -These options override the \f[B]DC_PROMPT\f[R] and \f[B]DC_TTY_MODE\f[R] -environment variables (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). +This option overrides the \f[B]DC_DIGIT_CLAMP\f[R] environment variable +(see the \f[B]ENVIRONMENT VARIABLES\f[R] section) and the default, which +can be queried with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-R\f[R], \f[B]--no-read-prompt\f[R] -Disables the read prompt in TTY mode. -(The read prompt is only enabled in TTY mode. -See the \f[B]TTY MODE\f[R] section.) This is mostly for those users that -do not want a read prompt or are not used to having them in dc(1). -Most of those users would want to put this option in -\f[B]BC_ENV_ARGS\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). -This option is also useful in hash bang lines of dc(1) scripts that -prompt for user input. +\f[B]\-c\f[R], \f[B]\-\-digit\-clamp\f[R] +Enables clamping of digits greater than or equal to the current +\f[B]ibase\f[R] when parsing numbers. .RS .PP -This option does not disable the regular prompt because the read prompt -is only used when the \f[B]?\f[R] command is used. +This means that digits that the value added to a number from a digit +that is greater than or equal to the ibase is the value of ibase minus 1 +all multiplied by the value of ibase raised to the power of the +digit\[cq]s position, which starts from 0 at the least significant +digit. .PP -These options \f[I]do\f[R] override the \f[B]DC_PROMPT\f[R] and -\f[B]DC_TTY_MODE\f[R] environment variables (see the \f[B]ENVIRONMENT -VARIABLES\f[R] section), but only for the read prompt. +If this and/or the \f[B]\-C\f[R] or \f[B]\-\-no\-digit\-clamp\f[R] +options are given multiple times, the last one given is used. .PP -This is a \f[B]non-portable extension\f[R]. -.RE -.TP -\f[B]-x\f[R] \f[B]--extended-register\f[R] -Enables extended register mode. -See the \f[I]Extended Register Mode\f[R] subsection of the -\f[B]REGISTERS\f[R] section for more information. -.RS +This option overrides the \f[B]DC_DIGIT_CLAMP\f[R] environment variable +(see the \f[B]ENVIRONMENT VARIABLES\f[R] section) and the default, which +can be queried with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .PP -This is a \f[B]non-portable extension\f[R]. +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 -.TP -\f[B]-e\f[R] \f[I]expr\f[R], \f[B]--expression\f[R]=\f[I]expr\f[R] +\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 @@ -151,41 +109,44 @@ 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 +If this option is given on the command\-line (i.e., not in \f[B]DC_ENV_ARGS\f[R], see the \f[B]ENVIRONMENT VARIABLES\f[R] section), then after processing all expressions and files, dc(1) will exit, unless -\f[B]-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to -\f[B]-f\f[R] or \f[B]--file\f[R], whether on the command-line or in +\f[B]\-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to +\f[B]\-f\f[R] or \f[B]\-\-file\f[R], whether on the command\-line or in \f[B]DC_ENV_ARGS\f[R]. -However, if any other \f[B]-e\f[R], \f[B]--expression\f[R], -\f[B]-f\f[R], or \f[B]--file\f[R] arguments are given after -\f[B]-f-\f[R] or equivalent is given, dc(1) will give a fatal error and -exit. +However, if any other \f[B]\-e\f[R], \f[B]\-\-expression\f[R], +\f[B]\-f\f[R], or \f[B]\-\-file\f[R] arguments are given after +\f[B]\-f\-\f[R] or equivalent is given, dc(1) will give a fatal error +and exit. .PP -This is a \f[B]non-portable extension\f[R]. +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] +\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 +If this option is given on the command\-line (i.e., not in \f[B]DC_ENV_ARGS\f[R], see the \f[B]ENVIRONMENT VARIABLES\f[R] section), then after processing all expressions and files, dc(1) will exit, unless -\f[B]-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to -\f[B]-f\f[R] or \f[B]--file\f[R]. -However, if any other \f[B]-e\f[R], \f[B]--expression\f[R], -\f[B]-f\f[R], or \f[B]--file\f[R] arguments are given after -\f[B]-f-\f[R] or equivalent is given, dc(1) will give a fatal error and -exit. +\f[B]\-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to +\f[B]\-f\f[R] or \f[B]\-\-file\f[R]. +However, if any other \f[B]\-e\f[R], \f[B]\-\-expression\f[R], +\f[B]\-f\f[R], or \f[B]\-\-file\f[R] arguments are given after +\f[B]\-f\-\f[R] or equivalent is given, dc(1) will give a fatal error +and exit. .PP -This is a \f[B]non-portable extension\f[R]. +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] +\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. It is a fatal error if \f[I]ibase\f[R] is not a valid number. @@ -193,10 +154,28 @@ It is a fatal error if \f[I]ibase\f[R] is not a valid number. .PP If multiple instances of this option are given, the last is used. .PP -This is a \f[B]non-portable extension\f[R]. +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] +\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. @@ -204,10 +183,48 @@ It is a fatal error if \f[I]obase\f[R] is not a valid number. .PP If multiple instances of this option are given, the last is used. .PP -This is a \f[B]non-portable extension\f[R]. +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] +\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. @@ -215,15 +232,34 @@ It is a fatal error if \f[I]scale\f[R] is not a valid number. .PP If multiple instances of this option are given, the last is used. .PP -This is a \f[B]non-portable extension\f[R]. +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 -All long options are \f[B]non-portable extensions\f[R]. -.SH STDIN +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 -If no files are given on the command-line and no files or expressions -are given by the \f[B]-f\f[R], \f[B]--file\f[R], \f[B]-e\f[R], or -\f[B]--expression\f[R] options, then dc(1) reads from \f[B]stdin\f[R]. +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 +If no files are given on the command\-line and no files or expressions +are given by the \f[B]\-f\f[R], \f[B]\-\-file\f[R], \f[B]\-e\f[R], or +\f[B]\-\-expression\f[R] options, then dc(1) reads from \f[B]stdin\f[R]. .PP However, there is a caveat to this. .PP @@ -233,8 +269,7 @@ ended. This means that, except for escaped brackets, all brackets must be balanced before dc(1) parses and executes. .SH STDOUT -.PP -Any non-error output is written to \f[B]stdout\f[R]. +Any non\-error output is written to \f[B]stdout\f[R]. In addition, if history (see the \f[B]HISTORY\f[R] section) and the prompt (see the \f[B]TTY MODE\f[R] section) are enabled, both are output to \f[B]stdout\f[R]. @@ -242,7 +277,7 @@ to \f[B]stdout\f[R]. \f[B]Note\f[R]: Unlike other dc(1) implementations, this dc(1) will issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot write to \f[B]stdout\f[R], so if \f[B]stdout\f[R] is closed, as in -\f[B]dc >&-\f[R], it will quit with an error. +\f[B]dc >&\-\f[R], it will quit with an error. This is done so that dc(1) can report problems when \f[B]stdout\f[R] is redirected to a file. .PP @@ -250,13 +285,12 @@ If there are scripts that depend on the behavior of other dc(1) implementations, it is recommended that those scripts be changed to redirect \f[B]stdout\f[R] to \f[B]/dev/null\f[R]. .SH STDERR -.PP Any error output is written to \f[B]stderr\f[R]. .PP \f[B]Note\f[R]: Unlike other dc(1) implementations, this dc(1) will issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot write to \f[B]stderr\f[R], so if \f[B]stderr\f[R] is closed, as in -\f[B]dc 2>&-\f[R], it will quit with an error. +\f[B]dc 2>&\-\f[R], it will quit with an error. This is done so that dc(1) can exit with an error code when \f[B]stderr\f[R] is redirected to a file. .PP @@ -264,7 +298,6 @@ If there are scripts that depend on the behavior of other dc(1) implementations, it is recommended that those scripts be changed to redirect \f[B]stderr\f[R] to \f[B]/dev/null\f[R]. .SH SYNTAX -.PP Each item in the input source code, either a number (see the \f[B]NUMBERS\f[R] section) or a command (see the \f[B]COMMANDS\f[R] section), is processed and executed, in order. @@ -299,30 +332,57 @@ precision of any operations (with exceptions). The max allowable value for \f[B]scale\f[R] can be queried in dc(1) programs with the \f[B]V\f[R] command. .SS Comments -.PP Comments go from \f[B]#\f[R] until, and not including, the next newline. -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .SH NUMBERS -.PP Numbers are strings made up of digits, uppercase letters up to \f[B]F\f[R], and at most \f[B]1\f[R] period for a radix. Numbers can have up to \f[B]DC_NUM_MAX\f[R] digits. -Uppercase letters are equal to \f[B]9\f[R] + their position in the +Uppercase letters are equal to \f[B]9\f[R] plus their position in the alphabet (i.e., \f[B]A\f[R] equals \f[B]10\f[R], or \f[B]9+1\f[R]). -If a digit or letter makes no sense with the current value of -\f[B]ibase\f[R], they are set to the value of the highest valid digit in -\f[B]ibase\f[R]. .PP -Single-character numbers (i.e., \f[B]A\f[R] alone) take the value that -they would have if they were valid digits, regardless of the value of -\f[B]ibase\f[R]. +If a digit or letter makes no sense with the current value of +\f[B]ibase\f[R] (i.e., they are greater than or equal to the current +value of \f[B]ibase\f[R]), then the behavior depends on the existence of +the \f[B]\-c\f[R]/\f[B]\-\-digit\-clamp\f[R] or +\f[B]\-C\f[R]/\f[B]\-\-no\-digit\-clamp\f[R] options (see the +\f[B]OPTIONS\f[R] section), the existence and setting of the +\f[B]DC_DIGIT_CLAMP\f[R] environment variable (see the \f[B]ENVIRONMENT +VARIABLES\f[R] section), or the default, which can be queried with the +\f[B]\-h\f[R]/\f[B]\-\-help\f[R] option. +.PP +If clamping is off, then digits or letters that are greater than or +equal to the current value of \f[B]ibase\f[R] are not changed. +Instead, their given value is multiplied by the appropriate power of +\f[B]ibase\f[R] and added into the number. +This means that, with an \f[B]ibase\f[R] of \f[B]3\f[R], the number +\f[B]AB\f[R] is equal to \f[B]3\[ha]1*A+3\[ha]0*B\f[R], which is +\f[B]3\f[R] times \f[B]10\f[R] plus \f[B]11\f[R], or \f[B]41\f[R]. +.PP +If clamping is on, then digits or letters that are greater than or equal +to the current value of \f[B]ibase\f[R] are set to the value of the +highest valid digit in \f[B]ibase\f[R] before being multiplied by the +appropriate power of \f[B]ibase\f[R] and added into the number. +This means that, with an \f[B]ibase\f[R] of \f[B]3\f[R], the number +\f[B]AB\f[R] is equal to \f[B]3\[ha]1*2+3\[ha]0*2\f[R], which is +\f[B]3\f[R] times \f[B]2\f[R] plus \f[B]2\f[R], or \f[B]8\f[R]. +.PP +There is one exception to clamping: single\-character numbers (i.e., +\f[B]A\f[R] alone). +Such numbers are never clamped and always take the value they would have +in the highest possible \f[B]ibase\f[R]. This means that \f[B]A\f[R] alone always equals decimal \f[B]10\f[R] and -\f[B]F\f[R] alone always equals decimal \f[B]15\f[R]. +\f[B]Z\f[R] alone always equals decimal \f[B]35\f[R]. +This behavior is mandated by the standard for bc(1) (see the STANDARDS +section) and is meant to provide an easy way to set the current +\f[B]ibase\f[R] (with the \f[B]i\f[R] command) regardless of the current +value of \f[B]ibase\f[R]. +.PP +If clamping is on, and the clamped value of a character is needed, use a +leading zero, i.e., for \f[B]A\f[R], use \f[B]0A\f[R]. .SH COMMANDS -.PP The valid commands are listed below. .SS Printing -.PP These commands are used for printing. .TP \f[B]p\f[R] @@ -343,12 +403,12 @@ Pops a value off the stack. .PP If the value is a number, it is truncated and the absolute value of the result is printed as though \f[B]obase\f[R] is \f[B]256\f[R] and each -digit is interpreted as an 8-bit ASCII character, making it a byte +digit is interpreted as an 8\-bit ASCII character, making it a byte stream. .PP If the value is a string, it is printed without a trailing newline. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]f\f[R] @@ -359,7 +419,6 @@ without altering anything. Users should use this command when they get lost. .RE .SS Arithmetic -.PP These are the commands used for arithmetic. .TP \f[B]+\f[R] @@ -368,7 +427,7 @@ pushed onto the stack. The \f[I]scale\f[R] of the result is equal to the max \f[I]scale\f[R] of both operands. .TP -\f[B]-\f[R] +\f[B]\-\f[R] The top two values are popped off the stack, subtracted, and the result is pushed onto the stack. The \f[I]scale\f[R] of the result is equal to the max \f[I]scale\f[R] of @@ -389,7 +448,7 @@ pushed onto the stack. The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R]. .RS .PP -The first value popped off of the stack must be non-zero. +The first value popped off of the stack must be non\-zero. .RE .TP \f[B]%\f[R] @@ -399,10 +458,10 @@ is pushed onto the stack. .PP Remaindering is equivalent to 1) Computing \f[B]a/b\f[R] to current \f[B]scale\f[R], and 2) Using the result of step 1 to calculate -\f[B]a-(a/b)*b\f[R] to \f[I]scale\f[R] +\f[B]a\-(a/b)*b\f[R] to \f[I]scale\f[R] \f[B]max(scale+scale(b),scale(a))\f[R]. .PP -The first value popped off of the stack must be non-zero. +The first value popped off of the stack must be non\-zero. .RE .TP \f[B]\[ti]\f[R] @@ -413,9 +472,9 @@ This is equivalent to \f[B]x y / x y %\f[R] except that \f[B]x\f[R] and \f[B]y\f[R] are only evaluated once. .RS .PP -The first value popped off of the stack must be non-zero. +The first value popped off of the stack must be non\-zero. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]\[ha]\f[R] @@ -426,7 +485,7 @@ The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R]. .PP The first value popped off of the stack must be an integer, and if that value is negative, the second value popped off of the stack must be -non-zero. +non\-zero. .RE .TP \f[B]v\f[R] @@ -435,7 +494,7 @@ the result is pushed onto the stack. The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R]. .RS .PP -The value popped off of the stack must be non-negative. +The value popped off of the stack must be non\-negative. .RE .TP \f[B]_\f[R] @@ -445,7 +504,7 @@ or other commands), then that number is input as a negative number. .PP Otherwise, the top value on the stack is popped and copied, and the copy is negated and pushed onto the stack. -This behavior without a number is a \f[B]non-portable extension\f[R]. +This behavior without a number is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]b\f[R] @@ -454,7 +513,7 @@ back onto the stack. Otherwise, its absolute value is pushed onto the stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]|\f[R] @@ -463,12 +522,12 @@ is computed, and the result is pushed onto the stack. .RS .PP The first value popped is used as the reduction modulus and must be an -integer and non-zero. +integer and non\-zero. The second value popped is used as the exponent and must be an integer -and non-negative. +and non\-negative. The third value popped is the base and must be an integer. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]G\f[R] @@ -476,7 +535,7 @@ The top two values are popped off of the stack, they are compared, and a \f[B]1\f[R] is pushed if they are equal, or \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]N\f[R] @@ -484,7 +543,7 @@ The top value is popped off of the stack, and if it a \f[B]0\f[R], a \f[B]1\f[R] is pushed; otherwise, a \f[B]0\f[R] is pushed. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B](\f[R] @@ -493,7 +552,7 @@ The top two values are popped off of the stack, they are compared, and a \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]{\f[R] @@ -502,7 +561,7 @@ The top two values are popped off of the stack, they are compared, and a or \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B])\f[R] @@ -511,7 +570,7 @@ The top two values are popped off of the stack, they are compared, and a \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]}\f[R] @@ -520,36 +579,35 @@ The top two values are popped off of the stack, they are compared, and a second, or \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]M\f[R] The top two values are popped off of the stack. -If they are both non-zero, a \f[B]1\f[R] is pushed onto the stack. +If they are both non\-zero, a \f[B]1\f[R] is pushed onto the stack. If either of them is zero, or both of them are, then a \f[B]0\f[R] is pushed onto the stack. .RS .PP This is like the \f[B]&&\f[R] operator in bc(1), and it is \f[I]not\f[R] -a short-circuit operator. +a short\-circuit operator. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]m\f[R] The top two values are popped off of the stack. -If at least one of them is non-zero, a \f[B]1\f[R] is pushed onto the +If at least one of them is non\-zero, a \f[B]1\f[R] is pushed onto the stack. If both of them are zero, then a \f[B]0\f[R] is pushed onto the stack. .RS .PP This is like the \f[B]||\f[R] operator in bc(1), and it is \f[I]not\f[R] -a short-circuit operator. +a short\-circuit operator. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .SS Stack Control -.PP These commands control the stack. .TP \f[B]c\f[R] @@ -565,7 +623,6 @@ Swaps (\[lq]reverses\[rq]) the two top items on the stack. \f[B]R\f[R] Pops (\[lq]removes\[rq]) the top value from the stack. .SS Register Control -.PP These commands control registers (see the \f[B]REGISTERS\f[R] section). .TP \f[B]s\f[R]\f[I]r\f[R] @@ -587,7 +644,6 @@ push it onto the main stack. The previous value in the stack for register \f[I]r\f[R], if any, is now accessible via the \f[B]l\f[R]\f[I]r\f[R] command. .SS Parameters -.PP These commands control the values of \f[B]ibase\f[R], \f[B]obase\f[R], and \f[B]scale\f[R]. Also see the \f[B]SYNTAX\f[R] section. @@ -614,7 +670,7 @@ If the value on top of the stack has any \f[I]scale\f[R], the .TP \f[B]k\f[R] Pops the value off of the top of the stack and uses it to set -\f[B]scale\f[R], which must be non-negative. +\f[B]scale\f[R], which must be non\-negative. .RS .PP If the value on top of the stack has any \f[I]scale\f[R], the @@ -635,7 +691,7 @@ Pushes the maximum allowable value of \f[B]ibase\f[R] onto the main stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]U\f[R] @@ -643,7 +699,7 @@ Pushes the maximum allowable value of \f[B]obase\f[R] onto the main stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]V\f[R] @@ -651,10 +707,9 @@ Pushes the maximum allowable value of \f[B]scale\f[R] onto the main stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .SS Strings -.PP The following commands control strings. .PP dc(1) can work with both numbers and strings, and registers (see the @@ -692,16 +747,16 @@ The value on top of the stack is popped. If it is a number, it is truncated and its absolute value is taken. The result mod \f[B]256\f[R] is calculated. If that result is \f[B]0\f[R], push an empty string; otherwise, push a -one-character string where the character is the result of the mod +one\-character string where the character is the result of the mod interpreted as an ASCII character. .PP If it is a string, then a new string is made. If the original string is empty, the new string is empty. If it is not, then the first character of the original string is used to -create the new string as a one-character string. +create the new string as a one\-character string. The new string is then pushed onto the stack. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]x\f[R] @@ -737,7 +792,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]!>\f[R]\f[I]r\f[R] @@ -758,7 +813,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]<\f[R]\f[I]r\f[R] @@ -779,7 +834,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]!<\f[R]\f[I]r\f[R] @@ -800,7 +855,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]=\f[R]\f[I]r\f[R] @@ -821,7 +876,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]!=\f[R]\f[I]r\f[R] @@ -842,7 +897,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]?\f[R] @@ -855,7 +910,7 @@ the execution of the macro that executed it. If there are no macros, or only one macro executing, dc(1) exits. .TP \f[B]Q\f[R] -Pops a value from the stack which must be non-negative and is used the +Pops a value from the stack which must be non\-negative and is used the number of macro executions to pop off of the execution stack. If the number of levels to pop is greater than the number of executing macros, dc(1) exits. @@ -866,8 +921,11 @@ The execution stack is the stack of string executions. The number that is pushed onto the stack is exactly as many as is needed to make dc(1) exit with the \f[B]Q\f[R] command, so the sequence \f[B],Q\f[R] will make dc(1) exit. -.SS Status +.RS .PP +This is a \f[B]non\-portable extension\f[R]. +.RE +.SS Status These commands query status of the stack or its top value. .TP \f[B]Z\f[R] @@ -892,6 +950,24 @@ stack. If it is a string, pushes \f[B]0\f[R]. .RE .TP +\f[B]u\f[R] +Pops one value off of the stack. +If the value is a number, this pushes \f[B]1\f[R] onto the stack. +Otherwise (if it is a string), it pushes \f[B]0\f[R]. +.RS +.PP +This is a \f[B]non\-portable extension\f[R]. +.RE +.TP +\f[B]t\f[R] +Pops one value off of the stack. +If the value is a string, this pushes \f[B]1\f[R] onto the stack. +Otherwise (if it is a number), it pushes \f[B]0\f[R]. +.RS +.PP +This is a \f[B]non\-portable extension\f[R]. +.RE +.TP \f[B]z\f[R] Pushes the current depth of the stack (before execution of this command) onto the stack. @@ -907,10 +983,9 @@ register\[cq]s stack must always have at least one item; dc(1) will give an error and reset otherwise (see the \f[B]RESET\f[R] section). This means that this command will never push \f[B]0\f[R]. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .SS Arrays -.PP These commands manipulate arrays. .TP \f[B]:\f[R]\f[I]r\f[R] @@ -927,10 +1002,9 @@ The selected value is then pushed onto the stack. Pushes the length of the array \f[I]r\f[R] onto the stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .SS Global Settings -.PP These commands retrieve global settings. These are the only commands that require multiple specific characters, and all of them begin with the letter \f[B]g\f[R]. @@ -942,12 +1016,17 @@ section). Pushes the line length set by \f[B]DC_LINE_LENGTH\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section) onto the stack. .TP +\f[B]gx\f[R] +Pushes \f[B]1\f[R] onto the stack if extended register mode is on, +\f[B]0\f[R] otherwise. +See the \f[I]Extended Register Mode\f[R] subsection of the +\f[B]REGISTERS\f[R] section for more information. +.TP \f[B]gz\f[R] Pushes \f[B]0\f[R] onto the stack if the leading zero setting has not -been enabled with the \f[B]-z\f[R] or \f[B]--leading-zeroes\f[R] options -(see the \f[B]OPTIONS\f[R] section), non-zero otherwise. +been enabled with the \f[B]\-z\f[R] or \f[B]\-\-leading\-zeroes\f[R] +options (see the \f[B]OPTIONS\f[R] section), non\-zero otherwise. .SH REGISTERS -.PP Registers are names that can store strings, numbers, and arrays. (Number/string registers do not interfere with array registers.) .PP @@ -957,45 +1036,45 @@ All registers, when first referenced, have one value (\f[B]0\f[R]) in their stack, and it is a runtime error to attempt to pop that item off of the register stack. .PP -In non-extended register mode, a register name is just the single +In non\-extended register mode, a register name is just the single character that follows any command that needs a register name. The only exceptions are: a newline (\f[B]`\[rs]n'\f[R]) and a left bracket (\f[B]`['\f[R]); it is a parse error for a newline or a left bracket to be used as a register name. .SS Extended Register Mode -.PP Unlike most other dc(1) implentations, this dc(1) provides nearly unlimited amounts of registers, if extended register mode is enabled. .PP -If extended register mode is enabled (\f[B]-x\f[R] or -\f[B]--extended-register\f[R] command-line arguments are given), then -normal single character registers are used \f[I]unless\f[R] the +If extended register mode is enabled (\f[B]\-x\f[R] or +\f[B]\-\-extended\-register\f[R] command\-line arguments are given), +then normal single character registers are used \f[I]unless\f[R] the character immediately following a command that needs a register name is a space (according to \f[B]isspace()\f[R]) and not a newline (\f[B]`\[rs]n'\f[R]). .PP In that case, the register name is found according to the regex -\f[B][a-z][a-z0-9_]*\f[R] (like bc(1) identifiers), and it is a parse -error if the next non-space characters do not match that regex. +\f[B][a\-z][a\-z0\-9_]*\f[R] (like bc(1) identifiers), and it is a parse +error if the next non\-space characters do not match that regex. .SH RESET -.PP -When dc(1) encounters an error or a signal that it has a non-default +When dc(1) encounters an error or a signal that it has a non\-default handler for, it resets. This means that several things happen. .PP First, any macros that are executing are stopped and popped off the -stack. +execution stack. The behavior is not unlike that of exceptions in programming languages. Then the execution point is set so that any code waiting to execute (after all macros returned) is skipped. .PP +However, the stack of values is \f[I]not\f[R] cleared; in interactive +mode, users can inspect the stack and manipulate it. +.PP Thus, when dc(1) resets, it skips any remaining code waiting to be executed. Then, if it is interactive mode, and the error was not a fatal error (see the \f[B]EXIT STATUS\f[R] section), it asks for more input; otherwise, it exits with the appropriate return code. .SH PERFORMANCE -.PP Most dc(1) implementations use \f[B]char\f[R] types to calculate the value of \f[B]1\f[R] decimal digit at a time, but that can be slow. This dc(1) does something different. @@ -1015,7 +1094,6 @@ checking. This integer type depends on the value of \f[B]DC_LONG_BIT\f[R], but is always at least twice as large as the integer type used to store digits. .SH LIMITS -.PP The following are the limits on dc(1): .TP \f[B]DC_LONG_BIT\f[R] @@ -1045,24 +1123,24 @@ Set at \f[B]DC_BASE_POW\f[R]. .TP \f[B]DC_DIM_MAX\f[R] The maximum size of arrays. -Set at \f[B]SIZE_MAX-1\f[R]. +Set at \f[B]SIZE_MAX\-1\f[R]. .TP \f[B]DC_SCALE_MAX\f[R] The maximum \f[B]scale\f[R]. -Set at \f[B]DC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]DC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]DC_STRING_MAX\f[R] The maximum length of strings. -Set at \f[B]DC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]DC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]DC_NAME_MAX\f[R] The maximum length of identifiers. -Set at \f[B]DC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]DC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]DC_NUM_MAX\f[R] The maximum length of a number (in decimal digits), which includes digits after the decimal point. -Set at \f[B]DC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]DC_OVERFLOW_MAX\-1\f[R]. .TP Exponent The maximum allowable exponent (positive or negative). @@ -1070,27 +1148,27 @@ Set at \f[B]DC_OVERFLOW_MAX\f[R]. .TP Number of vars The maximum number of vars/arrays. -Set at \f[B]SIZE_MAX-1\f[R]. +Set at \f[B]SIZE_MAX\-1\f[R]. .PP -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. +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 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). -They should be in the same format as all other command-line arguments. +This is another way to give command\-line arguments to dc(1). +They should be in the same format as all other command\-line arguments. These are always processed first, so any files given in \f[B]DC_ENV_ARGS\f[R] will be processed before arguments and files given -on the command-line. +on the command\-line. This gives the user the ability to set up \[lq]standard\[rq] options and files to be used at every invocation. The most useful thing for such files to contain would be useful functions that the user might want every time dc(1) runs. -Another use would be to use the \f[B]-e\f[R] option to set +Another use would be to use the \f[B]\-e\f[R] option to set \f[B]scale\f[R] to a value other than \f[B]0\f[R]. .RS .PP @@ -1108,14 +1186,14 @@ you can use double quotes as the outside quotes, as in \f[B]\[lq]some quotes. However, handling a file with both kinds of quotes in \f[B]DC_ENV_ARGS\f[R] is not supported due to the complexity of the -parsing, though such files are still supported on the command-line where -the parsing is done by the shell. +parsing, though such files are still supported on the command\-line +where the parsing is done by the shell. .RE .TP \f[B]DC_LINE_LENGTH\f[R] If this environment variable exists and contains an integer that is greater than \f[B]1\f[R] and is less than \f[B]UINT16_MAX\f[R] -(\f[B]2\[ha]16-1\f[R]), dc(1) will output lines to that length, +(\f[B]2\[ha]16\-1\f[R]), dc(1) will output lines to that length, including the backslash newline combo. The default line length is \f[B]70\f[R]. .RS @@ -1132,13 +1210,13 @@ exits on \f[B]SIGINT\f[R] when not in interactive mode. .RS .PP However, when dc(1) is in interactive mode, then if this environment -variable exists and contains an integer, a non-zero value makes dc(1) +variable exists and contains an integer, a non\-zero value makes dc(1) reset on \f[B]SIGINT\f[R], rather than exit, and zero makes dc(1) exit. If this environment variable exists and is \f[I]not\f[R] an integer, then dc(1) will exit on \f[B]SIGINT\f[R]. .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. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]DC_TTY_MODE\f[R] @@ -1147,11 +1225,11 @@ section), then this environment variable has no effect. .RS .PP However, when TTY mode is available, then if this environment variable -exists and contains an integer, then a non-zero value makes dc(1) use +exists and contains an integer, then a non\-zero value makes dc(1) use TTY mode, and zero makes dc(1) not use TTY mode. .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. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]DC_PROMPT\f[R] @@ -1160,30 +1238,46 @@ section), then this environment variable has no effect. .RS .PP However, when TTY mode is available, then if this environment variable -exists and contains an integer, a non-zero value makes dc(1) use a -prompt, and zero or a non-integer makes dc(1) not use a prompt. +exists and contains an integer, a non\-zero value makes dc(1) use a +prompt, and zero or a non\-integer makes dc(1) not use a prompt. If this environment variable does not exist and \f[B]DC_TTY_MODE\f[R] does, then the value of the \f[B]DC_TTY_MODE\f[R] environment variable is used. .PP This environment variable and the \f[B]DC_TTY_MODE\f[R] environment variable override the default, which can be queried with the -\f[B]-h\f[R] or \f[B]--help\f[R] options. +\f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]DC_EXPR_EXIT\f[R] -If any expressions or expression files are given on the command-line -with \f[B]-e\f[R], \f[B]--expression\f[R], \f[B]-f\f[R], or -\f[B]--file\f[R], then if this environment variable exists and contains -an integer, a non-zero value makes dc(1) exit after executing the -expressions and expression files, and a zero value makes dc(1) not exit. +If any expressions or expression files are given on the command\-line +with \f[B]\-e\f[R], \f[B]\-\-expression\f[R], \f[B]\-f\f[R], or +\f[B]\-\-file\f[R], then if this environment variable exists and +contains an integer, a non\-zero value makes dc(1) exit after executing +the expressions and expression files, and a zero value makes dc(1) not +exit. .RS .PP This environment variable overrides the default, which can be queried -with the \f[B]-h\f[R] or \f[B]--help\f[R] options. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE -.SH EXIT STATUS +.TP +\f[B]DC_DIGIT_CLAMP\f[R] +When parsing numbers and if this environment variable exists and +contains an integer, a non\-zero value makes dc(1) clamp digits that are +greater than or equal to the current \f[B]ibase\f[R] so that all such +digits are considered equal to the \f[B]ibase\f[R] minus 1, and a zero +value disables such clamping so that those digits are always equal to +their value, which is multiplied by the power of the \f[B]ibase\f[R]. +.RS .PP +This never applies to single\-digit numbers, as per the bc(1) standard +(see the \f[B]STANDARDS\f[R] section). +.PP +This environment variable overrides the default, which can be queried +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. +.RE +.SH EXIT STATUS dc(1) returns the following exit statuses: .TP \f[B]0\f[R] @@ -1199,7 +1293,7 @@ Math errors include divide by \f[B]0\f[R], taking the square root of a negative number, attempting to convert a negative number to a hardware integer, overflow when converting a number to a hardware integer, overflow when calculating the size of a number, and attempting to use a -non-integer where an integer is required. +non\-integer where an integer is required. .PP Converting to a hardware integer happens for the second operand of the power (\f[B]\[ha]\f[R]) operator. @@ -1233,7 +1327,7 @@ A fatal error occurred. Fatal errors include memory allocation errors, I/O errors, failing to open files, attempting to use files that do not have only ASCII characters (dc(1) only accepts ASCII characters), attempting to open a -directory as a file, and giving invalid command-line options. +directory as a file, and giving invalid command\-line options. .RE .PP The exit status \f[B]4\f[R] is special; when a fatal error occurs, dc(1) @@ -1244,17 +1338,17 @@ interactive mode (see the \f[B]INTERACTIVE MODE\f[R] section), since dc(1) resets its state (see the \f[B]RESET\f[R] section) and accepts more input when one of those errors occurs in interactive mode. This is also the case when interactive mode is forced by the -\f[B]-i\f[R] flag or \f[B]--interactive\f[R] option. +\f[B]\-i\f[R] flag or \f[B]\-\-interactive\f[R] option. .PP These exit statuses allow dc(1) to be used in shell scripting with error checking, and its normal behavior can be forced by using the -\f[B]-i\f[R] flag or \f[B]--interactive\f[R] option. +\f[B]\-i\f[R] flag or \f[B]\-\-interactive\f[R] option. .SH INTERACTIVE MODE -.PP -Like bc(1), dc(1) has an interactive mode and a non-interactive mode. +Like bc(1), dc(1) has an interactive mode and a non\-interactive mode. Interactive mode is turned on automatically when both \f[B]stdin\f[R] -and \f[B]stdout\f[R] are hooked to a terminal, but the \f[B]-i\f[R] flag -and \f[B]--interactive\f[R] option can turn it on in other situations. +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. .PP In interactive mode, dc(1) attempts to recover from errors (see the \f[B]RESET\f[R] section), and in normal execution, flushes @@ -1263,7 +1357,6 @@ dc(1) may also reset on \f[B]SIGINT\f[R] instead of exit, depending on the contents of, or default for, the \f[B]DC_SIGINT_RESET\f[R] environment variable (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). .SH TTY MODE -.PP If \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all connected to a TTY, then \[lq]TTY mode\[rq] is considered to be available, and thus, dc(1) can turn on TTY mode, subject to some @@ -1271,45 +1364,42 @@ settings. .PP If there is the environment variable \f[B]DC_TTY_MODE\f[R] in the environment (see the \f[B]ENVIRONMENT VARIABLES\f[R] section), then if -that environment variable contains a non-zero integer, dc(1) will turn +that environment variable contains a non\-zero integer, dc(1) will turn on TTY mode when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all connected to a TTY. If the \f[B]DC_TTY_MODE\f[R] environment variable exists but is -\f[I]not\f[R] a non-zero integer, then dc(1) will not turn TTY mode on. +\f[I]not\f[R] a non\-zero integer, then dc(1) will not turn TTY mode on. .PP If the environment variable \f[B]DC_TTY_MODE\f[R] does \f[I]not\f[R] exist, the default setting is used. -The default setting can be queried with the \f[B]-h\f[R] or -\f[B]--help\f[R] options. +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. Like TTY mode itself, it can be turned on or off with an environment variable: \f[B]DC_PROMPT\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). .PP -If the environment variable \f[B]DC_PROMPT\f[R] exists and is a non-zero -integer, then the prompt is turned on when \f[B]stdin\f[R], +If the environment variable \f[B]DC_PROMPT\f[R] exists and is a +non\-zero integer, then the prompt is turned on when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are connected to a TTY and the -\f[B]-P\f[R] and \f[B]--no-prompt\f[R] options were not used. +\f[B]\-P\f[R] and \f[B]\-\-no\-prompt\f[R] options were not used. The read prompt will be turned on under the same conditions, except that -the \f[B]-R\f[R] and \f[B]--no-read-prompt\f[R] options must also not be -used. +the \f[B]\-R\f[R] and \f[B]\-\-no\-read\-prompt\f[R] options must also +not be used. .PP However, if \f[B]DC_PROMPT\f[R] does not exist, the prompt can be enabled or disabled with the \f[B]DC_TTY_MODE\f[R] environment variable, -the \f[B]-P\f[R] and \f[B]--no-prompt\f[R] options, and the \f[B]-R\f[R] -and \f[B]--no-read-prompt\f[R] options. +the \f[B]\-P\f[R] and \f[B]\-\-no\-prompt\f[R] options, and the +\f[B]\-R\f[R] and \f[B]\-\-no\-read\-prompt\f[R] options. See the \f[B]ENVIRONMENT VARIABLES\f[R] and \f[B]OPTIONS\f[R] sections for more details. .SH SIGNAL HANDLING -.PP Sending a \f[B]SIGINT\f[R] will cause dc(1) to do one of two things. .PP If dc(1) is not in interactive mode (see the \f[B]INTERACTIVE MODE\f[R] @@ -1318,7 +1408,7 @@ section), or the \f[B]DC_SIGINT_RESET\f[R] environment variable (see the an integer or it is zero, dc(1) will exit. .PP However, if dc(1) is in interactive mode, and the -\f[B]DC_SIGINT_RESET\f[R] or its default is an integer and non-zero, +\f[B]DC_SIGINT_RESET\f[R] or its default is an integer and non\-zero, then dc(1) will stop executing the current input and reset (see the \f[B]RESET\f[R] section) upon receiving a \f[B]SIGINT\f[R]. .PP @@ -1341,19 +1431,17 @@ the user to continue. \f[B]SIGTERM\f[R] and \f[B]SIGQUIT\f[R] cause dc(1) to clean up and exit, and it uses the default handler for all other signals. .SH SEE ALSO -.PP bc(1) .SH STANDARDS -.PP -The dc(1) utility operators are compliant with the operators in the IEEE -Std 1003.1-2017 (\[lq]POSIX.1-2017\[rq]) specification at -https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html for -bc(1). +The dc(1) utility operators and some behavior are compliant with the +operators in the IEEE Std 1003.1\-2017 (\[lq]POSIX.1\-2017\[rq]) bc(1) +specification at +https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html . .SH BUGS -.PP None are known. -Report bugs at https://git.yzena.com/gavin/bc. +Report bugs at https://git.gavinhoward.com/gavin/bc . .SH AUTHOR -.PP -Gavin D. -Howard <gavin@yzena.com> and contributors. +Gavin D. Howard \c +.MT gavin@gavinhoward.com +.ME \c +\ and contributors. diff --git a/contrib/bc/manuals/dc/EHN.1.md b/contrib/bc/manuals/dc/EHN.1.md index e3b42d4453f6..51e30849996e 100644 --- a/contrib/bc/manuals/dc/EHN.1.md +++ b/contrib/bc/manuals/dc/EHN.1.md @@ -2,7 +2,7 @@ SPDX-License-Identifier: BSD-2-Clause -Copyright (c) 2018-2021 Gavin D. Howard and contributors. +Copyright (c) 2018-2024 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** - -: Prints a usage message and quits. - -**-v**, **-V**, **-\-version** - -: Print the version information (copyright header) and exit. - -**-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). +**-C**, **-\-no-digit-clamp** - This is a **non-portable extension**. - -**-P**, **-\-no-prompt** +: Disables clamping of digits greater than or equal to the current **ibase** + when parsing numbers. -: 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 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. - This option does not disable the regular prompt because the read prompt is - only used when the **?** command is used. + If this and/or the **-c** or **-\-digit-clamp** options are given multiple + times, the last one given 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 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**. -**-x** **-\-extended-register** - -: Enables extended register mode. See the *Extended Register Mode* subsection - of the **REGISTERS** section for more information. +**-c**, **-\-digit-clamp** - This is a **non-portable extension**. +: Enables clamping of digits greater than or equal to the current **ibase** + when parsing numbers. -**-z**, **-\-leading-zeroes** + 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. -: Makes dc(1) print all numbers greater than **-1** and less than **1**, and - not equal to **0**, with a leading zero. + If this and/or the **-C** or **-\-no-digit-clamp** options are given + multiple times, the last one given is used. - 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,24 @@ 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 is a **non-portable extension**. + All long options are **non-portable extensions**. # STDIN @@ -263,15 +296,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**. - -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**. +Uppercase letters are equal to **9** plus 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** (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 +827,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 +851,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) @@ -840,6 +914,12 @@ other character produces a parse error (see the **ERRORS** section). : Pushes the line length set by **DC_LINE_LENGTH** (see the **ENVIRONMENT VARIABLES** section) onto the stack. +**gx** + +: Pushes **1** onto the stack if extended register mode is on, **0** + otherwise. See the *Extended Register Mode* subsection of the **REGISTERS** + section for more information. + **gz** : Pushes **0** onto the stack if the leading zero setting has not been enabled @@ -881,11 +961,14 @@ the next non-space characters do not match that regex. When dc(1) encounters an error or a signal that it has a non-default handler for, it resets. This means that several things happen. -First, any macros that are executing are stopped and popped off the stack. -The behavior is not unlike that of exceptions in programming languages. Then -the execution point is set so that any code waiting to execute (after all +First, any macros that are executing are stopped and popped off the execution +stack. The behavior is not unlike that of exceptions in programming languages. +Then the execution point is set so that any code waiting to execute (after all macros returned) is skipped. +However, the stack of values is *not* cleared; in interactive mode, users can +inspect the stack and manipulate it. + Thus, when dc(1) resets, it skips any remaining code waiting to be executed. Then, if it is interactive mode, and the error was not a fatal error (see the **EXIT STATUS** section), it asks for more input; otherwise, it exits with the @@ -974,7 +1057,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 +1147,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 +1256,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,14 +1312,14 @@ 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.gavinhoward.com/gavin/bc . # AUTHOR -Gavin D. Howard <gavin@yzena.com> and contributors. +Gavin D. Howard <gavin@gavinhoward.com> and contributors. diff --git a/contrib/bc/manuals/dc/EN.1 b/contrib/bc/manuals/dc/EN.1 index d941c130e847..5ce8defc91c7 100644 --- a/contrib/bc/manuals/dc/EN.1 +++ b/contrib/bc/manuals/dc/EN.1 @@ -1,7 +1,7 @@ .\" .\" SPDX-License-Identifier: BSD-2-Clause .\" -.\" Copyright (c) 2018-2021 Gavin D. Howard and contributors. +.\" Copyright (c) 2018-2024 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,124 +25,82 @@ .\" 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" "August 2024" "Gavin D. Howard" "General Commands Manual" .nh .ad l .SH Name -.PP -dc - arbitrary-precision decimal reverse-Polish notation calculator +dc \- arbitrary\-precision decimal reverse\-Polish notation calculator .SH SYNOPSIS -.PP -\f[B]dc\f[R] [\f[B]-hiPRvVx\f[R]] [\f[B]--version\f[R]] -[\f[B]--help\f[R]] [\f[B]--interactive\f[R]] [\f[B]--no-prompt\f[R]] -[\f[B]--no-read-prompt\f[R]] [\f[B]--extended-register\f[R]] -[\f[B]-e\f[R] \f[I]expr\f[R]] -[\f[B]--expression\f[R]=\f[I]expr\f[R]\&...] [\f[B]-f\f[R] -\f[I]file\f[R]\&...] [\f[B]--file\f[R]=\f[I]file\f[R]\&...] +\f[B]dc\f[R] [\f[B]\-cChiPRvVx\f[R]] [\f[B]\-\-version\f[R]] +[\f[B]\-\-help\f[R]] [\f[B]\-\-digit\-clamp\f[R]] +[\f[B]\-\-no\-digit\-clamp\f[R]] [\f[B]\-\-interactive\f[R]] +[\f[B]\-\-no\-prompt\f[R]] [\f[B]\-\-no\-read\-prompt\f[R]] +[\f[B]\-\-extended\-register\f[R]] [\f[B]\-e\f[R] \f[I]expr\f[R]] +[\f[B]\-\-expression\f[R]=\f[I]expr\f[R]\&...] +[\f[B]\-f\f[R] \f[I]file\f[R]\&...] +[\f[B]\-\-file\f[R]=\f[I]file\f[R]\&...] [\f[I]file\f[R]\&...] .SH DESCRIPTION -.PP -dc(1) is an arbitrary-precision calculator. +dc(1) is an arbitrary\-precision calculator. It uses a stack (reverse Polish notation) to store numbers and results of computations. Arithmetic operations pop arguments off of the stack and push the results. .PP -If no files are given on the command-line, then dc(1) reads from +If no files are given on the command\-line, then dc(1) reads from \f[B]stdin\f[R] (see the \f[B]STDIN\f[R] section). Otherwise, those files are processed, and dc(1) will then exit. .PP If a user wants to set up a standard environment, they can use \f[B]DC_ENV_ARGS\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). For example, if a user wants the \f[B]scale\f[R] always set to -\f[B]10\f[R], they can set \f[B]DC_ENV_ARGS\f[R] to \f[B]-e 10k\f[R], +\f[B]10\f[R], they can set \f[B]DC_ENV_ARGS\f[R] to \f[B]\-e 10k\f[R], and this dc(1) will always start with a \f[B]scale\f[R] of \f[B]10\f[R]. .SH OPTIONS -.PP The following are the options that dc(1) accepts. .TP -\f[B]-h\f[R], \f[B]--help\f[R] -Prints a usage message and quits. -.TP -\f[B]-v\f[R], \f[B]-V\f[R], \f[B]--version\f[R] -Print the version information (copyright header) and exit. -.TP -\f[B]-i\f[R], \f[B]--interactive\f[R] -Forces interactive mode. -(See the \f[B]INTERACTIVE MODE\f[R] section.) +\f[B]\-C\f[R], \f[B]\-\-no\-digit\-clamp\f[R] +Disables clamping of digits greater than or equal to the current +\f[B]ibase\f[R] when parsing numbers. .RS .PP -This is a \f[B]non-portable extension\f[R]. -.RE -.TP -\f[B]-L\f[R], \f[B]--no-line-length\f[R] -Disables line length checking and prints numbers without backslashes and -newlines. -In other words, this option sets \f[B]BC_LINE_LENGTH\f[R] to \f[B]0\f[R] -(see the \f[B]ENVIRONMENT VARIABLES\f[R] section). -.RS +This means that the value added to a number from a digit is always that +digit\[cq]s value multiplied by the value of ibase raised to the power +of the digit\[cq]s position, which starts from 0 at the least +significant digit. .PP -This is a \f[B]non-portable extension\f[R]. -.RE -.TP -\f[B]-P\f[R], \f[B]--no-prompt\f[R] -Disables the prompt in TTY mode. -(The prompt is only enabled in TTY mode. -See the \f[B]TTY MODE\f[R] section.) This is mostly for those users that -do not want a prompt or are not used to having them in dc(1). -Most of those users would want to put this option in -\f[B]DC_ENV_ARGS\f[R]. -.RS +If this and/or the \f[B]\-c\f[R] or \f[B]\-\-digit\-clamp\f[R] options +are given multiple times, the last one given is used. .PP -These options override the \f[B]DC_PROMPT\f[R] and \f[B]DC_TTY_MODE\f[R] -environment variables (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). +This option overrides the \f[B]DC_DIGIT_CLAMP\f[R] environment variable +(see the \f[B]ENVIRONMENT VARIABLES\f[R] section) and the default, which +can be queried with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-R\f[R], \f[B]--no-read-prompt\f[R] -Disables the read prompt in TTY mode. -(The read prompt is only enabled in TTY mode. -See the \f[B]TTY MODE\f[R] section.) This is mostly for those users that -do not want a read prompt or are not used to having them in dc(1). -Most of those users would want to put this option in -\f[B]BC_ENV_ARGS\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). -This option is also useful in hash bang lines of dc(1) scripts that -prompt for user input. +\f[B]\-c\f[R], \f[B]\-\-digit\-clamp\f[R] +Enables clamping of digits greater than or equal to the current +\f[B]ibase\f[R] when parsing numbers. .RS .PP -This option does not disable the regular prompt because the read prompt -is only used when the \f[B]?\f[R] command is used. -.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 +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 -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 +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 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]. +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] +\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 @@ -151,41 +109,44 @@ 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 +If this option is given on the command\-line (i.e., not in \f[B]DC_ENV_ARGS\f[R], see the \f[B]ENVIRONMENT VARIABLES\f[R] section), then after processing all expressions and files, dc(1) will exit, unless -\f[B]-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to -\f[B]-f\f[R] or \f[B]--file\f[R], whether on the command-line or in +\f[B]\-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to +\f[B]\-f\f[R] or \f[B]\-\-file\f[R], whether on the command\-line or in \f[B]DC_ENV_ARGS\f[R]. -However, if any other \f[B]-e\f[R], \f[B]--expression\f[R], -\f[B]-f\f[R], or \f[B]--file\f[R] arguments are given after -\f[B]-f-\f[R] or equivalent is given, dc(1) will give a fatal error and -exit. +However, if any other \f[B]\-e\f[R], \f[B]\-\-expression\f[R], +\f[B]\-f\f[R], or \f[B]\-\-file\f[R] arguments are given after +\f[B]\-f\-\f[R] or equivalent is given, dc(1) will give a fatal error +and exit. .PP -This is a \f[B]non-portable extension\f[R]. +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] +\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 +If this option is given on the command\-line (i.e., not in \f[B]DC_ENV_ARGS\f[R], see the \f[B]ENVIRONMENT VARIABLES\f[R] section), then after processing all expressions and files, dc(1) will exit, unless -\f[B]-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to -\f[B]-f\f[R] or \f[B]--file\f[R]. -However, if any other \f[B]-e\f[R], \f[B]--expression\f[R], -\f[B]-f\f[R], or \f[B]--file\f[R] arguments are given after -\f[B]-f-\f[R] or equivalent is given, dc(1) will give a fatal error and -exit. +\f[B]\-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to +\f[B]\-f\f[R] or \f[B]\-\-file\f[R]. +However, if any other \f[B]\-e\f[R], \f[B]\-\-expression\f[R], +\f[B]\-f\f[R], or \f[B]\-\-file\f[R] arguments are given after +\f[B]\-f\-\f[R] or equivalent is given, dc(1) will give a fatal error +and exit. .PP -This is a \f[B]non-portable extension\f[R]. +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] +\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. It is a fatal error if \f[I]ibase\f[R] is not a valid number. @@ -193,10 +154,28 @@ It is a fatal error if \f[I]ibase\f[R] is not a valid number. .PP If multiple instances of this option are given, the last is used. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-O\f[R] \f[I]obase\f[R], \f[B]--obase\f[R]=\f[I]obase\f[R] +\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. It is a fatal error if \f[I]obase\f[R] is not a valid number. @@ -204,10 +183,48 @@ It is a fatal error if \f[I]obase\f[R] is not a valid number. .PP If multiple instances of this option are given, the last is used. .PP -This is a \f[B]non-portable extension\f[R]. +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] +\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. @@ -215,15 +232,34 @@ It is a fatal error if \f[I]scale\f[R] is not a valid number. .PP If multiple instances of this option are given, the last is used. .PP -This is a \f[B]non-portable extension\f[R]. +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 -All long options are \f[B]non-portable extensions\f[R]. -.SH STDIN +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 -If no files are given on the command-line and no files or expressions -are given by the \f[B]-f\f[R], \f[B]--file\f[R], \f[B]-e\f[R], or -\f[B]--expression\f[R] options, then dc(1) reads from \f[B]stdin\f[R]. +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 +If no files are given on the command\-line and no files or expressions +are given by the \f[B]\-f\f[R], \f[B]\-\-file\f[R], \f[B]\-e\f[R], or +\f[B]\-\-expression\f[R] options, then dc(1) reads from \f[B]stdin\f[R]. .PP However, there is a caveat to this. .PP @@ -233,8 +269,7 @@ ended. This means that, except for escaped brackets, all brackets must be balanced before dc(1) parses and executes. .SH STDOUT -.PP -Any non-error output is written to \f[B]stdout\f[R]. +Any non\-error output is written to \f[B]stdout\f[R]. In addition, if history (see the \f[B]HISTORY\f[R] section) and the prompt (see the \f[B]TTY MODE\f[R] section) are enabled, both are output to \f[B]stdout\f[R]. @@ -242,7 +277,7 @@ to \f[B]stdout\f[R]. \f[B]Note\f[R]: Unlike other dc(1) implementations, this dc(1) will issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot write to \f[B]stdout\f[R], so if \f[B]stdout\f[R] is closed, as in -\f[B]dc >&-\f[R], it will quit with an error. +\f[B]dc >&\-\f[R], it will quit with an error. This is done so that dc(1) can report problems when \f[B]stdout\f[R] is redirected to a file. .PP @@ -250,13 +285,12 @@ If there are scripts that depend on the behavior of other dc(1) implementations, it is recommended that those scripts be changed to redirect \f[B]stdout\f[R] to \f[B]/dev/null\f[R]. .SH STDERR -.PP Any error output is written to \f[B]stderr\f[R]. .PP \f[B]Note\f[R]: Unlike other dc(1) implementations, this dc(1) will issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot write to \f[B]stderr\f[R], so if \f[B]stderr\f[R] is closed, as in -\f[B]dc 2>&-\f[R], it will quit with an error. +\f[B]dc 2>&\-\f[R], it will quit with an error. This is done so that dc(1) can exit with an error code when \f[B]stderr\f[R] is redirected to a file. .PP @@ -264,7 +298,6 @@ If there are scripts that depend on the behavior of other dc(1) implementations, it is recommended that those scripts be changed to redirect \f[B]stderr\f[R] to \f[B]/dev/null\f[R]. .SH SYNTAX -.PP Each item in the input source code, either a number (see the \f[B]NUMBERS\f[R] section) or a command (see the \f[B]COMMANDS\f[R] section), is processed and executed, in order. @@ -299,30 +332,57 @@ precision of any operations (with exceptions). The max allowable value for \f[B]scale\f[R] can be queried in dc(1) programs with the \f[B]V\f[R] command. .SS Comments -.PP Comments go from \f[B]#\f[R] until, and not including, the next newline. -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .SH NUMBERS -.PP Numbers are strings made up of digits, uppercase letters up to \f[B]F\f[R], and at most \f[B]1\f[R] period for a radix. Numbers can have up to \f[B]DC_NUM_MAX\f[R] digits. -Uppercase letters are equal to \f[B]9\f[R] + their position in the +Uppercase letters are equal to \f[B]9\f[R] plus their position in the alphabet (i.e., \f[B]A\f[R] equals \f[B]10\f[R], or \f[B]9+1\f[R]). -If a digit or letter makes no sense with the current value of -\f[B]ibase\f[R], they are set to the value of the highest valid digit in -\f[B]ibase\f[R]. .PP -Single-character numbers (i.e., \f[B]A\f[R] alone) take the value that -they would have if they were valid digits, regardless of the value of -\f[B]ibase\f[R]. +If a digit or letter makes no sense with the current value of +\f[B]ibase\f[R] (i.e., they are greater than or equal to the current +value of \f[B]ibase\f[R]), then the behavior depends on the existence of +the \f[B]\-c\f[R]/\f[B]\-\-digit\-clamp\f[R] or +\f[B]\-C\f[R]/\f[B]\-\-no\-digit\-clamp\f[R] options (see the +\f[B]OPTIONS\f[R] section), the existence and setting of the +\f[B]DC_DIGIT_CLAMP\f[R] environment variable (see the \f[B]ENVIRONMENT +VARIABLES\f[R] section), or the default, which can be queried with the +\f[B]\-h\f[R]/\f[B]\-\-help\f[R] option. +.PP +If clamping is off, then digits or letters that are greater than or +equal to the current value of \f[B]ibase\f[R] are not changed. +Instead, their given value is multiplied by the appropriate power of +\f[B]ibase\f[R] and added into the number. +This means that, with an \f[B]ibase\f[R] of \f[B]3\f[R], the number +\f[B]AB\f[R] is equal to \f[B]3\[ha]1*A+3\[ha]0*B\f[R], which is +\f[B]3\f[R] times \f[B]10\f[R] plus \f[B]11\f[R], or \f[B]41\f[R]. +.PP +If clamping is on, then digits or letters that are greater than or equal +to the current value of \f[B]ibase\f[R] are set to the value of the +highest valid digit in \f[B]ibase\f[R] before being multiplied by the +appropriate power of \f[B]ibase\f[R] and added into the number. +This means that, with an \f[B]ibase\f[R] of \f[B]3\f[R], the number +\f[B]AB\f[R] is equal to \f[B]3\[ha]1*2+3\[ha]0*2\f[R], which is +\f[B]3\f[R] times \f[B]2\f[R] plus \f[B]2\f[R], or \f[B]8\f[R]. +.PP +There is one exception to clamping: single\-character numbers (i.e., +\f[B]A\f[R] alone). +Such numbers are never clamped and always take the value they would have +in the highest possible \f[B]ibase\f[R]. This means that \f[B]A\f[R] alone always equals decimal \f[B]10\f[R] and -\f[B]F\f[R] alone always equals decimal \f[B]15\f[R]. +\f[B]Z\f[R] alone always equals decimal \f[B]35\f[R]. +This behavior is mandated by the standard for bc(1) (see the STANDARDS +section) and is meant to provide an easy way to set the current +\f[B]ibase\f[R] (with the \f[B]i\f[R] command) regardless of the current +value of \f[B]ibase\f[R]. +.PP +If clamping is on, and the clamped value of a character is needed, use a +leading zero, i.e., for \f[B]A\f[R], use \f[B]0A\f[R]. .SH COMMANDS -.PP The valid commands are listed below. .SS Printing -.PP These commands are used for printing. .TP \f[B]p\f[R] @@ -343,12 +403,12 @@ Pops a value off the stack. .PP If the value is a number, it is truncated and the absolute value of the result is printed as though \f[B]obase\f[R] is \f[B]256\f[R] and each -digit is interpreted as an 8-bit ASCII character, making it a byte +digit is interpreted as an 8\-bit ASCII character, making it a byte stream. .PP If the value is a string, it is printed without a trailing newline. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]f\f[R] @@ -359,7 +419,6 @@ without altering anything. Users should use this command when they get lost. .RE .SS Arithmetic -.PP These are the commands used for arithmetic. .TP \f[B]+\f[R] @@ -368,7 +427,7 @@ pushed onto the stack. The \f[I]scale\f[R] of the result is equal to the max \f[I]scale\f[R] of both operands. .TP -\f[B]-\f[R] +\f[B]\-\f[R] The top two values are popped off the stack, subtracted, and the result is pushed onto the stack. The \f[I]scale\f[R] of the result is equal to the max \f[I]scale\f[R] of @@ -389,7 +448,7 @@ pushed onto the stack. The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R]. .RS .PP -The first value popped off of the stack must be non-zero. +The first value popped off of the stack must be non\-zero. .RE .TP \f[B]%\f[R] @@ -399,10 +458,10 @@ is pushed onto the stack. .PP Remaindering is equivalent to 1) Computing \f[B]a/b\f[R] to current \f[B]scale\f[R], and 2) Using the result of step 1 to calculate -\f[B]a-(a/b)*b\f[R] to \f[I]scale\f[R] +\f[B]a\-(a/b)*b\f[R] to \f[I]scale\f[R] \f[B]max(scale+scale(b),scale(a))\f[R]. .PP -The first value popped off of the stack must be non-zero. +The first value popped off of the stack must be non\-zero. .RE .TP \f[B]\[ti]\f[R] @@ -413,9 +472,9 @@ This is equivalent to \f[B]x y / x y %\f[R] except that \f[B]x\f[R] and \f[B]y\f[R] are only evaluated once. .RS .PP -The first value popped off of the stack must be non-zero. +The first value popped off of the stack must be non\-zero. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]\[ha]\f[R] @@ -426,7 +485,7 @@ The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R]. .PP The first value popped off of the stack must be an integer, and if that value is negative, the second value popped off of the stack must be -non-zero. +non\-zero. .RE .TP \f[B]v\f[R] @@ -435,7 +494,7 @@ the result is pushed onto the stack. The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R]. .RS .PP -The value popped off of the stack must be non-negative. +The value popped off of the stack must be non\-negative. .RE .TP \f[B]_\f[R] @@ -445,7 +504,7 @@ or other commands), then that number is input as a negative number. .PP Otherwise, the top value on the stack is popped and copied, and the copy is negated and pushed onto the stack. -This behavior without a number is a \f[B]non-portable extension\f[R]. +This behavior without a number is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]b\f[R] @@ -454,7 +513,7 @@ back onto the stack. Otherwise, its absolute value is pushed onto the stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]|\f[R] @@ -463,12 +522,12 @@ is computed, and the result is pushed onto the stack. .RS .PP The first value popped is used as the reduction modulus and must be an -integer and non-zero. +integer and non\-zero. The second value popped is used as the exponent and must be an integer -and non-negative. +and non\-negative. The third value popped is the base and must be an integer. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]G\f[R] @@ -476,7 +535,7 @@ The top two values are popped off of the stack, they are compared, and a \f[B]1\f[R] is pushed if they are equal, or \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]N\f[R] @@ -484,7 +543,7 @@ The top value is popped off of the stack, and if it a \f[B]0\f[R], a \f[B]1\f[R] is pushed; otherwise, a \f[B]0\f[R] is pushed. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B](\f[R] @@ -493,7 +552,7 @@ The top two values are popped off of the stack, they are compared, and a \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]{\f[R] @@ -502,7 +561,7 @@ The top two values are popped off of the stack, they are compared, and a or \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B])\f[R] @@ -511,7 +570,7 @@ The top two values are popped off of the stack, they are compared, and a \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]}\f[R] @@ -520,36 +579,35 @@ The top two values are popped off of the stack, they are compared, and a second, or \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]M\f[R] The top two values are popped off of the stack. -If they are both non-zero, a \f[B]1\f[R] is pushed onto the stack. +If they are both non\-zero, a \f[B]1\f[R] is pushed onto the stack. If either of them is zero, or both of them are, then a \f[B]0\f[R] is pushed onto the stack. .RS .PP This is like the \f[B]&&\f[R] operator in bc(1), and it is \f[I]not\f[R] -a short-circuit operator. +a short\-circuit operator. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]m\f[R] The top two values are popped off of the stack. -If at least one of them is non-zero, a \f[B]1\f[R] is pushed onto the +If at least one of them is non\-zero, a \f[B]1\f[R] is pushed onto the stack. If both of them are zero, then a \f[B]0\f[R] is pushed onto the stack. .RS .PP This is like the \f[B]||\f[R] operator in bc(1), and it is \f[I]not\f[R] -a short-circuit operator. +a short\-circuit operator. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .SS Stack Control -.PP These commands control the stack. .TP \f[B]c\f[R] @@ -565,7 +623,6 @@ Swaps (\[lq]reverses\[rq]) the two top items on the stack. \f[B]R\f[R] Pops (\[lq]removes\[rq]) the top value from the stack. .SS Register Control -.PP These commands control registers (see the \f[B]REGISTERS\f[R] section). .TP \f[B]s\f[R]\f[I]r\f[R] @@ -587,7 +644,6 @@ push it onto the main stack. The previous value in the stack for register \f[I]r\f[R], if any, is now accessible via the \f[B]l\f[R]\f[I]r\f[R] command. .SS Parameters -.PP These commands control the values of \f[B]ibase\f[R], \f[B]obase\f[R], and \f[B]scale\f[R]. Also see the \f[B]SYNTAX\f[R] section. @@ -614,7 +670,7 @@ If the value on top of the stack has any \f[I]scale\f[R], the .TP \f[B]k\f[R] Pops the value off of the top of the stack and uses it to set -\f[B]scale\f[R], which must be non-negative. +\f[B]scale\f[R], which must be non\-negative. .RS .PP If the value on top of the stack has any \f[I]scale\f[R], the @@ -635,7 +691,7 @@ Pushes the maximum allowable value of \f[B]ibase\f[R] onto the main stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]U\f[R] @@ -643,7 +699,7 @@ Pushes the maximum allowable value of \f[B]obase\f[R] onto the main stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]V\f[R] @@ -651,10 +707,9 @@ Pushes the maximum allowable value of \f[B]scale\f[R] onto the main stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .SS Strings -.PP The following commands control strings. .PP dc(1) can work with both numbers and strings, and registers (see the @@ -692,16 +747,16 @@ The value on top of the stack is popped. If it is a number, it is truncated and its absolute value is taken. The result mod \f[B]256\f[R] is calculated. If that result is \f[B]0\f[R], push an empty string; otherwise, push a -one-character string where the character is the result of the mod +one\-character string where the character is the result of the mod interpreted as an ASCII character. .PP If it is a string, then a new string is made. If the original string is empty, the new string is empty. If it is not, then the first character of the original string is used to -create the new string as a one-character string. +create the new string as a one\-character string. The new string is then pushed onto the stack. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]x\f[R] @@ -737,7 +792,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]!>\f[R]\f[I]r\f[R] @@ -758,7 +813,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]<\f[R]\f[I]r\f[R] @@ -779,7 +834,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]!<\f[R]\f[I]r\f[R] @@ -800,7 +855,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]=\f[R]\f[I]r\f[R] @@ -821,7 +876,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]!=\f[R]\f[I]r\f[R] @@ -842,7 +897,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]?\f[R] @@ -855,7 +910,7 @@ the execution of the macro that executed it. If there are no macros, or only one macro executing, dc(1) exits. .TP \f[B]Q\f[R] -Pops a value from the stack which must be non-negative and is used the +Pops a value from the stack which must be non\-negative and is used the number of macro executions to pop off of the execution stack. If the number of levels to pop is greater than the number of executing macros, dc(1) exits. @@ -866,8 +921,11 @@ The execution stack is the stack of string executions. The number that is pushed onto the stack is exactly as many as is needed to make dc(1) exit with the \f[B]Q\f[R] command, so the sequence \f[B],Q\f[R] will make dc(1) exit. -.SS Status +.RS .PP +This is a \f[B]non\-portable extension\f[R]. +.RE +.SS Status These commands query status of the stack or its top value. .TP \f[B]Z\f[R] @@ -892,6 +950,24 @@ stack. If it is a string, pushes \f[B]0\f[R]. .RE .TP +\f[B]u\f[R] +Pops one value off of the stack. +If the value is a number, this pushes \f[B]1\f[R] onto the stack. +Otherwise (if it is a string), it pushes \f[B]0\f[R]. +.RS +.PP +This is a \f[B]non\-portable extension\f[R]. +.RE +.TP +\f[B]t\f[R] +Pops one value off of the stack. +If the value is a string, this pushes \f[B]1\f[R] onto the stack. +Otherwise (if it is a number), it pushes \f[B]0\f[R]. +.RS +.PP +This is a \f[B]non\-portable extension\f[R]. +.RE +.TP \f[B]z\f[R] Pushes the current depth of the stack (before execution of this command) onto the stack. @@ -907,10 +983,9 @@ register\[cq]s stack must always have at least one item; dc(1) will give an error and reset otherwise (see the \f[B]RESET\f[R] section). This means that this command will never push \f[B]0\f[R]. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .SS Arrays -.PP These commands manipulate arrays. .TP \f[B]:\f[R]\f[I]r\f[R] @@ -927,10 +1002,9 @@ The selected value is then pushed onto the stack. Pushes the length of the array \f[I]r\f[R] onto the stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .SS Global Settings -.PP These commands retrieve global settings. These are the only commands that require multiple specific characters, and all of them begin with the letter \f[B]g\f[R]. @@ -942,12 +1016,17 @@ section). Pushes the line length set by \f[B]DC_LINE_LENGTH\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section) onto the stack. .TP +\f[B]gx\f[R] +Pushes \f[B]1\f[R] onto the stack if extended register mode is on, +\f[B]0\f[R] otherwise. +See the \f[I]Extended Register Mode\f[R] subsection of the +\f[B]REGISTERS\f[R] section for more information. +.TP \f[B]gz\f[R] Pushes \f[B]0\f[R] onto the stack if the leading zero setting has not -been enabled with the \f[B]-z\f[R] or \f[B]--leading-zeroes\f[R] options -(see the \f[B]OPTIONS\f[R] section), non-zero otherwise. +been enabled with the \f[B]\-z\f[R] or \f[B]\-\-leading\-zeroes\f[R] +options (see the \f[B]OPTIONS\f[R] section), non\-zero otherwise. .SH REGISTERS -.PP Registers are names that can store strings, numbers, and arrays. (Number/string registers do not interfere with array registers.) .PP @@ -957,45 +1036,45 @@ All registers, when first referenced, have one value (\f[B]0\f[R]) in their stack, and it is a runtime error to attempt to pop that item off of the register stack. .PP -In non-extended register mode, a register name is just the single +In non\-extended register mode, a register name is just the single character that follows any command that needs a register name. The only exceptions are: a newline (\f[B]`\[rs]n'\f[R]) and a left bracket (\f[B]`['\f[R]); it is a parse error for a newline or a left bracket to be used as a register name. .SS Extended Register Mode -.PP Unlike most other dc(1) implentations, this dc(1) provides nearly unlimited amounts of registers, if extended register mode is enabled. .PP -If extended register mode is enabled (\f[B]-x\f[R] or -\f[B]--extended-register\f[R] command-line arguments are given), then -normal single character registers are used \f[I]unless\f[R] the +If extended register mode is enabled (\f[B]\-x\f[R] or +\f[B]\-\-extended\-register\f[R] command\-line arguments are given), +then normal single character registers are used \f[I]unless\f[R] the character immediately following a command that needs a register name is a space (according to \f[B]isspace()\f[R]) and not a newline (\f[B]`\[rs]n'\f[R]). .PP In that case, the register name is found according to the regex -\f[B][a-z][a-z0-9_]*\f[R] (like bc(1) identifiers), and it is a parse -error if the next non-space characters do not match that regex. +\f[B][a\-z][a\-z0\-9_]*\f[R] (like bc(1) identifiers), and it is a parse +error if the next non\-space characters do not match that regex. .SH RESET -.PP -When dc(1) encounters an error or a signal that it has a non-default +When dc(1) encounters an error or a signal that it has a non\-default handler for, it resets. This means that several things happen. .PP First, any macros that are executing are stopped and popped off the -stack. +execution stack. The behavior is not unlike that of exceptions in programming languages. Then the execution point is set so that any code waiting to execute (after all macros returned) is skipped. .PP +However, the stack of values is \f[I]not\f[R] cleared; in interactive +mode, users can inspect the stack and manipulate it. +.PP Thus, when dc(1) resets, it skips any remaining code waiting to be executed. Then, if it is interactive mode, and the error was not a fatal error (see the \f[B]EXIT STATUS\f[R] section), it asks for more input; otherwise, it exits with the appropriate return code. .SH PERFORMANCE -.PP Most dc(1) implementations use \f[B]char\f[R] types to calculate the value of \f[B]1\f[R] decimal digit at a time, but that can be slow. This dc(1) does something different. @@ -1015,7 +1094,6 @@ checking. This integer type depends on the value of \f[B]DC_LONG_BIT\f[R], but is always at least twice as large as the integer type used to store digits. .SH LIMITS -.PP The following are the limits on dc(1): .TP \f[B]DC_LONG_BIT\f[R] @@ -1045,24 +1123,24 @@ Set at \f[B]DC_BASE_POW\f[R]. .TP \f[B]DC_DIM_MAX\f[R] The maximum size of arrays. -Set at \f[B]SIZE_MAX-1\f[R]. +Set at \f[B]SIZE_MAX\-1\f[R]. .TP \f[B]DC_SCALE_MAX\f[R] The maximum \f[B]scale\f[R]. -Set at \f[B]DC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]DC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]DC_STRING_MAX\f[R] The maximum length of strings. -Set at \f[B]DC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]DC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]DC_NAME_MAX\f[R] The maximum length of identifiers. -Set at \f[B]DC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]DC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]DC_NUM_MAX\f[R] The maximum length of a number (in decimal digits), which includes digits after the decimal point. -Set at \f[B]DC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]DC_OVERFLOW_MAX\-1\f[R]. .TP Exponent The maximum allowable exponent (positive or negative). @@ -1070,27 +1148,27 @@ Set at \f[B]DC_OVERFLOW_MAX\f[R]. .TP Number of vars The maximum number of vars/arrays. -Set at \f[B]SIZE_MAX-1\f[R]. +Set at \f[B]SIZE_MAX\-1\f[R]. .PP -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. +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 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). -They should be in the same format as all other command-line arguments. +This is another way to give command\-line arguments to dc(1). +They should be in the same format as all other command\-line arguments. These are always processed first, so any files given in \f[B]DC_ENV_ARGS\f[R] will be processed before arguments and files given -on the command-line. +on the command\-line. This gives the user the ability to set up \[lq]standard\[rq] options and files to be used at every invocation. The most useful thing for such files to contain would be useful functions that the user might want every time dc(1) runs. -Another use would be to use the \f[B]-e\f[R] option to set +Another use would be to use the \f[B]\-e\f[R] option to set \f[B]scale\f[R] to a value other than \f[B]0\f[R]. .RS .PP @@ -1108,14 +1186,14 @@ you can use double quotes as the outside quotes, as in \f[B]\[lq]some quotes. However, handling a file with both kinds of quotes in \f[B]DC_ENV_ARGS\f[R] is not supported due to the complexity of the -parsing, though such files are still supported on the command-line where -the parsing is done by the shell. +parsing, though such files are still supported on the command\-line +where the parsing is done by the shell. .RE .TP \f[B]DC_LINE_LENGTH\f[R] If this environment variable exists and contains an integer that is greater than \f[B]1\f[R] and is less than \f[B]UINT16_MAX\f[R] -(\f[B]2\[ha]16-1\f[R]), dc(1) will output lines to that length, +(\f[B]2\[ha]16\-1\f[R]), dc(1) will output lines to that length, including the backslash newline combo. The default line length is \f[B]70\f[R]. .RS @@ -1132,13 +1210,13 @@ exits on \f[B]SIGINT\f[R] when not in interactive mode. .RS .PP However, when dc(1) is in interactive mode, then if this environment -variable exists and contains an integer, a non-zero value makes dc(1) +variable exists and contains an integer, a non\-zero value makes dc(1) reset on \f[B]SIGINT\f[R], rather than exit, and zero makes dc(1) exit. If this environment variable exists and is \f[I]not\f[R] an integer, then dc(1) will exit on \f[B]SIGINT\f[R]. .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. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]DC_TTY_MODE\f[R] @@ -1147,11 +1225,11 @@ section), then this environment variable has no effect. .RS .PP However, when TTY mode is available, then if this environment variable -exists and contains an integer, then a non-zero value makes dc(1) use +exists and contains an integer, then a non\-zero value makes dc(1) use TTY mode, and zero makes dc(1) not use TTY mode. .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. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]DC_PROMPT\f[R] @@ -1160,30 +1238,46 @@ section), then this environment variable has no effect. .RS .PP However, when TTY mode is available, then if this environment variable -exists and contains an integer, a non-zero value makes dc(1) use a -prompt, and zero or a non-integer makes dc(1) not use a prompt. +exists and contains an integer, a non\-zero value makes dc(1) use a +prompt, and zero or a non\-integer makes dc(1) not use a prompt. If this environment variable does not exist and \f[B]DC_TTY_MODE\f[R] does, then the value of the \f[B]DC_TTY_MODE\f[R] environment variable is used. .PP This environment variable and the \f[B]DC_TTY_MODE\f[R] environment variable override the default, which can be queried with the -\f[B]-h\f[R] or \f[B]--help\f[R] options. +\f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]DC_EXPR_EXIT\f[R] -If any expressions or expression files are given on the command-line -with \f[B]-e\f[R], \f[B]--expression\f[R], \f[B]-f\f[R], or -\f[B]--file\f[R], then if this environment variable exists and contains -an integer, a non-zero value makes dc(1) exit after executing the -expressions and expression files, and a zero value makes dc(1) not exit. +If any expressions or expression files are given on the command\-line +with \f[B]\-e\f[R], \f[B]\-\-expression\f[R], \f[B]\-f\f[R], or +\f[B]\-\-file\f[R], then if this environment variable exists and +contains an integer, a non\-zero value makes dc(1) exit after executing +the expressions and expression files, and a zero value makes dc(1) not +exit. .RS .PP This environment variable overrides the default, which can be queried -with the \f[B]-h\f[R] or \f[B]--help\f[R] options. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE -.SH EXIT STATUS +.TP +\f[B]DC_DIGIT_CLAMP\f[R] +When parsing numbers and if this environment variable exists and +contains an integer, a non\-zero value makes dc(1) clamp digits that are +greater than or equal to the current \f[B]ibase\f[R] so that all such +digits are considered equal to the \f[B]ibase\f[R] minus 1, and a zero +value disables such clamping so that those digits are always equal to +their value, which is multiplied by the power of the \f[B]ibase\f[R]. +.RS +.PP +This never applies to single\-digit numbers, as per the bc(1) standard +(see the \f[B]STANDARDS\f[R] section). .PP +This environment variable overrides the default, which can be queried +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. +.RE +.SH EXIT STATUS dc(1) returns the following exit statuses: .TP \f[B]0\f[R] @@ -1199,7 +1293,7 @@ Math errors include divide by \f[B]0\f[R], taking the square root of a negative number, attempting to convert a negative number to a hardware integer, overflow when converting a number to a hardware integer, overflow when calculating the size of a number, and attempting to use a -non-integer where an integer is required. +non\-integer where an integer is required. .PP Converting to a hardware integer happens for the second operand of the power (\f[B]\[ha]\f[R]) operator. @@ -1233,7 +1327,7 @@ A fatal error occurred. Fatal errors include memory allocation errors, I/O errors, failing to open files, attempting to use files that do not have only ASCII characters (dc(1) only accepts ASCII characters), attempting to open a -directory as a file, and giving invalid command-line options. +directory as a file, and giving invalid command\-line options. .RE .PP The exit status \f[B]4\f[R] is special; when a fatal error occurs, dc(1) @@ -1244,17 +1338,17 @@ interactive mode (see the \f[B]INTERACTIVE MODE\f[R] section), since dc(1) resets its state (see the \f[B]RESET\f[R] section) and accepts more input when one of those errors occurs in interactive mode. This is also the case when interactive mode is forced by the -\f[B]-i\f[R] flag or \f[B]--interactive\f[R] option. +\f[B]\-i\f[R] flag or \f[B]\-\-interactive\f[R] option. .PP These exit statuses allow dc(1) to be used in shell scripting with error checking, and its normal behavior can be forced by using the -\f[B]-i\f[R] flag or \f[B]--interactive\f[R] option. +\f[B]\-i\f[R] flag or \f[B]\-\-interactive\f[R] option. .SH INTERACTIVE MODE -.PP -Like bc(1), dc(1) has an interactive mode and a non-interactive mode. +Like bc(1), dc(1) has an interactive mode and a non\-interactive mode. Interactive mode is turned on automatically when both \f[B]stdin\f[R] -and \f[B]stdout\f[R] are hooked to a terminal, but the \f[B]-i\f[R] flag -and \f[B]--interactive\f[R] option can turn it on in other situations. +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. .PP In interactive mode, dc(1) attempts to recover from errors (see the \f[B]RESET\f[R] section), and in normal execution, flushes @@ -1263,7 +1357,6 @@ dc(1) may also reset on \f[B]SIGINT\f[R] instead of exit, depending on the contents of, or default for, the \f[B]DC_SIGINT_RESET\f[R] environment variable (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). .SH TTY MODE -.PP If \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all connected to a TTY, then \[lq]TTY mode\[rq] is considered to be available, and thus, dc(1) can turn on TTY mode, subject to some @@ -1271,53 +1364,49 @@ settings. .PP If there is the environment variable \f[B]DC_TTY_MODE\f[R] in the environment (see the \f[B]ENVIRONMENT VARIABLES\f[R] section), then if -that environment variable contains a non-zero integer, dc(1) will turn +that environment variable contains a non\-zero integer, dc(1) will turn on TTY mode when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all connected to a TTY. If the \f[B]DC_TTY_MODE\f[R] environment variable exists but is -\f[I]not\f[R] a non-zero integer, then dc(1) will not turn TTY mode on. +\f[I]not\f[R] a non\-zero integer, then dc(1) will not turn TTY mode on. .PP If the environment variable \f[B]DC_TTY_MODE\f[R] does \f[I]not\f[R] exist, the default setting is used. -The default setting can be queried with the \f[B]-h\f[R] or -\f[B]--help\f[R] options. +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. -.SS Command-Line History -.PP -Command-line history is only enabled if TTY mode is, i.e., that +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 +Command\-line history is only enabled if TTY mode is, i.e., that \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are connected to a TTY and the \f[B]DC_TTY_MODE\f[R] environment variable (see the \f[B]ENVIRONMENT VARIABLES\f[R] section) and its default do not disable TTY mode. See the \f[B]COMMAND LINE HISTORY\f[R] section for more information. .SS Prompt -.PP If TTY mode is available, then a prompt can be enabled. Like TTY mode itself, it can be turned on or off with an environment variable: \f[B]DC_PROMPT\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). .PP -If the environment variable \f[B]DC_PROMPT\f[R] exists and is a non-zero -integer, then the prompt is turned on when \f[B]stdin\f[R], +If the environment variable \f[B]DC_PROMPT\f[R] exists and is a +non\-zero integer, then the prompt is turned on when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are connected to a TTY and the -\f[B]-P\f[R] and \f[B]--no-prompt\f[R] options were not used. +\f[B]\-P\f[R] and \f[B]\-\-no\-prompt\f[R] options were not used. The read prompt will be turned on under the same conditions, except that -the \f[B]-R\f[R] and \f[B]--no-read-prompt\f[R] options must also not be -used. +the \f[B]\-R\f[R] and \f[B]\-\-no\-read\-prompt\f[R] options must also +not be used. .PP However, if \f[B]DC_PROMPT\f[R] does not exist, the prompt can be enabled or disabled with the \f[B]DC_TTY_MODE\f[R] environment variable, -the \f[B]-P\f[R] and \f[B]--no-prompt\f[R] options, and the \f[B]-R\f[R] -and \f[B]--no-read-prompt\f[R] options. +the \f[B]\-P\f[R] and \f[B]\-\-no\-prompt\f[R] options, and the +\f[B]\-R\f[R] and \f[B]\-\-no\-read\-prompt\f[R] options. See the \f[B]ENVIRONMENT VARIABLES\f[R] and \f[B]OPTIONS\f[R] sections for more details. .SH SIGNAL HANDLING -.PP Sending a \f[B]SIGINT\f[R] will cause dc(1) to do one of two things. .PP If dc(1) is not in interactive mode (see the \f[B]INTERACTIVE MODE\f[R] @@ -1326,7 +1415,7 @@ section), or the \f[B]DC_SIGINT_RESET\f[R] environment variable (see the an integer or it is zero, dc(1) will exit. .PP However, if dc(1) is in interactive mode, and the -\f[B]DC_SIGINT_RESET\f[R] or its default is an integer and non-zero, +\f[B]DC_SIGINT_RESET\f[R] or its default is an integer and non\-zero, then dc(1) will stop executing the current input and reset (see the \f[B]RESET\f[R] section) upon receiving a \f[B]SIGINT\f[R]. .PP @@ -1352,12 +1441,11 @@ The one exception is \f[B]SIGHUP\f[R]; in that case, and only when dc(1) is in TTY mode (see the \f[B]TTY MODE\f[R] section), a \f[B]SIGHUP\f[R] will cause dc(1) to clean up and exit. .SH COMMAND LINE HISTORY -.PP -dc(1) supports interactive command-line editing. +dc(1) supports interactive command\-line editing. .PP If dc(1) can be in TTY mode (see the \f[B]TTY MODE\f[R] section), history can be enabled. -This means that command-line history can only be enabled when +This means that command\-line history can only be enabled when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all connected to a TTY. .PP @@ -1367,19 +1455,17 @@ section). .PP \f[B]Note\f[R]: tabs are converted to 8 spaces. .SH SEE ALSO -.PP bc(1) .SH STANDARDS -.PP -The dc(1) utility operators are compliant with the operators in the IEEE -Std 1003.1-2017 (\[lq]POSIX.1-2017\[rq]) specification at -https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html for -bc(1). +The dc(1) utility operators and some behavior are compliant with the +operators in the IEEE Std 1003.1\-2017 (\[lq]POSIX.1\-2017\[rq]) bc(1) +specification at +https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html . .SH BUGS -.PP None are known. -Report bugs at https://git.yzena.com/gavin/bc. +Report bugs at https://git.gavinhoward.com/gavin/bc . .SH AUTHOR -.PP -Gavin D. -Howard <gavin@yzena.com> and contributors. +Gavin D. Howard \c +.MT gavin@gavinhoward.com +.ME \c +\ and contributors. diff --git a/contrib/bc/manuals/dc/EN.1.md b/contrib/bc/manuals/dc/EN.1.md index fa02ccf4b43f..ab9647a196be 100644 --- a/contrib/bc/manuals/dc/EN.1.md +++ b/contrib/bc/manuals/dc/EN.1.md @@ -2,7 +2,7 @@ SPDX-License-Identifier: BSD-2-Clause -Copyright (c) 2018-2021 Gavin D. Howard and contributors. +Copyright (c) 2018-2024 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** - -: Prints a usage message and quits. - -**-v**, **-V**, **-\-version** - -: Print the version information (copyright header) and exit. - -**-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). +**-C**, **-\-no-digit-clamp** - This is a **non-portable extension**. - -**-P**, **-\-no-prompt** +: Disables clamping of digits greater than or equal to the current **ibase** + when parsing numbers. -: 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 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. - This option does not disable the regular prompt because the read prompt is - only used when the **?** command is used. + If this and/or the **-c** or **-\-digit-clamp** options are given multiple + times, the last one given 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 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**. -**-x** **-\-extended-register** - -: Enables extended register mode. See the *Extended Register Mode* subsection - of the **REGISTERS** section for more information. +**-c**, **-\-digit-clamp** - This is a **non-portable extension**. +: Enables clamping of digits greater than or equal to the current **ibase** + when parsing numbers. -**-z**, **-\-leading-zeroes** + 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. -: Makes dc(1) print all numbers greater than **-1** and less than **1**, and - not equal to **0**, with a leading zero. + If this and/or the **-C** or **-\-no-digit-clamp** options are given + multiple times, the last one given is used. - 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,24 @@ 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 is a **non-portable extension**. + All long options are **non-portable extensions**. # STDIN @@ -263,15 +296,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**. - -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**. +Uppercase letters are equal to **9** plus 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** (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 +827,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 +851,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) @@ -840,6 +914,12 @@ other character produces a parse error (see the **ERRORS** section). : Pushes the line length set by **DC_LINE_LENGTH** (see the **ENVIRONMENT VARIABLES** section) onto the stack. +**gx** + +: Pushes **1** onto the stack if extended register mode is on, **0** + otherwise. See the *Extended Register Mode* subsection of the **REGISTERS** + section for more information. + **gz** : Pushes **0** onto the stack if the leading zero setting has not been enabled @@ -881,11 +961,14 @@ the next non-space characters do not match that regex. When dc(1) encounters an error or a signal that it has a non-default handler for, it resets. This means that several things happen. -First, any macros that are executing are stopped and popped off the stack. -The behavior is not unlike that of exceptions in programming languages. Then -the execution point is set so that any code waiting to execute (after all +First, any macros that are executing are stopped and popped off the execution +stack. The behavior is not unlike that of exceptions in programming languages. +Then the execution point is set so that any code waiting to execute (after all macros returned) is skipped. +However, the stack of values is *not* cleared; in interactive mode, users can +inspect the stack and manipulate it. + Thus, when dc(1) resets, it skips any remaining code waiting to be executed. Then, if it is interactive mode, and the error was not a fatal error (see the **EXIT STATUS** section), it asks for more input; otherwise, it exits with the @@ -974,7 +1057,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 +1147,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 +1256,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,14 +1335,14 @@ 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.gavinhoward.com/gavin/bc . # AUTHOR -Gavin D. Howard <gavin@yzena.com> and contributors. +Gavin D. Howard <gavin@gavinhoward.com> and contributors. diff --git a/contrib/bc/manuals/dc/H.1 b/contrib/bc/manuals/dc/H.1 index 58703e03be34..82c1bbd5c2b9 100644 --- a/contrib/bc/manuals/dc/H.1 +++ b/contrib/bc/manuals/dc/H.1 @@ -1,7 +1,7 @@ .\" .\" SPDX-License-Identifier: BSD-2-Clause .\" -.\" Copyright (c) 2018-2021 Gavin D. Howard and contributors. +.\" Copyright (c) 2018-2024 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,128 +25,97 @@ .\" 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" "August 2024" "Gavin D. Howard" "General Commands Manual" .nh .ad l .SH Name -.PP -dc - arbitrary-precision decimal reverse-Polish notation calculator +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. +dc(1) is an arbitrary\-precision calculator. It uses a stack (reverse Polish notation) to store numbers and results of computations. Arithmetic operations pop arguments off of the stack and push the results. .PP -If no files are given on the command-line, then dc(1) reads from +If no files are given on the command\-line, then dc(1) reads from \f[B]stdin\f[R] (see the \f[B]STDIN\f[R] section). Otherwise, those files are processed, and dc(1) will then exit. .PP If a user wants to set up a standard environment, they can use \f[B]DC_ENV_ARGS\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). For example, if a user wants the \f[B]scale\f[R] always set to -\f[B]10\f[R], they can set \f[B]DC_ENV_ARGS\f[R] to \f[B]-e 10k\f[R], +\f[B]10\f[R], they can set \f[B]DC_ENV_ARGS\f[R] to \f[B]\-e 10k\f[R], and this dc(1) will always start with a \f[B]scale\f[R] of \f[B]10\f[R]. .SH OPTIONS -.PP The following are the options that dc(1) accepts. .TP -\f[B]-h\f[R], \f[B]--help\f[R] -Prints a usage message and quits. -.TP -\f[B]-v\f[R], \f[B]-V\f[R], \f[B]--version\f[R] -Print the version information (copyright header) and exit. -.TP -\f[B]-i\f[R], \f[B]--interactive\f[R] -Forces interactive mode. -(See the \f[B]INTERACTIVE MODE\f[R] section.) +\f[B]\-C\f[R], \f[B]\-\-no\-digit\-clamp\f[R] +Disables clamping of digits greater than or equal to the current +\f[B]ibase\f[R] when parsing numbers. .RS .PP -This is a \f[B]non-portable extension\f[R]. -.RE -.TP -\f[B]-L\f[R], \f[B]--no-line-length\f[R] -Disables line length checking and prints numbers without backslashes and -newlines. -In other words, this option sets \f[B]BC_LINE_LENGTH\f[R] to \f[B]0\f[R] -(see the \f[B]ENVIRONMENT VARIABLES\f[R] section). -.RS +This means that the value added to a number from a digit is always that +digit\[cq]s value multiplied by the value of ibase raised to the power +of the digit\[cq]s position, which starts from 0 at the least +significant digit. .PP -This is a \f[B]non-portable extension\f[R]. -.RE -.TP -\f[B]-P\f[R], \f[B]--no-prompt\f[R] -Disables the prompt in TTY mode. -(The prompt is only enabled in TTY mode. -See the \f[B]TTY MODE\f[R] section.) This is mostly for those users that -do not want a prompt or are not used to having them in dc(1). -Most of those users would want to put this option in -\f[B]DC_ENV_ARGS\f[R]. -.RS +If this and/or the \f[B]\-c\f[R] or \f[B]\-\-digit\-clamp\f[R] options +are given multiple times, the last one given is used. .PP -These options override the \f[B]DC_PROMPT\f[R] and \f[B]DC_TTY_MODE\f[R] -environment variables (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). +This option overrides the \f[B]DC_DIGIT_CLAMP\f[R] environment variable +(see the \f[B]ENVIRONMENT VARIABLES\f[R] section) and the default, which +can be queried with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-R\f[R], \f[B]--no-read-prompt\f[R] -Disables the read prompt in TTY mode. -(The read prompt is only enabled in TTY mode. -See the \f[B]TTY MODE\f[R] section.) This is mostly for those users that -do not want a read prompt or are not used to having them in dc(1). -Most of those users would want to put this option in -\f[B]BC_ENV_ARGS\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). -This option is also useful in hash bang lines of dc(1) scripts that -prompt for user input. +\f[B]\-c\f[R], \f[B]\-\-digit\-clamp\f[R] +Enables clamping of digits greater than or equal to the current +\f[B]ibase\f[R] when parsing numbers. .RS .PP -This option does not disable the regular prompt because the read prompt -is only used when the \f[B]?\f[R] command is used. +This means that digits that the value added to a number from a digit +that is greater than or equal to the ibase is the value of ibase minus 1 +all multiplied by the value of ibase raised to the power of the +digit\[cq]s position, which starts from 0 at the least significant +digit. .PP -These options \f[I]do\f[R] override the \f[B]DC_PROMPT\f[R] and -\f[B]DC_TTY_MODE\f[R] environment variables (see the \f[B]ENVIRONMENT -VARIABLES\f[R] section), but only for the read prompt. +If this and/or the \f[B]\-C\f[R] or \f[B]\-\-no\-digit\-clamp\f[R] +options are given multiple times, the last one given is used. .PP -This is a \f[B]non-portable extension\f[R]. -.RE -.TP -\f[B]-x\f[R] \f[B]--extended-register\f[R] -Enables extended register mode. -See the \f[I]Extended Register Mode\f[R] subsection of the -\f[B]REGISTERS\f[R] section for more information. -.RS +This option overrides the \f[B]DC_DIGIT_CLAMP\f[R] environment variable +(see the \f[B]ENVIRONMENT VARIABLES\f[R] section) and the default, which +can be queried with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-z\f[R], \f[B]--leading-zeroes\f[R] -Makes dc(1) print all numbers greater than \f[B]-1\f[R] and less than -\f[B]1\f[R], and not equal to \f[B]0\f[R], with a leading zero. +\f[B]\-E\f[R] \f[I]seed\f[R], \f[B]\-\-seed\f[R]=\f[I]seed\f[R] +Sets the builtin variable \f[B]seed\f[R] to the value \f[I]seed\f[R] +assuming that \f[I]seed\f[R] is in base 10. +It is a fatal error if \f[I]seed\f[R] is not a valid number. .RS .PP -This can be set for individual numbers with the \f[B]plz(x)\f[R], -plznl(x)**, \f[B]pnlz(x)\f[R], and \f[B]pnlznl(x)\f[R] functions in the -extended math library (see the \f[B]LIBRARY\f[R] section). +If multiple instances of this option are given, the last is used. .PP -This is a \f[B]non-portable extension\f[R]. +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] +\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 @@ -155,41 +124,44 @@ 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 +If this option is given on the command\-line (i.e., not in \f[B]DC_ENV_ARGS\f[R], see the \f[B]ENVIRONMENT VARIABLES\f[R] section), then after processing all expressions and files, dc(1) will exit, unless -\f[B]-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to -\f[B]-f\f[R] or \f[B]--file\f[R], whether on the command-line or in +\f[B]\-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to +\f[B]\-f\f[R] or \f[B]\-\-file\f[R], whether on the command\-line or in \f[B]DC_ENV_ARGS\f[R]. -However, if any other \f[B]-e\f[R], \f[B]--expression\f[R], -\f[B]-f\f[R], or \f[B]--file\f[R] arguments are given after -\f[B]-f-\f[R] or equivalent is given, dc(1) will give a fatal error and -exit. +However, if any other \f[B]\-e\f[R], \f[B]\-\-expression\f[R], +\f[B]\-f\f[R], or \f[B]\-\-file\f[R] arguments are given after +\f[B]\-f\-\f[R] or equivalent is given, dc(1) will give a fatal error +and exit. .PP -This is a \f[B]non-portable extension\f[R]. +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] +\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 +If this option is given on the command\-line (i.e., not in \f[B]DC_ENV_ARGS\f[R], see the \f[B]ENVIRONMENT VARIABLES\f[R] section), then after processing all expressions and files, dc(1) will exit, unless -\f[B]-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to -\f[B]-f\f[R] or \f[B]--file\f[R]. -However, if any other \f[B]-e\f[R], \f[B]--expression\f[R], -\f[B]-f\f[R], or \f[B]--file\f[R] arguments are given after -\f[B]-f-\f[R] or equivalent is given, dc(1) will give a fatal error and -exit. +\f[B]\-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to +\f[B]\-f\f[R] or \f[B]\-\-file\f[R]. +However, if any other \f[B]\-e\f[R], \f[B]\-\-expression\f[R], +\f[B]\-f\f[R], or \f[B]\-\-file\f[R] arguments are given after +\f[B]\-f\-\f[R] or equivalent is given, dc(1) will give a fatal error +and exit. .PP -This is a \f[B]non-portable extension\f[R]. +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] +\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. It is a fatal error if \f[I]ibase\f[R] is not a valid number. @@ -197,10 +169,28 @@ It is a fatal error if \f[I]ibase\f[R] is not a valid number. .PP If multiple instances of this option are given, the last is used. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-O\f[R] \f[I]obase\f[R], \f[B]--obase\f[R]=\f[I]obase\f[R] +\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. It is a fatal error if \f[I]obase\f[R] is not a valid number. @@ -208,10 +198,48 @@ It is a fatal error if \f[I]obase\f[R] is not a valid number. .PP If multiple instances of this option are given, the last is used. .PP -This is a \f[B]non-portable extension\f[R]. +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]-S\f[R] \f[I]scale\f[R], \f[B]--scale\f[R]=\f[I]scale\f[R] +\f[B]\-R\f[R], \f[B]\-\-no\-read\-prompt\f[R] +Disables the read prompt in TTY mode. +(The read prompt is only enabled in TTY mode. +See the \f[B]TTY MODE\f[R] section.) +This is mostly for those users that do not want a read prompt or are not +used to having them in dc(1). +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. It is a fatal error if \f[I]scale\f[R] is not a valid number. @@ -219,26 +247,34 @@ It is a fatal error if \f[I]scale\f[R] is not a valid number. .PP If multiple instances of this option are given, the last is used. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-E\f[R] \f[I]seed\f[R], \f[B]--seed\f[R]=\f[I]seed\f[R] -Sets the builtin variable \f[B]seed\f[R] to the value \f[I]seed\f[R] -assuming that \f[I]seed\f[R] is in base 10. -It is a fatal error if \f[I]seed\f[R] is not a valid number. +\f[B]\-v\f[R], \f[B]\-V\f[R], \f[B]\-\-version\f[R] +Print the version information (copyright header) and exits. +.TP +\f[B]\-x\f[R] \f[B]\-\-extended\-register\f[R] +Enables extended register mode. +See the \f[I]Extended Register Mode\f[R] subsection of the +\f[B]REGISTERS\f[R] section for more information. .RS .PP -If multiple instances of this option are given, the last is used. +This is a \f[B]non\-portable extension\f[R]. +.RE +.TP +\f[B]\-z\f[R], \f[B]\-\-leading\-zeroes\f[R] +Makes dc(1) print all numbers greater than \f[B]\-1\f[R] and less than +\f[B]1\f[R], and not equal to \f[B]0\f[R], with a leading zero. +.RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .PP -All long options are \f[B]non-portable extensions\f[R]. +All long options are \f[B]non\-portable extensions\f[R]. .SH STDIN -.PP -If no files are given on the command-line and no files or expressions -are given by the \f[B]-f\f[R], \f[B]--file\f[R], \f[B]-e\f[R], or -\f[B]--expression\f[R] options, then dc(1) reads from \f[B]stdin\f[R]. +If no files are given on the command\-line and no files or expressions +are given by the \f[B]\-f\f[R], \f[B]\-\-file\f[R], \f[B]\-e\f[R], or +\f[B]\-\-expression\f[R] options, then dc(1) reads from \f[B]stdin\f[R]. .PP However, there is a caveat to this. .PP @@ -248,8 +284,7 @@ ended. This means that, except for escaped brackets, all brackets must be balanced before dc(1) parses and executes. .SH STDOUT -.PP -Any non-error output is written to \f[B]stdout\f[R]. +Any non\-error output is written to \f[B]stdout\f[R]. In addition, if history (see the \f[B]HISTORY\f[R] section) and the prompt (see the \f[B]TTY MODE\f[R] section) are enabled, both are output to \f[B]stdout\f[R]. @@ -257,7 +292,7 @@ to \f[B]stdout\f[R]. \f[B]Note\f[R]: Unlike other dc(1) implementations, this dc(1) will issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot write to \f[B]stdout\f[R], so if \f[B]stdout\f[R] is closed, as in -\f[B]dc >&-\f[R], it will quit with an error. +\f[B]dc >&\-\f[R], it will quit with an error. This is done so that dc(1) can report problems when \f[B]stdout\f[R] is redirected to a file. .PP @@ -265,13 +300,12 @@ If there are scripts that depend on the behavior of other dc(1) implementations, it is recommended that those scripts be changed to redirect \f[B]stdout\f[R] to \f[B]/dev/null\f[R]. .SH STDERR -.PP Any error output is written to \f[B]stderr\f[R]. .PP \f[B]Note\f[R]: Unlike other dc(1) implementations, this dc(1) will issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot write to \f[B]stderr\f[R], so if \f[B]stderr\f[R] is closed, as in -\f[B]dc 2>&-\f[R], it will quit with an error. +\f[B]dc 2>&\-\f[R], it will quit with an error. This is done so that dc(1) can exit with an error code when \f[B]stderr\f[R] is redirected to a file. .PP @@ -279,7 +313,6 @@ If there are scripts that depend on the behavior of other dc(1) implementations, it is recommended that those scripts be changed to redirect \f[B]stderr\f[R] to \f[B]/dev/null\f[R]. .SH SYNTAX -.PP Each item in the input source code, either a number (see the \f[B]NUMBERS\f[R] section) or a command (see the \f[B]COMMANDS\f[R] section), is processed and executed, in order. @@ -308,8 +341,8 @@ notation, and if \f[B]obase\f[R] is \f[B]1\f[R], values are output in engineering notation. Otherwise, values are output in the specified base. .PP -Outputting in scientific and engineering notations are \f[B]non-portable -extensions\f[R]. +Outputting in scientific and engineering notations are +\f[B]non\-portable extensions\f[R]. .PP The \f[I]scale\f[R] of an expression is the number of digits in the result of the expression right of the decimal point, and \f[B]scale\f[R] @@ -321,14 +354,14 @@ The max allowable value for \f[B]scale\f[R] can be queried in dc(1) programs with the \f[B]V\f[R] command. .PP \f[B]seed\f[R] is a register containing the current seed for the -pseudo-random number generator. +pseudo\-random number generator. If the current value of \f[B]seed\f[R] is queried and stored, then if it -is assigned to \f[B]seed\f[R] later, the pseudo-random number generator -is guaranteed to produce the same sequence of pseudo-random numbers that -were generated after the value of \f[B]seed\f[R] was first queried. +is assigned to \f[B]seed\f[R] later, the pseudo\-random number generator +is guaranteed to produce the same sequence of pseudo\-random numbers +that were generated after the value of \f[B]seed\f[R] was first queried. .PP Multiple values assigned to \f[B]seed\f[R] can produce the same sequence -of pseudo-random numbers. +of pseudo\-random numbers. Likewise, when a value is assigned to \f[B]seed\f[R], it is not guaranteed that querying \f[B]seed\f[R] immediately after will return the same value. @@ -338,39 +371,68 @@ get receive a value of \f[B]0\f[R] or \f[B]1\f[R]. The maximum integer returned by the \f[B]\[cq]\f[R] command can be queried with the \f[B]W\f[R] command. .PP -\f[B]Note\f[R]: The values returned by the pseudo-random number +\f[B]Note\f[R]: The values returned by the pseudo\-random number generator with the \f[B]\[cq]\f[R] and \f[B]\[lq]\f[R] commands are guaranteed to \f[B]NOT\f[R] be cryptographically secure. -This is a consequence of using a seeded pseudo-random number generator. +This is a consequence of using a seeded pseudo\-random number generator. However, they \f[I]are\f[R] guaranteed to be reproducible with identical \f[B]seed\f[R] values. -This means that the pseudo-random values from dc(1) should only be used -where a reproducible stream of pseudo-random numbers is +This means that the pseudo\-random values from dc(1) should only be used +where a reproducible stream of pseudo\-random numbers is \f[I]ESSENTIAL\f[R]. -In any other case, use a non-seeded pseudo-random number generator. +In any other case, use a non\-seeded pseudo\-random number generator. .PP -The pseudo-random number generator, \f[B]seed\f[R], and all associated -operations are \f[B]non-portable extensions\f[R]. +The pseudo\-random number generator, \f[B]seed\f[R], and all associated +operations are \f[B]non\-portable extensions\f[R]. .SS Comments -.PP Comments go from \f[B]#\f[R] until, and not including, the next newline. -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .SH NUMBERS -.PP Numbers are strings made up of digits, uppercase letters up to \f[B]F\f[R], and at most \f[B]1\f[R] period for a radix. Numbers can have up to \f[B]DC_NUM_MAX\f[R] digits. -Uppercase letters are equal to \f[B]9\f[R] + their position in the +Uppercase letters are equal to \f[B]9\f[R] plus their position in the alphabet (i.e., \f[B]A\f[R] equals \f[B]10\f[R], or \f[B]9+1\f[R]). -If a digit or letter makes no sense with the current value of -\f[B]ibase\f[R], they are set to the value of the highest valid digit in -\f[B]ibase\f[R]. .PP -Single-character numbers (i.e., \f[B]A\f[R] alone) take the value that -they would have if they were valid digits, regardless of the value of -\f[B]ibase\f[R]. +If a digit or letter makes no sense with the current value of +\f[B]ibase\f[R] (i.e., they are greater than or equal to the current +value of \f[B]ibase\f[R]), then the behavior depends on the existence of +the \f[B]\-c\f[R]/\f[B]\-\-digit\-clamp\f[R] or +\f[B]\-C\f[R]/\f[B]\-\-no\-digit\-clamp\f[R] options (see the +\f[B]OPTIONS\f[R] section), the existence and setting of the +\f[B]DC_DIGIT_CLAMP\f[R] environment variable (see the \f[B]ENVIRONMENT +VARIABLES\f[R] section), or the default, which can be queried with the +\f[B]\-h\f[R]/\f[B]\-\-help\f[R] option. +.PP +If clamping is off, then digits or letters that are greater than or +equal to the current value of \f[B]ibase\f[R] are not changed. +Instead, their given value is multiplied by the appropriate power of +\f[B]ibase\f[R] and added into the number. +This means that, with an \f[B]ibase\f[R] of \f[B]3\f[R], the number +\f[B]AB\f[R] is equal to \f[B]3\[ha]1*A+3\[ha]0*B\f[R], which is +\f[B]3\f[R] times \f[B]10\f[R] plus \f[B]11\f[R], or \f[B]41\f[R]. +.PP +If clamping is on, then digits or letters that are greater than or equal +to the current value of \f[B]ibase\f[R] are set to the value of the +highest valid digit in \f[B]ibase\f[R] before being multiplied by the +appropriate power of \f[B]ibase\f[R] and added into the number. +This means that, with an \f[B]ibase\f[R] of \f[B]3\f[R], the number +\f[B]AB\f[R] is equal to \f[B]3\[ha]1*2+3\[ha]0*2\f[R], which is +\f[B]3\f[R] times \f[B]2\f[R] plus \f[B]2\f[R], or \f[B]8\f[R]. +.PP +There is one exception to clamping: single\-character numbers (i.e., +\f[B]A\f[R] alone). +Such numbers are never clamped and always take the value they would have +in the highest possible \f[B]ibase\f[R]. This means that \f[B]A\f[R] alone always equals decimal \f[B]10\f[R] and -\f[B]F\f[R] alone always equals decimal \f[B]15\f[R]. +\f[B]Z\f[R] alone always equals decimal \f[B]35\f[R]. +This behavior is mandated by the standard for bc(1) (see the STANDARDS +section) and is meant to provide an easy way to set the current +\f[B]ibase\f[R] (with the \f[B]i\f[R] command) regardless of the current +value of \f[B]ibase\f[R]. +.PP +If clamping is on, and the clamped value of a character is needed, use a +leading zero, i.e., for \f[B]A\f[R], use \f[B]0A\f[R]. .PP In addition, dc(1) accepts numbers in scientific notation. These have the form \f[B]<number>e<integer>\f[R]. @@ -389,13 +451,11 @@ number string \f[B]FFeA\f[R], the resulting decimal number will be \f[B]2550000000000\f[R], and if dc(1) is given the number string \f[B]10e_4\f[R], the resulting decimal number will be \f[B]0.0016\f[R]. .PP -Accepting input as scientific notation is a \f[B]non-portable +Accepting input as scientific notation is a \f[B]non\-portable extension\f[R]. .SH COMMANDS -.PP The valid commands are listed below. .SS Printing -.PP These commands are used for printing. .PP Note that both scientific notation and engineering notation are @@ -407,7 +467,7 @@ activated by assigning \f[B]1\f[R] to \f[B]obase\f[R] using To deactivate them, just assign a different value to \f[B]obase\f[R]. .PP Printing numbers in scientific notation and/or engineering notation is a -\f[B]non-portable extension\f[R]. +\f[B]non\-portable extension\f[R]. .TP \f[B]p\f[R] Prints the value on top of the stack, whether number or string, and @@ -427,12 +487,12 @@ Pops a value off the stack. .PP If the value is a number, it is truncated and the absolute value of the result is printed as though \f[B]obase\f[R] is \f[B]256\f[R] and each -digit is interpreted as an 8-bit ASCII character, making it a byte +digit is interpreted as an 8\-bit ASCII character, making it a byte stream. .PP If the value is a string, it is printed without a trailing newline. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]f\f[R] @@ -443,7 +503,6 @@ without altering anything. Users should use this command when they get lost. .RE .SS Arithmetic -.PP These are the commands used for arithmetic. .TP \f[B]+\f[R] @@ -452,7 +511,7 @@ pushed onto the stack. The \f[I]scale\f[R] of the result is equal to the max \f[I]scale\f[R] of both operands. .TP -\f[B]-\f[R] +\f[B]\-\f[R] The top two values are popped off the stack, subtracted, and the result is pushed onto the stack. The \f[I]scale\f[R] of the result is equal to the max \f[I]scale\f[R] of @@ -473,7 +532,7 @@ pushed onto the stack. The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R]. .RS .PP -The first value popped off of the stack must be non-zero. +The first value popped off of the stack must be non\-zero. .RE .TP \f[B]%\f[R] @@ -483,10 +542,10 @@ is pushed onto the stack. .PP Remaindering is equivalent to 1) Computing \f[B]a/b\f[R] to current \f[B]scale\f[R], and 2) Using the result of step 1 to calculate -\f[B]a-(a/b)*b\f[R] to \f[I]scale\f[R] +\f[B]a\-(a/b)*b\f[R] to \f[I]scale\f[R] \f[B]max(scale+scale(b),scale(a))\f[R]. .PP -The first value popped off of the stack must be non-zero. +The first value popped off of the stack must be non\-zero. .RE .TP \f[B]\[ti]\f[R] @@ -497,9 +556,9 @@ This is equivalent to \f[B]x y / x y %\f[R] except that \f[B]x\f[R] and \f[B]y\f[R] are only evaluated once. .RS .PP -The first value popped off of the stack must be non-zero. +The first value popped off of the stack must be non\-zero. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]\[ha]\f[R] @@ -510,7 +569,7 @@ The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R]. .PP The first value popped off of the stack must be an integer, and if that value is negative, the second value popped off of the stack must be -non-zero. +non\-zero. .RE .TP \f[B]v\f[R] @@ -519,7 +578,7 @@ the result is pushed onto the stack. The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R]. .RS .PP -The value popped off of the stack must be non-negative. +The value popped off of the stack must be non\-negative. .RE .TP \f[B]_\f[R] @@ -529,7 +588,7 @@ or other commands), then that number is input as a negative number. .PP Otherwise, the top value on the stack is popped and copied, and the copy is negated and pushed onto the stack. -This behavior without a number is a \f[B]non-portable extension\f[R]. +This behavior without a number is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]b\f[R] @@ -538,7 +597,7 @@ back onto the stack. Otherwise, its absolute value is pushed onto the stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]|\f[R] @@ -547,12 +606,12 @@ is computed, and the result is pushed onto the stack. .RS .PP The first value popped is used as the reduction modulus and must be an -integer and non-zero. +integer and non\-zero. The second value popped is used as the exponent and must be an integer -and non-negative. +and non\-negative. The third value popped is the base and must be an integer. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]$\f[R] @@ -560,7 +619,7 @@ The top value is popped off the stack and copied, and the copy is truncated and pushed onto the stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]\[at]\f[R] @@ -570,9 +629,9 @@ extension. .RS .PP The first value popped off of the stack must be an integer and -non-negative. +non\-negative. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]H\f[R] @@ -581,9 +640,9 @@ left (radix shifted right) to the value of the first. .RS .PP The first value popped off of the stack must be an integer and -non-negative. +non\-negative. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]h\f[R] @@ -592,9 +651,9 @@ right (radix shifted left) to the value of the first. .RS .PP The first value popped off of the stack must be an integer and -non-negative. +non\-negative. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]G\f[R] @@ -602,7 +661,7 @@ The top two values are popped off of the stack, they are compared, and a \f[B]1\f[R] is pushed if they are equal, or \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]N\f[R] @@ -610,7 +669,7 @@ The top value is popped off of the stack, and if it a \f[B]0\f[R], a \f[B]1\f[R] is pushed; otherwise, a \f[B]0\f[R] is pushed. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B](\f[R] @@ -619,7 +678,7 @@ The top two values are popped off of the stack, they are compared, and a \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]{\f[R] @@ -628,7 +687,7 @@ The top two values are popped off of the stack, they are compared, and a or \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B])\f[R] @@ -637,7 +696,7 @@ The top two values are popped off of the stack, they are compared, and a \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]}\f[R] @@ -646,42 +705,41 @@ The top two values are popped off of the stack, they are compared, and a second, or \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]M\f[R] The top two values are popped off of the stack. -If they are both non-zero, a \f[B]1\f[R] is pushed onto the stack. +If they are both non\-zero, a \f[B]1\f[R] is pushed onto the stack. If either of them is zero, or both of them are, then a \f[B]0\f[R] is pushed onto the stack. .RS .PP This is like the \f[B]&&\f[R] operator in bc(1), and it is \f[I]not\f[R] -a short-circuit operator. +a short\-circuit operator. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]m\f[R] The top two values are popped off of the stack. -If at least one of them is non-zero, a \f[B]1\f[R] is pushed onto the +If at least one of them is non\-zero, a \f[B]1\f[R] is pushed onto the stack. If both of them are zero, then a \f[B]0\f[R] is pushed onto the stack. .RS .PP This is like the \f[B]||\f[R] operator in bc(1), and it is \f[I]not\f[R] -a short-circuit operator. +a short\-circuit operator. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE -.SS Pseudo-Random Number Generator -.PP -dc(1) has a built-in pseudo-random number generator. -These commands query the pseudo-random number generator. +.SS Pseudo\-Random Number Generator +dc(1) has a built\-in pseudo\-random number generator. +These commands query the pseudo\-random number generator. (See Parameters for more information about the \f[B]seed\f[R] value that -controls the pseudo-random number generator.) +controls the pseudo\-random number generator.) .PP -The pseudo-random number generator is guaranteed to \f[B]NOT\f[R] be +The pseudo\-random number generator is guaranteed to \f[B]NOT\f[R] be cryptographically secure. .TP \f[B]\[cq]\f[R] @@ -690,19 +748,19 @@ the \f[B]LIMITS\f[R] section). .RS .PP The generated integer is made as unbiased as possible, subject to the -limitations of the pseudo-random number generator. +limitations of the pseudo\-random number generator. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]\[lq]\f[R] Pops a value off of the stack, which is used as an \f[B]exclusive\f[R] upper bound on the integer that will be generated. -If the bound is negative or is a non-integer, an error is raised, and +If the bound is negative or is a non\-integer, an error is raised, and dc(1) resets (see the \f[B]RESET\f[R] section) while \f[B]seed\f[R] remains unchanged. If the bound is larger than \f[B]DC_RAND_MAX\f[R], the higher bound is -honored by generating several pseudo-random integers, multiplying them +honored by generating several pseudo\-random integers, multiplying them by appropriate powers of \f[B]DC_RAND_MAX+1\f[R], and adding them together. Thus, the size of integer that can be generated with this command is @@ -714,12 +772,11 @@ is \f[I]not\f[R] changed. .RS .PP The generated integer is made as unbiased as possible, subject to the -limitations of the pseudo-random number generator. +limitations of the pseudo\-random number generator. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .SS Stack Control -.PP These commands control the stack. .TP \f[B]c\f[R] @@ -735,7 +792,6 @@ Swaps (\[lq]reverses\[rq]) the two top items on the stack. \f[B]R\f[R] Pops (\[lq]removes\[rq]) the top value from the stack. .SS Register Control -.PP These commands control registers (see the \f[B]REGISTERS\f[R] section). .TP \f[B]s\f[R]\f[I]r\f[R] @@ -757,7 +813,6 @@ push it onto the main stack. The previous value in the stack for register \f[I]r\f[R], if any, is now accessible via the \f[B]l\f[R]\f[I]r\f[R] command. .SS Parameters -.PP These commands control the values of \f[B]ibase\f[R], \f[B]obase\f[R], \f[B]scale\f[R], and \f[B]seed\f[R]. Also see the \f[B]SYNTAX\f[R] section. @@ -785,7 +840,7 @@ If the value on top of the stack has any \f[I]scale\f[R], the .TP \f[B]k\f[R] Pops the value off of the top of the stack and uses it to set -\f[B]scale\f[R], which must be non-negative. +\f[B]scale\f[R], which must be non\-negative. .RS .PP If the value on top of the stack has any \f[I]scale\f[R], the @@ -795,7 +850,7 @@ If the value on top of the stack has any \f[I]scale\f[R], the \f[B]j\f[R] Pops the value off of the top of the stack and uses it to set \f[B]seed\f[R]. -The meaning of \f[B]seed\f[R] is dependent on the current pseudo-random +The meaning of \f[B]seed\f[R] is dependent on the current pseudo\-random number generator but is guaranteed to not change except for new major versions. .RS @@ -803,22 +858,22 @@ versions. The \f[I]scale\f[R] and sign of the value may be significant. .PP If a previously used \f[B]seed\f[R] value is used again, the -pseudo-random number generator is guaranteed to produce the same -sequence of pseudo-random numbers as it did when the \f[B]seed\f[R] +pseudo\-random number generator is guaranteed to produce the same +sequence of pseudo\-random numbers as it did when the \f[B]seed\f[R] value was previously used. .PP The exact value assigned to \f[B]seed\f[R] is not guaranteed to be returned if the \f[B]J\f[R] command is used. However, if \f[B]seed\f[R] \f[I]does\f[R] return a different value, both values, when assigned to \f[B]seed\f[R], are guaranteed to produce the -same sequence of pseudo-random numbers. +same sequence of pseudo\-random numbers. This means that certain values assigned to \f[B]seed\f[R] will not -produce unique sequences of pseudo-random numbers. +produce unique sequences of pseudo\-random numbers. .PP There is no limit to the length (number of significant decimal digits) or \f[I]scale\f[R] of the value that can be assigned to \f[B]seed\f[R]. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]I\f[R] @@ -834,7 +889,7 @@ Pushes the current value of \f[B]scale\f[R] onto the main stack. Pushes the current value of \f[B]seed\f[R] onto the main stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]T\f[R] @@ -842,7 +897,7 @@ Pushes the maximum allowable value of \f[B]ibase\f[R] onto the main stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]U\f[R] @@ -850,7 +905,7 @@ Pushes the maximum allowable value of \f[B]obase\f[R] onto the main stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]V\f[R] @@ -858,18 +913,17 @@ Pushes the maximum allowable value of \f[B]scale\f[R] onto the main stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]W\f[R] Pushes the maximum (inclusive) integer that can be generated with the -\f[B]\[cq]\f[R] pseudo-random number generator command. +\f[B]\[cq]\f[R] pseudo\-random number generator command. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .SS Strings -.PP The following commands control strings. .PP dc(1) can work with both numbers and strings, and registers (see the @@ -907,16 +961,16 @@ The value on top of the stack is popped. If it is a number, it is truncated and its absolute value is taken. The result mod \f[B]256\f[R] is calculated. If that result is \f[B]0\f[R], push an empty string; otherwise, push a -one-character string where the character is the result of the mod +one\-character string where the character is the result of the mod interpreted as an ASCII character. .PP If it is a string, then a new string is made. If the original string is empty, the new string is empty. If it is not, then the first character of the original string is used to -create the new string as a one-character string. +create the new string as a one\-character string. The new string is then pushed onto the stack. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]x\f[R] @@ -952,7 +1006,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]!>\f[R]\f[I]r\f[R] @@ -973,7 +1027,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]<\f[R]\f[I]r\f[R] @@ -994,7 +1048,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]!<\f[R]\f[I]r\f[R] @@ -1015,7 +1069,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]=\f[R]\f[I]r\f[R] @@ -1036,7 +1090,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]!=\f[R]\f[I]r\f[R] @@ -1057,7 +1111,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]?\f[R] @@ -1070,7 +1124,7 @@ the execution of the macro that executed it. If there are no macros, or only one macro executing, dc(1) exits. .TP \f[B]Q\f[R] -Pops a value from the stack which must be non-negative and is used the +Pops a value from the stack which must be non\-negative and is used the number of macro executions to pop off of the execution stack. If the number of levels to pop is greater than the number of executing macros, dc(1) exits. @@ -1081,8 +1135,11 @@ The execution stack is the stack of string executions. The number that is pushed onto the stack is exactly as many as is needed to make dc(1) exit with the \f[B]Q\f[R] command, so the sequence \f[B],Q\f[R] will make dc(1) exit. -.SS Status +.RS .PP +This is a \f[B]non\-portable extension\f[R]. +.RE +.SS Status These commands query status of the stack or its top value. .TP \f[B]Z\f[R] @@ -1107,6 +1164,24 @@ stack. If it is a string, pushes \f[B]0\f[R]. .RE .TP +\f[B]u\f[R] +Pops one value off of the stack. +If the value is a number, this pushes \f[B]1\f[R] onto the stack. +Otherwise (if it is a string), it pushes \f[B]0\f[R]. +.RS +.PP +This is a \f[B]non\-portable extension\f[R]. +.RE +.TP +\f[B]t\f[R] +Pops one value off of the stack. +If the value is a string, this pushes \f[B]1\f[R] onto the stack. +Otherwise (if it is a number), it pushes \f[B]0\f[R]. +.RS +.PP +This is a \f[B]non\-portable extension\f[R]. +.RE +.TP \f[B]z\f[R] Pushes the current depth of the stack (before execution of this command) onto the stack. @@ -1122,10 +1197,9 @@ register\[cq]s stack must always have at least one item; dc(1) will give an error and reset otherwise (see the \f[B]RESET\f[R] section). This means that this command will never push \f[B]0\f[R]. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .SS Arrays -.PP These commands manipulate arrays. .TP \f[B]:\f[R]\f[I]r\f[R] @@ -1142,10 +1216,9 @@ The selected value is then pushed onto the stack. Pushes the length of the array \f[I]r\f[R] onto the stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .SS Global Settings -.PP These commands retrieve global settings. These are the only commands that require multiple specific characters, and all of them begin with the letter \f[B]g\f[R]. @@ -1157,12 +1230,17 @@ section). Pushes the line length set by \f[B]DC_LINE_LENGTH\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section) onto the stack. .TP +\f[B]gx\f[R] +Pushes \f[B]1\f[R] onto the stack if extended register mode is on, +\f[B]0\f[R] otherwise. +See the \f[I]Extended Register Mode\f[R] subsection of the +\f[B]REGISTERS\f[R] section for more information. +.TP \f[B]gz\f[R] Pushes \f[B]0\f[R] onto the stack if the leading zero setting has not -been enabled with the \f[B]-z\f[R] or \f[B]--leading-zeroes\f[R] options -(see the \f[B]OPTIONS\f[R] section), non-zero otherwise. +been enabled with the \f[B]\-z\f[R] or \f[B]\-\-leading\-zeroes\f[R] +options (see the \f[B]OPTIONS\f[R] section), non\-zero otherwise. .SH REGISTERS -.PP Registers are names that can store strings, numbers, and arrays. (Number/string registers do not interfere with array registers.) .PP @@ -1172,45 +1250,45 @@ All registers, when first referenced, have one value (\f[B]0\f[R]) in their stack, and it is a runtime error to attempt to pop that item off of the register stack. .PP -In non-extended register mode, a register name is just the single +In non\-extended register mode, a register name is just the single character that follows any command that needs a register name. The only exceptions are: a newline (\f[B]`\[rs]n'\f[R]) and a left bracket (\f[B]`['\f[R]); it is a parse error for a newline or a left bracket to be used as a register name. .SS Extended Register Mode -.PP Unlike most other dc(1) implentations, this dc(1) provides nearly unlimited amounts of registers, if extended register mode is enabled. .PP -If extended register mode is enabled (\f[B]-x\f[R] or -\f[B]--extended-register\f[R] command-line arguments are given), then -normal single character registers are used \f[I]unless\f[R] the +If extended register mode is enabled (\f[B]\-x\f[R] or +\f[B]\-\-extended\-register\f[R] command\-line arguments are given), +then normal single character registers are used \f[I]unless\f[R] the character immediately following a command that needs a register name is a space (according to \f[B]isspace()\f[R]) and not a newline (\f[B]`\[rs]n'\f[R]). .PP In that case, the register name is found according to the regex -\f[B][a-z][a-z0-9_]*\f[R] (like bc(1) identifiers), and it is a parse -error if the next non-space characters do not match that regex. +\f[B][a\-z][a\-z0\-9_]*\f[R] (like bc(1) identifiers), and it is a parse +error if the next non\-space characters do not match that regex. .SH RESET -.PP -When dc(1) encounters an error or a signal that it has a non-default +When dc(1) encounters an error or a signal that it has a non\-default handler for, it resets. This means that several things happen. .PP First, any macros that are executing are stopped and popped off the -stack. +execution stack. The behavior is not unlike that of exceptions in programming languages. Then the execution point is set so that any code waiting to execute (after all macros returned) is skipped. .PP +However, the stack of values is \f[I]not\f[R] cleared; in interactive +mode, users can inspect the stack and manipulate it. +.PP Thus, when dc(1) resets, it skips any remaining code waiting to be executed. Then, if it is interactive mode, and the error was not a fatal error (see the \f[B]EXIT STATUS\f[R] section), it asks for more input; otherwise, it exits with the appropriate return code. .SH PERFORMANCE -.PP Most dc(1) implementations use \f[B]char\f[R] types to calculate the value of \f[B]1\f[R] decimal digit at a time, but that can be slow. This dc(1) does something different. @@ -1230,7 +1308,6 @@ checking. This integer type depends on the value of \f[B]DC_LONG_BIT\f[R], but is always at least twice as large as the integer type used to store digits. .SH LIMITS -.PP The following are the limits on dc(1): .TP \f[B]DC_LONG_BIT\f[R] @@ -1260,29 +1337,29 @@ Set at \f[B]DC_BASE_POW\f[R]. .TP \f[B]DC_DIM_MAX\f[R] The maximum size of arrays. -Set at \f[B]SIZE_MAX-1\f[R]. +Set at \f[B]SIZE_MAX\-1\f[R]. .TP \f[B]DC_SCALE_MAX\f[R] The maximum \f[B]scale\f[R]. -Set at \f[B]DC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]DC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]DC_STRING_MAX\f[R] The maximum length of strings. -Set at \f[B]DC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]DC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]DC_NAME_MAX\f[R] The maximum length of identifiers. -Set at \f[B]DC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]DC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]DC_NUM_MAX\f[R] The maximum length of a number (in decimal digits), which includes digits after the decimal point. -Set at \f[B]DC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]DC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]DC_RAND_MAX\f[R] The maximum integer (inclusive) returned by the \f[B]\[cq]\f[R] command, if dc(1). -Set at \f[B]2\[ha]DC_LONG_BIT-1\f[R]. +Set at \f[B]2\[ha]DC_LONG_BIT\-1\f[R]. .TP Exponent The maximum allowable exponent (positive or negative). @@ -1290,27 +1367,27 @@ Set at \f[B]DC_OVERFLOW_MAX\f[R]. .TP Number of vars The maximum number of vars/arrays. -Set at \f[B]SIZE_MAX-1\f[R]. +Set at \f[B]SIZE_MAX\-1\f[R]. .PP -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. +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 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). -They should be in the same format as all other command-line arguments. +This is another way to give command\-line arguments to dc(1). +They should be in the same format as all other command\-line arguments. These are always processed first, so any files given in \f[B]DC_ENV_ARGS\f[R] will be processed before arguments and files given -on the command-line. +on the command\-line. This gives the user the ability to set up \[lq]standard\[rq] options and files to be used at every invocation. The most useful thing for such files to contain would be useful functions that the user might want every time dc(1) runs. -Another use would be to use the \f[B]-e\f[R] option to set +Another use would be to use the \f[B]\-e\f[R] option to set \f[B]scale\f[R] to a value other than \f[B]0\f[R]. .RS .PP @@ -1328,14 +1405,14 @@ you can use double quotes as the outside quotes, as in \f[B]\[lq]some quotes. However, handling a file with both kinds of quotes in \f[B]DC_ENV_ARGS\f[R] is not supported due to the complexity of the -parsing, though such files are still supported on the command-line where -the parsing is done by the shell. +parsing, though such files are still supported on the command\-line +where the parsing is done by the shell. .RE .TP \f[B]DC_LINE_LENGTH\f[R] If this environment variable exists and contains an integer that is greater than \f[B]1\f[R] and is less than \f[B]UINT16_MAX\f[R] -(\f[B]2\[ha]16-1\f[R]), dc(1) will output lines to that length, +(\f[B]2\[ha]16\-1\f[R]), dc(1) will output lines to that length, including the backslash newline combo. The default line length is \f[B]70\f[R]. .RS @@ -1352,13 +1429,13 @@ exits on \f[B]SIGINT\f[R] when not in interactive mode. .RS .PP However, when dc(1) is in interactive mode, then if this environment -variable exists and contains an integer, a non-zero value makes dc(1) +variable exists and contains an integer, a non\-zero value makes dc(1) reset on \f[B]SIGINT\f[R], rather than exit, and zero makes dc(1) exit. If this environment variable exists and is \f[I]not\f[R] an integer, then dc(1) will exit on \f[B]SIGINT\f[R]. .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. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]DC_TTY_MODE\f[R] @@ -1367,11 +1444,11 @@ section), then this environment variable has no effect. .RS .PP However, when TTY mode is available, then if this environment variable -exists and contains an integer, then a non-zero value makes dc(1) use +exists and contains an integer, then a non\-zero value makes dc(1) use TTY mode, and zero makes dc(1) not use TTY mode. .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. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]DC_PROMPT\f[R] @@ -1380,30 +1457,46 @@ section), then this environment variable has no effect. .RS .PP However, when TTY mode is available, then if this environment variable -exists and contains an integer, a non-zero value makes dc(1) use a -prompt, and zero or a non-integer makes dc(1) not use a prompt. +exists and contains an integer, a non\-zero value makes dc(1) use a +prompt, and zero or a non\-integer makes dc(1) not use a prompt. If this environment variable does not exist and \f[B]DC_TTY_MODE\f[R] does, then the value of the \f[B]DC_TTY_MODE\f[R] environment variable is used. .PP This environment variable and the \f[B]DC_TTY_MODE\f[R] environment variable override the default, which can be queried with the -\f[B]-h\f[R] or \f[B]--help\f[R] options. +\f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]DC_EXPR_EXIT\f[R] -If any expressions or expression files are given on the command-line -with \f[B]-e\f[R], \f[B]--expression\f[R], \f[B]-f\f[R], or -\f[B]--file\f[R], then if this environment variable exists and contains -an integer, a non-zero value makes dc(1) exit after executing the -expressions and expression files, and a zero value makes dc(1) not exit. +If any expressions or expression files are given on the command\-line +with \f[B]\-e\f[R], \f[B]\-\-expression\f[R], \f[B]\-f\f[R], or +\f[B]\-\-file\f[R], then if this environment variable exists and +contains an integer, a non\-zero value makes dc(1) exit after executing +the expressions and expression files, and a zero value makes dc(1) not +exit. .RS .PP This environment variable overrides the default, which can be queried -with the \f[B]-h\f[R] or \f[B]--help\f[R] options. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE -.SH EXIT STATUS +.TP +\f[B]DC_DIGIT_CLAMP\f[R] +When parsing numbers and if this environment variable exists and +contains an integer, a non\-zero value makes dc(1) clamp digits that are +greater than or equal to the current \f[B]ibase\f[R] so that all such +digits are considered equal to the \f[B]ibase\f[R] minus 1, and a zero +value disables such clamping so that those digits are always equal to +their value, which is multiplied by the power of the \f[B]ibase\f[R]. +.RS +.PP +This never applies to single\-digit numbers, as per the bc(1) standard +(see the \f[B]STANDARDS\f[R] section). .PP +This environment variable overrides the default, which can be queried +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. +.RE +.SH EXIT STATUS dc(1) returns the following exit statuses: .TP \f[B]0\f[R] @@ -1417,10 +1510,10 @@ since math errors will happen in the process of normal execution. .PP Math errors include divide by \f[B]0\f[R], taking the square root of a negative number, using a negative number as a bound for the -pseudo-random number generator, attempting to convert a negative number +pseudo\-random number generator, attempting to convert a negative number to a hardware integer, overflow when converting a number to a hardware integer, overflow when calculating the size of a number, and attempting -to use a non-integer where an integer is required. +to use a non\-integer where an integer is required. .PP Converting to a hardware integer happens for the second operand of the power (\f[B]\[ha]\f[R]), places (\f[B]\[at]\f[R]), left shift @@ -1455,7 +1548,7 @@ A fatal error occurred. Fatal errors include memory allocation errors, I/O errors, failing to open files, attempting to use files that do not have only ASCII characters (dc(1) only accepts ASCII characters), attempting to open a -directory as a file, and giving invalid command-line options. +directory as a file, and giving invalid command\-line options. .RE .PP The exit status \f[B]4\f[R] is special; when a fatal error occurs, dc(1) @@ -1466,17 +1559,17 @@ interactive mode (see the \f[B]INTERACTIVE MODE\f[R] section), since dc(1) resets its state (see the \f[B]RESET\f[R] section) and accepts more input when one of those errors occurs in interactive mode. This is also the case when interactive mode is forced by the -\f[B]-i\f[R] flag or \f[B]--interactive\f[R] option. +\f[B]\-i\f[R] flag or \f[B]\-\-interactive\f[R] option. .PP These exit statuses allow dc(1) to be used in shell scripting with error checking, and its normal behavior can be forced by using the -\f[B]-i\f[R] flag or \f[B]--interactive\f[R] option. +\f[B]\-i\f[R] flag or \f[B]\-\-interactive\f[R] option. .SH INTERACTIVE MODE -.PP -Like bc(1), dc(1) has an interactive mode and a non-interactive mode. +Like bc(1), dc(1) has an interactive mode and a non\-interactive mode. Interactive mode is turned on automatically when both \f[B]stdin\f[R] -and \f[B]stdout\f[R] are hooked to a terminal, but the \f[B]-i\f[R] flag -and \f[B]--interactive\f[R] option can turn it on in other situations. +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. .PP In interactive mode, dc(1) attempts to recover from errors (see the \f[B]RESET\f[R] section), and in normal execution, flushes @@ -1485,7 +1578,6 @@ dc(1) may also reset on \f[B]SIGINT\f[R] instead of exit, depending on the contents of, or default for, the \f[B]DC_SIGINT_RESET\f[R] environment variable (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). .SH TTY MODE -.PP If \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all connected to a TTY, then \[lq]TTY mode\[rq] is considered to be available, and thus, dc(1) can turn on TTY mode, subject to some @@ -1493,45 +1585,42 @@ settings. .PP If there is the environment variable \f[B]DC_TTY_MODE\f[R] in the environment (see the \f[B]ENVIRONMENT VARIABLES\f[R] section), then if -that environment variable contains a non-zero integer, dc(1) will turn +that environment variable contains a non\-zero integer, dc(1) will turn on TTY mode when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all connected to a TTY. If the \f[B]DC_TTY_MODE\f[R] environment variable exists but is -\f[I]not\f[R] a non-zero integer, then dc(1) will not turn TTY mode on. +\f[I]not\f[R] a non\-zero integer, then dc(1) will not turn TTY mode on. .PP If the environment variable \f[B]DC_TTY_MODE\f[R] does \f[I]not\f[R] exist, the default setting is used. -The default setting can be queried with the \f[B]-h\f[R] or -\f[B]--help\f[R] options. +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. Like TTY mode itself, it can be turned on or off with an environment variable: \f[B]DC_PROMPT\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). .PP -If the environment variable \f[B]DC_PROMPT\f[R] exists and is a non-zero -integer, then the prompt is turned on when \f[B]stdin\f[R], +If the environment variable \f[B]DC_PROMPT\f[R] exists and is a +non\-zero integer, then the prompt is turned on when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are connected to a TTY and the -\f[B]-P\f[R] and \f[B]--no-prompt\f[R] options were not used. +\f[B]\-P\f[R] and \f[B]\-\-no\-prompt\f[R] options were not used. The read prompt will be turned on under the same conditions, except that -the \f[B]-R\f[R] and \f[B]--no-read-prompt\f[R] options must also not be -used. +the \f[B]\-R\f[R] and \f[B]\-\-no\-read\-prompt\f[R] options must also +not be used. .PP However, if \f[B]DC_PROMPT\f[R] does not exist, the prompt can be enabled or disabled with the \f[B]DC_TTY_MODE\f[R] environment variable, -the \f[B]-P\f[R] and \f[B]--no-prompt\f[R] options, and the \f[B]-R\f[R] -and \f[B]--no-read-prompt\f[R] options. +the \f[B]\-P\f[R] and \f[B]\-\-no\-prompt\f[R] options, and the +\f[B]\-R\f[R] and \f[B]\-\-no\-read\-prompt\f[R] options. See the \f[B]ENVIRONMENT VARIABLES\f[R] and \f[B]OPTIONS\f[R] sections for more details. .SH SIGNAL HANDLING -.PP Sending a \f[B]SIGINT\f[R] will cause dc(1) to do one of two things. .PP If dc(1) is not in interactive mode (see the \f[B]INTERACTIVE MODE\f[R] @@ -1540,7 +1629,7 @@ section), or the \f[B]DC_SIGINT_RESET\f[R] environment variable (see the an integer or it is zero, dc(1) will exit. .PP However, if dc(1) is in interactive mode, and the -\f[B]DC_SIGINT_RESET\f[R] or its default is an integer and non-zero, +\f[B]DC_SIGINT_RESET\f[R] or its default is an integer and non\-zero, then dc(1) will stop executing the current input and reset (see the \f[B]RESET\f[R] section) upon receiving a \f[B]SIGINT\f[R]. .PP @@ -1563,23 +1652,20 @@ the user to continue. \f[B]SIGTERM\f[R] and \f[B]SIGQUIT\f[R] cause dc(1) to clean up and exit, and it uses the default handler for all other signals. .SH LOCALES -.PP This dc(1) ships with support for adding error messages for different locales and thus, supports \f[B]LC_MESSAGES\f[R]. .SH SEE ALSO -.PP bc(1) .SH STANDARDS -.PP -The dc(1) utility operators are compliant with the operators in the IEEE -Std 1003.1-2017 (\[lq]POSIX.1-2017\[rq]) specification at -https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html for -bc(1). +The dc(1) utility operators and some behavior are compliant with the +operators in the IEEE Std 1003.1\-2017 (\[lq]POSIX.1\-2017\[rq]) bc(1) +specification at +https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html . .SH BUGS -.PP None are known. -Report bugs at https://git.yzena.com/gavin/bc. +Report bugs at https://git.gavinhoward.com/gavin/bc . .SH AUTHOR -.PP -Gavin D. -Howard <gavin@yzena.com> and contributors. +Gavin D. Howard \c +.MT gavin@gavinhoward.com +.ME \c +\ and contributors. diff --git a/contrib/bc/manuals/dc/H.1.md b/contrib/bc/manuals/dc/H.1.md index 50111044d265..64c7142bc4a7 100644 --- a/contrib/bc/manuals/dc/H.1.md +++ b/contrib/bc/manuals/dc/H.1.md @@ -2,7 +2,7 @@ SPDX-License-Identifier: BSD-2-Clause -Copyright (c) 2018-2021 Gavin D. Howard and contributors. +Copyright (c) 2018-2024 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 is a **non-portable extension**. - -**-P**, **-\-no-prompt** + 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. -: 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**. + If this and/or the **-C** or **-\-no-digit-clamp** options are given + multiple times, the last one given is used. - These options override the **DC_PROMPT** and **DC_TTY_MODE** environment - variables (see the **ENVIRONMENT VARIABLES** 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**. -**-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** +**-E** *seed*, **-\-seed**=*seed* -: Makes dc(1) print all numbers greater than **-1** and less than **1**, and - not equal to **0**, with a leading zero. +: 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. - 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,21 @@ 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 is a **non-portable extension**. @@ -302,15 +335,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**. - -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**. +Uppercase letters are equal to **9** plus 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** (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 +996,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 +1020,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) @@ -1009,6 +1083,12 @@ other character produces a parse error (see the **ERRORS** section). : Pushes the line length set by **DC_LINE_LENGTH** (see the **ENVIRONMENT VARIABLES** section) onto the stack. +**gx** + +: Pushes **1** onto the stack if extended register mode is on, **0** + otherwise. See the *Extended Register Mode* subsection of the **REGISTERS** + section for more information. + **gz** : Pushes **0** onto the stack if the leading zero setting has not been enabled @@ -1050,11 +1130,14 @@ the next non-space characters do not match that regex. When dc(1) encounters an error or a signal that it has a non-default handler for, it resets. This means that several things happen. -First, any macros that are executing are stopped and popped off the stack. -The behavior is not unlike that of exceptions in programming languages. Then -the execution point is set so that any code waiting to execute (after all +First, any macros that are executing are stopped and popped off the execution +stack. The behavior is not unlike that of exceptions in programming languages. +Then the execution point is set so that any code waiting to execute (after all macros returned) is skipped. +However, the stack of values is *not* cleared; in interactive mode, users can +inspect the stack and manipulate it. + Thus, when dc(1) resets, it skips any remaining code waiting to be executed. Then, if it is interactive mode, and the error was not a fatal error (see the **EXIT STATUS** section), it asks for more input; otherwise, it exits with the @@ -1148,7 +1231,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 +1321,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 +1432,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,14 +1493,14 @@ 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.gavinhoward.com/gavin/bc . # AUTHOR -Gavin D. Howard <gavin@yzena.com> and contributors. +Gavin D. Howard <gavin@gavinhoward.com> and contributors. diff --git a/contrib/bc/manuals/dc/HN.1 b/contrib/bc/manuals/dc/HN.1 index d67e2325817e..c3f8c8ab1ff5 100644 --- a/contrib/bc/manuals/dc/HN.1 +++ b/contrib/bc/manuals/dc/HN.1 @@ -1,7 +1,7 @@ .\" .\" SPDX-License-Identifier: BSD-2-Clause .\" -.\" Copyright (c) 2018-2021 Gavin D. Howard and contributors. +.\" Copyright (c) 2018-2024 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,128 +25,97 @@ .\" 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" "August 2024" "Gavin D. Howard" "General Commands Manual" .nh .ad l .SH Name -.PP -dc - arbitrary-precision decimal reverse-Polish notation calculator +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. +dc(1) is an arbitrary\-precision calculator. It uses a stack (reverse Polish notation) to store numbers and results of computations. Arithmetic operations pop arguments off of the stack and push the results. .PP -If no files are given on the command-line, then dc(1) reads from +If no files are given on the command\-line, then dc(1) reads from \f[B]stdin\f[R] (see the \f[B]STDIN\f[R] section). Otherwise, those files are processed, and dc(1) will then exit. .PP If a user wants to set up a standard environment, they can use \f[B]DC_ENV_ARGS\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). For example, if a user wants the \f[B]scale\f[R] always set to -\f[B]10\f[R], they can set \f[B]DC_ENV_ARGS\f[R] to \f[B]-e 10k\f[R], +\f[B]10\f[R], they can set \f[B]DC_ENV_ARGS\f[R] to \f[B]\-e 10k\f[R], and this dc(1) will always start with a \f[B]scale\f[R] of \f[B]10\f[R]. .SH OPTIONS -.PP The following are the options that dc(1) accepts. .TP -\f[B]-h\f[R], \f[B]--help\f[R] -Prints a usage message and quits. -.TP -\f[B]-v\f[R], \f[B]-V\f[R], \f[B]--version\f[R] -Print the version information (copyright header) and exit. -.TP -\f[B]-i\f[R], \f[B]--interactive\f[R] -Forces interactive mode. -(See the \f[B]INTERACTIVE MODE\f[R] section.) +\f[B]\-C\f[R], \f[B]\-\-no\-digit\-clamp\f[R] +Disables clamping of digits greater than or equal to the current +\f[B]ibase\f[R] when parsing numbers. .RS .PP -This is a \f[B]non-portable extension\f[R]. -.RE -.TP -\f[B]-L\f[R], \f[B]--no-line-length\f[R] -Disables line length checking and prints numbers without backslashes and -newlines. -In other words, this option sets \f[B]BC_LINE_LENGTH\f[R] to \f[B]0\f[R] -(see the \f[B]ENVIRONMENT VARIABLES\f[R] section). -.RS +This means that the value added to a number from a digit is always that +digit\[cq]s value multiplied by the value of ibase raised to the power +of the digit\[cq]s position, which starts from 0 at the least +significant digit. .PP -This is a \f[B]non-portable extension\f[R]. -.RE -.TP -\f[B]-P\f[R], \f[B]--no-prompt\f[R] -Disables the prompt in TTY mode. -(The prompt is only enabled in TTY mode. -See the \f[B]TTY MODE\f[R] section.) This is mostly for those users that -do not want a prompt or are not used to having them in dc(1). -Most of those users would want to put this option in -\f[B]DC_ENV_ARGS\f[R]. -.RS +If this and/or the \f[B]\-c\f[R] or \f[B]\-\-digit\-clamp\f[R] options +are given multiple times, the last one given is used. .PP -These options override the \f[B]DC_PROMPT\f[R] and \f[B]DC_TTY_MODE\f[R] -environment variables (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). +This option overrides the \f[B]DC_DIGIT_CLAMP\f[R] environment variable +(see the \f[B]ENVIRONMENT VARIABLES\f[R] section) and the default, which +can be queried with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-R\f[R], \f[B]--no-read-prompt\f[R] -Disables the read prompt in TTY mode. -(The read prompt is only enabled in TTY mode. -See the \f[B]TTY MODE\f[R] section.) This is mostly for those users that -do not want a read prompt or are not used to having them in dc(1). -Most of those users would want to put this option in -\f[B]BC_ENV_ARGS\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). -This option is also useful in hash bang lines of dc(1) scripts that -prompt for user input. +\f[B]\-c\f[R], \f[B]\-\-digit\-clamp\f[R] +Enables clamping of digits greater than or equal to the current +\f[B]ibase\f[R] when parsing numbers. .RS .PP -This option does not disable the regular prompt because the read prompt -is only used when the \f[B]?\f[R] command is used. +This means that digits that the value added to a number from a digit +that is greater than or equal to the ibase is the value of ibase minus 1 +all multiplied by the value of ibase raised to the power of the +digit\[cq]s position, which starts from 0 at the least significant +digit. .PP -These options \f[I]do\f[R] override the \f[B]DC_PROMPT\f[R] and -\f[B]DC_TTY_MODE\f[R] environment variables (see the \f[B]ENVIRONMENT -VARIABLES\f[R] section), but only for the read prompt. +If this and/or the \f[B]\-C\f[R] or \f[B]\-\-no\-digit\-clamp\f[R] +options are given multiple times, the last one given is used. .PP -This is a \f[B]non-portable extension\f[R]. -.RE -.TP -\f[B]-x\f[R] \f[B]--extended-register\f[R] -Enables extended register mode. -See the \f[I]Extended Register Mode\f[R] subsection of the -\f[B]REGISTERS\f[R] section for more information. -.RS +This option overrides the \f[B]DC_DIGIT_CLAMP\f[R] environment variable +(see the \f[B]ENVIRONMENT VARIABLES\f[R] section) and the default, which +can be queried with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-z\f[R], \f[B]--leading-zeroes\f[R] -Makes dc(1) print all numbers greater than \f[B]-1\f[R] and less than -\f[B]1\f[R], and not equal to \f[B]0\f[R], with a leading zero. +\f[B]\-E\f[R] \f[I]seed\f[R], \f[B]\-\-seed\f[R]=\f[I]seed\f[R] +Sets the builtin variable \f[B]seed\f[R] to the value \f[I]seed\f[R] +assuming that \f[I]seed\f[R] is in base 10. +It is a fatal error if \f[I]seed\f[R] is not a valid number. .RS .PP -This can be set for individual numbers with the \f[B]plz(x)\f[R], -plznl(x)**, \f[B]pnlz(x)\f[R], and \f[B]pnlznl(x)\f[R] functions in the -extended math library (see the \f[B]LIBRARY\f[R] section). +If multiple instances of this option are given, the last is used. .PP -This is a \f[B]non-portable extension\f[R]. +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] +\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 @@ -155,41 +124,44 @@ 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 +If this option is given on the command\-line (i.e., not in \f[B]DC_ENV_ARGS\f[R], see the \f[B]ENVIRONMENT VARIABLES\f[R] section), then after processing all expressions and files, dc(1) will exit, unless -\f[B]-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to -\f[B]-f\f[R] or \f[B]--file\f[R], whether on the command-line or in +\f[B]\-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to +\f[B]\-f\f[R] or \f[B]\-\-file\f[R], whether on the command\-line or in \f[B]DC_ENV_ARGS\f[R]. -However, if any other \f[B]-e\f[R], \f[B]--expression\f[R], -\f[B]-f\f[R], or \f[B]--file\f[R] arguments are given after -\f[B]-f-\f[R] or equivalent is given, dc(1) will give a fatal error and -exit. +However, if any other \f[B]\-e\f[R], \f[B]\-\-expression\f[R], +\f[B]\-f\f[R], or \f[B]\-\-file\f[R] arguments are given after +\f[B]\-f\-\f[R] or equivalent is given, dc(1) will give a fatal error +and exit. .PP -This is a \f[B]non-portable extension\f[R]. +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] +\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 +If this option is given on the command\-line (i.e., not in \f[B]DC_ENV_ARGS\f[R], see the \f[B]ENVIRONMENT VARIABLES\f[R] section), then after processing all expressions and files, dc(1) will exit, unless -\f[B]-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to -\f[B]-f\f[R] or \f[B]--file\f[R]. -However, if any other \f[B]-e\f[R], \f[B]--expression\f[R], -\f[B]-f\f[R], or \f[B]--file\f[R] arguments are given after -\f[B]-f-\f[R] or equivalent is given, dc(1) will give a fatal error and -exit. +\f[B]\-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to +\f[B]\-f\f[R] or \f[B]\-\-file\f[R]. +However, if any other \f[B]\-e\f[R], \f[B]\-\-expression\f[R], +\f[B]\-f\f[R], or \f[B]\-\-file\f[R] arguments are given after +\f[B]\-f\-\f[R] or equivalent is given, dc(1) will give a fatal error +and exit. .PP -This is a \f[B]non-portable extension\f[R]. +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] +\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. It is a fatal error if \f[I]ibase\f[R] is not a valid number. @@ -197,10 +169,28 @@ It is a fatal error if \f[I]ibase\f[R] is not a valid number. .PP If multiple instances of this option are given, the last is used. .PP -This is a \f[B]non-portable extension\f[R]. +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] +\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. @@ -208,10 +198,48 @@ It is a fatal error if \f[I]obase\f[R] is not a valid number. .PP If multiple instances of this option are given, the last is used. .PP -This is a \f[B]non-portable extension\f[R]. +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] +\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. @@ -219,26 +247,34 @@ It is a fatal error if \f[I]scale\f[R] is not a valid number. .PP If multiple instances of this option are given, the last is used. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-E\f[R] \f[I]seed\f[R], \f[B]--seed\f[R]=\f[I]seed\f[R] -Sets the builtin variable \f[B]seed\f[R] to the value \f[I]seed\f[R] -assuming that \f[I]seed\f[R] is in base 10. -It is a fatal error if \f[I]seed\f[R] is not a valid number. +\f[B]\-v\f[R], \f[B]\-V\f[R], \f[B]\-\-version\f[R] +Print the version information (copyright header) and exits. +.TP +\f[B]\-x\f[R] \f[B]\-\-extended\-register\f[R] +Enables extended register mode. +See the \f[I]Extended Register Mode\f[R] subsection of the +\f[B]REGISTERS\f[R] section for more information. .RS .PP -If multiple instances of this option are given, the last is used. +This is a \f[B]non\-portable extension\f[R]. +.RE +.TP +\f[B]\-z\f[R], \f[B]\-\-leading\-zeroes\f[R] +Makes dc(1) print all numbers greater than \f[B]\-1\f[R] and less than +\f[B]1\f[R], and not equal to \f[B]0\f[R], with a leading zero. +.RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .PP -All long options are \f[B]non-portable extensions\f[R]. +All long options are \f[B]non\-portable extensions\f[R]. .SH STDIN -.PP -If no files are given on the command-line and no files or expressions -are given by the \f[B]-f\f[R], \f[B]--file\f[R], \f[B]-e\f[R], or -\f[B]--expression\f[R] options, then dc(1) reads from \f[B]stdin\f[R]. +If no files are given on the command\-line and no files or expressions +are given by the \f[B]\-f\f[R], \f[B]\-\-file\f[R], \f[B]\-e\f[R], or +\f[B]\-\-expression\f[R] options, then dc(1) reads from \f[B]stdin\f[R]. .PP However, there is a caveat to this. .PP @@ -248,8 +284,7 @@ ended. This means that, except for escaped brackets, all brackets must be balanced before dc(1) parses and executes. .SH STDOUT -.PP -Any non-error output is written to \f[B]stdout\f[R]. +Any non\-error output is written to \f[B]stdout\f[R]. In addition, if history (see the \f[B]HISTORY\f[R] section) and the prompt (see the \f[B]TTY MODE\f[R] section) are enabled, both are output to \f[B]stdout\f[R]. @@ -257,7 +292,7 @@ to \f[B]stdout\f[R]. \f[B]Note\f[R]: Unlike other dc(1) implementations, this dc(1) will issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot write to \f[B]stdout\f[R], so if \f[B]stdout\f[R] is closed, as in -\f[B]dc >&-\f[R], it will quit with an error. +\f[B]dc >&\-\f[R], it will quit with an error. This is done so that dc(1) can report problems when \f[B]stdout\f[R] is redirected to a file. .PP @@ -265,13 +300,12 @@ If there are scripts that depend on the behavior of other dc(1) implementations, it is recommended that those scripts be changed to redirect \f[B]stdout\f[R] to \f[B]/dev/null\f[R]. .SH STDERR -.PP Any error output is written to \f[B]stderr\f[R]. .PP \f[B]Note\f[R]: Unlike other dc(1) implementations, this dc(1) will issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot write to \f[B]stderr\f[R], so if \f[B]stderr\f[R] is closed, as in -\f[B]dc 2>&-\f[R], it will quit with an error. +\f[B]dc 2>&\-\f[R], it will quit with an error. This is done so that dc(1) can exit with an error code when \f[B]stderr\f[R] is redirected to a file. .PP @@ -279,7 +313,6 @@ If there are scripts that depend on the behavior of other dc(1) implementations, it is recommended that those scripts be changed to redirect \f[B]stderr\f[R] to \f[B]/dev/null\f[R]. .SH SYNTAX -.PP Each item in the input source code, either a number (see the \f[B]NUMBERS\f[R] section) or a command (see the \f[B]COMMANDS\f[R] section), is processed and executed, in order. @@ -308,8 +341,8 @@ notation, and if \f[B]obase\f[R] is \f[B]1\f[R], values are output in engineering notation. Otherwise, values are output in the specified base. .PP -Outputting in scientific and engineering notations are \f[B]non-portable -extensions\f[R]. +Outputting in scientific and engineering notations are +\f[B]non\-portable extensions\f[R]. .PP The \f[I]scale\f[R] of an expression is the number of digits in the result of the expression right of the decimal point, and \f[B]scale\f[R] @@ -321,14 +354,14 @@ The max allowable value for \f[B]scale\f[R] can be queried in dc(1) programs with the \f[B]V\f[R] command. .PP \f[B]seed\f[R] is a register containing the current seed for the -pseudo-random number generator. +pseudo\-random number generator. If the current value of \f[B]seed\f[R] is queried and stored, then if it -is assigned to \f[B]seed\f[R] later, the pseudo-random number generator -is guaranteed to produce the same sequence of pseudo-random numbers that -were generated after the value of \f[B]seed\f[R] was first queried. +is assigned to \f[B]seed\f[R] later, the pseudo\-random number generator +is guaranteed to produce the same sequence of pseudo\-random numbers +that were generated after the value of \f[B]seed\f[R] was first queried. .PP Multiple values assigned to \f[B]seed\f[R] can produce the same sequence -of pseudo-random numbers. +of pseudo\-random numbers. Likewise, when a value is assigned to \f[B]seed\f[R], it is not guaranteed that querying \f[B]seed\f[R] immediately after will return the same value. @@ -338,39 +371,68 @@ get receive a value of \f[B]0\f[R] or \f[B]1\f[R]. The maximum integer returned by the \f[B]\[cq]\f[R] command can be queried with the \f[B]W\f[R] command. .PP -\f[B]Note\f[R]: The values returned by the pseudo-random number +\f[B]Note\f[R]: The values returned by the pseudo\-random number generator with the \f[B]\[cq]\f[R] and \f[B]\[lq]\f[R] commands are guaranteed to \f[B]NOT\f[R] be cryptographically secure. -This is a consequence of using a seeded pseudo-random number generator. +This is a consequence of using a seeded pseudo\-random number generator. However, they \f[I]are\f[R] guaranteed to be reproducible with identical \f[B]seed\f[R] values. -This means that the pseudo-random values from dc(1) should only be used -where a reproducible stream of pseudo-random numbers is +This means that the pseudo\-random values from dc(1) should only be used +where a reproducible stream of pseudo\-random numbers is \f[I]ESSENTIAL\f[R]. -In any other case, use a non-seeded pseudo-random number generator. +In any other case, use a non\-seeded pseudo\-random number generator. .PP -The pseudo-random number generator, \f[B]seed\f[R], and all associated -operations are \f[B]non-portable extensions\f[R]. +The pseudo\-random number generator, \f[B]seed\f[R], and all associated +operations are \f[B]non\-portable extensions\f[R]. .SS Comments -.PP Comments go from \f[B]#\f[R] until, and not including, the next newline. -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .SH NUMBERS -.PP Numbers are strings made up of digits, uppercase letters up to \f[B]F\f[R], and at most \f[B]1\f[R] period for a radix. Numbers can have up to \f[B]DC_NUM_MAX\f[R] digits. -Uppercase letters are equal to \f[B]9\f[R] + their position in the +Uppercase letters are equal to \f[B]9\f[R] plus their position in the alphabet (i.e., \f[B]A\f[R] equals \f[B]10\f[R], or \f[B]9+1\f[R]). -If a digit or letter makes no sense with the current value of -\f[B]ibase\f[R], they are set to the value of the highest valid digit in -\f[B]ibase\f[R]. .PP -Single-character numbers (i.e., \f[B]A\f[R] alone) take the value that -they would have if they were valid digits, regardless of the value of -\f[B]ibase\f[R]. +If a digit or letter makes no sense with the current value of +\f[B]ibase\f[R] (i.e., they are greater than or equal to the current +value of \f[B]ibase\f[R]), then the behavior depends on the existence of +the \f[B]\-c\f[R]/\f[B]\-\-digit\-clamp\f[R] or +\f[B]\-C\f[R]/\f[B]\-\-no\-digit\-clamp\f[R] options (see the +\f[B]OPTIONS\f[R] section), the existence and setting of the +\f[B]DC_DIGIT_CLAMP\f[R] environment variable (see the \f[B]ENVIRONMENT +VARIABLES\f[R] section), or the default, which can be queried with the +\f[B]\-h\f[R]/\f[B]\-\-help\f[R] option. +.PP +If clamping is off, then digits or letters that are greater than or +equal to the current value of \f[B]ibase\f[R] are not changed. +Instead, their given value is multiplied by the appropriate power of +\f[B]ibase\f[R] and added into the number. +This means that, with an \f[B]ibase\f[R] of \f[B]3\f[R], the number +\f[B]AB\f[R] is equal to \f[B]3\[ha]1*A+3\[ha]0*B\f[R], which is +\f[B]3\f[R] times \f[B]10\f[R] plus \f[B]11\f[R], or \f[B]41\f[R]. +.PP +If clamping is on, then digits or letters that are greater than or equal +to the current value of \f[B]ibase\f[R] are set to the value of the +highest valid digit in \f[B]ibase\f[R] before being multiplied by the +appropriate power of \f[B]ibase\f[R] and added into the number. +This means that, with an \f[B]ibase\f[R] of \f[B]3\f[R], the number +\f[B]AB\f[R] is equal to \f[B]3\[ha]1*2+3\[ha]0*2\f[R], which is +\f[B]3\f[R] times \f[B]2\f[R] plus \f[B]2\f[R], or \f[B]8\f[R]. +.PP +There is one exception to clamping: single\-character numbers (i.e., +\f[B]A\f[R] alone). +Such numbers are never clamped and always take the value they would have +in the highest possible \f[B]ibase\f[R]. This means that \f[B]A\f[R] alone always equals decimal \f[B]10\f[R] and -\f[B]F\f[R] alone always equals decimal \f[B]15\f[R]. +\f[B]Z\f[R] alone always equals decimal \f[B]35\f[R]. +This behavior is mandated by the standard for bc(1) (see the STANDARDS +section) and is meant to provide an easy way to set the current +\f[B]ibase\f[R] (with the \f[B]i\f[R] command) regardless of the current +value of \f[B]ibase\f[R]. +.PP +If clamping is on, and the clamped value of a character is needed, use a +leading zero, i.e., for \f[B]A\f[R], use \f[B]0A\f[R]. .PP In addition, dc(1) accepts numbers in scientific notation. These have the form \f[B]<number>e<integer>\f[R]. @@ -389,13 +451,11 @@ number string \f[B]FFeA\f[R], the resulting decimal number will be \f[B]2550000000000\f[R], and if dc(1) is given the number string \f[B]10e_4\f[R], the resulting decimal number will be \f[B]0.0016\f[R]. .PP -Accepting input as scientific notation is a \f[B]non-portable +Accepting input as scientific notation is a \f[B]non\-portable extension\f[R]. .SH COMMANDS -.PP The valid commands are listed below. .SS Printing -.PP These commands are used for printing. .PP Note that both scientific notation and engineering notation are @@ -407,7 +467,7 @@ activated by assigning \f[B]1\f[R] to \f[B]obase\f[R] using To deactivate them, just assign a different value to \f[B]obase\f[R]. .PP Printing numbers in scientific notation and/or engineering notation is a -\f[B]non-portable extension\f[R]. +\f[B]non\-portable extension\f[R]. .TP \f[B]p\f[R] Prints the value on top of the stack, whether number or string, and @@ -427,12 +487,12 @@ Pops a value off the stack. .PP If the value is a number, it is truncated and the absolute value of the result is printed as though \f[B]obase\f[R] is \f[B]256\f[R] and each -digit is interpreted as an 8-bit ASCII character, making it a byte +digit is interpreted as an 8\-bit ASCII character, making it a byte stream. .PP If the value is a string, it is printed without a trailing newline. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]f\f[R] @@ -443,7 +503,6 @@ without altering anything. Users should use this command when they get lost. .RE .SS Arithmetic -.PP These are the commands used for arithmetic. .TP \f[B]+\f[R] @@ -452,7 +511,7 @@ pushed onto the stack. The \f[I]scale\f[R] of the result is equal to the max \f[I]scale\f[R] of both operands. .TP -\f[B]-\f[R] +\f[B]\-\f[R] The top two values are popped off the stack, subtracted, and the result is pushed onto the stack. The \f[I]scale\f[R] of the result is equal to the max \f[I]scale\f[R] of @@ -473,7 +532,7 @@ pushed onto the stack. The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R]. .RS .PP -The first value popped off of the stack must be non-zero. +The first value popped off of the stack must be non\-zero. .RE .TP \f[B]%\f[R] @@ -483,10 +542,10 @@ is pushed onto the stack. .PP Remaindering is equivalent to 1) Computing \f[B]a/b\f[R] to current \f[B]scale\f[R], and 2) Using the result of step 1 to calculate -\f[B]a-(a/b)*b\f[R] to \f[I]scale\f[R] +\f[B]a\-(a/b)*b\f[R] to \f[I]scale\f[R] \f[B]max(scale+scale(b),scale(a))\f[R]. .PP -The first value popped off of the stack must be non-zero. +The first value popped off of the stack must be non\-zero. .RE .TP \f[B]\[ti]\f[R] @@ -497,9 +556,9 @@ This is equivalent to \f[B]x y / x y %\f[R] except that \f[B]x\f[R] and \f[B]y\f[R] are only evaluated once. .RS .PP -The first value popped off of the stack must be non-zero. +The first value popped off of the stack must be non\-zero. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]\[ha]\f[R] @@ -510,7 +569,7 @@ The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R]. .PP The first value popped off of the stack must be an integer, and if that value is negative, the second value popped off of the stack must be -non-zero. +non\-zero. .RE .TP \f[B]v\f[R] @@ -519,7 +578,7 @@ the result is pushed onto the stack. The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R]. .RS .PP -The value popped off of the stack must be non-negative. +The value popped off of the stack must be non\-negative. .RE .TP \f[B]_\f[R] @@ -529,7 +588,7 @@ or other commands), then that number is input as a negative number. .PP Otherwise, the top value on the stack is popped and copied, and the copy is negated and pushed onto the stack. -This behavior without a number is a \f[B]non-portable extension\f[R]. +This behavior without a number is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]b\f[R] @@ -538,7 +597,7 @@ back onto the stack. Otherwise, its absolute value is pushed onto the stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]|\f[R] @@ -547,12 +606,12 @@ is computed, and the result is pushed onto the stack. .RS .PP The first value popped is used as the reduction modulus and must be an -integer and non-zero. +integer and non\-zero. The second value popped is used as the exponent and must be an integer -and non-negative. +and non\-negative. The third value popped is the base and must be an integer. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]$\f[R] @@ -560,7 +619,7 @@ The top value is popped off the stack and copied, and the copy is truncated and pushed onto the stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]\[at]\f[R] @@ -570,9 +629,9 @@ extension. .RS .PP The first value popped off of the stack must be an integer and -non-negative. +non\-negative. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]H\f[R] @@ -581,9 +640,9 @@ left (radix shifted right) to the value of the first. .RS .PP The first value popped off of the stack must be an integer and -non-negative. +non\-negative. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]h\f[R] @@ -592,9 +651,9 @@ right (radix shifted left) to the value of the first. .RS .PP The first value popped off of the stack must be an integer and -non-negative. +non\-negative. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]G\f[R] @@ -602,7 +661,7 @@ The top two values are popped off of the stack, they are compared, and a \f[B]1\f[R] is pushed if they are equal, or \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]N\f[R] @@ -610,7 +669,7 @@ The top value is popped off of the stack, and if it a \f[B]0\f[R], a \f[B]1\f[R] is pushed; otherwise, a \f[B]0\f[R] is pushed. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B](\f[R] @@ -619,7 +678,7 @@ The top two values are popped off of the stack, they are compared, and a \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]{\f[R] @@ -628,7 +687,7 @@ The top two values are popped off of the stack, they are compared, and a or \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B])\f[R] @@ -637,7 +696,7 @@ The top two values are popped off of the stack, they are compared, and a \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]}\f[R] @@ -646,42 +705,41 @@ The top two values are popped off of the stack, they are compared, and a second, or \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]M\f[R] The top two values are popped off of the stack. -If they are both non-zero, a \f[B]1\f[R] is pushed onto the stack. +If they are both non\-zero, a \f[B]1\f[R] is pushed onto the stack. If either of them is zero, or both of them are, then a \f[B]0\f[R] is pushed onto the stack. .RS .PP This is like the \f[B]&&\f[R] operator in bc(1), and it is \f[I]not\f[R] -a short-circuit operator. +a short\-circuit operator. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]m\f[R] The top two values are popped off of the stack. -If at least one of them is non-zero, a \f[B]1\f[R] is pushed onto the +If at least one of them is non\-zero, a \f[B]1\f[R] is pushed onto the stack. If both of them are zero, then a \f[B]0\f[R] is pushed onto the stack. .RS .PP This is like the \f[B]||\f[R] operator in bc(1), and it is \f[I]not\f[R] -a short-circuit operator. +a short\-circuit operator. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE -.SS Pseudo-Random Number Generator -.PP -dc(1) has a built-in pseudo-random number generator. -These commands query the pseudo-random number generator. +.SS Pseudo\-Random Number Generator +dc(1) has a built\-in pseudo\-random number generator. +These commands query the pseudo\-random number generator. (See Parameters for more information about the \f[B]seed\f[R] value that -controls the pseudo-random number generator.) +controls the pseudo\-random number generator.) .PP -The pseudo-random number generator is guaranteed to \f[B]NOT\f[R] be +The pseudo\-random number generator is guaranteed to \f[B]NOT\f[R] be cryptographically secure. .TP \f[B]\[cq]\f[R] @@ -690,19 +748,19 @@ the \f[B]LIMITS\f[R] section). .RS .PP The generated integer is made as unbiased as possible, subject to the -limitations of the pseudo-random number generator. +limitations of the pseudo\-random number generator. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]\[lq]\f[R] Pops a value off of the stack, which is used as an \f[B]exclusive\f[R] upper bound on the integer that will be generated. -If the bound is negative or is a non-integer, an error is raised, and +If the bound is negative or is a non\-integer, an error is raised, and dc(1) resets (see the \f[B]RESET\f[R] section) while \f[B]seed\f[R] remains unchanged. If the bound is larger than \f[B]DC_RAND_MAX\f[R], the higher bound is -honored by generating several pseudo-random integers, multiplying them +honored by generating several pseudo\-random integers, multiplying them by appropriate powers of \f[B]DC_RAND_MAX+1\f[R], and adding them together. Thus, the size of integer that can be generated with this command is @@ -714,12 +772,11 @@ is \f[I]not\f[R] changed. .RS .PP The generated integer is made as unbiased as possible, subject to the -limitations of the pseudo-random number generator. +limitations of the pseudo\-random number generator. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .SS Stack Control -.PP These commands control the stack. .TP \f[B]c\f[R] @@ -735,7 +792,6 @@ Swaps (\[lq]reverses\[rq]) the two top items on the stack. \f[B]R\f[R] Pops (\[lq]removes\[rq]) the top value from the stack. .SS Register Control -.PP These commands control registers (see the \f[B]REGISTERS\f[R] section). .TP \f[B]s\f[R]\f[I]r\f[R] @@ -757,7 +813,6 @@ push it onto the main stack. The previous value in the stack for register \f[I]r\f[R], if any, is now accessible via the \f[B]l\f[R]\f[I]r\f[R] command. .SS Parameters -.PP These commands control the values of \f[B]ibase\f[R], \f[B]obase\f[R], \f[B]scale\f[R], and \f[B]seed\f[R]. Also see the \f[B]SYNTAX\f[R] section. @@ -785,7 +840,7 @@ If the value on top of the stack has any \f[I]scale\f[R], the .TP \f[B]k\f[R] Pops the value off of the top of the stack and uses it to set -\f[B]scale\f[R], which must be non-negative. +\f[B]scale\f[R], which must be non\-negative. .RS .PP If the value on top of the stack has any \f[I]scale\f[R], the @@ -795,7 +850,7 @@ If the value on top of the stack has any \f[I]scale\f[R], the \f[B]j\f[R] Pops the value off of the top of the stack and uses it to set \f[B]seed\f[R]. -The meaning of \f[B]seed\f[R] is dependent on the current pseudo-random +The meaning of \f[B]seed\f[R] is dependent on the current pseudo\-random number generator but is guaranteed to not change except for new major versions. .RS @@ -803,22 +858,22 @@ versions. The \f[I]scale\f[R] and sign of the value may be significant. .PP If a previously used \f[B]seed\f[R] value is used again, the -pseudo-random number generator is guaranteed to produce the same -sequence of pseudo-random numbers as it did when the \f[B]seed\f[R] +pseudo\-random number generator is guaranteed to produce the same +sequence of pseudo\-random numbers as it did when the \f[B]seed\f[R] value was previously used. .PP The exact value assigned to \f[B]seed\f[R] is not guaranteed to be returned if the \f[B]J\f[R] command is used. However, if \f[B]seed\f[R] \f[I]does\f[R] return a different value, both values, when assigned to \f[B]seed\f[R], are guaranteed to produce the -same sequence of pseudo-random numbers. +same sequence of pseudo\-random numbers. This means that certain values assigned to \f[B]seed\f[R] will not -produce unique sequences of pseudo-random numbers. +produce unique sequences of pseudo\-random numbers. .PP There is no limit to the length (number of significant decimal digits) or \f[I]scale\f[R] of the value that can be assigned to \f[B]seed\f[R]. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]I\f[R] @@ -834,7 +889,7 @@ Pushes the current value of \f[B]scale\f[R] onto the main stack. Pushes the current value of \f[B]seed\f[R] onto the main stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]T\f[R] @@ -842,7 +897,7 @@ Pushes the maximum allowable value of \f[B]ibase\f[R] onto the main stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]U\f[R] @@ -850,7 +905,7 @@ Pushes the maximum allowable value of \f[B]obase\f[R] onto the main stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]V\f[R] @@ -858,18 +913,17 @@ Pushes the maximum allowable value of \f[B]scale\f[R] onto the main stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]W\f[R] Pushes the maximum (inclusive) integer that can be generated with the -\f[B]\[cq]\f[R] pseudo-random number generator command. +\f[B]\[cq]\f[R] pseudo\-random number generator command. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .SS Strings -.PP The following commands control strings. .PP dc(1) can work with both numbers and strings, and registers (see the @@ -907,16 +961,16 @@ The value on top of the stack is popped. If it is a number, it is truncated and its absolute value is taken. The result mod \f[B]256\f[R] is calculated. If that result is \f[B]0\f[R], push an empty string; otherwise, push a -one-character string where the character is the result of the mod +one\-character string where the character is the result of the mod interpreted as an ASCII character. .PP If it is a string, then a new string is made. If the original string is empty, the new string is empty. If it is not, then the first character of the original string is used to -create the new string as a one-character string. +create the new string as a one\-character string. The new string is then pushed onto the stack. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]x\f[R] @@ -952,7 +1006,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]!>\f[R]\f[I]r\f[R] @@ -973,7 +1027,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]<\f[R]\f[I]r\f[R] @@ -994,7 +1048,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]!<\f[R]\f[I]r\f[R] @@ -1015,7 +1069,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]=\f[R]\f[I]r\f[R] @@ -1036,7 +1090,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]!=\f[R]\f[I]r\f[R] @@ -1057,7 +1111,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]?\f[R] @@ -1070,7 +1124,7 @@ the execution of the macro that executed it. If there are no macros, or only one macro executing, dc(1) exits. .TP \f[B]Q\f[R] -Pops a value from the stack which must be non-negative and is used the +Pops a value from the stack which must be non\-negative and is used the number of macro executions to pop off of the execution stack. If the number of levels to pop is greater than the number of executing macros, dc(1) exits. @@ -1081,8 +1135,11 @@ The execution stack is the stack of string executions. The number that is pushed onto the stack is exactly as many as is needed to make dc(1) exit with the \f[B]Q\f[R] command, so the sequence \f[B],Q\f[R] will make dc(1) exit. -.SS Status +.RS .PP +This is a \f[B]non\-portable extension\f[R]. +.RE +.SS Status These commands query status of the stack or its top value. .TP \f[B]Z\f[R] @@ -1107,6 +1164,24 @@ stack. If it is a string, pushes \f[B]0\f[R]. .RE .TP +\f[B]u\f[R] +Pops one value off of the stack. +If the value is a number, this pushes \f[B]1\f[R] onto the stack. +Otherwise (if it is a string), it pushes \f[B]0\f[R]. +.RS +.PP +This is a \f[B]non\-portable extension\f[R]. +.RE +.TP +\f[B]t\f[R] +Pops one value off of the stack. +If the value is a string, this pushes \f[B]1\f[R] onto the stack. +Otherwise (if it is a number), it pushes \f[B]0\f[R]. +.RS +.PP +This is a \f[B]non\-portable extension\f[R]. +.RE +.TP \f[B]z\f[R] Pushes the current depth of the stack (before execution of this command) onto the stack. @@ -1122,10 +1197,9 @@ register\[cq]s stack must always have at least one item; dc(1) will give an error and reset otherwise (see the \f[B]RESET\f[R] section). This means that this command will never push \f[B]0\f[R]. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .SS Arrays -.PP These commands manipulate arrays. .TP \f[B]:\f[R]\f[I]r\f[R] @@ -1142,10 +1216,9 @@ The selected value is then pushed onto the stack. Pushes the length of the array \f[I]r\f[R] onto the stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .SS Global Settings -.PP These commands retrieve global settings. These are the only commands that require multiple specific characters, and all of them begin with the letter \f[B]g\f[R]. @@ -1157,12 +1230,17 @@ section). Pushes the line length set by \f[B]DC_LINE_LENGTH\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section) onto the stack. .TP +\f[B]gx\f[R] +Pushes \f[B]1\f[R] onto the stack if extended register mode is on, +\f[B]0\f[R] otherwise. +See the \f[I]Extended Register Mode\f[R] subsection of the +\f[B]REGISTERS\f[R] section for more information. +.TP \f[B]gz\f[R] Pushes \f[B]0\f[R] onto the stack if the leading zero setting has not -been enabled with the \f[B]-z\f[R] or \f[B]--leading-zeroes\f[R] options -(see the \f[B]OPTIONS\f[R] section), non-zero otherwise. +been enabled with the \f[B]\-z\f[R] or \f[B]\-\-leading\-zeroes\f[R] +options (see the \f[B]OPTIONS\f[R] section), non\-zero otherwise. .SH REGISTERS -.PP Registers are names that can store strings, numbers, and arrays. (Number/string registers do not interfere with array registers.) .PP @@ -1172,45 +1250,45 @@ All registers, when first referenced, have one value (\f[B]0\f[R]) in their stack, and it is a runtime error to attempt to pop that item off of the register stack. .PP -In non-extended register mode, a register name is just the single +In non\-extended register mode, a register name is just the single character that follows any command that needs a register name. The only exceptions are: a newline (\f[B]`\[rs]n'\f[R]) and a left bracket (\f[B]`['\f[R]); it is a parse error for a newline or a left bracket to be used as a register name. .SS Extended Register Mode -.PP Unlike most other dc(1) implentations, this dc(1) provides nearly unlimited amounts of registers, if extended register mode is enabled. .PP -If extended register mode is enabled (\f[B]-x\f[R] or -\f[B]--extended-register\f[R] command-line arguments are given), then -normal single character registers are used \f[I]unless\f[R] the +If extended register mode is enabled (\f[B]\-x\f[R] or +\f[B]\-\-extended\-register\f[R] command\-line arguments are given), +then normal single character registers are used \f[I]unless\f[R] the character immediately following a command that needs a register name is a space (according to \f[B]isspace()\f[R]) and not a newline (\f[B]`\[rs]n'\f[R]). .PP In that case, the register name is found according to the regex -\f[B][a-z][a-z0-9_]*\f[R] (like bc(1) identifiers), and it is a parse -error if the next non-space characters do not match that regex. +\f[B][a\-z][a\-z0\-9_]*\f[R] (like bc(1) identifiers), and it is a parse +error if the next non\-space characters do not match that regex. .SH RESET -.PP -When dc(1) encounters an error or a signal that it has a non-default +When dc(1) encounters an error or a signal that it has a non\-default handler for, it resets. This means that several things happen. .PP First, any macros that are executing are stopped and popped off the -stack. +execution stack. The behavior is not unlike that of exceptions in programming languages. Then the execution point is set so that any code waiting to execute (after all macros returned) is skipped. .PP +However, the stack of values is \f[I]not\f[R] cleared; in interactive +mode, users can inspect the stack and manipulate it. +.PP Thus, when dc(1) resets, it skips any remaining code waiting to be executed. Then, if it is interactive mode, and the error was not a fatal error (see the \f[B]EXIT STATUS\f[R] section), it asks for more input; otherwise, it exits with the appropriate return code. .SH PERFORMANCE -.PP Most dc(1) implementations use \f[B]char\f[R] types to calculate the value of \f[B]1\f[R] decimal digit at a time, but that can be slow. This dc(1) does something different. @@ -1230,7 +1308,6 @@ checking. This integer type depends on the value of \f[B]DC_LONG_BIT\f[R], but is always at least twice as large as the integer type used to store digits. .SH LIMITS -.PP The following are the limits on dc(1): .TP \f[B]DC_LONG_BIT\f[R] @@ -1260,29 +1337,29 @@ Set at \f[B]DC_BASE_POW\f[R]. .TP \f[B]DC_DIM_MAX\f[R] The maximum size of arrays. -Set at \f[B]SIZE_MAX-1\f[R]. +Set at \f[B]SIZE_MAX\-1\f[R]. .TP \f[B]DC_SCALE_MAX\f[R] The maximum \f[B]scale\f[R]. -Set at \f[B]DC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]DC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]DC_STRING_MAX\f[R] The maximum length of strings. -Set at \f[B]DC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]DC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]DC_NAME_MAX\f[R] The maximum length of identifiers. -Set at \f[B]DC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]DC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]DC_NUM_MAX\f[R] The maximum length of a number (in decimal digits), which includes digits after the decimal point. -Set at \f[B]DC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]DC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]DC_RAND_MAX\f[R] The maximum integer (inclusive) returned by the \f[B]\[cq]\f[R] command, if dc(1). -Set at \f[B]2\[ha]DC_LONG_BIT-1\f[R]. +Set at \f[B]2\[ha]DC_LONG_BIT\-1\f[R]. .TP Exponent The maximum allowable exponent (positive or negative). @@ -1290,27 +1367,27 @@ Set at \f[B]DC_OVERFLOW_MAX\f[R]. .TP Number of vars The maximum number of vars/arrays. -Set at \f[B]SIZE_MAX-1\f[R]. +Set at \f[B]SIZE_MAX\-1\f[R]. .PP -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. +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 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). -They should be in the same format as all other command-line arguments. +This is another way to give command\-line arguments to dc(1). +They should be in the same format as all other command\-line arguments. These are always processed first, so any files given in \f[B]DC_ENV_ARGS\f[R] will be processed before arguments and files given -on the command-line. +on the command\-line. This gives the user the ability to set up \[lq]standard\[rq] options and files to be used at every invocation. The most useful thing for such files to contain would be useful functions that the user might want every time dc(1) runs. -Another use would be to use the \f[B]-e\f[R] option to set +Another use would be to use the \f[B]\-e\f[R] option to set \f[B]scale\f[R] to a value other than \f[B]0\f[R]. .RS .PP @@ -1328,14 +1405,14 @@ you can use double quotes as the outside quotes, as in \f[B]\[lq]some quotes. However, handling a file with both kinds of quotes in \f[B]DC_ENV_ARGS\f[R] is not supported due to the complexity of the -parsing, though such files are still supported on the command-line where -the parsing is done by the shell. +parsing, though such files are still supported on the command\-line +where the parsing is done by the shell. .RE .TP \f[B]DC_LINE_LENGTH\f[R] If this environment variable exists and contains an integer that is greater than \f[B]1\f[R] and is less than \f[B]UINT16_MAX\f[R] -(\f[B]2\[ha]16-1\f[R]), dc(1) will output lines to that length, +(\f[B]2\[ha]16\-1\f[R]), dc(1) will output lines to that length, including the backslash newline combo. The default line length is \f[B]70\f[R]. .RS @@ -1352,13 +1429,13 @@ exits on \f[B]SIGINT\f[R] when not in interactive mode. .RS .PP However, when dc(1) is in interactive mode, then if this environment -variable exists and contains an integer, a non-zero value makes dc(1) +variable exists and contains an integer, a non\-zero value makes dc(1) reset on \f[B]SIGINT\f[R], rather than exit, and zero makes dc(1) exit. If this environment variable exists and is \f[I]not\f[R] an integer, then dc(1) will exit on \f[B]SIGINT\f[R]. .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. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]DC_TTY_MODE\f[R] @@ -1367,11 +1444,11 @@ section), then this environment variable has no effect. .RS .PP However, when TTY mode is available, then if this environment variable -exists and contains an integer, then a non-zero value makes dc(1) use +exists and contains an integer, then a non\-zero value makes dc(1) use TTY mode, and zero makes dc(1) not use TTY mode. .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. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]DC_PROMPT\f[R] @@ -1380,30 +1457,46 @@ section), then this environment variable has no effect. .RS .PP However, when TTY mode is available, then if this environment variable -exists and contains an integer, a non-zero value makes dc(1) use a -prompt, and zero or a non-integer makes dc(1) not use a prompt. +exists and contains an integer, a non\-zero value makes dc(1) use a +prompt, and zero or a non\-integer makes dc(1) not use a prompt. If this environment variable does not exist and \f[B]DC_TTY_MODE\f[R] does, then the value of the \f[B]DC_TTY_MODE\f[R] environment variable is used. .PP This environment variable and the \f[B]DC_TTY_MODE\f[R] environment variable override the default, which can be queried with the -\f[B]-h\f[R] or \f[B]--help\f[R] options. +\f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]DC_EXPR_EXIT\f[R] -If any expressions or expression files are given on the command-line -with \f[B]-e\f[R], \f[B]--expression\f[R], \f[B]-f\f[R], or -\f[B]--file\f[R], then if this environment variable exists and contains -an integer, a non-zero value makes dc(1) exit after executing the -expressions and expression files, and a zero value makes dc(1) not exit. +If any expressions or expression files are given on the command\-line +with \f[B]\-e\f[R], \f[B]\-\-expression\f[R], \f[B]\-f\f[R], or +\f[B]\-\-file\f[R], then if this environment variable exists and +contains an integer, a non\-zero value makes dc(1) exit after executing +the expressions and expression files, and a zero value makes dc(1) not +exit. .RS .PP This environment variable overrides the default, which can be queried -with the \f[B]-h\f[R] or \f[B]--help\f[R] options. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE -.SH EXIT STATUS +.TP +\f[B]DC_DIGIT_CLAMP\f[R] +When parsing numbers and if this environment variable exists and +contains an integer, a non\-zero value makes dc(1) clamp digits that are +greater than or equal to the current \f[B]ibase\f[R] so that all such +digits are considered equal to the \f[B]ibase\f[R] minus 1, and a zero +value disables such clamping so that those digits are always equal to +their value, which is multiplied by the power of the \f[B]ibase\f[R]. +.RS .PP +This never applies to single\-digit numbers, as per the bc(1) standard +(see the \f[B]STANDARDS\f[R] section). +.PP +This environment variable overrides the default, which can be queried +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. +.RE +.SH EXIT STATUS dc(1) returns the following exit statuses: .TP \f[B]0\f[R] @@ -1417,10 +1510,10 @@ since math errors will happen in the process of normal execution. .PP Math errors include divide by \f[B]0\f[R], taking the square root of a negative number, using a negative number as a bound for the -pseudo-random number generator, attempting to convert a negative number +pseudo\-random number generator, attempting to convert a negative number to a hardware integer, overflow when converting a number to a hardware integer, overflow when calculating the size of a number, and attempting -to use a non-integer where an integer is required. +to use a non\-integer where an integer is required. .PP Converting to a hardware integer happens for the second operand of the power (\f[B]\[ha]\f[R]), places (\f[B]\[at]\f[R]), left shift @@ -1455,7 +1548,7 @@ A fatal error occurred. Fatal errors include memory allocation errors, I/O errors, failing to open files, attempting to use files that do not have only ASCII characters (dc(1) only accepts ASCII characters), attempting to open a -directory as a file, and giving invalid command-line options. +directory as a file, and giving invalid command\-line options. .RE .PP The exit status \f[B]4\f[R] is special; when a fatal error occurs, dc(1) @@ -1466,17 +1559,17 @@ interactive mode (see the \f[B]INTERACTIVE MODE\f[R] section), since dc(1) resets its state (see the \f[B]RESET\f[R] section) and accepts more input when one of those errors occurs in interactive mode. This is also the case when interactive mode is forced by the -\f[B]-i\f[R] flag or \f[B]--interactive\f[R] option. +\f[B]\-i\f[R] flag or \f[B]\-\-interactive\f[R] option. .PP These exit statuses allow dc(1) to be used in shell scripting with error checking, and its normal behavior can be forced by using the -\f[B]-i\f[R] flag or \f[B]--interactive\f[R] option. +\f[B]\-i\f[R] flag or \f[B]\-\-interactive\f[R] option. .SH INTERACTIVE MODE -.PP -Like bc(1), dc(1) has an interactive mode and a non-interactive mode. +Like bc(1), dc(1) has an interactive mode and a non\-interactive mode. Interactive mode is turned on automatically when both \f[B]stdin\f[R] -and \f[B]stdout\f[R] are hooked to a terminal, but the \f[B]-i\f[R] flag -and \f[B]--interactive\f[R] option can turn it on in other situations. +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. .PP In interactive mode, dc(1) attempts to recover from errors (see the \f[B]RESET\f[R] section), and in normal execution, flushes @@ -1485,7 +1578,6 @@ dc(1) may also reset on \f[B]SIGINT\f[R] instead of exit, depending on the contents of, or default for, the \f[B]DC_SIGINT_RESET\f[R] environment variable (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). .SH TTY MODE -.PP If \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all connected to a TTY, then \[lq]TTY mode\[rq] is considered to be available, and thus, dc(1) can turn on TTY mode, subject to some @@ -1493,45 +1585,42 @@ settings. .PP If there is the environment variable \f[B]DC_TTY_MODE\f[R] in the environment (see the \f[B]ENVIRONMENT VARIABLES\f[R] section), then if -that environment variable contains a non-zero integer, dc(1) will turn +that environment variable contains a non\-zero integer, dc(1) will turn on TTY mode when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all connected to a TTY. If the \f[B]DC_TTY_MODE\f[R] environment variable exists but is -\f[I]not\f[R] a non-zero integer, then dc(1) will not turn TTY mode on. +\f[I]not\f[R] a non\-zero integer, then dc(1) will not turn TTY mode on. .PP If the environment variable \f[B]DC_TTY_MODE\f[R] does \f[I]not\f[R] exist, the default setting is used. -The default setting can be queried with the \f[B]-h\f[R] or -\f[B]--help\f[R] options. +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. Like TTY mode itself, it can be turned on or off with an environment variable: \f[B]DC_PROMPT\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). .PP -If the environment variable \f[B]DC_PROMPT\f[R] exists and is a non-zero -integer, then the prompt is turned on when \f[B]stdin\f[R], +If the environment variable \f[B]DC_PROMPT\f[R] exists and is a +non\-zero integer, then the prompt is turned on when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are connected to a TTY and the -\f[B]-P\f[R] and \f[B]--no-prompt\f[R] options were not used. +\f[B]\-P\f[R] and \f[B]\-\-no\-prompt\f[R] options were not used. The read prompt will be turned on under the same conditions, except that -the \f[B]-R\f[R] and \f[B]--no-read-prompt\f[R] options must also not be -used. +the \f[B]\-R\f[R] and \f[B]\-\-no\-read\-prompt\f[R] options must also +not be used. .PP However, if \f[B]DC_PROMPT\f[R] does not exist, the prompt can be enabled or disabled with the \f[B]DC_TTY_MODE\f[R] environment variable, -the \f[B]-P\f[R] and \f[B]--no-prompt\f[R] options, and the \f[B]-R\f[R] -and \f[B]--no-read-prompt\f[R] options. +the \f[B]\-P\f[R] and \f[B]\-\-no\-prompt\f[R] options, and the +\f[B]\-R\f[R] and \f[B]\-\-no\-read\-prompt\f[R] options. See the \f[B]ENVIRONMENT VARIABLES\f[R] and \f[B]OPTIONS\f[R] sections for more details. .SH SIGNAL HANDLING -.PP Sending a \f[B]SIGINT\f[R] will cause dc(1) to do one of two things. .PP If dc(1) is not in interactive mode (see the \f[B]INTERACTIVE MODE\f[R] @@ -1540,7 +1629,7 @@ section), or the \f[B]DC_SIGINT_RESET\f[R] environment variable (see the an integer or it is zero, dc(1) will exit. .PP However, if dc(1) is in interactive mode, and the -\f[B]DC_SIGINT_RESET\f[R] or its default is an integer and non-zero, +\f[B]DC_SIGINT_RESET\f[R] or its default is an integer and non\-zero, then dc(1) will stop executing the current input and reset (see the \f[B]RESET\f[R] section) upon receiving a \f[B]SIGINT\f[R]. .PP @@ -1563,19 +1652,17 @@ the user to continue. \f[B]SIGTERM\f[R] and \f[B]SIGQUIT\f[R] cause dc(1) to clean up and exit, and it uses the default handler for all other signals. .SH SEE ALSO -.PP bc(1) .SH STANDARDS -.PP -The dc(1) utility operators are compliant with the operators in the IEEE -Std 1003.1-2017 (\[lq]POSIX.1-2017\[rq]) specification at -https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html for -bc(1). +The dc(1) utility operators and some behavior are compliant with the +operators in the IEEE Std 1003.1\-2017 (\[lq]POSIX.1\-2017\[rq]) bc(1) +specification at +https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html . .SH BUGS -.PP None are known. -Report bugs at https://git.yzena.com/gavin/bc. +Report bugs at https://git.gavinhoward.com/gavin/bc . .SH AUTHOR -.PP -Gavin D. -Howard <gavin@yzena.com> and contributors. +Gavin D. Howard \c +.MT gavin@gavinhoward.com +.ME \c +\ and contributors. diff --git a/contrib/bc/manuals/dc/HN.1.md b/contrib/bc/manuals/dc/HN.1.md index 79292243304c..28b9dadd4b4f 100644 --- a/contrib/bc/manuals/dc/HN.1.md +++ b/contrib/bc/manuals/dc/HN.1.md @@ -2,7 +2,7 @@ SPDX-License-Identifier: BSD-2-Clause -Copyright (c) 2018-2021 Gavin D. Howard and contributors. +Copyright (c) 2018-2024 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 is a **non-portable extension**. - -**-P**, **-\-no-prompt** + 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. -: 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**. + If this and/or the **-C** or **-\-no-digit-clamp** options are given + multiple times, the last one given is used. - These options override the **DC_PROMPT** and **DC_TTY_MODE** environment - variables (see the **ENVIRONMENT VARIABLES** 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**. -**-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** +**-E** *seed*, **-\-seed**=*seed* -: Makes dc(1) print all numbers greater than **-1** and less than **1**, and - not equal to **0**, with a leading zero. +: 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. - 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,21 @@ 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 is a **non-portable extension**. @@ -302,15 +335,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**. - -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**. +Uppercase letters are equal to **9** plus 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** (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 +996,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 +1020,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) @@ -1009,6 +1083,12 @@ other character produces a parse error (see the **ERRORS** section). : Pushes the line length set by **DC_LINE_LENGTH** (see the **ENVIRONMENT VARIABLES** section) onto the stack. +**gx** + +: Pushes **1** onto the stack if extended register mode is on, **0** + otherwise. See the *Extended Register Mode* subsection of the **REGISTERS** + section for more information. + **gz** : Pushes **0** onto the stack if the leading zero setting has not been enabled @@ -1050,11 +1130,14 @@ the next non-space characters do not match that regex. When dc(1) encounters an error or a signal that it has a non-default handler for, it resets. This means that several things happen. -First, any macros that are executing are stopped and popped off the stack. -The behavior is not unlike that of exceptions in programming languages. Then -the execution point is set so that any code waiting to execute (after all +First, any macros that are executing are stopped and popped off the execution +stack. The behavior is not unlike that of exceptions in programming languages. +Then the execution point is set so that any code waiting to execute (after all macros returned) is skipped. +However, the stack of values is *not* cleared; in interactive mode, users can +inspect the stack and manipulate it. + Thus, when dc(1) resets, it skips any remaining code waiting to be executed. Then, if it is interactive mode, and the error was not a fatal error (see the **EXIT STATUS** section), it asks for more input; otherwise, it exits with the @@ -1148,7 +1231,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 +1321,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 +1432,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,14 +1488,14 @@ 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.gavinhoward.com/gavin/bc . # AUTHOR -Gavin D. Howard <gavin@yzena.com> and contributors. +Gavin D. Howard <gavin@gavinhoward.com> and contributors. diff --git a/contrib/bc/manuals/dc/N.1 b/contrib/bc/manuals/dc/N.1 index 39782bf95e5e..6e2baa587b1c 100644 --- a/contrib/bc/manuals/dc/N.1 +++ b/contrib/bc/manuals/dc/N.1 @@ -1,7 +1,7 @@ .\" .\" SPDX-License-Identifier: BSD-2-Clause .\" -.\" Copyright (c) 2018-2021 Gavin D. Howard and contributors. +.\" Copyright (c) 2018-2024 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,128 +25,97 @@ .\" 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" "August 2024" "Gavin D. Howard" "General Commands Manual" .nh .ad l .SH Name -.PP -dc - arbitrary-precision decimal reverse-Polish notation calculator +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. +dc(1) is an arbitrary\-precision calculator. It uses a stack (reverse Polish notation) to store numbers and results of computations. Arithmetic operations pop arguments off of the stack and push the results. .PP -If no files are given on the command-line, then dc(1) reads from +If no files are given on the command\-line, then dc(1) reads from \f[B]stdin\f[R] (see the \f[B]STDIN\f[R] section). Otherwise, those files are processed, and dc(1) will then exit. .PP If a user wants to set up a standard environment, they can use \f[B]DC_ENV_ARGS\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). For example, if a user wants the \f[B]scale\f[R] always set to -\f[B]10\f[R], they can set \f[B]DC_ENV_ARGS\f[R] to \f[B]-e 10k\f[R], +\f[B]10\f[R], they can set \f[B]DC_ENV_ARGS\f[R] to \f[B]\-e 10k\f[R], and this dc(1) will always start with a \f[B]scale\f[R] of \f[B]10\f[R]. .SH OPTIONS -.PP The following are the options that dc(1) accepts. .TP -\f[B]-h\f[R], \f[B]--help\f[R] -Prints a usage message and quits. -.TP -\f[B]-v\f[R], \f[B]-V\f[R], \f[B]--version\f[R] -Print the version information (copyright header) and exit. -.TP -\f[B]-i\f[R], \f[B]--interactive\f[R] -Forces interactive mode. -(See the \f[B]INTERACTIVE MODE\f[R] section.) +\f[B]\-C\f[R], \f[B]\-\-no\-digit\-clamp\f[R] +Disables clamping of digits greater than or equal to the current +\f[B]ibase\f[R] when parsing numbers. .RS .PP -This is a \f[B]non-portable extension\f[R]. -.RE -.TP -\f[B]-L\f[R], \f[B]--no-line-length\f[R] -Disables line length checking and prints numbers without backslashes and -newlines. -In other words, this option sets \f[B]BC_LINE_LENGTH\f[R] to \f[B]0\f[R] -(see the \f[B]ENVIRONMENT VARIABLES\f[R] section). -.RS +This means that the value added to a number from a digit is always that +digit\[cq]s value multiplied by the value of ibase raised to the power +of the digit\[cq]s position, which starts from 0 at the least +significant digit. .PP -This is a \f[B]non-portable extension\f[R]. -.RE -.TP -\f[B]-P\f[R], \f[B]--no-prompt\f[R] -Disables the prompt in TTY mode. -(The prompt is only enabled in TTY mode. -See the \f[B]TTY MODE\f[R] section.) This is mostly for those users that -do not want a prompt or are not used to having them in dc(1). -Most of those users would want to put this option in -\f[B]DC_ENV_ARGS\f[R]. -.RS +If this and/or the \f[B]\-c\f[R] or \f[B]\-\-digit\-clamp\f[R] options +are given multiple times, the last one given is used. .PP -These options override the \f[B]DC_PROMPT\f[R] and \f[B]DC_TTY_MODE\f[R] -environment variables (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). +This option overrides the \f[B]DC_DIGIT_CLAMP\f[R] environment variable +(see the \f[B]ENVIRONMENT VARIABLES\f[R] section) and the default, which +can be queried with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-R\f[R], \f[B]--no-read-prompt\f[R] -Disables the read prompt in TTY mode. -(The read prompt is only enabled in TTY mode. -See the \f[B]TTY MODE\f[R] section.) This is mostly for those users that -do not want a read prompt or are not used to having them in dc(1). -Most of those users would want to put this option in -\f[B]BC_ENV_ARGS\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). -This option is also useful in hash bang lines of dc(1) scripts that -prompt for user input. +\f[B]\-c\f[R], \f[B]\-\-digit\-clamp\f[R] +Enables clamping of digits greater than or equal to the current +\f[B]ibase\f[R] when parsing numbers. .RS .PP -This option does not disable the regular prompt because the read prompt -is only used when the \f[B]?\f[R] command is used. +This means that digits that the value added to a number from a digit +that is greater than or equal to the ibase is the value of ibase minus 1 +all multiplied by the value of ibase raised to the power of the +digit\[cq]s position, which starts from 0 at the least significant +digit. .PP -These options \f[I]do\f[R] override the \f[B]DC_PROMPT\f[R] and -\f[B]DC_TTY_MODE\f[R] environment variables (see the \f[B]ENVIRONMENT -VARIABLES\f[R] section), but only for the read prompt. +If this and/or the \f[B]\-C\f[R] or \f[B]\-\-no\-digit\-clamp\f[R] +options are given multiple times, the last one given is used. .PP -This is a \f[B]non-portable extension\f[R]. -.RE -.TP -\f[B]-x\f[R] \f[B]--extended-register\f[R] -Enables extended register mode. -See the \f[I]Extended Register Mode\f[R] subsection of the -\f[B]REGISTERS\f[R] section for more information. -.RS +This option overrides the \f[B]DC_DIGIT_CLAMP\f[R] environment variable +(see the \f[B]ENVIRONMENT VARIABLES\f[R] section) and the default, which +can be queried with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-z\f[R], \f[B]--leading-zeroes\f[R] -Makes dc(1) print all numbers greater than \f[B]-1\f[R] and less than -\f[B]1\f[R], and not equal to \f[B]0\f[R], with a leading zero. +\f[B]\-E\f[R] \f[I]seed\f[R], \f[B]\-\-seed\f[R]=\f[I]seed\f[R] +Sets the builtin variable \f[B]seed\f[R] to the value \f[I]seed\f[R] +assuming that \f[I]seed\f[R] is in base 10. +It is a fatal error if \f[I]seed\f[R] is not a valid number. .RS .PP -This can be set for individual numbers with the \f[B]plz(x)\f[R], -plznl(x)**, \f[B]pnlz(x)\f[R], and \f[B]pnlznl(x)\f[R] functions in the -extended math library (see the \f[B]LIBRARY\f[R] section). +If multiple instances of this option are given, the last is used. .PP -This is a \f[B]non-portable extension\f[R]. +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] +\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 @@ -155,41 +124,44 @@ 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 +If this option is given on the command\-line (i.e., not in \f[B]DC_ENV_ARGS\f[R], see the \f[B]ENVIRONMENT VARIABLES\f[R] section), then after processing all expressions and files, dc(1) will exit, unless -\f[B]-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to -\f[B]-f\f[R] or \f[B]--file\f[R], whether on the command-line or in +\f[B]\-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to +\f[B]\-f\f[R] or \f[B]\-\-file\f[R], whether on the command\-line or in \f[B]DC_ENV_ARGS\f[R]. -However, if any other \f[B]-e\f[R], \f[B]--expression\f[R], -\f[B]-f\f[R], or \f[B]--file\f[R] arguments are given after -\f[B]-f-\f[R] or equivalent is given, dc(1) will give a fatal error and -exit. +However, if any other \f[B]\-e\f[R], \f[B]\-\-expression\f[R], +\f[B]\-f\f[R], or \f[B]\-\-file\f[R] arguments are given after +\f[B]\-f\-\f[R] or equivalent is given, dc(1) will give a fatal error +and exit. .PP -This is a \f[B]non-portable extension\f[R]. +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] +\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 +If this option is given on the command\-line (i.e., not in \f[B]DC_ENV_ARGS\f[R], see the \f[B]ENVIRONMENT VARIABLES\f[R] section), then after processing all expressions and files, dc(1) will exit, unless -\f[B]-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to -\f[B]-f\f[R] or \f[B]--file\f[R]. -However, if any other \f[B]-e\f[R], \f[B]--expression\f[R], -\f[B]-f\f[R], or \f[B]--file\f[R] arguments are given after -\f[B]-f-\f[R] or equivalent is given, dc(1) will give a fatal error and -exit. +\f[B]\-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to +\f[B]\-f\f[R] or \f[B]\-\-file\f[R]. +However, if any other \f[B]\-e\f[R], \f[B]\-\-expression\f[R], +\f[B]\-f\f[R], or \f[B]\-\-file\f[R] arguments are given after +\f[B]\-f\-\f[R] or equivalent is given, dc(1) will give a fatal error +and exit. .PP -This is a \f[B]non-portable extension\f[R]. +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] +\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. It is a fatal error if \f[I]ibase\f[R] is not a valid number. @@ -197,10 +169,28 @@ It is a fatal error if \f[I]ibase\f[R] is not a valid number. .PP If multiple instances of this option are given, the last is used. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-O\f[R] \f[I]obase\f[R], \f[B]--obase\f[R]=\f[I]obase\f[R] +\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. It is a fatal error if \f[I]obase\f[R] is not a valid number. @@ -208,10 +198,48 @@ It is a fatal error if \f[I]obase\f[R] is not a valid number. .PP If multiple instances of this option are given, the last is used. .PP -This is a \f[B]non-portable extension\f[R]. +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] +\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. @@ -219,26 +247,34 @@ It is a fatal error if \f[I]scale\f[R] is not a valid number. .PP If multiple instances of this option are given, the last is used. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP -\f[B]-E\f[R] \f[I]seed\f[R], \f[B]--seed\f[R]=\f[I]seed\f[R] -Sets the builtin variable \f[B]seed\f[R] to the value \f[I]seed\f[R] -assuming that \f[I]seed\f[R] is in base 10. -It is a fatal error if \f[I]seed\f[R] is not a valid number. +\f[B]\-v\f[R], \f[B]\-V\f[R], \f[B]\-\-version\f[R] +Print the version information (copyright header) and exits. +.TP +\f[B]\-x\f[R] \f[B]\-\-extended\-register\f[R] +Enables extended register mode. +See the \f[I]Extended Register Mode\f[R] subsection of the +\f[B]REGISTERS\f[R] section for more information. .RS .PP -If multiple instances of this option are given, the last is used. +This is a \f[B]non\-portable extension\f[R]. +.RE +.TP +\f[B]\-z\f[R], \f[B]\-\-leading\-zeroes\f[R] +Makes dc(1) print all numbers greater than \f[B]\-1\f[R] and less than +\f[B]1\f[R], and not equal to \f[B]0\f[R], with a leading zero. +.RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .PP -All long options are \f[B]non-portable extensions\f[R]. +All long options are \f[B]non\-portable extensions\f[R]. .SH STDIN -.PP -If no files are given on the command-line and no files or expressions -are given by the \f[B]-f\f[R], \f[B]--file\f[R], \f[B]-e\f[R], or -\f[B]--expression\f[R] options, then dc(1) reads from \f[B]stdin\f[R]. +If no files are given on the command\-line and no files or expressions +are given by the \f[B]\-f\f[R], \f[B]\-\-file\f[R], \f[B]\-e\f[R], or +\f[B]\-\-expression\f[R] options, then dc(1) reads from \f[B]stdin\f[R]. .PP However, there is a caveat to this. .PP @@ -248,8 +284,7 @@ ended. This means that, except for escaped brackets, all brackets must be balanced before dc(1) parses and executes. .SH STDOUT -.PP -Any non-error output is written to \f[B]stdout\f[R]. +Any non\-error output is written to \f[B]stdout\f[R]. In addition, if history (see the \f[B]HISTORY\f[R] section) and the prompt (see the \f[B]TTY MODE\f[R] section) are enabled, both are output to \f[B]stdout\f[R]. @@ -257,7 +292,7 @@ to \f[B]stdout\f[R]. \f[B]Note\f[R]: Unlike other dc(1) implementations, this dc(1) will issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot write to \f[B]stdout\f[R], so if \f[B]stdout\f[R] is closed, as in -\f[B]dc >&-\f[R], it will quit with an error. +\f[B]dc >&\-\f[R], it will quit with an error. This is done so that dc(1) can report problems when \f[B]stdout\f[R] is redirected to a file. .PP @@ -265,13 +300,12 @@ If there are scripts that depend on the behavior of other dc(1) implementations, it is recommended that those scripts be changed to redirect \f[B]stdout\f[R] to \f[B]/dev/null\f[R]. .SH STDERR -.PP Any error output is written to \f[B]stderr\f[R]. .PP \f[B]Note\f[R]: Unlike other dc(1) implementations, this dc(1) will issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot write to \f[B]stderr\f[R], so if \f[B]stderr\f[R] is closed, as in -\f[B]dc 2>&-\f[R], it will quit with an error. +\f[B]dc 2>&\-\f[R], it will quit with an error. This is done so that dc(1) can exit with an error code when \f[B]stderr\f[R] is redirected to a file. .PP @@ -279,7 +313,6 @@ If there are scripts that depend on the behavior of other dc(1) implementations, it is recommended that those scripts be changed to redirect \f[B]stderr\f[R] to \f[B]/dev/null\f[R]. .SH SYNTAX -.PP Each item in the input source code, either a number (see the \f[B]NUMBERS\f[R] section) or a command (see the \f[B]COMMANDS\f[R] section), is processed and executed, in order. @@ -308,8 +341,8 @@ notation, and if \f[B]obase\f[R] is \f[B]1\f[R], values are output in engineering notation. Otherwise, values are output in the specified base. .PP -Outputting in scientific and engineering notations are \f[B]non-portable -extensions\f[R]. +Outputting in scientific and engineering notations are +\f[B]non\-portable extensions\f[R]. .PP The \f[I]scale\f[R] of an expression is the number of digits in the result of the expression right of the decimal point, and \f[B]scale\f[R] @@ -321,14 +354,14 @@ The max allowable value for \f[B]scale\f[R] can be queried in dc(1) programs with the \f[B]V\f[R] command. .PP \f[B]seed\f[R] is a register containing the current seed for the -pseudo-random number generator. +pseudo\-random number generator. If the current value of \f[B]seed\f[R] is queried and stored, then if it -is assigned to \f[B]seed\f[R] later, the pseudo-random number generator -is guaranteed to produce the same sequence of pseudo-random numbers that -were generated after the value of \f[B]seed\f[R] was first queried. +is assigned to \f[B]seed\f[R] later, the pseudo\-random number generator +is guaranteed to produce the same sequence of pseudo\-random numbers +that were generated after the value of \f[B]seed\f[R] was first queried. .PP Multiple values assigned to \f[B]seed\f[R] can produce the same sequence -of pseudo-random numbers. +of pseudo\-random numbers. Likewise, when a value is assigned to \f[B]seed\f[R], it is not guaranteed that querying \f[B]seed\f[R] immediately after will return the same value. @@ -338,39 +371,68 @@ get receive a value of \f[B]0\f[R] or \f[B]1\f[R]. The maximum integer returned by the \f[B]\[cq]\f[R] command can be queried with the \f[B]W\f[R] command. .PP -\f[B]Note\f[R]: The values returned by the pseudo-random number +\f[B]Note\f[R]: The values returned by the pseudo\-random number generator with the \f[B]\[cq]\f[R] and \f[B]\[lq]\f[R] commands are guaranteed to \f[B]NOT\f[R] be cryptographically secure. -This is a consequence of using a seeded pseudo-random number generator. +This is a consequence of using a seeded pseudo\-random number generator. However, they \f[I]are\f[R] guaranteed to be reproducible with identical \f[B]seed\f[R] values. -This means that the pseudo-random values from dc(1) should only be used -where a reproducible stream of pseudo-random numbers is +This means that the pseudo\-random values from dc(1) should only be used +where a reproducible stream of pseudo\-random numbers is \f[I]ESSENTIAL\f[R]. -In any other case, use a non-seeded pseudo-random number generator. +In any other case, use a non\-seeded pseudo\-random number generator. .PP -The pseudo-random number generator, \f[B]seed\f[R], and all associated -operations are \f[B]non-portable extensions\f[R]. +The pseudo\-random number generator, \f[B]seed\f[R], and all associated +operations are \f[B]non\-portable extensions\f[R]. .SS Comments -.PP Comments go from \f[B]#\f[R] until, and not including, the next newline. -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .SH NUMBERS -.PP Numbers are strings made up of digits, uppercase letters up to \f[B]F\f[R], and at most \f[B]1\f[R] period for a radix. Numbers can have up to \f[B]DC_NUM_MAX\f[R] digits. -Uppercase letters are equal to \f[B]9\f[R] + their position in the +Uppercase letters are equal to \f[B]9\f[R] plus their position in the alphabet (i.e., \f[B]A\f[R] equals \f[B]10\f[R], or \f[B]9+1\f[R]). -If a digit or letter makes no sense with the current value of -\f[B]ibase\f[R], they are set to the value of the highest valid digit in -\f[B]ibase\f[R]. .PP -Single-character numbers (i.e., \f[B]A\f[R] alone) take the value that -they would have if they were valid digits, regardless of the value of -\f[B]ibase\f[R]. +If a digit or letter makes no sense with the current value of +\f[B]ibase\f[R] (i.e., they are greater than or equal to the current +value of \f[B]ibase\f[R]), then the behavior depends on the existence of +the \f[B]\-c\f[R]/\f[B]\-\-digit\-clamp\f[R] or +\f[B]\-C\f[R]/\f[B]\-\-no\-digit\-clamp\f[R] options (see the +\f[B]OPTIONS\f[R] section), the existence and setting of the +\f[B]DC_DIGIT_CLAMP\f[R] environment variable (see the \f[B]ENVIRONMENT +VARIABLES\f[R] section), or the default, which can be queried with the +\f[B]\-h\f[R]/\f[B]\-\-help\f[R] option. +.PP +If clamping is off, then digits or letters that are greater than or +equal to the current value of \f[B]ibase\f[R] are not changed. +Instead, their given value is multiplied by the appropriate power of +\f[B]ibase\f[R] and added into the number. +This means that, with an \f[B]ibase\f[R] of \f[B]3\f[R], the number +\f[B]AB\f[R] is equal to \f[B]3\[ha]1*A+3\[ha]0*B\f[R], which is +\f[B]3\f[R] times \f[B]10\f[R] plus \f[B]11\f[R], or \f[B]41\f[R]. +.PP +If clamping is on, then digits or letters that are greater than or equal +to the current value of \f[B]ibase\f[R] are set to the value of the +highest valid digit in \f[B]ibase\f[R] before being multiplied by the +appropriate power of \f[B]ibase\f[R] and added into the number. +This means that, with an \f[B]ibase\f[R] of \f[B]3\f[R], the number +\f[B]AB\f[R] is equal to \f[B]3\[ha]1*2+3\[ha]0*2\f[R], which is +\f[B]3\f[R] times \f[B]2\f[R] plus \f[B]2\f[R], or \f[B]8\f[R]. +.PP +There is one exception to clamping: single\-character numbers (i.e., +\f[B]A\f[R] alone). +Such numbers are never clamped and always take the value they would have +in the highest possible \f[B]ibase\f[R]. This means that \f[B]A\f[R] alone always equals decimal \f[B]10\f[R] and -\f[B]F\f[R] alone always equals decimal \f[B]15\f[R]. +\f[B]Z\f[R] alone always equals decimal \f[B]35\f[R]. +This behavior is mandated by the standard for bc(1) (see the STANDARDS +section) and is meant to provide an easy way to set the current +\f[B]ibase\f[R] (with the \f[B]i\f[R] command) regardless of the current +value of \f[B]ibase\f[R]. +.PP +If clamping is on, and the clamped value of a character is needed, use a +leading zero, i.e., for \f[B]A\f[R], use \f[B]0A\f[R]. .PP In addition, dc(1) accepts numbers in scientific notation. These have the form \f[B]<number>e<integer>\f[R]. @@ -389,13 +451,11 @@ number string \f[B]FFeA\f[R], the resulting decimal number will be \f[B]2550000000000\f[R], and if dc(1) is given the number string \f[B]10e_4\f[R], the resulting decimal number will be \f[B]0.0016\f[R]. .PP -Accepting input as scientific notation is a \f[B]non-portable +Accepting input as scientific notation is a \f[B]non\-portable extension\f[R]. .SH COMMANDS -.PP The valid commands are listed below. .SS Printing -.PP These commands are used for printing. .PP Note that both scientific notation and engineering notation are @@ -407,7 +467,7 @@ activated by assigning \f[B]1\f[R] to \f[B]obase\f[R] using To deactivate them, just assign a different value to \f[B]obase\f[R]. .PP Printing numbers in scientific notation and/or engineering notation is a -\f[B]non-portable extension\f[R]. +\f[B]non\-portable extension\f[R]. .TP \f[B]p\f[R] Prints the value on top of the stack, whether number or string, and @@ -427,12 +487,12 @@ Pops a value off the stack. .PP If the value is a number, it is truncated and the absolute value of the result is printed as though \f[B]obase\f[R] is \f[B]256\f[R] and each -digit is interpreted as an 8-bit ASCII character, making it a byte +digit is interpreted as an 8\-bit ASCII character, making it a byte stream. .PP If the value is a string, it is printed without a trailing newline. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]f\f[R] @@ -443,7 +503,6 @@ without altering anything. Users should use this command when they get lost. .RE .SS Arithmetic -.PP These are the commands used for arithmetic. .TP \f[B]+\f[R] @@ -452,7 +511,7 @@ pushed onto the stack. The \f[I]scale\f[R] of the result is equal to the max \f[I]scale\f[R] of both operands. .TP -\f[B]-\f[R] +\f[B]\-\f[R] The top two values are popped off the stack, subtracted, and the result is pushed onto the stack. The \f[I]scale\f[R] of the result is equal to the max \f[I]scale\f[R] of @@ -473,7 +532,7 @@ pushed onto the stack. The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R]. .RS .PP -The first value popped off of the stack must be non-zero. +The first value popped off of the stack must be non\-zero. .RE .TP \f[B]%\f[R] @@ -483,10 +542,10 @@ is pushed onto the stack. .PP Remaindering is equivalent to 1) Computing \f[B]a/b\f[R] to current \f[B]scale\f[R], and 2) Using the result of step 1 to calculate -\f[B]a-(a/b)*b\f[R] to \f[I]scale\f[R] +\f[B]a\-(a/b)*b\f[R] to \f[I]scale\f[R] \f[B]max(scale+scale(b),scale(a))\f[R]. .PP -The first value popped off of the stack must be non-zero. +The first value popped off of the stack must be non\-zero. .RE .TP \f[B]\[ti]\f[R] @@ -497,9 +556,9 @@ This is equivalent to \f[B]x y / x y %\f[R] except that \f[B]x\f[R] and \f[B]y\f[R] are only evaluated once. .RS .PP -The first value popped off of the stack must be non-zero. +The first value popped off of the stack must be non\-zero. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]\[ha]\f[R] @@ -510,7 +569,7 @@ The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R]. .PP The first value popped off of the stack must be an integer, and if that value is negative, the second value popped off of the stack must be -non-zero. +non\-zero. .RE .TP \f[B]v\f[R] @@ -519,7 +578,7 @@ the result is pushed onto the stack. The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R]. .RS .PP -The value popped off of the stack must be non-negative. +The value popped off of the stack must be non\-negative. .RE .TP \f[B]_\f[R] @@ -529,7 +588,7 @@ or other commands), then that number is input as a negative number. .PP Otherwise, the top value on the stack is popped and copied, and the copy is negated and pushed onto the stack. -This behavior without a number is a \f[B]non-portable extension\f[R]. +This behavior without a number is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]b\f[R] @@ -538,7 +597,7 @@ back onto the stack. Otherwise, its absolute value is pushed onto the stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]|\f[R] @@ -547,12 +606,12 @@ is computed, and the result is pushed onto the stack. .RS .PP The first value popped is used as the reduction modulus and must be an -integer and non-zero. +integer and non\-zero. The second value popped is used as the exponent and must be an integer -and non-negative. +and non\-negative. The third value popped is the base and must be an integer. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]$\f[R] @@ -560,7 +619,7 @@ The top value is popped off the stack and copied, and the copy is truncated and pushed onto the stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]\[at]\f[R] @@ -570,9 +629,9 @@ extension. .RS .PP The first value popped off of the stack must be an integer and -non-negative. +non\-negative. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]H\f[R] @@ -581,9 +640,9 @@ left (radix shifted right) to the value of the first. .RS .PP The first value popped off of the stack must be an integer and -non-negative. +non\-negative. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]h\f[R] @@ -592,9 +651,9 @@ right (radix shifted left) to the value of the first. .RS .PP The first value popped off of the stack must be an integer and -non-negative. +non\-negative. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]G\f[R] @@ -602,7 +661,7 @@ The top two values are popped off of the stack, they are compared, and a \f[B]1\f[R] is pushed if they are equal, or \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]N\f[R] @@ -610,7 +669,7 @@ The top value is popped off of the stack, and if it a \f[B]0\f[R], a \f[B]1\f[R] is pushed; otherwise, a \f[B]0\f[R] is pushed. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B](\f[R] @@ -619,7 +678,7 @@ The top two values are popped off of the stack, they are compared, and a \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]{\f[R] @@ -628,7 +687,7 @@ The top two values are popped off of the stack, they are compared, and a or \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B])\f[R] @@ -637,7 +696,7 @@ The top two values are popped off of the stack, they are compared, and a \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]}\f[R] @@ -646,42 +705,41 @@ The top two values are popped off of the stack, they are compared, and a second, or \f[B]0\f[R] otherwise. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]M\f[R] The top two values are popped off of the stack. -If they are both non-zero, a \f[B]1\f[R] is pushed onto the stack. +If they are both non\-zero, a \f[B]1\f[R] is pushed onto the stack. If either of them is zero, or both of them are, then a \f[B]0\f[R] is pushed onto the stack. .RS .PP This is like the \f[B]&&\f[R] operator in bc(1), and it is \f[I]not\f[R] -a short-circuit operator. +a short\-circuit operator. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]m\f[R] The top two values are popped off of the stack. -If at least one of them is non-zero, a \f[B]1\f[R] is pushed onto the +If at least one of them is non\-zero, a \f[B]1\f[R] is pushed onto the stack. If both of them are zero, then a \f[B]0\f[R] is pushed onto the stack. .RS .PP This is like the \f[B]||\f[R] operator in bc(1), and it is \f[I]not\f[R] -a short-circuit operator. +a short\-circuit operator. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE -.SS Pseudo-Random Number Generator -.PP -dc(1) has a built-in pseudo-random number generator. -These commands query the pseudo-random number generator. +.SS Pseudo\-Random Number Generator +dc(1) has a built\-in pseudo\-random number generator. +These commands query the pseudo\-random number generator. (See Parameters for more information about the \f[B]seed\f[R] value that -controls the pseudo-random number generator.) +controls the pseudo\-random number generator.) .PP -The pseudo-random number generator is guaranteed to \f[B]NOT\f[R] be +The pseudo\-random number generator is guaranteed to \f[B]NOT\f[R] be cryptographically secure. .TP \f[B]\[cq]\f[R] @@ -690,19 +748,19 @@ the \f[B]LIMITS\f[R] section). .RS .PP The generated integer is made as unbiased as possible, subject to the -limitations of the pseudo-random number generator. +limitations of the pseudo\-random number generator. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]\[lq]\f[R] Pops a value off of the stack, which is used as an \f[B]exclusive\f[R] upper bound on the integer that will be generated. -If the bound is negative or is a non-integer, an error is raised, and +If the bound is negative or is a non\-integer, an error is raised, and dc(1) resets (see the \f[B]RESET\f[R] section) while \f[B]seed\f[R] remains unchanged. If the bound is larger than \f[B]DC_RAND_MAX\f[R], the higher bound is -honored by generating several pseudo-random integers, multiplying them +honored by generating several pseudo\-random integers, multiplying them by appropriate powers of \f[B]DC_RAND_MAX+1\f[R], and adding them together. Thus, the size of integer that can be generated with this command is @@ -714,12 +772,11 @@ is \f[I]not\f[R] changed. .RS .PP The generated integer is made as unbiased as possible, subject to the -limitations of the pseudo-random number generator. +limitations of the pseudo\-random number generator. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .SS Stack Control -.PP These commands control the stack. .TP \f[B]c\f[R] @@ -735,7 +792,6 @@ Swaps (\[lq]reverses\[rq]) the two top items on the stack. \f[B]R\f[R] Pops (\[lq]removes\[rq]) the top value from the stack. .SS Register Control -.PP These commands control registers (see the \f[B]REGISTERS\f[R] section). .TP \f[B]s\f[R]\f[I]r\f[R] @@ -757,7 +813,6 @@ push it onto the main stack. The previous value in the stack for register \f[I]r\f[R], if any, is now accessible via the \f[B]l\f[R]\f[I]r\f[R] command. .SS Parameters -.PP These commands control the values of \f[B]ibase\f[R], \f[B]obase\f[R], \f[B]scale\f[R], and \f[B]seed\f[R]. Also see the \f[B]SYNTAX\f[R] section. @@ -785,7 +840,7 @@ If the value on top of the stack has any \f[I]scale\f[R], the .TP \f[B]k\f[R] Pops the value off of the top of the stack and uses it to set -\f[B]scale\f[R], which must be non-negative. +\f[B]scale\f[R], which must be non\-negative. .RS .PP If the value on top of the stack has any \f[I]scale\f[R], the @@ -795,7 +850,7 @@ If the value on top of the stack has any \f[I]scale\f[R], the \f[B]j\f[R] Pops the value off of the top of the stack and uses it to set \f[B]seed\f[R]. -The meaning of \f[B]seed\f[R] is dependent on the current pseudo-random +The meaning of \f[B]seed\f[R] is dependent on the current pseudo\-random number generator but is guaranteed to not change except for new major versions. .RS @@ -803,22 +858,22 @@ versions. The \f[I]scale\f[R] and sign of the value may be significant. .PP If a previously used \f[B]seed\f[R] value is used again, the -pseudo-random number generator is guaranteed to produce the same -sequence of pseudo-random numbers as it did when the \f[B]seed\f[R] +pseudo\-random number generator is guaranteed to produce the same +sequence of pseudo\-random numbers as it did when the \f[B]seed\f[R] value was previously used. .PP The exact value assigned to \f[B]seed\f[R] is not guaranteed to be returned if the \f[B]J\f[R] command is used. However, if \f[B]seed\f[R] \f[I]does\f[R] return a different value, both values, when assigned to \f[B]seed\f[R], are guaranteed to produce the -same sequence of pseudo-random numbers. +same sequence of pseudo\-random numbers. This means that certain values assigned to \f[B]seed\f[R] will not -produce unique sequences of pseudo-random numbers. +produce unique sequences of pseudo\-random numbers. .PP There is no limit to the length (number of significant decimal digits) or \f[I]scale\f[R] of the value that can be assigned to \f[B]seed\f[R]. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]I\f[R] @@ -834,7 +889,7 @@ Pushes the current value of \f[B]scale\f[R] onto the main stack. Pushes the current value of \f[B]seed\f[R] onto the main stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]T\f[R] @@ -842,7 +897,7 @@ Pushes the maximum allowable value of \f[B]ibase\f[R] onto the main stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]U\f[R] @@ -850,7 +905,7 @@ Pushes the maximum allowable value of \f[B]obase\f[R] onto the main stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]V\f[R] @@ -858,18 +913,17 @@ Pushes the maximum allowable value of \f[B]scale\f[R] onto the main stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]W\f[R] Pushes the maximum (inclusive) integer that can be generated with the -\f[B]\[cq]\f[R] pseudo-random number generator command. +\f[B]\[cq]\f[R] pseudo\-random number generator command. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .SS Strings -.PP The following commands control strings. .PP dc(1) can work with both numbers and strings, and registers (see the @@ -907,16 +961,16 @@ The value on top of the stack is popped. If it is a number, it is truncated and its absolute value is taken. The result mod \f[B]256\f[R] is calculated. If that result is \f[B]0\f[R], push an empty string; otherwise, push a -one-character string where the character is the result of the mod +one\-character string where the character is the result of the mod interpreted as an ASCII character. .PP If it is a string, then a new string is made. If the original string is empty, the new string is empty. If it is not, then the first character of the original string is used to -create the new string as a one-character string. +create the new string as a one\-character string. The new string is then pushed onto the stack. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]x\f[R] @@ -952,7 +1006,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]!>\f[R]\f[I]r\f[R] @@ -973,7 +1027,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]<\f[R]\f[I]r\f[R] @@ -994,7 +1048,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]!<\f[R]\f[I]r\f[R] @@ -1015,7 +1069,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]=\f[R]\f[I]r\f[R] @@ -1036,7 +1090,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]!=\f[R]\f[I]r\f[R] @@ -1057,7 +1111,7 @@ fails. If either or both of the values are not numbers, dc(1) will raise an error and reset (see the \f[B]RESET\f[R] section). .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .TP \f[B]?\f[R] @@ -1070,7 +1124,7 @@ the execution of the macro that executed it. If there are no macros, or only one macro executing, dc(1) exits. .TP \f[B]Q\f[R] -Pops a value from the stack which must be non-negative and is used the +Pops a value from the stack which must be non\-negative and is used the number of macro executions to pop off of the execution stack. If the number of levels to pop is greater than the number of executing macros, dc(1) exits. @@ -1081,8 +1135,11 @@ The execution stack is the stack of string executions. The number that is pushed onto the stack is exactly as many as is needed to make dc(1) exit with the \f[B]Q\f[R] command, so the sequence \f[B],Q\f[R] will make dc(1) exit. -.SS Status +.RS .PP +This is a \f[B]non\-portable extension\f[R]. +.RE +.SS Status These commands query status of the stack or its top value. .TP \f[B]Z\f[R] @@ -1107,6 +1164,24 @@ stack. If it is a string, pushes \f[B]0\f[R]. .RE .TP +\f[B]u\f[R] +Pops one value off of the stack. +If the value is a number, this pushes \f[B]1\f[R] onto the stack. +Otherwise (if it is a string), it pushes \f[B]0\f[R]. +.RS +.PP +This is a \f[B]non\-portable extension\f[R]. +.RE +.TP +\f[B]t\f[R] +Pops one value off of the stack. +If the value is a string, this pushes \f[B]1\f[R] onto the stack. +Otherwise (if it is a number), it pushes \f[B]0\f[R]. +.RS +.PP +This is a \f[B]non\-portable extension\f[R]. +.RE +.TP \f[B]z\f[R] Pushes the current depth of the stack (before execution of this command) onto the stack. @@ -1122,10 +1197,9 @@ register\[cq]s stack must always have at least one item; dc(1) will give an error and reset otherwise (see the \f[B]RESET\f[R] section). This means that this command will never push \f[B]0\f[R]. .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .SS Arrays -.PP These commands manipulate arrays. .TP \f[B]:\f[R]\f[I]r\f[R] @@ -1142,10 +1216,9 @@ The selected value is then pushed onto the stack. Pushes the length of the array \f[I]r\f[R] onto the stack. .RS .PP -This is a \f[B]non-portable extension\f[R]. +This is a \f[B]non\-portable extension\f[R]. .RE .SS Global Settings -.PP These commands retrieve global settings. These are the only commands that require multiple specific characters, and all of them begin with the letter \f[B]g\f[R]. @@ -1157,12 +1230,17 @@ section). Pushes the line length set by \f[B]DC_LINE_LENGTH\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section) onto the stack. .TP +\f[B]gx\f[R] +Pushes \f[B]1\f[R] onto the stack if extended register mode is on, +\f[B]0\f[R] otherwise. +See the \f[I]Extended Register Mode\f[R] subsection of the +\f[B]REGISTERS\f[R] section for more information. +.TP \f[B]gz\f[R] Pushes \f[B]0\f[R] onto the stack if the leading zero setting has not -been enabled with the \f[B]-z\f[R] or \f[B]--leading-zeroes\f[R] options -(see the \f[B]OPTIONS\f[R] section), non-zero otherwise. +been enabled with the \f[B]\-z\f[R] or \f[B]\-\-leading\-zeroes\f[R] +options (see the \f[B]OPTIONS\f[R] section), non\-zero otherwise. .SH REGISTERS -.PP Registers are names that can store strings, numbers, and arrays. (Number/string registers do not interfere with array registers.) .PP @@ -1172,45 +1250,45 @@ All registers, when first referenced, have one value (\f[B]0\f[R]) in their stack, and it is a runtime error to attempt to pop that item off of the register stack. .PP -In non-extended register mode, a register name is just the single +In non\-extended register mode, a register name is just the single character that follows any command that needs a register name. The only exceptions are: a newline (\f[B]`\[rs]n'\f[R]) and a left bracket (\f[B]`['\f[R]); it is a parse error for a newline or a left bracket to be used as a register name. .SS Extended Register Mode -.PP Unlike most other dc(1) implentations, this dc(1) provides nearly unlimited amounts of registers, if extended register mode is enabled. .PP -If extended register mode is enabled (\f[B]-x\f[R] or -\f[B]--extended-register\f[R] command-line arguments are given), then -normal single character registers are used \f[I]unless\f[R] the +If extended register mode is enabled (\f[B]\-x\f[R] or +\f[B]\-\-extended\-register\f[R] command\-line arguments are given), +then normal single character registers are used \f[I]unless\f[R] the character immediately following a command that needs a register name is a space (according to \f[B]isspace()\f[R]) and not a newline (\f[B]`\[rs]n'\f[R]). .PP In that case, the register name is found according to the regex -\f[B][a-z][a-z0-9_]*\f[R] (like bc(1) identifiers), and it is a parse -error if the next non-space characters do not match that regex. +\f[B][a\-z][a\-z0\-9_]*\f[R] (like bc(1) identifiers), and it is a parse +error if the next non\-space characters do not match that regex. .SH RESET -.PP -When dc(1) encounters an error or a signal that it has a non-default +When dc(1) encounters an error or a signal that it has a non\-default handler for, it resets. This means that several things happen. .PP First, any macros that are executing are stopped and popped off the -stack. +execution stack. The behavior is not unlike that of exceptions in programming languages. Then the execution point is set so that any code waiting to execute (after all macros returned) is skipped. .PP +However, the stack of values is \f[I]not\f[R] cleared; in interactive +mode, users can inspect the stack and manipulate it. +.PP Thus, when dc(1) resets, it skips any remaining code waiting to be executed. Then, if it is interactive mode, and the error was not a fatal error (see the \f[B]EXIT STATUS\f[R] section), it asks for more input; otherwise, it exits with the appropriate return code. .SH PERFORMANCE -.PP Most dc(1) implementations use \f[B]char\f[R] types to calculate the value of \f[B]1\f[R] decimal digit at a time, but that can be slow. This dc(1) does something different. @@ -1230,7 +1308,6 @@ checking. This integer type depends on the value of \f[B]DC_LONG_BIT\f[R], but is always at least twice as large as the integer type used to store digits. .SH LIMITS -.PP The following are the limits on dc(1): .TP \f[B]DC_LONG_BIT\f[R] @@ -1260,29 +1337,29 @@ Set at \f[B]DC_BASE_POW\f[R]. .TP \f[B]DC_DIM_MAX\f[R] The maximum size of arrays. -Set at \f[B]SIZE_MAX-1\f[R]. +Set at \f[B]SIZE_MAX\-1\f[R]. .TP \f[B]DC_SCALE_MAX\f[R] The maximum \f[B]scale\f[R]. -Set at \f[B]DC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]DC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]DC_STRING_MAX\f[R] The maximum length of strings. -Set at \f[B]DC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]DC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]DC_NAME_MAX\f[R] The maximum length of identifiers. -Set at \f[B]DC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]DC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]DC_NUM_MAX\f[R] The maximum length of a number (in decimal digits), which includes digits after the decimal point. -Set at \f[B]DC_OVERFLOW_MAX-1\f[R]. +Set at \f[B]DC_OVERFLOW_MAX\-1\f[R]. .TP \f[B]DC_RAND_MAX\f[R] The maximum integer (inclusive) returned by the \f[B]\[cq]\f[R] command, if dc(1). -Set at \f[B]2\[ha]DC_LONG_BIT-1\f[R]. +Set at \f[B]2\[ha]DC_LONG_BIT\-1\f[R]. .TP Exponent The maximum allowable exponent (positive or negative). @@ -1290,27 +1367,27 @@ Set at \f[B]DC_OVERFLOW_MAX\f[R]. .TP Number of vars The maximum number of vars/arrays. -Set at \f[B]SIZE_MAX-1\f[R]. +Set at \f[B]SIZE_MAX\-1\f[R]. .PP -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. +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 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). -They should be in the same format as all other command-line arguments. +This is another way to give command\-line arguments to dc(1). +They should be in the same format as all other command\-line arguments. These are always processed first, so any files given in \f[B]DC_ENV_ARGS\f[R] will be processed before arguments and files given -on the command-line. +on the command\-line. This gives the user the ability to set up \[lq]standard\[rq] options and files to be used at every invocation. The most useful thing for such files to contain would be useful functions that the user might want every time dc(1) runs. -Another use would be to use the \f[B]-e\f[R] option to set +Another use would be to use the \f[B]\-e\f[R] option to set \f[B]scale\f[R] to a value other than \f[B]0\f[R]. .RS .PP @@ -1328,14 +1405,14 @@ you can use double quotes as the outside quotes, as in \f[B]\[lq]some quotes. However, handling a file with both kinds of quotes in \f[B]DC_ENV_ARGS\f[R] is not supported due to the complexity of the -parsing, though such files are still supported on the command-line where -the parsing is done by the shell. +parsing, though such files are still supported on the command\-line +where the parsing is done by the shell. .RE .TP \f[B]DC_LINE_LENGTH\f[R] If this environment variable exists and contains an integer that is greater than \f[B]1\f[R] and is less than \f[B]UINT16_MAX\f[R] -(\f[B]2\[ha]16-1\f[R]), dc(1) will output lines to that length, +(\f[B]2\[ha]16\-1\f[R]), dc(1) will output lines to that length, including the backslash newline combo. The default line length is \f[B]70\f[R]. .RS @@ -1352,13 +1429,13 @@ exits on \f[B]SIGINT\f[R] when not in interactive mode. .RS .PP However, when dc(1) is in interactive mode, then if this environment -variable exists and contains an integer, a non-zero value makes dc(1) +variable exists and contains an integer, a non\-zero value makes dc(1) reset on \f[B]SIGINT\f[R], rather than exit, and zero makes dc(1) exit. If this environment variable exists and is \f[I]not\f[R] an integer, then dc(1) will exit on \f[B]SIGINT\f[R]. .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. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]DC_TTY_MODE\f[R] @@ -1367,11 +1444,11 @@ section), then this environment variable has no effect. .RS .PP However, when TTY mode is available, then if this environment variable -exists and contains an integer, then a non-zero value makes dc(1) use +exists and contains an integer, then a non\-zero value makes dc(1) use TTY mode, and zero makes dc(1) not use TTY mode. .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. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]DC_PROMPT\f[R] @@ -1380,30 +1457,46 @@ section), then this environment variable has no effect. .RS .PP However, when TTY mode is available, then if this environment variable -exists and contains an integer, a non-zero value makes dc(1) use a -prompt, and zero or a non-integer makes dc(1) not use a prompt. +exists and contains an integer, a non\-zero value makes dc(1) use a +prompt, and zero or a non\-integer makes dc(1) not use a prompt. If this environment variable does not exist and \f[B]DC_TTY_MODE\f[R] does, then the value of the \f[B]DC_TTY_MODE\f[R] environment variable is used. .PP This environment variable and the \f[B]DC_TTY_MODE\f[R] environment variable override the default, which can be queried with the -\f[B]-h\f[R] or \f[B]--help\f[R] options. +\f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE .TP \f[B]DC_EXPR_EXIT\f[R] -If any expressions or expression files are given on the command-line -with \f[B]-e\f[R], \f[B]--expression\f[R], \f[B]-f\f[R], or -\f[B]--file\f[R], then if this environment variable exists and contains -an integer, a non-zero value makes dc(1) exit after executing the -expressions and expression files, and a zero value makes dc(1) not exit. +If any expressions or expression files are given on the command\-line +with \f[B]\-e\f[R], \f[B]\-\-expression\f[R], \f[B]\-f\f[R], or +\f[B]\-\-file\f[R], then if this environment variable exists and +contains an integer, a non\-zero value makes dc(1) exit after executing +the expressions and expression files, and a zero value makes dc(1) not +exit. .RS .PP This environment variable overrides the default, which can be queried -with the \f[B]-h\f[R] or \f[B]--help\f[R] options. +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. .RE -.SH EXIT STATUS +.TP +\f[B]DC_DIGIT_CLAMP\f[R] +When parsing numbers and if this environment variable exists and +contains an integer, a non\-zero value makes dc(1) clamp digits that are +greater than or equal to the current \f[B]ibase\f[R] so that all such +digits are considered equal to the \f[B]ibase\f[R] minus 1, and a zero +value disables such clamping so that those digits are always equal to +their value, which is multiplied by the power of the \f[B]ibase\f[R]. +.RS +.PP +This never applies to single\-digit numbers, as per the bc(1) standard +(see the \f[B]STANDARDS\f[R] section). .PP +This environment variable overrides the default, which can be queried +with the \f[B]\-h\f[R] or \f[B]\-\-help\f[R] options. +.RE +.SH EXIT STATUS dc(1) returns the following exit statuses: .TP \f[B]0\f[R] @@ -1417,10 +1510,10 @@ since math errors will happen in the process of normal execution. .PP Math errors include divide by \f[B]0\f[R], taking the square root of a negative number, using a negative number as a bound for the -pseudo-random number generator, attempting to convert a negative number +pseudo\-random number generator, attempting to convert a negative number to a hardware integer, overflow when converting a number to a hardware integer, overflow when calculating the size of a number, and attempting -to use a non-integer where an integer is required. +to use a non\-integer where an integer is required. .PP Converting to a hardware integer happens for the second operand of the power (\f[B]\[ha]\f[R]), places (\f[B]\[at]\f[R]), left shift @@ -1455,7 +1548,7 @@ A fatal error occurred. Fatal errors include memory allocation errors, I/O errors, failing to open files, attempting to use files that do not have only ASCII characters (dc(1) only accepts ASCII characters), attempting to open a -directory as a file, and giving invalid command-line options. +directory as a file, and giving invalid command\-line options. .RE .PP The exit status \f[B]4\f[R] is special; when a fatal error occurs, dc(1) @@ -1466,17 +1559,17 @@ interactive mode (see the \f[B]INTERACTIVE MODE\f[R] section), since dc(1) resets its state (see the \f[B]RESET\f[R] section) and accepts more input when one of those errors occurs in interactive mode. This is also the case when interactive mode is forced by the -\f[B]-i\f[R] flag or \f[B]--interactive\f[R] option. +\f[B]\-i\f[R] flag or \f[B]\-\-interactive\f[R] option. .PP These exit statuses allow dc(1) to be used in shell scripting with error checking, and its normal behavior can be forced by using the -\f[B]-i\f[R] flag or \f[B]--interactive\f[R] option. +\f[B]\-i\f[R] flag or \f[B]\-\-interactive\f[R] option. .SH INTERACTIVE MODE -.PP -Like bc(1), dc(1) has an interactive mode and a non-interactive mode. +Like bc(1), dc(1) has an interactive mode and a non\-interactive mode. Interactive mode is turned on automatically when both \f[B]stdin\f[R] -and \f[B]stdout\f[R] are hooked to a terminal, but the \f[B]-i\f[R] flag -and \f[B]--interactive\f[R] option can turn it on in other situations. +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. .PP In interactive mode, dc(1) attempts to recover from errors (see the \f[B]RESET\f[R] section), and in normal execution, flushes @@ -1485,7 +1578,6 @@ dc(1) may also reset on \f[B]SIGINT\f[R] instead of exit, depending on the contents of, or default for, the \f[B]DC_SIGINT_RESET\f[R] environment variable (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). .SH TTY MODE -.PP If \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all connected to a TTY, then \[lq]TTY mode\[rq] is considered to be available, and thus, dc(1) can turn on TTY mode, subject to some @@ -1493,53 +1585,49 @@ settings. .PP If there is the environment variable \f[B]DC_TTY_MODE\f[R] in the environment (see the \f[B]ENVIRONMENT VARIABLES\f[R] section), then if -that environment variable contains a non-zero integer, dc(1) will turn +that environment variable contains a non\-zero integer, dc(1) will turn on TTY mode when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all connected to a TTY. If the \f[B]DC_TTY_MODE\f[R] environment variable exists but is -\f[I]not\f[R] a non-zero integer, then dc(1) will not turn TTY mode on. +\f[I]not\f[R] a non\-zero integer, then dc(1) will not turn TTY mode on. .PP If the environment variable \f[B]DC_TTY_MODE\f[R] does \f[I]not\f[R] exist, the default setting is used. -The default setting can be queried with the \f[B]-h\f[R] or -\f[B]--help\f[R] options. +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. -.SS Command-Line History -.PP -Command-line history is only enabled if TTY mode is, i.e., that +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 +Command\-line history is only enabled if TTY mode is, i.e., that \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are connected to a TTY and the \f[B]DC_TTY_MODE\f[R] environment variable (see the \f[B]ENVIRONMENT VARIABLES\f[R] section) and its default do not disable TTY mode. See the \f[B]COMMAND LINE HISTORY\f[R] section for more information. .SS Prompt -.PP If TTY mode is available, then a prompt can be enabled. Like TTY mode itself, it can be turned on or off with an environment variable: \f[B]DC_PROMPT\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section). .PP -If the environment variable \f[B]DC_PROMPT\f[R] exists and is a non-zero -integer, then the prompt is turned on when \f[B]stdin\f[R], +If the environment variable \f[B]DC_PROMPT\f[R] exists and is a +non\-zero integer, then the prompt is turned on when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are connected to a TTY and the -\f[B]-P\f[R] and \f[B]--no-prompt\f[R] options were not used. +\f[B]\-P\f[R] and \f[B]\-\-no\-prompt\f[R] options were not used. The read prompt will be turned on under the same conditions, except that -the \f[B]-R\f[R] and \f[B]--no-read-prompt\f[R] options must also not be -used. +the \f[B]\-R\f[R] and \f[B]\-\-no\-read\-prompt\f[R] options must also +not be used. .PP However, if \f[B]DC_PROMPT\f[R] does not exist, the prompt can be enabled or disabled with the \f[B]DC_TTY_MODE\f[R] environment variable, -the \f[B]-P\f[R] and \f[B]--no-prompt\f[R] options, and the \f[B]-R\f[R] -and \f[B]--no-read-prompt\f[R] options. +the \f[B]\-P\f[R] and \f[B]\-\-no\-prompt\f[R] options, and the +\f[B]\-R\f[R] and \f[B]\-\-no\-read\-prompt\f[R] options. See the \f[B]ENVIRONMENT VARIABLES\f[R] and \f[B]OPTIONS\f[R] sections for more details. .SH SIGNAL HANDLING -.PP Sending a \f[B]SIGINT\f[R] will cause dc(1) to do one of two things. .PP If dc(1) is not in interactive mode (see the \f[B]INTERACTIVE MODE\f[R] @@ -1548,7 +1636,7 @@ section), or the \f[B]DC_SIGINT_RESET\f[R] environment variable (see the an integer or it is zero, dc(1) will exit. .PP However, if dc(1) is in interactive mode, and the -\f[B]DC_SIGINT_RESET\f[R] or its default is an integer and non-zero, +\f[B]DC_SIGINT_RESET\f[R] or its default is an integer and non\-zero, then dc(1) will stop executing the current input and reset (see the \f[B]RESET\f[R] section) upon receiving a \f[B]SIGINT\f[R]. .PP @@ -1574,12 +1662,11 @@ The one exception is \f[B]SIGHUP\f[R]; in that case, and only when dc(1) is in TTY mode (see the \f[B]TTY MODE\f[R] section), a \f[B]SIGHUP\f[R] will cause dc(1) to clean up and exit. .SH COMMAND LINE HISTORY -.PP -dc(1) supports interactive command-line editing. +dc(1) supports interactive command\-line editing. .PP If dc(1) can be in TTY mode (see the \f[B]TTY MODE\f[R] section), history can be enabled. -This means that command-line history can only be enabled when +This means that command\-line history can only be enabled when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all connected to a TTY. .PP @@ -1589,19 +1676,17 @@ section). .PP \f[B]Note\f[R]: tabs are converted to 8 spaces. .SH SEE ALSO -.PP bc(1) .SH STANDARDS -.PP -The dc(1) utility operators are compliant with the operators in the IEEE -Std 1003.1-2017 (\[lq]POSIX.1-2017\[rq]) specification at -https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html for -bc(1). +The dc(1) utility operators and some behavior are compliant with the +operators in the IEEE Std 1003.1\-2017 (\[lq]POSIX.1\-2017\[rq]) bc(1) +specification at +https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html . .SH BUGS -.PP None are known. -Report bugs at https://git.yzena.com/gavin/bc. +Report bugs at https://git.gavinhoward.com/gavin/bc . .SH AUTHOR -.PP -Gavin D. -Howard <gavin@yzena.com> and contributors. +Gavin D. Howard \c +.MT gavin@gavinhoward.com +.ME \c +\ and contributors. diff --git a/contrib/bc/manuals/dc/N.1.md b/contrib/bc/manuals/dc/N.1.md index 25c13b7c2fd4..22ea9c96bc80 100644 --- a/contrib/bc/manuals/dc/N.1.md +++ b/contrib/bc/manuals/dc/N.1.md @@ -2,7 +2,7 @@ SPDX-License-Identifier: BSD-2-Clause -Copyright (c) 2018-2021 Gavin D. Howard and contributors. +Copyright (c) 2018-2024 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 is a **non-portable extension**. - -**-P**, **-\-no-prompt** + 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. -: 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**. + If this and/or the **-C** or **-\-no-digit-clamp** options are given + multiple times, the last one given is used. - These options override the **DC_PROMPT** and **DC_TTY_MODE** environment - variables (see the **ENVIRONMENT VARIABLES** 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**. -**-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** +**-E** *seed*, **-\-seed**=*seed* -: Makes dc(1) print all numbers greater than **-1** and less than **1**, and - not equal to **0**, with a leading zero. +: 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. - 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,21 @@ 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 is a **non-portable extension**. @@ -302,15 +335,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**. - -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**. +Uppercase letters are equal to **9** plus 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** (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 +996,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 +1020,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) @@ -1009,6 +1083,12 @@ other character produces a parse error (see the **ERRORS** section). : Pushes the line length set by **DC_LINE_LENGTH** (see the **ENVIRONMENT VARIABLES** section) onto the stack. +**gx** + +: Pushes **1** onto the stack if extended register mode is on, **0** + otherwise. See the *Extended Register Mode* subsection of the **REGISTERS** + section for more information. + **gz** : Pushes **0** onto the stack if the leading zero setting has not been enabled @@ -1050,11 +1130,14 @@ the next non-space characters do not match that regex. When dc(1) encounters an error or a signal that it has a non-default handler for, it resets. This means that several things happen. -First, any macros that are executing are stopped and popped off the stack. -The behavior is not unlike that of exceptions in programming languages. Then -the execution point is set so that any code waiting to execute (after all +First, any macros that are executing are stopped and popped off the execution +stack. The behavior is not unlike that of exceptions in programming languages. +Then the execution point is set so that any code waiting to execute (after all macros returned) is skipped. +However, the stack of values is *not* cleared; in interactive mode, users can +inspect the stack and manipulate it. + Thus, when dc(1) resets, it skips any remaining code waiting to be executed. Then, if it is interactive mode, and the error was not a fatal error (see the **EXIT STATUS** section), it asks for more input; otherwise, it exits with the @@ -1148,7 +1231,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 +1321,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 +1432,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,14 +1511,14 @@ 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.gavinhoward.com/gavin/bc . # AUTHOR -Gavin D. Howard <gavin@yzena.com> and contributors. +Gavin D. Howard <gavin@gavinhoward.com> and contributors. diff --git a/contrib/bc/scripts/exec-install.sh b/contrib/bc/scripts/exec-install.sh index f36caa37e6f8..581b6bd1ed24 100755 --- a/contrib/bc/scripts/exec-install.sh +++ b/contrib/bc/scripts/exec-install.sh @@ -2,7 +2,7 @@ # # SPDX-License-Identifier: BSD-2-Clause # -# Copyright (c) 2018-2021 Gavin D. Howard and contributors. +# Copyright (c) 2018-2024 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: @@ -60,6 +60,12 @@ fi # If it's a symlink, create an equivalent in the install directory. for exe in $bindir/*; do + # Skip any directories in case the bin/ directory is also used as the + # prefix. + if [ -d "$exe" ]; then + continue + fi + base=$(basename "$exe") if [ -L "$exe" ]; then diff --git a/contrib/bc/scripts/format.sh b/contrib/bc/scripts/format.sh index 3e399da5777c..f76aed378186 100755 --- a/contrib/bc/scripts/format.sh +++ b/contrib/bc/scripts/format.sh @@ -2,7 +2,7 @@ # # SPDX-License-Identifier: BSD-2-Clause # -# Copyright (c) 2018-2021 Gavin D. Howard and contributors. +# Copyright (c) 2018-2024 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: @@ -29,6 +29,8 @@ scriptdir=$(dirname "$0") +. "$scriptdir/functions.sh" + cd "$scriptdir/.." if [ "$#" -gt 0 ]; then @@ -47,3 +49,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 diff --git a/contrib/bc/scripts/functions.sh b/contrib/bc/scripts/functions.sh index f2c5b0b50eae..1599fea4847e 100755 --- a/contrib/bc/scripts/functions.sh +++ b/contrib/bc/scripts/functions.sh @@ -2,7 +2,7 @@ # # SPDX-License-Identifier: BSD-2-Clause # -# Copyright (c) 2018-2021 Gavin D. Howard and contributors. +# Copyright (c) 2018-2024 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,88 @@ err_exit() { exit "$2" } +# Function for checking the "d"/"dir" argument of scripts. This function expects +# a usage() function to exist in the caller. +# @param 1 The argument to check. +check_d_arg() { + + if [ "$#" -ne 1 ]; then + printf 'Invalid number of args to check_d_arg\n' + exit 1 + fi + + _check_d_arg_arg="$1" + shift + + if [ "$_check_d_arg_arg" != "bc" ] && [ "$_check_d_arg_arg" != "dc" ]; then + _check_d_arg_msg=$(printf 'Invalid d arg: %s\nMust be either "bc" or "dc".\n\n' \ + "$_check_d_arg_arg") + usage "$_check_d_arg_msg" + fi +} + +# Function for checking the boolean arguments of scripts. This function expects +# a usage() function to exist in the caller. +# @param 1 The argument to check. +check_bool_arg() { + + if [ "$#" -ne 1 ]; then + printf 'Invalid number of args to check_bool_arg\n' + exit 1 + fi + + _check_bool_arg_arg="$1" + shift + + if [ "$_check_bool_arg_arg" != "0" ] && [ "$_check_bool_arg_arg" != "1" ]; then + _check_bool_arg_msg=$(printf 'Invalid bool arg: %s\nMust be either "0" or "1".\n\n' \ + "$_check_bool_arg_arg") + usage "$_check_bool_arg_msg" + fi +} + +# Function for checking the executable arguments of scripts. This function +# expects a usage() function to exist in the caller. +# @param 1 The argument to check. +check_exec_arg() { + + if [ "$#" -ne 1 ]; then + printf 'Invalid number of args to check_exec_arg\n' + exit 1 + fi + + _check_exec_arg_arg="$1" + shift + + if [ ! -x "$_check_exec_arg_arg" ]; then + if ! command -v "$_check_exec_arg_arg" >/dev/null 2>&1; then + _check_exec_arg_msg=$(printf 'Invalid exec arg: %s\nMust be an executable file.\n\n' \ + "$_check_exec_arg_arg") + usage "$_check_exec_arg_msg" + fi + fi +} + +# Function for checking the file arguments of scripts. This function expects a +# usage() function to exist in the caller. +# @param 1 The argument to check. +check_file_arg() { + + if [ "$#" -ne 1 ]; then + printf 'Invalid number of args to check_file_arg\n' + exit 1 + fi + + _check_file_arg_arg="$1" + shift + + if [ ! -f "$_check_file_arg_arg" ]; then + _check_file_arg_msg=$(printf 'Invalid file arg: %s\nMust be a file.\n\n' \ + "$_check_file_arg_arg") + usage "$_check_file_arg_msg" + fi +} + # Check the return code on a test and exit with a fail if it's non-zero. # @param d The calculator under test. # @param err The return code. diff --git a/contrib/bc/scripts/karatsuba.py b/contrib/bc/scripts/karatsuba.py index 9aa1c2a5457f..637887986ee8 100755 --- a/contrib/bc/scripts/karatsuba.py +++ b/contrib/bc/scripts/karatsuba.py @@ -2,7 +2,7 @@ # # SPDX-License-Identifier: BSD-2-Clause # -# Copyright (c) 2018-2021 Gavin D. Howard and contributors. +# Copyright (c) 2018-2024 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: diff --git a/contrib/bc/scripts/link.sh b/contrib/bc/scripts/link.sh index f1c403d50dda..772de27a08c2 100755 --- a/contrib/bc/scripts/link.sh +++ b/contrib/bc/scripts/link.sh @@ -2,7 +2,7 @@ # # SPDX-License-Identifier: BSD-2-Clause # -# Copyright (c) 2018-2021 Gavin D. Howard and contributors. +# Copyright (c) 2018-2024 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: @@ -32,6 +32,11 @@ usage() { exit 1 } +script="$0" +scriptdir=$(dirname "$script") + +. "$scriptdir/functions.sh" + # Command-line processing. test "$#" -gt 1 || usage diff --git a/contrib/bc/scripts/lint.sh b/contrib/bc/scripts/lint.sh index 65f81c5f6511..14cdc5c3afc8 100755 --- a/contrib/bc/scripts/lint.sh +++ b/contrib/bc/scripts/lint.sh @@ -2,7 +2,7 @@ # # SPDX-License-Identifier: BSD-2-Clause # -# Copyright (c) 2018-2021 Gavin D. Howard and contributors. +# Copyright (c) 2018-2024 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: @@ -27,7 +27,10 @@ # POSSIBILITY OF SUCH DAMAGE. # -scriptdir=$(dirname "$0") +script="$0" +scriptdir=$(dirname "$script") + +. "$scriptdir/functions.sh" cd "$scriptdir/.." diff --git a/contrib/bc/scripts/locale_install.sh b/contrib/bc/scripts/locale_install.sh index a67e6aa52970..e891bf57db81 100755 --- a/contrib/bc/scripts/locale_install.sh +++ b/contrib/bc/scripts/locale_install.sh @@ -2,7 +2,7 @@ # # SPDX-License-Identifier: BSD-2-Clause # -# Copyright (c) 2018-2021 Gavin D. Howard and contributors. +# Copyright (c) 2018-2024 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,6 +28,7 @@ # # Just print the usage and exit with an error. +# @param 1 A message to print. usage() { if [ $# -eq 1 ]; then printf '%s\n' "$1" @@ -183,13 +184,14 @@ all_locales=0 while getopts "l" opt; do case "$opt" in - l) all_locales=1 ; shift ;; + l) all_locales=1 ;; ?) usage "Invalid option: $opt" ;; esac done +shift $(($OPTIND - 1)) -test "$#" -ge 2 || usage +test "$#" -ge 2 || usage "Must have at least two arguments" nlspath="$1" shift @@ -240,11 +242,15 @@ for file in $locales_dir/*.msg; do continue fi + printf 'Installing %s...' "$locale" + # Generate the proper location for the cat file. loc=$(gen_nlspath "$destdir/$nlspath" "$locale" "$main_exec") gencatfile "$loc" "$file" + printf 'done\n' + done # Now that we have done the non-symlinks, it's time to do the symlinks. Think @@ -275,6 +281,8 @@ for file in $locales_dir/*.msg; do # Make sure to skip non-symlinks; they are already done. if [ -L "$file" ]; then + printf 'Linking %s...' "$locale" + # This song and dance is because we want to generate relative symlinks. # They take less space, but also, they are more resilient to being # moved. @@ -294,6 +302,8 @@ for file in $locales_dir/*.msg; do # Finally, symlink to the install of the generated cat file that # corresponds to the correct msg file. ln -fs "$rel" "$loc" + + printf 'done\n' fi done diff --git a/contrib/bc/scripts/locale_uninstall.sh b/contrib/bc/scripts/locale_uninstall.sh index 3e79e083b803..1bf292b801e6 100755 --- a/contrib/bc/scripts/locale_uninstall.sh +++ b/contrib/bc/scripts/locale_uninstall.sh @@ -2,7 +2,7 @@ # # SPDX-License-Identifier: BSD-2-Clause # -# Copyright (c) 2018-2021 Gavin D. Howard and contributors. +# Copyright (c) 2018-2024 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: diff --git a/contrib/bc/scripts/os.c b/contrib/bc/scripts/os.c new file mode 100644 index 000000000000..212a61772ccf --- /dev/null +++ b/contrib/bc/scripts/os.c @@ -0,0 +1,59 @@ +/* + * ***************************************************************************** + * + * SPDX-License-Identifier: BSD-2-Clause + * + * Copyright (c) 2018-2024 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: + * + * * Redistributions of source code must retain the above copyright notice, this + * list of conditions and the following disclaimer. + * + * * Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + * + * ***************************************************************************** + * + * File for testing compilation on different platforms. + * + */ + +// This is used by configure.sh to test for OpenBSD. +#ifdef BC_TEST_OPENBSD +#ifdef __OpenBSD__ +#error On OpenBSD without _BSD_SOURCE +#endif // __OpenBSD__ +#endif // BC_TEST_OPENBSD + +// This is used by configure.sh to test for FreeBSD. +#ifdef BC_TEST_FREEBSD +#ifdef __FreeBSD__ +#error On FreeBSD with _POSIX_C_SOURCE +#endif // __FreeBSD__ +#endif // BC_TEST_FREEBSD + +// This is used by configure.sh to test for macOS. +#ifdef BC_TEST_APPLE +#ifdef __APPLE__ +#error On macOS without _DARWIN_C_SOURCE +#endif // __APPLE__ +#endif // BC_TEST_APPLE + +extern int test; + +int test; diff --git a/contrib/bc/scripts/safe-install.sh b/contrib/bc/scripts/safe-install.sh index 041088386682..5774a17e20de 100755 --- a/contrib/bc/scripts/safe-install.sh +++ b/contrib/bc/scripts/safe-install.sh @@ -41,7 +41,7 @@ set -e if test "$mkdirp" ; then umask 022 -case "$2" in +case "$dst" in */*) mkdir -p "${dst%/*}" ;; esac fi @@ -51,15 +51,15 @@ trap 'rm -f "$tmp"' EXIT INT QUIT TERM HUP umask 077 if test "$symlink" ; then -ln -s "$1" "$tmp" +ln -s "$src" "$tmp" else -cat < "$1" > "$tmp" +cat < "$src" > "$tmp" chmod "$mode" "$tmp" fi -mv -f "$tmp" "$2" -test -d "$2" && { -rm -f "$2/$tmp" +mv -f "$tmp" "$dst" +test -d "$dst" && { +rm -f "$dst/$tmp" printf "%s: %s is a directory\n" "$0" "$dst" 1>&2 exit 1 } diff --git a/contrib/bc/scripts/sqrt_frac_guess.bc b/contrib/bc/scripts/sqrt_frac_guess.bc new file mode 100644 index 000000000000..acbcb368d2de --- /dev/null +++ b/contrib/bc/scripts/sqrt_frac_guess.bc @@ -0,0 +1,126 @@ +#! /usr/bin/bc +# +# SPDX-License-Identifier: BSD-2-Clause +# +# Copyright (c) 2018-2024 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: +# +# * Redistributions of source code must retain the above copyright notice, this +# list of conditions and the following disclaimer. +# +# * Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE +# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +# POSSIBILITY OF SUCH DAMAGE. +# + +scale = 20 + +# Adjust this number to try ranges below different powers of 10. +shift = 4 + +# Adjust this to try extra digits. For example, a value of one means that one +# digit is checked (such as 0.09 through 0.01), a value of two means that two +# digits are checked (0.090 through 0.010), etc. +max = shift + 2 + +n = (9 >> shift) +inc = (1 >> max) +stop = (1 >> shift) + +# Uncomment this to test the high part of the ranges. +#n += (1 - (1 >> max + 5)) >> shift + +for (i = n; i >= stop; i -= inc) +{ + # This is the lower limit. + t1 = sqrt(1/(3*i)) + + # Start with the inverse. + t2 = (1/i) + + # And take half its length of course. + l = length(t2$)/2 + + temp = i + odd = 0 + + # We go by powers of 10 below, but there is a degenerate case: an exact + # power of 10, for which length() will return one digit more. So we check + # for that and fix it. + while (temp < 1) + { + temp <<= 1 + odd = !odd + } + + if (temp == 1) + { + odd = !odd + } + + print "i: ", i, "\n" + print "t2: ", t2, "\n" + #print "l: ", l, "\n" + print "odd: ", odd, "\n" + + if (odd) + { + # Limit between 6 and 7.5. + limit1 = 6.7 >> (l$ * 2 + 1) + + # Limit between 1.5 and 1.83-ish. + limit2 = 1.7 >> (l$ * 2 + 1) + print "limit1: ", limit1, "\n" + print "limit2: ", limit2, "\n" + + if (i >= limit1) + { + t2 = (t2 >> l$) + } + else if (i >= limit2) + { + t2 = (t2 >> l$) / 2 + } + else + { + t2 = (t2 >> l$) / 4 + } + } + else + { + # Limit between 2.4 and 3. + limit = 2.7 >> (l$ * 2) + print "limit: ", limit, "\n" + + if (i >= limit) + { + t2 = (t2 >> l$) * 2 + } + else + { + t2 = (t2 >> l$) + } + } + #t2 = 1 + t3 = sqrt(5/(3*i)) + good = (t1 < t2 && t2 < t3) + + print t1, " < ", t2, " < ", t3, ": ", good, "\n\n" + if (!good) sqrt(-1) +} + +halt diff --git a/contrib/bc/scripts/sqrt_int_guess.bc b/contrib/bc/scripts/sqrt_int_guess.bc new file mode 100644 index 000000000000..925b7af7e103 --- /dev/null +++ b/contrib/bc/scripts/sqrt_int_guess.bc @@ -0,0 +1,94 @@ +#! /usr/bin/bc -l +# +# SPDX-License-Identifier: BSD-2-Clause +# +# Copyright (c) 2018-2024 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: +# +# * Redistributions of source code must retain the above copyright notice, this +# list of conditions and the following disclaimer. +# +# * Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE +# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +# POSSIBILITY OF SUCH DAMAGE. +# + +# Adjust this number to try ranges above different powers of 10. +max = 0 + +n = (1 << max) + +# Uncomment this to test the high part of the ranges. +#n += (1 - (1 >> 10)) + +n + +# Loop from the start number to the next power of 10. +for (i = n; i < (n$ << 1); i += 1) +{ + # This is the lower limit. + t1 = sqrt(1/(3*i)) + + l = length(i$)/2 + + print "i: ", i, "\n" + #print "l: ", l, "\n" + + if (l$ != l) + { + # Limit between 2.4 and 3. + limit = 2.7 << (l$ * 2) + #print "limit: ", limit, "\n" + + if (i >= limit) + { + t2 = 1/(i >> (l$)) * 2 + } + else + { + t2 = 1/(i >> (l$)) + } + } + else + { + # Limit between 3.8-ish and 4.8 + limit = 4.3 << (l$ * 2 - 1) + #print "limit: ", limit, "\n" + + if (i >= limit) + { + t2 = 1/(i >> (l$ - 1)) * 8 + } + else + { + t2 = 1/(i >> (l$ - 1)) * 4 + } + } + + # This is the upper limit. + t3 = sqrt(5/(3*i)) + + # This is true when the guess is in between the limits. + good = (t1 < t2 && t2 < t3) + + print t1, " < ", t2, " < ", t3, ": ", good, "\n" + + # Error if we have a problem. + if (!good) sqrt(-1) +} + +halt diff --git a/contrib/bc/scripts/sqrt_random.bc b/contrib/bc/scripts/sqrt_random.bc new file mode 100644 index 000000000000..1f58c2e30c5d --- /dev/null +++ b/contrib/bc/scripts/sqrt_random.bc @@ -0,0 +1,129 @@ +#! /usr/bin/bc +# +# SPDX-License-Identifier: BSD-2-Clause +# +# Copyright (c) 2018-2024 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: +# +# * Redistributions of source code must retain the above copyright notice, this +# list of conditions and the following disclaimer. +# +# * Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE +# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +# POSSIBILITY OF SUCH DAMAGE. +# + +scale = 0 + +bits = rand() + +# This extracts a bit and takes it out of the original value. +# +# Here, I am getting a bit to say whether we should have a value that is less +# than 1. +bits = divmod(bits, 2, negpow[]) + +# Get a bit that will say whether the value should be an exact square. +bits = divmod(bits, 2, square[]) + +# See below. This is to help bias toward small numbers. +pow = 4 + +# I want to bias toward small numbers, so let's give a 50 percent chance to +# values below 16 or so. +bits = divmod(bits, 2, small[]) + +# Let's keep raising the power limit by 2^4 when the bit is zero. +while (!small[0]) +{ + pow += 4 + bits = divmod(bits, 2, small[]) +} + +limit = 2^pow + +# Okay, this is the starting number. +num = irand(limit) + 1 + +# Figure out if we should have (more) fractional digits. +bits = divmod(bits, 2, extra_digits[]) + +if (square[0]) +{ + # Okay, I lied. If we need a perfect square, square now. + num *= num + + # If we need extra digits, we need to multiply by an even power of 10. + if (extra_digits[0]) + { + extra = (irand(8) + 1) * 2 + } + else + { + extra = 0 + } + + # If we need a number less than 1, just take the inverse, which will still + # be a perfect square. + if (negpow[0]) + { + scale = length(num) + 5 + num = 1/num + scale = 0 + + num >>= extra + } + else + { + num <<= extra + } +} +else +{ + # Get this for later. + l = length(num) + + # If we need extra digits. + if (extra_digits[0]) + { + # Add up to 32 decimal places. + num += frand(irand(32) + 1) + } + + # If we need a value less than 1... + if (negpow[0]) + { + # Move right until the number is + num >>= l + } +} + +bits = divmod(bits, 2, zero_scale[]) + +# Do we want a zero scale? +if (zero_scale[0]) +{ + print "scale = 0\n" +} +else +{ + print "scale = 20\n" +} + +print "sqrt(", num, ")\n" + +halt diff --git a/contrib/bc/scripts/sqrt_random.sh b/contrib/bc/scripts/sqrt_random.sh new file mode 100755 index 000000000000..e107ef532f6e --- /dev/null +++ b/contrib/bc/scripts/sqrt_random.sh @@ -0,0 +1,77 @@ +#! /bin/sh +# +# SPDX-License-Identifier: BSD-2-Clause +# +# Copyright (c) 2018-2024 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: +# +# * Redistributions of source code must retain the above copyright notice, this +# list of conditions and the following disclaimer. +# +# * Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE +# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +# POSSIBILITY OF SUCH DAMAGE. +# + +scriptdir=$(dirname "$0") + +gnu=/usr/bin/bc +gdh=/usr/local/bin/bc + +if [ "$#" -lt 1 ]; then + printf 'err: must provide path to new bc\n' + exit 1 +fi + +new="$1" +shift + +unset BC_LINE_LENGTH && unset BC_ENV_ARGS + +gdh_fail_file="sqrt_fails.bc" +new_fail_file="new_sqrt_fails.bc" + +rm -rf "$gdh_fail_file" +rm -rf "$new_fail_file" + +while [ true ]; do + + tst=$("$gdh" -l "$scriptdir/sqrt_random.bc") + err=$? + + if [ "$err" -ne 0 ]; then + printf 'err: failed to create test\n' + exit 2 + fi + + good=$(printf '%s\n' "$tst" | "$gnu" -l) + + gdh_out=$(printf '%s\n' "$tst" | "$gdh" -l) + new_out=$(printf '%s\n' "$tst" | "$new" -l) + + gdh_good=$(printf '%s == %s\n' "$good" "$gdh_out" | "$gnu") + new_good=$(printf '%s == %s\n' "$good" "$new_out" | "$gnu") + + if [ "$gdh_good" -eq 0 ]; then + printf '%s\n' "$tst" >> "$gdh_fail_file" + fi + + if [ "$new_good" -eq 0 ]; then + printf '%s\n' "$tst" >> "$new_fail_file" + fi + +done diff --git a/contrib/bc/src/args.c b/contrib/bc/src/args.c index 64fd02c1d7b8..6eba802d34ac 100644 --- a/contrib/bc/src/args.c +++ b/contrib/bc/src/args.c @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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: @@ -48,6 +48,7 @@ #include <args.h> #include <opt.h> #include <num.h> +#include <vm.h> /** * Adds @a str to the list of expressions to execute later. @@ -57,9 +58,14 @@ static void bc_args_exprs(const char* str) { BC_SIG_ASSERT_LOCKED; - if (vm.exprs.v == NULL) bc_vec_init(&vm.exprs, sizeof(uchar), BC_DTOR_NONE); - bc_vec_concat(&vm.exprs, str); - bc_vec_concat(&vm.exprs, "\n"); + + if (vm->exprs.v == NULL) + { + bc_vec_init(&vm->exprs, sizeof(uchar), BC_DTOR_NONE); + } + + bc_vec_concat(&vm->exprs, str); + bc_vec_concat(&vm->exprs, "\n"); } /** @@ -74,7 +80,7 @@ bc_args_file(const char* file) BC_SIG_ASSERT_LOCKED; - vm.file = file; + vm->file = file; buf = bc_read_file(file); @@ -131,7 +137,7 @@ bc_args_redefine(const char* keyword) { if (BC_LEX_KW_POSIX(kw)) break; - vm.redefined_kws[i] = true; + vm->redefined_kws[i] = true; return; } @@ -143,15 +149,15 @@ bc_args_redefine(const char* keyword) #endif // BC_ENABLED void -bc_args(int argc, char* argv[], bool exit_exprs, BcBigDig scale) +bc_args(int argc, const char* argv[], bool exit_exprs, BcBigDig* scale, + BcBigDig* ibase, BcBigDig* obase) { int c; size_t i; bool do_exit = false, version = false; BcOpt opts; - BcBigDig newscale = scale, ibase = BC_BASE, obase = BC_BASE; #if BC_ENABLE_EXTRA_MATH - char* seed = NULL; + const char* seed = NULL; #endif // BC_ENABLE_EXTRA_MATH BC_SIG_ASSERT_LOCKED; @@ -164,17 +170,29 @@ bc_args(int argc, char* argv[], bool exit_exprs, BcBigDig scale) { switch (c) { + case 'c': + { + vm->flags |= BC_FLAG_DIGIT_CLAMP; + break; + } + + case 'C': + { + vm->flags &= ~BC_FLAG_DIGIT_CLAMP; + break; + } + case 'e': { // Barf if not allowed. - if (vm.no_exprs) + if (vm->no_exprs) { bc_verr(BC_ERR_FATAL_OPTION, "-e (--expression)"); } // Add the expressions and set exit. bc_args_exprs(opts.optarg); - vm.exit_exprs = (exit_exprs || vm.exit_exprs); + vm->exit_exprs = (exit_exprs || vm->exit_exprs); break; } @@ -182,18 +200,18 @@ bc_args(int argc, char* argv[], bool exit_exprs, BcBigDig scale) case 'f': { // Figure out if exiting on expressions is disabled. - if (!strcmp(opts.optarg, "-")) vm.no_exprs = true; + if (!strcmp(opts.optarg, "-")) vm->no_exprs = true; else { // Barf if not allowed. - if (vm.no_exprs) + if (vm->no_exprs) { bc_verr(BC_ERR_FATAL_OPTION, "-f (--file)"); } // Add the expressions and set exit. bc_args_file(opts.optarg); - vm.exit_exprs = (exit_exprs || vm.exit_exprs); + vm->exit_exprs = (exit_exprs || vm->exit_exprs); } break; @@ -201,56 +219,56 @@ bc_args(int argc, char* argv[], bool exit_exprs, BcBigDig scale) case 'h': { - bc_vm_info(vm.help); + bc_vm_info(vm->help); do_exit = true; break; } case 'i': { - vm.flags |= BC_FLAG_I; + vm->flags |= BC_FLAG_I; break; } case 'I': { - ibase = bc_args_builtin(opts.optarg); + *ibase = bc_args_builtin(opts.optarg); break; } case 'z': { - vm.flags |= BC_FLAG_Z; + vm->flags |= BC_FLAG_Z; break; } case 'L': { - vm.line_len = 0; + vm->line_len = 0; break; } case 'O': { - obase = bc_args_builtin(opts.optarg); + *obase = bc_args_builtin(opts.optarg); break; } case 'P': { - vm.flags &= ~(BC_FLAG_P); + vm->flags &= ~(BC_FLAG_P); break; } case 'R': { - vm.flags &= ~(BC_FLAG_R); + vm->flags &= ~(BC_FLAG_R); break; } case 'S': { - newscale = bc_args_builtin(opts.optarg); + *scale = bc_args_builtin(opts.optarg); break; } @@ -272,21 +290,21 @@ bc_args(int argc, char* argv[], bool exit_exprs, BcBigDig scale) case 'g': { assert(BC_IS_BC); - vm.flags |= BC_FLAG_G; + vm->flags |= BC_FLAG_G; break; } case 'l': { assert(BC_IS_BC); - vm.flags |= BC_FLAG_L; + vm->flags |= BC_FLAG_L; break; } case 'q': { assert(BC_IS_BC); - vm.flags &= ~(BC_FLAG_Q); + vm->flags &= ~(BC_FLAG_Q); break; } @@ -299,14 +317,14 @@ bc_args(int argc, char* argv[], bool exit_exprs, BcBigDig scale) case 's': { assert(BC_IS_BC); - vm.flags |= BC_FLAG_S; + vm->flags |= BC_FLAG_S; break; } case 'w': { assert(BC_IS_BC); - vm.flags |= BC_FLAG_W; + vm->flags |= BC_FLAG_W; break; } #endif // BC_ENABLED @@ -322,12 +340,12 @@ bc_args(int argc, char* argv[], bool exit_exprs, BcBigDig scale) case 'x': { assert(BC_IS_DC); - vm.flags |= DC_FLAG_X; + vm->flags |= DC_FLAG_X; break; } #endif // DC_ENABLED -#ifndef NDEBUG +#if BC_DEBUG // We shouldn't get here because bc_opt_error()/bc_error() should // longjmp() out. case '?': @@ -335,33 +353,35 @@ bc_args(int argc, char* argv[], bool exit_exprs, BcBigDig scale) default: { BC_UNREACHABLE +#if !BC_CLANG abort(); +#endif // !BC_CLANG } -#endif // NDEBUG +#endif // BC_DEBUG } } if (version) bc_vm_info(NULL); if (do_exit) { - vm.status = (sig_atomic_t) BC_STATUS_QUIT; + vm->status = (sig_atomic_t) BC_STATUS_QUIT; BC_JMP; } // We do not print the banner if expressions are used or dc is used. - if (!BC_IS_BC || vm.exprs.len > 1) vm.flags &= ~(BC_FLAG_Q); + if (BC_ARGS_SHOULD_BE_QUIET) vm->flags &= ~(BC_FLAG_Q); // We need to make sure the files list is initialized. We don't want to // initialize it if there are no files because it's just a waste of memory. - if (opts.optind < (size_t) argc && vm.files.v == NULL) + if (opts.optind < (size_t) argc && vm->files.v == NULL) { - bc_vec_init(&vm.files, sizeof(char*), BC_DTOR_NONE); + bc_vec_init(&vm->files, sizeof(char*), BC_DTOR_NONE); } // Add all the files to the vector. for (i = opts.optind; i < (size_t) argc; ++i) { - bc_vec_push(&vm.files, argv + i); + bc_vec_push(&vm->files, argv + i); } #if BC_ENABLE_EXTRA_MATH @@ -375,31 +395,11 @@ bc_args(int argc, char* argv[], bool exit_exprs, BcBigDig scale) bc_num_parse(&n, seed, BC_BASE); - bc_program_assignSeed(&vm.prog, &n); + bc_program_assignSeed(&vm->prog, &n); BC_SIG_LOCK; bc_num_free(&n); } #endif // BC_ENABLE_EXTRA_MATH - - BC_SIG_UNLOCK; - - if (newscale != scale) - { - bc_program_assignBuiltin(&vm.prog, true, false, newscale); - } - - if (obase != BC_BASE) - { - bc_program_assignBuiltin(&vm.prog, false, true, obase); - } - - // This is last to avoid it affecting the value of the others. - if (ibase != BC_BASE) - { - bc_program_assignBuiltin(&vm.prog, false, false, ibase); - } - - BC_SIG_LOCK; } diff --git a/contrib/bc/src/bc.c b/contrib/bc/src/bc.c index 77fa06512dda..572e42b1a16d 100644 --- a/contrib/bc/src/bc.c +++ b/contrib/bc/src/bc.c @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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: @@ -45,20 +45,21 @@ * @param argc The number of arguments. * @param argv The arguments. */ -void -bc_main(int argc, char* argv[]) +BcStatus +bc_main(int argc, const char* argv[]) { // All of these just set bc-specific items in BcVm. - vm.read_ret = BC_INST_RET; - vm.help = bc_help; - vm.sigmsg = bc_sig_msg; - vm.siglen = bc_sig_msg_len; + vm->read_ret = BC_INST_RET; + vm->help = bc_help; + vm->sigmsg = bc_sig_msg; + vm->siglen = bc_sig_msg_len; - vm.next = bc_lex_token; - vm.parse = bc_parse_parse; - vm.expr = bc_parse_expr; + vm->next = bc_lex_token; + vm->parse = bc_parse_parse; + vm->expr = bc_parse_expr; - bc_vm_boot(argc, argv); + return bc_vm_boot(argc, argv); } + #endif // BC_ENABLED diff --git a/contrib/bc/src/bc_fuzzer.c b/contrib/bc/src/bc_fuzzer.c new file mode 100644 index 000000000000..7d7b3292b727 --- /dev/null +++ b/contrib/bc/src/bc_fuzzer.c @@ -0,0 +1,112 @@ +/* + * ***************************************************************************** + * + * SPDX-License-Identifier: BSD-2-Clause + * + * Copyright (c) 2018-2024 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: + * + * * Redistributions of source code must retain the above copyright notice, this + * list of conditions and the following disclaimer. + * + * * Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + * + * ***************************************************************************** + * + * The entry point for libFuzzer when fuzzing bc. + * + */ + +#include <setjmp.h> +#include <string.h> + +#include <version.h> +#include <status.h> +#include <ossfuzz.h> +#include <vm.h> +#include <bc.h> +#include <dc.h> + +uint8_t* bc_fuzzer_data; + +/// A boolean about whether we should use -c (false) or -C (true). +static bool bc_C; + +int +LLVMFuzzerInitialize(int* argc, char*** argv) +{ + BC_UNUSED(argc); + + if (argv == NULL || *argv == NULL) + { + bc_C = false; + } + else + { + char* name; + + // Get the basename + name = strrchr((*argv)[0], BC_FILE_SEP); + name = name == NULL ? (*argv)[0] : name + 1; + + // Figure out which to use. + bc_C = (strcmp(name, "bc_fuzzer_C") == 0); + } + + return 0; +} + +int +LLVMFuzzerTestOneInput(const uint8_t* Data, size_t Size) +{ + BcStatus s; + + // I've already tested empty input, so just ignore. + if (Size == 0 || Data[0] == '\0') return 0; + + // Clear the global. This is to ensure a clean start. + memset(vm, 0, sizeof(BcVm)); + + // Make sure to set the name. + vm->name = "bc"; + + BC_SIG_LOCK; + + // We *must* do this here. Otherwise, other code could not jump out all of + // the way. + bc_vec_init(&vm->jmp_bufs, sizeof(sigjmp_buf), BC_DTOR_NONE); + + BC_SETJMP_LOCKED(vm, exit); + + // Create a string with the data. + bc_fuzzer_data = bc_vm_malloc(Size + 1); + memcpy(bc_fuzzer_data, Data, Size); + bc_fuzzer_data[Size] = '\0'; + + s = bc_main((int) (bc_fuzzer_args_len - 1), + bc_C ? bc_fuzzer_args_C : bc_fuzzer_args_c); + +exit: + + BC_SIG_MAYLOCK; + + free(bc_fuzzer_data); + + return s == BC_STATUS_SUCCESS || s == BC_STATUS_QUIT ? 0 : -1; +} diff --git a/contrib/bc/src/bc_lex.c b/contrib/bc/src/bc_lex.c index 1097b92647a6..f83eaf731622 100644 --- a/contrib/bc/src/bc_lex.c +++ b/contrib/bc/src/bc_lex.c @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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: @@ -66,7 +66,7 @@ bc_lex_identifier(BcLex* l) // (it is not allowed for builtin libraries), break out of the loop // and use it as a name. This depends on the argument parser to // ensure that only non-POSIX keywords get redefined. - if (!vm.no_redefine && vm.redefined_kws[i]) break; + if (!vm->no_redefine && vm->redefined_kws[i]) break; l->t = BC_LEX_KW_AUTO + (BcLexType) i; @@ -115,7 +115,9 @@ bc_lex_string(BcLex* l) buf = l->buf; got_more = false; - assert(!vm.is_stdin || buf == vm.buffer.v); +#if !BC_ENABLE_OSSFUZZ + assert(vm->mode != BC_MODE_STDIN || buf == vm->buffer.v); +#endif // !BC_ENABLE_OSSFUZZ // Fortunately for us, bc doesn't escape quotes. Instead, the equivalent // is '\q', which makes this loop simpler. @@ -124,7 +126,7 @@ bc_lex_string(BcLex* l) nlines += (c == '\n'); } - if (BC_ERR(c == '\0') && !vm.eof && (l->is_stdin || l->is_exprs)) + if (BC_ERR(c == '\0') && !vm->eof && l->mode != BC_MODE_FILE) { got_more = bc_lex_readLine(l); } diff --git a/contrib/bc/src/bc_parse.c b/contrib/bc/src/bc_parse.c index 33f98c896398..cf4398709e58 100644 --- a/contrib/bc/src/bc_parse.c +++ b/contrib/bc/src/bc_parse.c @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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,11 +71,12 @@ bc_parse_expr_status(BcParse* p, uint8_t flags, BcParseNext next); * Returns true if an instruction could only have come from a "leaf" expression. * For more on what leaf expressions are, read the comment for BC_PARSE_LEAF(). * @param t The instruction to test. + * @return True if the instruction is a from a leaf expression. */ static bool bc_parse_inst_isLeaf(BcInst t) { - return (t >= BC_INST_NUM && t <= BC_INST_MAXSCALE) || + return (t >= BC_INST_NUM && t <= BC_INST_LEADING_ZERO) || #if BC_ENABLE_EXTRA_MATH t == BC_INST_TRUNC || #endif // BC_ENABLE_EXTRA_MATH @@ -206,7 +207,7 @@ bc_parse_createCondLabel(BcParse* p, size_t idx) bc_vec_push(&p->conds, &idx); } -/* +/** * Creates an exit label to be filled in later by bc_parse_setLabel(). Also, why * create a label to be filled in later? Because exit labels are meant to be * targeted by code that comes *before* the label. Since we have to parse that @@ -254,25 +255,30 @@ bc_parse_operator(BcParse* p, BcLexType type, size_t start, size_t* nexprs) uchar l, r = BC_PARSE_OP_PREC(type); uchar left = BC_PARSE_OP_LEFT(type); - // While we haven't hit the stop point yet. + // While we haven't hit the stop point yet... while (p->ops.len > start) { // Get the top operator. t = BC_PARSE_TOP_OP(p); - // If it's a right paren, we have reached the end of whatever expression - // this is no matter what. + // If it's a left paren, we have reached the end of whatever expression + // this is no matter what. We also don't pop the left paren because it + // will need to stay for the rest of the subexpression. if (t == BC_LEX_LPAREN) break; // Break for precedence. Precedence operates differently on left and // right associativity, by the way. A left associative operator that // matches the current precedence should take priority, but a right // associative operator should not. + // + // Also, a lower precedence value means a higher precedence. l = BC_PARSE_OP_PREC(t); if (l >= r && (l != r || !left)) break; // Do the housekeeping. In particular, make sure to note that one - // expression was consumed. (Two were, but another was added.) + // expression was consumed (well, two were, but another was added) if + // the operator was not a prefix operator. (Postfix operators are not + // handled by this function at all.) bc_parse_push(p, BC_PARSE_TOKEN_INST(t)); bc_vec_pop(&p->ops); *nexprs -= !BC_PARSE_OP_PREFIX(t); @@ -389,7 +395,11 @@ bc_parse_call(BcParse* p, const char* name, uint8_t flags) /** * Parses a name/identifier-based expression. It could be a variable, an array * element, an array itself (for function arguments), a function call, etc. - * + * @param p The parser. + * @param type A pointer to return the resulting instruction. + * @param can_assign A pointer to return true if the name can be assigned to, + * false otherwise. + * @param flags Flags restricting what kind of expression the name can be. */ static void bc_parse_name(BcParse* p, BcInst* type, bool* can_assign, uint8_t flags) @@ -401,7 +411,7 @@ bc_parse_name(BcParse* p, BcInst* type, bool* can_assign, uint8_t flags) // We want a copy of the name since the lexer might overwrite its copy. name = bc_vm_strdup(p->l.str.v); - BC_SETJMP_LOCKED(err); + BC_SETJMP_LOCKED(vm, err); // We need the next token to see if it's just a variable or something more. bc_lex_next(&p->l); @@ -474,7 +484,7 @@ bc_parse_name(BcParse* p, BcInst* type, bool* can_assign, uint8_t flags) err: // Need to make sure to unallocate the name. free(name); - BC_LONGJMP_CONT; + BC_LONGJMP_CONT(vm); BC_SIG_MAYLOCK; } @@ -522,7 +532,13 @@ bc_parse_builtin(BcParse* p, BcLexType type, uint8_t flags, BcInst* prev) flags |= BC_PARSE_NEEDVAL; // Since length can take arrays, we need to specially add that flag. - if (type == BC_LEX_KW_LENGTH) flags |= BC_PARSE_ARRAY; + if (type == BC_LEX_KW_LENGTH || type == BC_LEX_KW_ASCIIFY) + { + flags |= BC_PARSE_ARRAY; + } + + // Otherwise, we need to clear it because it could be set. + else flags &= ~(BC_PARSE_ARRAY); bc_parse_expr_status(p, flags, bc_parse_next_rel); @@ -539,6 +555,10 @@ bc_parse_builtin(BcParse* p, BcLexType type, uint8_t flags, BcInst* prev) /** * Parses a builtin function that takes 3 arguments. This includes modexp() and * divmod(). + * @param p The parser. + * @param type The lex token. + * @param flags The expression parsing flags for parsing the argument. + * @param prev An out parameter; the previous instruction pointer. */ static void bc_parse_builtin3(BcParse* p, BcLexType type, uint8_t flags, BcInst* prev) @@ -727,7 +747,7 @@ bc_parse_incdec(BcParse* p, BcInst* prev, bool* can_assign, size_t* nexs, if (type == BC_LEX_NAME) { // Parse the name. - uint8_t flags2 = flags & ~BC_PARSE_ARRAY; + uint8_t flags2 = flags & ~(BC_PARSE_ARRAY); bc_parse_name(p, prev, can_assign, flags2 | BC_PARSE_NOCALL); } // Is the next token a global? @@ -1090,9 +1110,9 @@ bc_parse_endif(BcParse* p) { // We set this to restore it later. We don't want the parser thinking // that we are on stdin for this one because it will want more. - bool is_stdin = vm.is_stdin; + BcMode mode = vm->mode; - vm.is_stdin = false; + vm->mode = BC_MODE_FILE; // End all of the if statements and loops. while (p->flags.len > 1 || BC_PARSE_IF_END(p)) @@ -1101,10 +1121,10 @@ bc_parse_endif(BcParse* p) if (p->flags.len > 1) bc_parse_endBody(p, false); } - vm.is_stdin = is_stdin; + vm->mode = (uchar) mode; } // If we reach here, a block was not properly closed, and we should error. - else bc_parse_err(&vm.prs, BC_ERR_PARSE_BLOCK); + else bc_parse_err(&vm->prs, BC_ERR_PARSE_BLOCK); } /** @@ -1692,6 +1712,8 @@ bc_parse_stmt(BcParse* p) #endif // BC_ENABLE_EXTRA_MATH case BC_LEX_KW_SQRT: case BC_LEX_KW_ABS: + case BC_LEX_KW_IS_NUMBER: + case BC_LEX_KW_IS_STRING: #if BC_ENABLE_EXTRA_MATH case BC_LEX_KW_IRAND: #endif // BC_ENABLE_EXTRA_MATH @@ -1803,7 +1825,7 @@ bc_parse_stmt(BcParse* p) { // Quit is a compile-time command. We don't exit directly, so the vm // can clean up. - vm.status = BC_STATUS_QUIT; + vm->status = BC_STATUS_QUIT; BC_JMP; break; } @@ -1820,7 +1842,78 @@ bc_parse_stmt(BcParse* p) break; } - default: + case BC_LEX_EOF: + case BC_LEX_INVALID: + case BC_LEX_NEG: +#if BC_ENABLE_EXTRA_MATH + case BC_LEX_OP_TRUNC: +#endif // BC_ENABLE_EXTRA_MATH + case BC_LEX_OP_POWER: + case BC_LEX_OP_MULTIPLY: + case BC_LEX_OP_DIVIDE: + case BC_LEX_OP_MODULUS: + case BC_LEX_OP_PLUS: +#if BC_ENABLE_EXTRA_MATH + case BC_LEX_OP_PLACES: + case BC_LEX_OP_LSHIFT: + case BC_LEX_OP_RSHIFT: +#endif // BC_ENABLE_EXTRA_MATH + case BC_LEX_OP_REL_EQ: + case BC_LEX_OP_REL_LE: + case BC_LEX_OP_REL_GE: + case BC_LEX_OP_REL_NE: + case BC_LEX_OP_REL_LT: + case BC_LEX_OP_REL_GT: + case BC_LEX_OP_BOOL_OR: + case BC_LEX_OP_BOOL_AND: + case BC_LEX_OP_ASSIGN_POWER: + case BC_LEX_OP_ASSIGN_MULTIPLY: + case BC_LEX_OP_ASSIGN_DIVIDE: + case BC_LEX_OP_ASSIGN_MODULUS: + case BC_LEX_OP_ASSIGN_PLUS: + case BC_LEX_OP_ASSIGN_MINUS: +#if BC_ENABLE_EXTRA_MATH + case BC_LEX_OP_ASSIGN_PLACES: + case BC_LEX_OP_ASSIGN_LSHIFT: + case BC_LEX_OP_ASSIGN_RSHIFT: +#endif // BC_ENABLE_EXTRA_MATH + case BC_LEX_OP_ASSIGN: + case BC_LEX_NLINE: + case BC_LEX_WHITESPACE: + case BC_LEX_RPAREN: + case BC_LEX_LBRACKET: + case BC_LEX_COMMA: + case BC_LEX_RBRACKET: + case BC_LEX_LBRACE: + case BC_LEX_KW_AUTO: + case BC_LEX_KW_DEFINE: +#if DC_ENABLED + case BC_LEX_EXTENDED_REGISTERS: + case BC_LEX_EQ_NO_REG: + case BC_LEX_COLON: + case BC_LEX_EXECUTE: + case BC_LEX_PRINT_STACK: + case BC_LEX_CLEAR_STACK: + case BC_LEX_REG_STACK_LEVEL: + case BC_LEX_STACK_LEVEL: + case BC_LEX_DUPLICATE: + case BC_LEX_SWAP: + case BC_LEX_POP: + case BC_LEX_STORE_IBASE: + case BC_LEX_STORE_OBASE: + case BC_LEX_STORE_SCALE: +#if BC_ENABLE_EXTRA_MATH + case BC_LEX_STORE_SEED: +#endif // BC_ENABLE_EXTRA_MATH + case BC_LEX_LOAD: + case BC_LEX_LOAD_POP: + case BC_LEX_STORE_PUSH: + case BC_LEX_PRINT_POP: + case BC_LEX_NQUIT: + case BC_LEX_EXEC_STACK_LENGTH: + case BC_LEX_SCALE_FACTOR: + case BC_LEX_ARRAY_LENGTH: +#endif // DC_ENABLED { bc_parse_err(p, BC_ERR_PARSE_TOKEN); } @@ -1836,7 +1929,7 @@ bc_parse_stmt(BcParse* p) } // Make sure semicolons are eaten. - while (p->l.t == BC_LEX_SCOLON) + while (p->l.t == BC_LEX_SCOLON || p->l.t == BC_LEX_NLINE) { bc_lex_next(&p->l); } @@ -1855,7 +1948,7 @@ bc_parse_parse(BcParse* p) { assert(p); - BC_SETJMP_LOCKED(exit); + BC_SETJMP_LOCKED(vm, exit); // We should not let an EOF get here unless some partial parse was not // completed, in which case, it's the user's fault. @@ -1881,12 +1974,12 @@ bc_parse_parse(BcParse* p) exit: // We need to reset on error. - if (BC_ERR(((vm.status && vm.status != BC_STATUS_QUIT) || vm.sig))) + if (BC_ERR(((vm->status && vm->status != BC_STATUS_QUIT) || vm->sig != 0))) { bc_parse_reset(p); } - BC_LONGJMP_CONT; + BC_LONGJMP_CONT(vm); BC_SIG_MAYLOCK; } @@ -1909,7 +2002,8 @@ bc_parse_expr_err(BcParse* p, uint8_t flags, BcParseNext next) BcLexType top, t; size_t nexprs, ops_bgn; uint32_t i, nparens, nrelops; - bool pfirst, rprn, done, get_token, assign, bin_last, incdec, can_assign; + bool pfirst, rprn, array_last, done, get_token, assign; + bool bin_last, incdec, can_assign; // One of these *must* be true. assert(!(flags & BC_PARSE_PRINT) || !(flags & BC_PARSE_NEEDVAL)); @@ -1926,6 +2020,7 @@ bc_parse_expr_err(BcParse* p, uint8_t flags, BcParseNext next) // - nrelops is the number of relational operators that appear in the expr. // - nexprs is the number of unused expressions. // - rprn is a right paren encountered last. + // - array_last is an array item encountered last. // - done means the expression has been fully parsed. // - get_token is true when a token is needed at the end of an iteration. // - assign is true when an assignment statement was parsed last. @@ -1937,7 +2032,7 @@ bc_parse_expr_err(BcParse* p, uint8_t flags, BcParseNext next) nparens = nrelops = 0; nexprs = 0; ops_bgn = p->ops.len; - rprn = done = get_token = assign = incdec = can_assign = false; + rprn = array_last = done = get_token = assign = incdec = can_assign = false; bin_last = true; // We want to eat newlines if newlines are not a valid ending token. @@ -1953,6 +2048,14 @@ bc_parse_expr_err(BcParse* p, uint8_t flags, BcParseNext next) // This is the Shunting-Yard algorithm loop. for (; !done && BC_PARSE_EXPR(t); t = p->l.t) { + // Make sure an array expression is not mixed with any others. However, + // a right parenthesis may end the expression, so we will need to take + // care of that right there. + if (BC_ERR(array_last && t != BC_LEX_RPAREN)) + { + bc_parse_err(p, BC_ERR_PARSE_EXPR); + } + switch (t) { case BC_LEX_OP_INC: @@ -2128,6 +2231,14 @@ bc_parse_expr_err(BcParse* p, uint8_t flags, BcParseNext next) break; } + // Now that we know the right paren has not ended the + // expression, make sure an array expression is not mixed with + // any others. + if (BC_ERR(array_last)) + { + bc_parse_err(p, BC_ERR_PARSE_EXPR); + } + nparens -= 1; rprn = true; get_token = bin_last = incdec = false; @@ -2170,6 +2281,7 @@ bc_parse_expr_err(BcParse* p, uint8_t flags, BcParseNext next) bc_parse_name(p, &prev, &can_assign, flags & ~BC_PARSE_NOCALL); rprn = (prev == BC_INST_CALL); + array_last = (prev == BC_INST_ARRAY); nexprs += 1; flags &= ~(BC_PARSE_ARRAY); @@ -2223,6 +2335,8 @@ bc_parse_expr_err(BcParse* p, uint8_t flags, BcParseNext next) case BC_LEX_KW_LENGTH: case BC_LEX_KW_SQRT: case BC_LEX_KW_ABS: + case BC_LEX_KW_IS_NUMBER: + case BC_LEX_KW_IS_STRING: #if BC_ENABLE_EXTRA_MATH case BC_LEX_KW_IRAND: #endif // BC_ENABLE_EXTRA_MATH @@ -2316,13 +2430,64 @@ bc_parse_expr_err(BcParse* p, uint8_t flags, BcParseNext next) break; } - default: + case BC_LEX_EOF: + case BC_LEX_INVALID: + case BC_LEX_NEG: + case BC_LEX_NLINE: + case BC_LEX_WHITESPACE: + case BC_LEX_LBRACKET: + case BC_LEX_COMMA: + case BC_LEX_RBRACKET: + case BC_LEX_LBRACE: + case BC_LEX_SCOLON: + case BC_LEX_RBRACE: + case BC_LEX_KW_AUTO: + case BC_LEX_KW_BREAK: + case BC_LEX_KW_CONTINUE: + case BC_LEX_KW_DEFINE: + case BC_LEX_KW_FOR: + case BC_LEX_KW_IF: + case BC_LEX_KW_LIMITS: + case BC_LEX_KW_RETURN: + case BC_LEX_KW_WHILE: + case BC_LEX_KW_HALT: + case BC_LEX_KW_PRINT: + case BC_LEX_KW_QUIT: + case BC_LEX_KW_STREAM: + case BC_LEX_KW_ELSE: +#if DC_ENABLED + case BC_LEX_EXTENDED_REGISTERS: + case BC_LEX_EQ_NO_REG: + case BC_LEX_COLON: + case BC_LEX_EXECUTE: + case BC_LEX_PRINT_STACK: + case BC_LEX_CLEAR_STACK: + case BC_LEX_REG_STACK_LEVEL: + case BC_LEX_STACK_LEVEL: + case BC_LEX_DUPLICATE: + case BC_LEX_SWAP: + case BC_LEX_POP: + case BC_LEX_STORE_IBASE: + case BC_LEX_STORE_OBASE: + case BC_LEX_STORE_SCALE: +#if BC_ENABLE_EXTRA_MATH + case BC_LEX_STORE_SEED: +#endif // BC_ENABLE_EXTRA_MATH + case BC_LEX_LOAD: + case BC_LEX_LOAD_POP: + case BC_LEX_STORE_PUSH: + case BC_LEX_PRINT_POP: + case BC_LEX_NQUIT: + case BC_LEX_EXEC_STACK_LENGTH: + case BC_LEX_SCALE_FACTOR: + case BC_LEX_ARRAY_LENGTH: +#endif // DC_ENABLED { -#ifndef NDEBUG +#if BC_DEBUG // We should never get here, even in debug builds. bc_parse_err(p, BC_ERR_PARSE_TOKEN); break; -#endif // NDEBUG +#endif // BC_DEBUG } } diff --git a/contrib/bc/src/data.c b/contrib/bc/src/data.c index 4009dcc1f0d1..bb1a6796f752 100644 --- a/contrib/bc/src/data.c +++ b/contrib/bc/src/data.c @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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: @@ -70,8 +70,8 @@ const uchar dc_sig_msg_len = (uchar) (sizeof(dc_sig_msg) - 1); /// The copyright banner. const char bc_copyright[] = - "Copyright (c) 2018-2022 Gavin D. Howard and contributors\n" - "Report bugs at: https://git.yzena.com/gavin/bc\n\n" + "Copyright (c) 2018-2024 Gavin D. Howard and contributors\n" + "Report bugs at: https://git.gavinhoward.com/gavin/bc\n\n" "This is free software with ABSOLUTELY NO WARRANTY.\n"; // clang-format on @@ -141,6 +141,7 @@ const char bc_pledge_end[] = ""; /// end. const BcOptLong bc_args_lopt[] = { + { "digit-clamp", BC_OPT_NONE, 'c' }, { "expression", BC_OPT_REQUIRED, 'e' }, { "file", BC_OPT_REQUIRED, 'f' }, { "help", BC_OPT_NONE, 'h' }, @@ -149,6 +150,7 @@ const BcOptLong bc_args_lopt[] = { { "leading-zeroes", BC_OPT_NONE, 'z' }, { "no-line-length", BC_OPT_NONE, 'L' }, { "obase", BC_OPT_REQUIRED, 'O' }, + { "no-digit-clamp", BC_OPT_NONE, 'C' }, { "no-prompt", BC_OPT_NONE, 'P' }, { "no-read-prompt", BC_OPT_NONE, 'R' }, { "scale", BC_OPT_REQUIRED, 'S' }, @@ -172,11 +174,64 @@ const BcOptLong bc_args_lopt[] = { }; -/// The function header for error messages. -const char* const bc_err_func_header = "Function:"; +#if BC_ENABLE_OSSFUZZ -/// The line format string for error messages. -const char* const bc_err_line = ":%zu"; +const char* bc_fuzzer_args_c[] = { + "bc", + "-lqc", + "-e", + "seed = 82507683022933941343198991100880559238.7080266844215897551270760113" + "4734858017748592704189096562163085637164174146616055338762825421827784" + "566630725748836994171142578125", + NULL, +}; + +const char* dc_fuzzer_args_c[] = { + "dc", + "-xc", + "-e", + "82507683022933941343198991100880559238.7080266844215897551270760113" + "4734858017748592704189096562163085637164174146616055338762825421827784" + "566630725748836994171142578125j", + NULL, +}; + +const char* bc_fuzzer_args_C[] = { + "bc", + "-lqC", + "-e", + "seed = 82507683022933941343198991100880559238.7080266844215897551270760113" + "4734858017748592704189096562163085637164174146616055338762825421827784" + "566630725748836994171142578125", + NULL, +}; + +const char* dc_fuzzer_args_C[] = { + "dc", + "-xC", + "-e", + "82507683022933941343198991100880559238.7080266844215897551270760113" + "4734858017748592704189096562163085637164174146616055338762825421827784" + "566630725748836994171142578125j", + NULL, +}; + +const size_t bc_fuzzer_args_len = sizeof(bc_fuzzer_args_c) / sizeof(char*); + +#if BC_C11 + +_Static_assert(sizeof(bc_fuzzer_args_C) / sizeof(char*) == bc_fuzzer_args_len, + "Wrong number of bc fuzzer args"); + +_Static_assert(sizeof(dc_fuzzer_args_c) / sizeof(char*) == bc_fuzzer_args_len, + "Wrong number of dc fuzzer args"); + +_Static_assert(sizeof(dc_fuzzer_args_C) / sizeof(char*) == bc_fuzzer_args_len, + "Wrong number of dc fuzzer args"); + +#endif // BC_C11 + +#endif // BC_ENABLE_OSSFUZZ // clang-format off @@ -312,9 +367,9 @@ const BcVecFree bc_vec_dtors[] = { bc_vec_free, bc_num_free, #if !BC_ENABLE_LIBRARY -#ifndef NDEBUG +#if BC_DEBUG bc_func_free, -#endif // NDEBUG +#endif // BC_DEBUG bc_slab_free, bc_const_free, bc_result_free, @@ -717,6 +772,8 @@ const char* bc_inst_names[] = { "BC_INST_SCALE_FUNC", "BC_INST_SQRT", "BC_INST_ABS", + "BC_INST_IS_NUMBER", + "BC_INST_IS_STRING", #if BC_ENABLE_EXTRA_MATH "BC_INST_IRAND", #endif // BC_ENABLE_EXTRA_MATH @@ -814,6 +871,8 @@ const BcLexKeyword bc_lex_kws[] = { BC_LEX_KW_ENTRY("print", 5, false), BC_LEX_KW_ENTRY("sqrt", 4, true), BC_LEX_KW_ENTRY("abs", 3, false), + BC_LEX_KW_ENTRY("is_number", 9, false), + BC_LEX_KW_ENTRY("is_string", 9, false), #if BC_ENABLE_EXTRA_MATH BC_LEX_KW_ENTRY("irand", 5, false), #endif // BC_ENABLE_EXTRA_MATH @@ -886,13 +945,13 @@ const uint8_t bc_parse_exprs[] = { BC_PARSE_EXPR_ENTRY(false, true, true, true, true, true, true, false), // Starts with BC_LEX_KW_SQRT. - BC_PARSE_EXPR_ENTRY(true, true, true, true, true, true, false, true), - - // Starts with BC_LEX_KW_MAXIBASE. BC_PARSE_EXPR_ENTRY(true, true, true, true, true, true, true, true), - // Starts with BC_LEX_KW_STREAM. - BC_PARSE_EXPR_ENTRY(false, false, 0, 0, 0, 0, 0, 0) + // Starts with BC_LEX_KW_QUIT. + BC_PARSE_EXPR_ENTRY(false, true, true, true, true, true, true, true), + + // Starts with BC_LEX_KW_GLOBAL_STACKS. + BC_PARSE_EXPR_ENTRY(true, true, false, false, 0, 0, 0, 0) #else // BC_ENABLE_EXTRA_MATH @@ -909,15 +968,19 @@ const uint8_t bc_parse_exprs[] = { BC_PARSE_EXPR_ENTRY(false, false, true, true, true, true, true, false), // Starts with BC_LEX_KW_SQRT. - BC_PARSE_EXPR_ENTRY(true, true, true, true, true, false, true, true), + BC_PARSE_EXPR_ENTRY(true, true, true, true, true, true, true, false), - // Starts with BC_LEX_KW_MAXSCALE, - BC_PARSE_EXPR_ENTRY(true, true, true, true, true, false, false, 0) + // Starts with BC_LEX_KW_MAXIBASE. + BC_PARSE_EXPR_ENTRY(true, true, true, true, true, true, true, false), + + // Starts with BC_LEX_KW_ELSE. + BC_PARSE_EXPR_ENTRY(false, 0, 0, 0, 0, 0, 0, 0) #endif // BC_ENABLE_EXTRA_MATH }; -/// An array of data for operators that correspond to token types. +/// An array of data for operators that correspond to token types. Note that a +/// lower precedence *value* means a higher precedence. const uchar bc_parse_ops[] = { BC_PARSE_OP(0, false), BC_PARSE_OP(0, false), BC_PARSE_OP(1, false), BC_PARSE_OP(1, false), @@ -1120,8 +1183,8 @@ const uchar dc_lex_tokens[] = { BC_LEX_KW_QUIT, BC_LEX_SWAP, BC_LEX_OP_ASSIGN, - BC_LEX_INVALID, - BC_LEX_INVALID, + BC_LEX_KW_IS_STRING, + BC_LEX_KW_IS_NUMBER, BC_LEX_KW_SQRT, BC_LEX_INVALID, BC_LEX_EXECUTE, @@ -1135,7 +1198,7 @@ const uchar dc_lex_tokens[] = { }; /// A list of instructions that correspond to lex tokens. If an entry is -/// BC_INST_INVALID, that lex token needs extra parsing in the dc parser. +/// @a BC_INST_INVALID, that lex token needs extra parsing in the dc parser. /// Otherwise, the token can trivially be replaced by the entry. This needs to /// be updated if the tokens change. const uchar dc_parse_insts[] = { @@ -1147,47 +1210,60 @@ const uchar dc_parse_insts[] = { #if BC_ENABLE_EXTRA_MATH BC_INST_TRUNC, #endif // BC_ENABLE_EXTRA_MATH - BC_INST_POWER, BC_INST_MULTIPLY, BC_INST_DIVIDE, - BC_INST_MODULUS, BC_INST_PLUS, BC_INST_MINUS, + BC_INST_POWER, BC_INST_MULTIPLY, + BC_INST_DIVIDE, BC_INST_MODULUS, + BC_INST_PLUS, BC_INST_MINUS, #if BC_ENABLE_EXTRA_MATH - BC_INST_PLACES, BC_INST_LSHIFT, BC_INST_RSHIFT, + BC_INST_PLACES, BC_INST_LSHIFT, + BC_INST_RSHIFT, #endif // BC_ENABLE_EXTRA_MATH - BC_INST_INVALID, BC_INST_INVALID, BC_INST_INVALID, - BC_INST_INVALID, BC_INST_INVALID, BC_INST_INVALID, + BC_INST_INVALID, BC_INST_INVALID, + BC_INST_INVALID, BC_INST_INVALID, + BC_INST_INVALID, BC_INST_INVALID, BC_INST_BOOL_OR, BC_INST_BOOL_AND, #if BC_ENABLED - BC_INST_INVALID, BC_INST_INVALID, BC_INST_INVALID, - BC_INST_INVALID, BC_INST_INVALID, BC_INST_INVALID, + BC_INST_INVALID, BC_INST_INVALID, + BC_INST_INVALID, BC_INST_INVALID, + BC_INST_INVALID, BC_INST_INVALID, #if BC_ENABLE_EXTRA_MATH - BC_INST_INVALID, BC_INST_INVALID, BC_INST_INVALID, + BC_INST_INVALID, BC_INST_INVALID, + BC_INST_INVALID, #endif // BC_ENABLE_EXTRA_MATH #endif // BC_ENABLED - BC_INST_INVALID, BC_INST_INVALID, BC_INST_INVALID, - BC_INST_REL_GT, BC_INST_REL_LT, BC_INST_INVALID, - BC_INST_INVALID, BC_INST_INVALID, BC_INST_REL_GE, - BC_INST_INVALID, BC_INST_REL_LE, BC_INST_INVALID, + BC_INST_INVALID, BC_INST_INVALID, + BC_INST_INVALID, BC_INST_REL_GT, + BC_INST_REL_LT, BC_INST_INVALID, + BC_INST_INVALID, BC_INST_INVALID, + BC_INST_REL_GE, BC_INST_INVALID, + BC_INST_REL_LE, BC_INST_INVALID, BC_INST_INVALID, BC_INST_INVALID, #if BC_ENABLED - BC_INST_INVALID, BC_INST_INVALID, BC_INST_INVALID, - BC_INST_INVALID, BC_INST_INVALID, BC_INST_INVALID, - BC_INST_INVALID, BC_INST_INVALID, BC_INST_INVALID, BC_INST_INVALID, BC_INST_INVALID, + BC_INST_INVALID, BC_INST_INVALID, + BC_INST_INVALID, BC_INST_INVALID, + BC_INST_INVALID, BC_INST_INVALID, + BC_INST_INVALID, BC_INST_INVALID, + BC_INST_INVALID, #endif // BC_ENABLED - BC_INST_IBASE, BC_INST_OBASE, BC_INST_SCALE, + BC_INST_IBASE, BC_INST_OBASE, + BC_INST_SCALE, #if BC_ENABLE_EXTRA_MATH BC_INST_SEED, #endif // BC_ENABLE_EXTRA_MATH - BC_INST_LENGTH, BC_INST_PRINT, BC_INST_SQRT, - BC_INST_ABS, + BC_INST_LENGTH, BC_INST_PRINT, + BC_INST_SQRT, BC_INST_ABS, + BC_INST_IS_NUMBER, BC_INST_IS_STRING, #if BC_ENABLE_EXTRA_MATH BC_INST_IRAND, #endif // BC_ENABLE_EXTRA_MATH - BC_INST_ASCIIFY, BC_INST_MODEXP, BC_INST_DIVMOD, - BC_INST_QUIT, BC_INST_INVALID, + BC_INST_ASCIIFY, BC_INST_MODEXP, + BC_INST_DIVMOD, BC_INST_QUIT, + BC_INST_INVALID, #if BC_ENABLE_EXTRA_MATH BC_INST_RAND, #endif // BC_ENABLE_EXTRA_MATH - BC_INST_MAXIBASE, BC_INST_MAXOBASE, BC_INST_MAXSCALE, + BC_INST_MAXIBASE, BC_INST_MAXOBASE, + BC_INST_MAXSCALE, #if BC_ENABLE_EXTRA_MATH BC_INST_MAXRAND, #endif // BC_ENABLE_EXTRA_MATH @@ -1195,17 +1271,21 @@ const uchar dc_parse_insts[] = { #if BC_ENABLED BC_INST_INVALID, #endif // BC_ENABLED - BC_INST_LEADING_ZERO, BC_INST_PRINT_STREAM, BC_INST_INVALID, - BC_INST_REL_EQ, BC_INST_INVALID, BC_INST_EXECUTE, - BC_INST_PRINT_STACK, BC_INST_CLEAR_STACK, BC_INST_INVALID, - BC_INST_STACK_LEN, BC_INST_DUPLICATE, BC_INST_SWAP, - BC_INST_POP, BC_INST_INVALID, BC_INST_INVALID, + BC_INST_LEADING_ZERO, BC_INST_PRINT_STREAM, + BC_INST_INVALID, BC_INST_EXTENDED_REGISTERS, + BC_INST_REL_EQ, BC_INST_INVALID, + BC_INST_EXECUTE, BC_INST_PRINT_STACK, + BC_INST_CLEAR_STACK, BC_INST_INVALID, + BC_INST_STACK_LEN, BC_INST_DUPLICATE, + BC_INST_SWAP, BC_INST_POP, + BC_INST_INVALID, BC_INST_INVALID, BC_INST_INVALID, #if BC_ENABLE_EXTRA_MATH BC_INST_INVALID, #endif // BC_ENABLE_EXTRA_MATH - BC_INST_INVALID, BC_INST_INVALID, BC_INST_INVALID, - BC_INST_PRINT_POP, BC_INST_NQUIT, BC_INST_EXEC_STACK_LEN, + BC_INST_INVALID, BC_INST_INVALID, + BC_INST_INVALID, BC_INST_PRINT_POP, + BC_INST_NQUIT, BC_INST_EXEC_STACK_LEN, BC_INST_SCALE_FUNC, BC_INST_INVALID, }; #endif // DC_ENABLED diff --git a/contrib/bc/src/dc.c b/contrib/bc/src/dc.c index f873241286e0..37419acd4bd4 100644 --- a/contrib/bc/src/dc.c +++ b/contrib/bc/src/dc.c @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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: @@ -45,20 +45,21 @@ * @param argc The number of arguments. * @param argv The arguments. */ -void -dc_main(int argc, char* argv[]) +BcStatus +dc_main(int argc, const char* argv[]) { // All of these just set dc-specific items in BcVm. - vm.read_ret = BC_INST_POP_EXEC; - vm.help = dc_help; - vm.sigmsg = dc_sig_msg; - vm.siglen = dc_sig_msg_len; + vm->read_ret = BC_INST_POP_EXEC; + vm->help = dc_help; + vm->sigmsg = dc_sig_msg; + vm->siglen = dc_sig_msg_len; - vm.next = dc_lex_token; - vm.parse = dc_parse_parse; - vm.expr = dc_parse_expr; + vm->next = dc_lex_token; + vm->parse = dc_parse_parse; + vm->expr = dc_parse_expr; - bc_vm_boot(argc, argv); + return bc_vm_boot(argc, argv); } + #endif // DC_ENABLED diff --git a/contrib/bc/src/dc_fuzzer.c b/contrib/bc/src/dc_fuzzer.c new file mode 100644 index 000000000000..adaf486a668c --- /dev/null +++ b/contrib/bc/src/dc_fuzzer.c @@ -0,0 +1,112 @@ +/* + * ***************************************************************************** + * + * SPDX-License-Identifier: BSD-2-Clause + * + * Copyright (c) 2018-2024 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: + * + * * Redistributions of source code must retain the above copyright notice, this + * list of conditions and the following disclaimer. + * + * * Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + * + * ***************************************************************************** + * + * The entry point for libFuzzer when fuzzing dc. + * + */ + +#include <setjmp.h> +#include <string.h> + +#include <version.h> +#include <status.h> +#include <ossfuzz.h> +#include <vm.h> +#include <bc.h> +#include <dc.h> + +uint8_t* bc_fuzzer_data; + +/// A boolean about whether we should use -c (false) or -C (true). +static bool dc_C; + +int +LLVMFuzzerInitialize(int* argc, char*** argv) +{ + BC_UNUSED(argc); + + if (argv == NULL || *argv == NULL) + { + dc_C = false; + } + else + { + char* name; + + // Get the basename + name = strrchr((*argv)[0], BC_FILE_SEP); + name = name == NULL ? (*argv)[0] : name + 1; + + // Figure out which to use. + dc_C = (strcmp(name, "dc_fuzzer_C") == 0); + } + + return 0; +} + +int +LLVMFuzzerTestOneInput(const uint8_t* Data, size_t Size) +{ + BcStatus s; + + // I've already tested empty input, so just ignore. + if (Size == 0 || Data[0] == '\0') return 0; + + // Clear the global. This is to ensure a clean start. + memset(vm, 0, sizeof(BcVm)); + + // Make sure to set the name. + vm->name = "dc"; + + BC_SIG_LOCK; + + // We *must* do this here. Otherwise, other code could not jump out all of + // the way. + bc_vec_init(&vm->jmp_bufs, sizeof(sigjmp_buf), BC_DTOR_NONE); + + BC_SETJMP_LOCKED(vm, exit); + + // Create a string with the data. + bc_fuzzer_data = bc_vm_malloc(Size + 1); + memcpy(bc_fuzzer_data, Data, Size); + bc_fuzzer_data[Size] = '\0'; + + s = dc_main((int) (bc_fuzzer_args_len - 1), + dc_C ? dc_fuzzer_args_C : dc_fuzzer_args_c); + +exit: + + BC_SIG_MAYLOCK; + + free(bc_fuzzer_data); + + return s == BC_STATUS_SUCCESS || s == BC_STATUS_QUIT ? 0 : -1; +} diff --git a/contrib/bc/src/dc_lex.c b/contrib/bc/src/dc_lex.c index b76c966f6059..d5131b45331d 100644 --- a/contrib/bc/src/dc_lex.c +++ b/contrib/bc/src/dc_lex.c @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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: @@ -114,7 +114,9 @@ dc_lex_string(BcLex* l) nls = 0; got_more = false; - assert(!l->is_stdin || l->buf == vm.buffer.v); +#if !BC_ENABLE_OSSFUZZ + assert(l->mode != BC_MODE_STDIN || l->buf == vm->buffer.v); +#endif // !BC_ENABLE_OSSFUZZ // This is the meat. As long as we don't run into the NUL byte, and we // have "depth", which means we haven't completely balanced brackets @@ -141,11 +143,15 @@ dc_lex_string(BcLex* l) if (BC_ERR(c == '\0' && depth)) { - if (!vm.eof && (l->is_stdin || l->is_exprs)) + if (!vm->eof && l->mode != BC_MODE_FILE) { got_more = bc_lex_readLine(l); } - if (got_more) bc_vec_popAll(&l->str); + + if (got_more) + { + bc_vec_popAll(&l->str); + } } } while (got_more && depth); @@ -274,6 +280,7 @@ dc_lex_token(BcLex* l) c2 = l->buf[l->i]; if (c2 == 'l') l->t = BC_LEX_KW_LINE_LENGTH; + else if (c2 == 'x') l->t = BC_LEX_EXTENDED_REGISTERS; else if (c2 == 'z') l->t = BC_LEX_KW_LEADING_ZERO; else bc_lex_invalidChar(l, c2); diff --git a/contrib/bc/src/dc_parse.c b/contrib/bc/src/dc_parse.c index d45f951bad4f..1996120461a8 100644 --- a/contrib/bc/src/dc_parse.c +++ b/contrib/bc/src/dc_parse.c @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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: @@ -255,7 +255,113 @@ dc_parse_token(BcParse* p, BcLexType t, uint8_t flags) break; } - default: + case BC_LEX_EOF: + case BC_LEX_INVALID: +#if BC_ENABLED + case BC_LEX_OP_INC: + case BC_LEX_OP_DEC: +#endif // BC_ENABLED + case BC_LEX_OP_BOOL_NOT: +#if BC_ENABLE_EXTRA_MATH + case BC_LEX_OP_TRUNC: +#endif // BC_ENABLE_EXTRA_MATH + case BC_LEX_OP_POWER: + case BC_LEX_OP_MULTIPLY: + case BC_LEX_OP_DIVIDE: + case BC_LEX_OP_MODULUS: + case BC_LEX_OP_PLUS: + case BC_LEX_OP_MINUS: +#if BC_ENABLE_EXTRA_MATH + case BC_LEX_OP_PLACES: + case BC_LEX_OP_LSHIFT: + case BC_LEX_OP_RSHIFT: +#endif // BC_ENABLE_EXTRA_MATH + case BC_LEX_OP_BOOL_OR: + case BC_LEX_OP_BOOL_AND: +#if BC_ENABLED + case BC_LEX_OP_ASSIGN_POWER: + case BC_LEX_OP_ASSIGN_MULTIPLY: + case BC_LEX_OP_ASSIGN_DIVIDE: + case BC_LEX_OP_ASSIGN_MODULUS: + case BC_LEX_OP_ASSIGN_PLUS: + case BC_LEX_OP_ASSIGN_MINUS: +#if BC_ENABLE_EXTRA_MATH + case BC_LEX_OP_ASSIGN_PLACES: + case BC_LEX_OP_ASSIGN_LSHIFT: + case BC_LEX_OP_ASSIGN_RSHIFT: +#endif // BC_ENABLE_EXTRA_MATH +#endif // BC_ENABLED + case BC_LEX_NLINE: + case BC_LEX_WHITESPACE: + case BC_LEX_LPAREN: + case BC_LEX_RPAREN: + case BC_LEX_LBRACKET: + case BC_LEX_COMMA: + case BC_LEX_RBRACKET: + case BC_LEX_LBRACE: + case BC_LEX_NAME: + case BC_LEX_RBRACE: +#if BC_ENABLED + case BC_LEX_KW_AUTO: + case BC_LEX_KW_BREAK: + case BC_LEX_KW_CONTINUE: + case BC_LEX_KW_DEFINE: + case BC_LEX_KW_FOR: + case BC_LEX_KW_IF: + case BC_LEX_KW_LIMITS: + case BC_LEX_KW_RETURN: + case BC_LEX_KW_WHILE: + case BC_LEX_KW_HALT: + case BC_LEX_KW_LAST: +#endif // BC_ENABLED + case BC_LEX_KW_IBASE: + case BC_LEX_KW_OBASE: + case BC_LEX_KW_SCALE: +#if BC_ENABLE_EXTRA_MATH + case BC_LEX_KW_SEED: +#endif // BC_ENABLE_EXTRA_MATH + case BC_LEX_KW_LENGTH: + case BC_LEX_KW_PRINT: + case BC_LEX_KW_SQRT: + case BC_LEX_KW_ABS: + case BC_LEX_KW_IS_NUMBER: + case BC_LEX_KW_IS_STRING: +#if BC_ENABLE_EXTRA_MATH + case BC_LEX_KW_IRAND: +#endif // BC_ENABLE_EXTRA_MATH + case BC_LEX_KW_ASCIIFY: + case BC_LEX_KW_MODEXP: + case BC_LEX_KW_DIVMOD: + case BC_LEX_KW_QUIT: +#if BC_ENABLE_EXTRA_MATH + case BC_LEX_KW_RAND: +#endif // BC_ENABLE_EXTRA_MATH + case BC_LEX_KW_MAXIBASE: + case BC_LEX_KW_MAXOBASE: + case BC_LEX_KW_MAXSCALE: +#if BC_ENABLE_EXTRA_MATH + case BC_LEX_KW_MAXRAND: +#endif // BC_ENABLE_EXTRA_MATH + case BC_LEX_KW_LINE_LENGTH: +#if BC_ENABLED + case BC_LEX_KW_GLOBAL_STACKS: +#endif // BC_ENABLED + case BC_LEX_KW_LEADING_ZERO: + case BC_LEX_KW_STREAM: + case BC_LEX_KW_ELSE: + case BC_LEX_EXTENDED_REGISTERS: + case BC_LEX_EQ_NO_REG: + case BC_LEX_EXECUTE: + case BC_LEX_PRINT_STACK: + case BC_LEX_CLEAR_STACK: + case BC_LEX_STACK_LEVEL: + case BC_LEX_DUPLICATE: + case BC_LEX_SWAP: + case BC_LEX_POP: + case BC_LEX_PRINT_POP: + case BC_LEX_NQUIT: + case BC_LEX_EXEC_STACK_LENGTH: + case BC_LEX_SCALE_FACTOR: { // All other tokens should be taken care of by the caller, or they // actually *are* invalid. @@ -320,7 +426,7 @@ dc_parse_parse(BcParse* p) { assert(p != NULL); - BC_SETJMP_LOCKED(exit); + BC_SETJMP_LOCKED(vm, exit); // If we have EOF, someone called this function one too many times. // Otherwise, parse. @@ -330,9 +436,9 @@ dc_parse_parse(BcParse* p) exit: // Need to reset if there was an error. - if (BC_SIG_EXC) bc_parse_reset(p); + if (BC_SIG_EXC(vm)) bc_parse_reset(p); - BC_LONGJMP_CONT; + BC_LONGJMP_CONT(vm); BC_SIG_MAYLOCK; } #endif // DC_ENABLED diff --git a/contrib/bc/src/file.c b/contrib/bc/src/file.c index e5d2f6ac73d8..9baea585603b 100644 --- a/contrib/bc/src/file.c +++ b/contrib/bc/src/file.c @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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: @@ -159,12 +159,12 @@ bc_file_flushErr(BcFile* restrict f, BcFlushType type) i += 1; // Save the extras. - bc_vec_string(&vm.history.extras, f->len - i, f->buf + i); + bc_vec_string(&vm->history.extras, f->len - i, f->buf + i); } // Else clear the extras if told to. else if (type >= BC_FLUSH_NO_EXTRAS_CLEAR) { - bc_vec_popAll(&vm.history.extras); + bc_vec_popAll(&vm->history.extras); } } #endif // BC_ENABLE_HISTORY @@ -196,12 +196,17 @@ bc_file_flush(BcFile* restrict f, BcFlushType type) // For EOF, set it and jump. if (s == BC_STATUS_EOF) { - vm.status = (sig_atomic_t) s; + vm->status = (sig_atomic_t) s; BC_SIG_TRYUNLOCK(lock); BC_JMP; } + // Make sure to handle non-fatal I/O properly. + else if (!f->errors_fatal) + { + bc_vm_fatalError(BC_ERR_FATAL_IO_ERR); + } // Blow up on fatal error. Okay, not blow up, just quit. - else bc_vm_fatalError(BC_ERR_FATAL_IO_ERR); + else exit(BC_STATUS_ERROR_FATAL); } BC_SIG_TRYUNLOCK(lock); @@ -234,12 +239,17 @@ bc_file_write(BcFile* restrict f, BcFlushType type, const char* buf, size_t n) // For EOF, set it and jump. if (s == BC_STATUS_EOF) { - vm.status = (sig_atomic_t) s; + vm->status = (sig_atomic_t) s; BC_SIG_TRYUNLOCK(lock); BC_JMP; } + // Make sure to handle non-fatal I/O properly. + else if (!f->errors_fatal) + { + bc_vm_fatalError(BC_ERR_FATAL_IO_ERR); + } // Blow up on fatal error. Okay, not blow up, just quit. - else bc_vm_fatalError(BC_ERR_FATAL_IO_ERR); + else exit(BC_STATUS_ERROR_FATAL); } } else @@ -276,103 +286,126 @@ bc_file_vprintf(BcFile* restrict f, const char* fmt, va_list args) #if BC_ENABLE_LINE_LIB - // Just print and propagate the error. - if (BC_ERR(vfprintf(f->f, fmt, args) < 0)) { - bc_vm_fatalError(BC_ERR_FATAL_IO_ERR); + int r; + + // This mess is to silence a warning. +#if BC_CLANG +#pragma clang diagnostic ignored "-Wformat-nonliteral" +#endif // BC_CLANG + r = vfprintf(f->f, fmt, args); +#if BC_CLANG +#pragma clang diagnostic warning "-Wformat-nonliteral" +#endif // BC_CLANG + + // Just print and propagate the error. + if (BC_ERR(r < 0)) + { + // Make sure to handle non-fatal I/O properly. + if (!f->errors_fatal) + { + bc_vm_fatalError(BC_ERR_FATAL_IO_ERR); + } + else + { + exit(BC_STATUS_ERROR_FATAL); + } + } } #else // BC_ENABLE_LINE_LIB - char* percent; - const char* ptr = fmt; - char buf[BC_FILE_ULL_LENGTH]; - - // This is a poor man's printf(). While I could look up algorithms to make - // it as fast as possible, and should when I write the standard library for - // a new language, for bc, outputting is not the bottleneck. So we cheese it - // for now. - - // Find each percent sign. - while ((percent = strchr(ptr, '%')) != NULL) { - char c; - - // If the percent sign is not where we are, write what's inbetween to - // the buffer. - if (percent != ptr) - { - size_t len = (size_t) (percent - ptr); - bc_file_write(f, bc_flush_none, ptr, len); - } + char* percent; + const char* ptr = fmt; + char buf[BC_FILE_ULL_LENGTH]; - c = percent[1]; - - // We only parse some format specifiers, the ones bc uses. If you add - // more, you need to make sure to add them here. - if (c == 'c') - { - uchar uc = (uchar) va_arg(args, int); - - bc_file_putchar(f, bc_flush_none, uc); - } - else if (c == 's') - { - char* s = va_arg(args, char*); + // This is a poor man's printf(). While I could look up algorithms to + // make it as fast as possible, and should when I write the standard + // library for a new language, for bc, outputting is not the bottleneck. + // So we cheese it for now. - bc_file_puts(f, bc_flush_none, s); - } -#if BC_DEBUG_CODE - // We only print signed integers in debug code. - else if (c == 'd') + // Find each percent sign. + while ((percent = strchr(ptr, '%')) != NULL) { - int d = va_arg(args, int); + char c; - // Take care of negative. Let's not worry about overflow. - if (d < 0) + // If the percent sign is not where we are, write what's inbetween + // to the buffer. + if (percent != ptr) { - bc_file_putchar(f, bc_flush_none, '-'); - d = -d; + size_t len = (size_t) (percent - ptr); + bc_file_write(f, bc_flush_none, ptr, len); } - // Either print 0 or translate and print. - if (!d) bc_file_putchar(f, bc_flush_none, '0'); - else + c = percent[1]; + + // We only parse some format specifiers, the ones bc uses. If you + // add more, you need to make sure to add them here. + if (c == 'c') { - bc_file_ultoa((unsigned long long) d, buf); - bc_file_puts(f, bc_flush_none, buf); + uchar uc = (uchar) va_arg(args, int); + + bc_file_putchar(f, bc_flush_none, uc); } - } -#endif // BC_DEBUG_CODE - else - { - unsigned long long ull; + else if (c == 's') + { + char* s = va_arg(args, char*); - // These are the ones that it expects from here. Fortunately, all of - // these are unsigned types, so they can use the same code, more or - // less. - assert((c == 'l' || c == 'z') && percent[2] == 'u'); + bc_file_puts(f, bc_flush_none, s); + } +#if BC_DEBUG + // We only print signed integers in debug code. + else if (c == 'd') + { + int d = va_arg(args, int); - if (c == 'z') ull = (unsigned long long) va_arg(args, size_t); - else ull = (unsigned long long) va_arg(args, unsigned long); + // Take care of negative. Let's not worry about overflow. + if (d < 0) + { + bc_file_putchar(f, bc_flush_none, '-'); + d = -d; + } - // Either print 0 or translate and print. - if (!ull) bc_file_putchar(f, bc_flush_none, '0'); + // Either print 0 or translate and print. + if (!d) bc_file_putchar(f, bc_flush_none, '0'); + else + { + bc_file_ultoa((unsigned long long) d, buf); + bc_file_puts(f, bc_flush_none, buf); + } + } +#endif // BC_DEBUG else { - bc_file_ultoa(ull, buf); - bc_file_puts(f, bc_flush_none, buf); + unsigned long long ull; + + // These are the ones that it expects from here. Fortunately, + // all of these are unsigned types, so they can use the same + // code, more or less. + assert((c == 'l' || c == 'z') && percent[2] == 'u'); + + if (c == 'z') ull = (unsigned long long) va_arg(args, size_t); + else ull = (unsigned long long) va_arg(args, unsigned long); + + // Either print 0 or translate and print. + if (!ull) bc_file_putchar(f, bc_flush_none, '0'); + else + { + bc_file_ultoa(ull, buf); + bc_file_puts(f, bc_flush_none, buf); + } } + + // Increment to the next spot after the specifier. + ptr = percent + 2 + (c == 'l' || c == 'z'); } - // Increment to the next spot after the specifier. - ptr = percent + 2 + (c == 'l' || c == 'z'); + // If we get here, there are no more percent signs, so we just output + // whatever is left. + if (ptr[0]) bc_file_puts(f, bc_flush_none, ptr); } - // If we get here, there are no more percent signs, so we just output - // whatever is left. - if (ptr[0]) bc_file_puts(f, bc_flush_none, ptr); - #endif // BC_ENABLE_LINE_LIB } @@ -403,7 +436,7 @@ bc_file_putchar(BcFile* restrict f, BcFlushType type, uchar c) // This is here to prevent a stack overflow from unbounded recursion. if (f->f == stderr) exit(BC_STATUS_ERROR_FATAL); - bc_vm_fatalError(BC_ERR_FATAL_IO_ERR); + bc_err(BC_ERR_FATAL_IO_ERR); } #else // BC_ENABLE_LINE_LIB @@ -423,16 +456,17 @@ bc_file_putchar(BcFile* restrict f, BcFlushType type, uchar c) #if BC_ENABLE_LINE_LIB void -bc_file_init(BcFile* f, FILE* file) +bc_file_init(BcFile* f, FILE* file, bool errors_fatal) { BC_SIG_ASSERT_LOCKED; f->f = file; + f->errors_fatal = errors_fatal; } #else // BC_ENABLE_LINE_LIB void -bc_file_init(BcFile* f, int fd, char* buf, size_t cap) +bc_file_init(BcFile* f, int fd, char* buf, size_t cap, bool errors_fatal) { BC_SIG_ASSERT_LOCKED; @@ -440,6 +474,7 @@ bc_file_init(BcFile* f, int fd, char* buf, size_t cap) f->buf = buf; f->len = 0; f->cap = cap; + f->errors_fatal = errors_fatal; } #endif // BC_ENABLE_LINE_LIB diff --git a/contrib/bc/src/history.c b/contrib/bc/src/history.c index 3433c0ed8ddf..32a19f71d777 100644 --- a/contrib/bc/src/history.c +++ b/contrib/bc/src/history.c @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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: @@ -159,12 +159,14 @@ volatile sig_atomic_t bc_history_inlinelib; static char* bc_history_prompt; static char bc_history_no_prompt[] = ""; static HistEvent bc_history_event; +static bool bc_history_use_prompt; static char* bc_history_promptFunc(EditLine* el) { BC_UNUSED(el); - return BC_PROMPT ? bc_history_prompt : bc_history_no_prompt; + return BC_PROMPT && bc_history_use_prompt ? bc_history_prompt : + bc_history_no_prompt; } void @@ -195,7 +197,7 @@ bc_history_init(BcHistory* h) h->hist = history_init(); if (BC_ERR(h->hist == NULL)) bc_vm_fatalError(BC_ERR_FATAL_ALLOC_ERR); - h->el = el_init(vm.name, stdin, stdout, stderr); + h->el = el_init(vm->name, stdin, stdout, stderr); if (BC_ERR(h->el == NULL)) bc_vm_fatalError(BC_ERR_FATAL_ALLOC_ERR); // I want history and a prompt. @@ -255,8 +257,29 @@ bc_history_line(BcHistory* h, BcVec* vec, const char* prompt) else bc_history_prompt = bc_vm_strdup(prompt); } + bc_history_use_prompt = true; + + line = NULL; + len = -1; + errno = EINTR; + // Get the line. - line = el_gets(h->el, &len); + // + // XXX: Why have a macro here? Because macOS needs to be special. Honestly, + // it's starting to feel special like Windows at this point. Anyway, the + // second SIGWINCH signal of multiple will return a valid line length on + // macOS, so we need to allow for that on macOS. However, FreeBSD's editline + // is different and will mess up the terminal if we do it that way. + // + // There is one limitation with this, however: Ctrl+D won't work on macOS. + // But it's because of macOS that this problem exists, and I can't really do + // anything about it. So macOS should fix their broken editline; once they + // do, I'll fix Ctrl+D on macOS. + while (BC_HISTORY_INVALID_LINE(line, len)) + { + line = el_gets(h->el, &len); + bc_history_use_prompt = false; + } // If there is no line... if (BC_ERR(line == NULL)) @@ -269,7 +292,7 @@ bc_history_line(BcHistory* h, BcVec* vec, const char* prompt) } else { - bc_file_printf(&vm.fout, "\n"); + bc_file_printf(&vm->fout, "\n"); s = BC_STATUS_EOF; } } @@ -368,7 +391,7 @@ bc_history_line(BcHistory* h, BcVec* vec, const char* prompt) } else if (h->line == NULL) { - bc_file_printf(&vm.fout, "%s\n", "^D"); + bc_file_printf(&vm->fout, "%s\n", "^D"); s = BC_STATUS_EOF; } else bc_vec_string(vec, 1, "\n"); @@ -566,9 +589,11 @@ bc_history_nextLen(const char* buf, size_t buf_len, size_t pos, size_t* col_len) { BC_UNREACHABLE +#if !BC_CLANG if (col_len != NULL) *col_len = 0; return 0; +#endif // !BC_CLANG } // Store the width of the character on screen. @@ -617,7 +642,9 @@ bc_history_prevLen(const char* buf, size_t pos) BC_UNREACHABLE +#if !BC_CLANG return 0; +#endif // BC_CLANG } /** @@ -670,6 +697,7 @@ static BcStatus bc_history_readCode(char* buf, size_t buf_len, uint32_t* cp, size_t* nread) { ssize_t n; + uchar byte; assert(buf_len >= 1); @@ -683,7 +711,7 @@ bc_history_readCode(char* buf, size_t buf_len, uint32_t* cp, size_t* nread) if (BC_ERR(n <= 0)) goto err; // Get the byte. - uchar byte = ((uchar*) buf)[0]; + byte = ((uchar*) buf)[0]; // Once again, this is the UTF-8 decoding algorithm, but it has reads // instead of actual decoding. @@ -898,8 +926,8 @@ bc_history_cursorPos(void) BC_SIG_ASSERT_LOCKED; // Report cursor location. - bc_file_write(&vm.fout, bc_flush_none, "\x1b[6n", 4); - bc_file_flush(&vm.fout, bc_flush_none); + bc_file_write(&vm->fout, bc_flush_none, "\x1b[6n", 4); + bc_file_flush(&vm->fout, bc_flush_none); // Read the response: ESC [ rows ; cols R. for (i = 0; i < sizeof(buf) - 1; ++i) @@ -942,7 +970,7 @@ bc_history_columns(void) struct winsize ws; int ret; - ret = ioctl(vm.fout.fd, TIOCGWINSZ, &ws); + ret = ioctl(vm->fout.fd, TIOCGWINSZ, &ws); if (BC_ERR(ret == -1 || !ws.ws_col)) { @@ -954,16 +982,16 @@ bc_history_columns(void) if (BC_ERR(start == SIZE_MAX)) return BC_HIST_DEF_COLS; // Go to right margin and get position. - bc_file_write(&vm.fout, bc_flush_none, "\x1b[999C", 6); - bc_file_flush(&vm.fout, bc_flush_none); + bc_file_write(&vm->fout, bc_flush_none, "\x1b[999C", 6); + bc_file_flush(&vm->fout, bc_flush_none); cols = bc_history_cursorPos(); if (BC_ERR(cols == SIZE_MAX)) return BC_HIST_DEF_COLS; // Restore position. if (cols > start) { - bc_file_printf(&vm.fout, "\x1b[%zuD", cols - start); - bc_file_flush(&vm.fout, bc_flush_none); + bc_file_printf(&vm->fout, "\x1b[%zuD", cols - start); + bc_file_flush(&vm->fout, bc_flush_none); } return cols; @@ -1021,7 +1049,7 @@ bc_history_refresh(BcHistory* h) BC_SIG_ASSERT_LOCKED; - bc_file_flush(&vm.fout, bc_flush_none); + bc_file_flush(&vm->fout, bc_flush_none); // Get to the prompt column position from the left. while (h->pcol + bc_history_colPos(buf, len, pos) >= h->cols) @@ -1040,7 +1068,7 @@ bc_history_refresh(BcHistory* h) } // Cursor to left edge. - bc_file_write(&vm.fout, bc_flush_none, "\r", 1); + bc_file_write(&vm->fout, bc_flush_none, "\r", 1); // Take the extra stuff into account. This is where history makes sure to // preserve stuff that was printed without a newline. @@ -1053,16 +1081,16 @@ bc_history_refresh(BcHistory* h) len += extras_len; pos += extras_len; - bc_file_write(&vm.fout, bc_flush_none, h->extras.v, extras_len); + bc_file_write(&vm->fout, bc_flush_none, h->extras.v, extras_len); } // Write the prompt, if desired. - if (BC_PROMPT) bc_file_write(&vm.fout, bc_flush_none, h->prompt, h->plen); + if (BC_PROMPT) bc_file_write(&vm->fout, bc_flush_none, h->prompt, h->plen); - bc_file_write(&vm.fout, bc_flush_none, h->buf.v, len - extras_len); + bc_file_write(&vm->fout, bc_flush_none, h->buf.v, len - extras_len); // Erase to right. - bc_file_write(&vm.fout, bc_flush_none, "\x1b[0K", 4); + bc_file_write(&vm->fout, bc_flush_none, "\x1b[0K", 4); // We need to be sure to grow this. if (pos >= h->buf.len - extras_len) bc_vec_grow(&h->buf, pos + extras_len); @@ -1070,13 +1098,13 @@ bc_history_refresh(BcHistory* h) // Move cursor to original position. Do NOT move the putchar of '\r' to the // printf with colpos. That causes a bug where the cursor will go to the end // of the line when there is no prompt. - bc_file_putchar(&vm.fout, bc_flush_none, '\r'); + bc_file_putchar(&vm->fout, bc_flush_none, '\r'); colpos = bc_history_colPos(h->buf.v, len - extras_len, pos) + h->pcol; // Set the cursor position again. - if (colpos) bc_file_printf(&vm.fout, "\x1b[%zuC", colpos); + if (colpos) bc_file_printf(&vm->fout, "\x1b[%zuC", colpos); - bc_file_flush(&vm.fout, bc_flush_none); + bc_file_flush(&vm->fout, bc_flush_none); } /** @@ -1114,8 +1142,8 @@ bc_history_edit_insert(BcHistory* h, const char* cbuf, size_t clen) if (colpos < h->cols) { // Avoid a full update of the line in the trivial case. - bc_file_write(&vm.fout, bc_flush_none, cbuf, clen); - bc_file_flush(&vm.fout, bc_flush_none); + bc_file_write(&vm->fout, bc_flush_none, cbuf, clen); + bc_file_flush(&vm->fout, bc_flush_none); } else bc_history_refresh(h); } @@ -1450,6 +1478,9 @@ bc_history_swap(BcHistory* h) BC_SIG_ASSERT_LOCKED; + // If there are no characters, skip. + if (!h->pos) return; + // Get the length of the previous and next characters. pcl = bc_history_prevLen(h->buf.v, h->pos); ncl = bc_history_nextLen(h->buf.v, BC_HIST_BUF_LEN(h), h->pos, NULL); @@ -1706,10 +1737,10 @@ bc_history_add(BcHistory* h, char* line) static void bc_history_add_empty(BcHistory* h) { - BC_SIG_ASSERT_LOCKED; - const char* line = ""; + BC_SIG_ASSERT_LOCKED; + // If there is something already there... if (h->history.len) { @@ -1768,12 +1799,13 @@ bc_history_printCtrl(BcHistory* h, unsigned int c) // Pop the string. bc_vec_npop(&h->buf, sizeof(str)); bc_vec_pushByte(&h->buf, '\0'); + h->pos = 0; if (c != BC_ACTION_CTRL_C && c != BC_ACTION_CTRL_D) { // We sometimes want to print a newline; for the times we don't; it's // because newlines are taken care of elsewhere. - bc_file_write(&vm.fout, bc_flush_none, newline, sizeof(newline) - 1); + bc_file_write(&vm->fout, bc_flush_none, newline, sizeof(newline) - 1); bc_history_refresh(h); } } @@ -1796,7 +1828,7 @@ bc_history_edit(BcHistory* h, const char* prompt) // Don't write the saved output the first time. This is because it has // already been written to output. In other words, don't uncomment the // line below or add anything like it. - // bc_file_write(&vm.fout, bc_flush_none, h->extras.v, h->extras.len - 1); + // bc_file_write(&vm->fout, bc_flush_none, h->extras.v, h->extras.len - 1); // Write the prompt if desired. if (BC_PROMPT) @@ -1805,8 +1837,8 @@ bc_history_edit(BcHistory* h, const char* prompt) h->plen = strlen(prompt); h->pcol = bc_history_promptColLen(prompt, h->plen); - bc_file_write(&vm.fout, bc_flush_none, prompt, h->plen); - bc_file_flush(&vm.fout, bc_flush_none); + bc_file_write(&vm->fout, bc_flush_none, prompt, h->plen); + bc_file_flush(&vm->fout, bc_flush_none); } // This is the input loop. @@ -1851,14 +1883,14 @@ bc_history_edit(BcHistory* h, const char* prompt) // Quit if the user wants it. if (!BC_SIGINT) { - vm.status = BC_STATUS_QUIT; + vm->status = BC_STATUS_QUIT; BC_SIG_UNLOCK; BC_JMP; } // Print the ready message. - bc_file_write(&vm.fout, bc_flush_none, vm.sigmsg, vm.siglen); - bc_file_write(&vm.fout, bc_flush_none, bc_program_ready_msg, + bc_file_write(&vm->fout, bc_flush_none, vm->sigmsg, vm->siglen); + bc_file_write(&vm->fout, bc_flush_none, bc_program_ready_msg, bc_program_ready_msg_len); bc_history_reset(h); bc_history_refresh(h); @@ -1964,7 +1996,7 @@ bc_history_edit(BcHistory* h, const char* prompt) // Clear screen. case BC_ACTION_CTRL_L: { - bc_file_write(&vm.fout, bc_flush_none, "\x1b[H\x1b[2J", 7); + bc_file_write(&vm->fout, bc_flush_none, "\x1b[H\x1b[2J", 7); bc_history_refresh(h); break; } @@ -1992,7 +2024,7 @@ bc_history_edit(BcHistory* h, const char* prompt) bc_history_raise(h, SIGQUIT); } #else // _WIN32 - vm.status = BC_STATUS_QUIT; + vm->status = BC_STATUS_QUIT; BC_SIG_UNLOCK; BC_JMP; #endif // _WIN32 @@ -2032,7 +2064,7 @@ bc_history_line(BcHistory* h, BcVec* vec, const char* prompt) BcStatus s; char* line; - assert(vm.fout.len == 0); + assert(vm->fout.len == 0); bc_history_enableRaw(h); @@ -2042,8 +2074,8 @@ bc_history_line(BcHistory* h, BcVec* vec, const char* prompt) s = bc_history_edit(h, prompt); // Print a newline and flush. - bc_file_write(&vm.fout, bc_flush_none, "\n", 1); - bc_file_flush(&vm.fout, bc_flush_none); + bc_file_write(&vm->fout, bc_flush_none, "\n", 1); + bc_file_flush(&vm->fout, bc_flush_none); BC_SIG_LOCK; @@ -2166,11 +2198,11 @@ bc_history_free(BcHistory* h) SetConsoleMode(GetStdHandle(STD_INPUT_HANDLE), h->orig_in); SetConsoleMode(GetStdHandle(STD_OUTPUT_HANDLE), h->orig_out); #endif // _WIN32 -#ifndef NDEBUG +#if BC_DEBUG bc_vec_free(&h->buf); bc_vec_free(&h->history); bc_vec_free(&h->extras); -#endif // NDEBUG +#endif // BC_DEBUG } #if BC_DEBUG_CODE @@ -2212,7 +2244,7 @@ bc_history_printKeyCodes(BcHistory* h) // Go left edge manually, we are in raw mode. bc_vm_putchar('\r', bc_flush_none); - bc_file_flush(&vm.fout, bc_flush_none); + bc_file_flush(&vm->fout, bc_flush_none); } bc_history_disableRaw(h); diff --git a/contrib/bc/src/lang.c b/contrib/bc/src/lang.c index bb028b25631a..7968bcbd9dfd 100644 --- a/contrib/bc/src/lang.c +++ b/contrib/bc/src/lang.c @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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: @@ -99,10 +99,6 @@ bc_func_init(BcFunc* f, const char* name) bc_vec_init(&f->code, sizeof(uchar), BC_DTOR_NONE); - bc_vec_init(&f->consts, sizeof(BcConst), BC_DTOR_CONST); - - bc_vec_init(&f->strs, sizeof(char*), BC_DTOR_NONE); - #if BC_ENABLED // Only bc needs these things. @@ -128,10 +124,6 @@ bc_func_reset(BcFunc* f) bc_vec_popAll(&f->code); - bc_vec_popAll(&f->consts); - - bc_vec_popAll(&f->strs); - #if BC_ENABLED if (BC_IS_BC) { @@ -144,7 +136,7 @@ bc_func_reset(BcFunc* f) #endif // BC_ENABLED } -#ifndef NDEBUG +#if BC_DEBUG || BC_ENABLE_MEMCHECK void bc_func_free(void* func) { @@ -155,10 +147,6 @@ bc_func_free(void* func) bc_vec_free(&f->code); - bc_vec_free(&f->consts); - - bc_vec_free(&f->strs); - #if BC_ENABLED if (BC_IS_BC) { @@ -167,7 +155,7 @@ bc_func_free(void* func) } #endif // BC_ENABLED } -#endif // NDEBUG +#endif // BC_DEBUG || BC_ENABLE_MEMCHECK void bc_array_init(BcVec* a, bool nums) @@ -314,10 +302,10 @@ bc_result_copy(BcResult* d, BcResult* src) case BC_RESULT_VOID: case BC_RESULT_LAST: { -#ifndef NDEBUG +#if BC_DEBUG // We should *never* try copying either of these. abort(); -#endif // NDEBUG +#endif // BC_DEBUG } #endif // BC_ENABLED } diff --git a/contrib/bc/src/lex.c b/contrib/bc/src/lex.c index 0fc405e50f88..37e52c33fffd 100644 --- a/contrib/bc/src/lex.c +++ b/contrib/bc/src/lex.c @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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,7 +79,9 @@ bc_lex_comment(BcLex* l) got_more = false; // If we are in stdin mode, the buffer must be the one used for stdin. - assert(!vm.is_stdin || buf == vm.buffer.v); +#if !BC_ENABLE_OSSFUZZ + assert(vm->mode != BC_MODE_STDIN || buf == vm->buffer.v); +#endif // !BC_ENABLE_OSSFUZZ // Find the end of the comment. for (i = l->i; !end; i += !end) @@ -93,11 +95,13 @@ bc_lex_comment(BcLex* l) // If this is true, we need to request more data. if (BC_ERR(!c || buf[i + 1] == '\0')) { +#if !BC_ENABLE_OSSFUZZ // Read more, if possible. - if (!vm.eof && (l->is_stdin || l->is_exprs)) + if (!vm->eof && l->mode != BC_MODE_FILE) { got_more = bc_lex_readLine(l); } +#endif // !BC_ENABLE_OSSFUZZ break; } @@ -293,7 +297,7 @@ bc_lex_file(BcLex* l, const char* file) { assert(l != NULL && file != NULL); l->line = 1; - vm.file = file; + vm->file = file; } void @@ -320,7 +324,7 @@ bc_lex_next(BcLex* l) // is so the parser doesn't get inundated with whitespace. do { - vm.next(l); + vm->next(l); } while (l->t == BC_LEX_WHITESPACE); } @@ -349,22 +353,50 @@ bc_lex_readLine(BcLex* l) BC_SIG_UNLOCK; // Make sure we read from the appropriate place. - if (l->is_stdin) good = bc_vm_readLine(false); - else + switch (l->mode) { - assert(l->is_exprs); - good = bc_vm_readBuf(false); + case BC_MODE_EXPRS: + { + good = bc_vm_readBuf(false); + break; + } + + case BC_MODE_FILE: + { + good = false; + break; + } + +#if !BC_ENABLE_OSSFUZZ + + case BC_MODE_STDIN: + { + good = bc_vm_readLine(false); + break; + } + +#endif // !BC_ENABLE_OSSFUZZ + +#ifdef __GNUC__ +#ifndef __clang__ + default: + { + // We should never get here. + abort(); + } +#endif // __clang__ +#endif // __GNUC__ } BC_SIG_LOCK; - bc_lex_fixText(l, vm.buffer.v, vm.buffer.len - 1); + bc_lex_fixText(l, vm->buffer.v, vm->buffer.len - 1); return good; } 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) { BC_SIG_ASSERT_LOCKED; @@ -373,10 +405,7 @@ bc_lex_text(BcLex* l, const char* text, bool is_stdin, bool is_exprs) bc_lex_fixText(l, text, strlen(text)); l->i = 0; l->t = l->last = BC_LEX_INVALID; - l->is_stdin = is_stdin; - l->is_exprs = is_exprs; - - assert(!l->is_stdin || !l->is_exprs); + l->mode = mode; bc_lex_next(l); } diff --git a/contrib/bc/src/library.c b/contrib/bc/src/library.c index b72b83589135..5451e91684a2 100644 --- a/contrib/bc/src/library.c +++ b/contrib/bc/src/library.c @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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: @@ -45,87 +45,200 @@ #include <num.h> #include <vm.h> +#ifndef _WIN32 +#include <pthread.h> +#endif // _WIN32 + // The asserts in this file are important to testing; in many cases, the test // would not work without the asserts, so don't remove them without reason. // // Also, there are many uses of bc_num_clear() here; that is because numbers are // being reused, and a clean slate is required. // -// Also, there are a bunch of BC_UNSETJMP and BC_SETJMP_LOCKED() between calls -// to bc_num_init(). That is because locals are being initialized, and unlike bc -// proper, this code cannot assume that allocation failures are fatal. So we -// have to reset the jumps every time to ensure that the locals will be correct -// after jumping. +// Also, there are a bunch of BC_UNSETJMP between calls to bc_num_init(). That +// is because locals are being initialized, and unlike bc proper, this code +// cannot assume that allocation failures are fatal. So we have to reset the +// jumps every time to ensure that the locals will be correct after jumping. -void -bcl_handleSignal(void) +#if BC_ENABLE_MEMCHECK + +BC_NORETURN void +bcl_invalidGeneration(void) +{ + abort(); +} + +BC_NORETURN void +bcl_nonexistentNum(void) +{ + abort(); +} + +BC_NORETURN void +bcl_numIdxOutOfRange(void) +{ + abort(); +} + +#endif // BC_ENABLE_MEMCHECK + +static BclTls* tls = NULL; +static BclTls tls_real; + +BclError +bcl_start(void) +{ +#ifndef _WIN32 + + int r; + + if (tls != NULL) return BCL_ERROR_NONE; + + r = pthread_key_create(&tls_real, NULL); + if (BC_ERR(r != 0)) return BCL_ERROR_FATAL_ALLOC_ERR; + +#else // _WIN32 + + if (tls != NULL) return BCL_ERROR_NONE; + + tls_real = TlsAlloc(); + if (BC_ERR(tls_real == TLS_OUT_OF_INDEXES)) + { + return BCL_ERROR_FATAL_ALLOC_ERR; + } + +#endif // _WIN32 + + tls = &tls_real; + + return BCL_ERROR_NONE; +} + +/** + * Sets the thread-specific data for the thread. + * @param vm The @a BcVm to set as the thread data. + * @return An error code, if any. + */ +static BclError +bcl_setspecific(BcVm* vm) { - // Signal already in flight, or bc is not executing. - if (vm.sig || !vm.running) return; +#ifndef _WIN32 + + int r; + + assert(tls != NULL); + + r = pthread_setspecific(tls_real, vm); + if (BC_ERR(r != 0)) return BCL_ERROR_FATAL_ALLOC_ERR; - vm.sig = 1; +#else // _WIN32 - assert(vm.jmp_bufs.len); + bool r; - if (!vm.sig_lock) BC_JMP; + assert(tls != NULL); + + r = TlsSetValue(tls_real, vm); + if (BC_ERR(!r)) return BCL_ERROR_FATAL_ALLOC_ERR; + +#endif // _WIN32 + + return BCL_ERROR_NONE; } -bool -bcl_running(void) +BcVm* +bcl_getspecific(void) { - return vm.running != 0; + BcVm* vm; + +#ifndef _WIN32 + + vm = pthread_getspecific(tls_real); + +#else // _WIN32 + + vm = TlsGetValue(tls_real); + +#endif // _WIN32 + + return vm; } BclError bcl_init(void) { BclError e = BCL_ERROR_NONE; + BcVm* vm; + + assert(tls != NULL); - BC_SIG_LOCK; + vm = bcl_getspecific(); + if (vm != NULL) + { + assert(vm->refs >= 1); - vm.refs += 1; + vm->refs += 1; - if (vm.refs > 1) + return e; + } + + vm = bc_vm_malloc(sizeof(BcVm)); + if (BC_ERR(vm == NULL)) return BCL_ERROR_FATAL_ALLOC_ERR; + + e = bcl_setspecific(vm); + if (BC_ERR(e != BCL_ERROR_NONE)) { - BC_SIG_UNLOCK; + free(vm); return e; } + memset(vm, 0, sizeof(BcVm)); + + vm->refs += 1; + + assert(vm->refs == 1); + // Setting these to NULL ensures that if an error occurs, we only free what // is necessary. - vm.ctxts.v = NULL; - vm.jmp_bufs.v = NULL; - vm.out.v = NULL; + vm->ctxts.v = NULL; + vm->jmp_bufs.v = NULL; + vm->out.v = NULL; - vm.abrt = false; + vm->abrt = false; + vm->leading_zeroes = false; + vm->digit_clamp = true; // The jmp_bufs always has to be initialized first. - bc_vec_init(&vm.jmp_bufs, sizeof(sigjmp_buf), BC_DTOR_NONE); + bc_vec_init(&vm->jmp_bufs, sizeof(sigjmp_buf), BC_DTOR_NONE); - BC_FUNC_HEADER_INIT(err); + BC_FUNC_HEADER(vm, err); bc_vm_init(); - bc_vec_init(&vm.ctxts, sizeof(BclContext), BC_DTOR_NONE); - bc_vec_init(&vm.out, sizeof(uchar), BC_DTOR_NONE); + bc_vec_init(&vm->ctxts, sizeof(BclContext), BC_DTOR_NONE); + bc_vec_init(&vm->out, sizeof(uchar), BC_DTOR_NONE); - // We need to seed this in case /dev/random and /dev/urandm don't work. +#if BC_ENABLE_EXTRA_MATH + + // We need to seed this in case /dev/random and /dev/urandom don't work. srand((unsigned int) time(NULL)); - bc_rand_init(&vm.rng); + bc_rand_init(&vm->rng); + +#endif // BC_ENABLE_EXTRA_MATH err: + + BC_FUNC_FOOTER(vm, e); + // This is why we had to set them to NULL. - if (BC_ERR(vm.err)) + if (BC_ERR(vm != NULL && vm->err)) { - if (vm.out.v != NULL) bc_vec_free(&vm.out); - if (vm.jmp_bufs.v != NULL) bc_vec_free(&vm.jmp_bufs); - if (vm.ctxts.v != NULL) bc_vec_free(&vm.ctxts); + if (vm->out.v != NULL) bc_vec_free(&vm->out); + if (vm->jmp_bufs.v != NULL) bc_vec_free(&vm->jmp_bufs); + if (vm->ctxts.v != NULL) bc_vec_free(&vm->ctxts); + bcl_setspecific(NULL); + free(vm); } - BC_FUNC_FOOTER_UNLOCK(e); - - assert(!vm.running && !vm.sig && !vm.sig_lock); - return e; } @@ -133,108 +246,153 @@ BclError bcl_pushContext(BclContext ctxt) { BclError e = BCL_ERROR_NONE; + BcVm* vm = bcl_getspecific(); - BC_FUNC_HEADER_LOCK(err); + BC_FUNC_HEADER(vm, err); - bc_vec_push(&vm.ctxts, &ctxt); + bc_vec_push(&vm->ctxts, &ctxt); err: - BC_FUNC_FOOTER_UNLOCK(e); + + BC_FUNC_FOOTER(vm, e); return e; } void bcl_popContext(void) { - if (vm.ctxts.len) bc_vec_pop(&vm.ctxts); + BcVm* vm = bcl_getspecific(); + + if (vm->ctxts.len) bc_vec_pop(&vm->ctxts); +} + +static BclContext +bcl_contextHelper(BcVm* vm) +{ + if (!vm->ctxts.len) return NULL; + return *((BclContext*) bc_vec_top(&vm->ctxts)); } BclContext bcl_context(void) { - if (!vm.ctxts.len) return NULL; - return *((BclContext*) bc_vec_top(&vm.ctxts)); + BcVm* vm = bcl_getspecific(); + return bcl_contextHelper(vm); } void bcl_free(void) { size_t i; + BcVm* vm = bcl_getspecific(); - BC_SIG_LOCK; + vm->refs -= 1; + if (vm->refs) return; - vm.refs -= 1; +#if BC_ENABLE_EXTRA_MATH + bc_rand_free(&vm->rng); +#endif // BC_ENABLE_EXTRA_MATH + bc_vec_free(&vm->out); - if (vm.refs) + for (i = 0; i < vm->ctxts.len; ++i) { - BC_SIG_UNLOCK; - return; - } - - bc_rand_free(&vm.rng); - bc_vec_free(&vm.out); - - for (i = 0; i < vm.ctxts.len; ++i) - { - BclContext ctxt = *((BclContext*) bc_vec_item(&vm.ctxts, i)); + BclContext ctxt = *((BclContext*) bc_vec_item(&vm->ctxts, i)); bcl_ctxt_free(ctxt); } - bc_vec_free(&vm.ctxts); + bc_vec_free(&vm->ctxts); bc_vm_atexit(); - BC_SIG_UNLOCK; + free(vm); + bcl_setspecific(NULL); +} + +void +bcl_end(void) +{ +#ifndef _WIN32 - memset(&vm, 0, sizeof(BcVm)); + // We ignore the return value. + pthread_key_delete(tls_real); - assert(!vm.running && !vm.sig && !vm.sig_lock); +#else // _WIN32 + + // We ignore the return value. + TlsFree(tls_real); + +#endif // _WIN32 + + tls = NULL; } void bcl_gc(void) { - BC_SIG_LOCK; bc_vm_freeTemps(); - BC_SIG_UNLOCK; } bool bcl_abortOnFatalError(void) { - return vm.abrt; + BcVm* vm = bcl_getspecific(); + + return vm->abrt; } void bcl_setAbortOnFatalError(bool abrt) { - vm.abrt = abrt; + BcVm* vm = bcl_getspecific(); + + vm->abrt = abrt; } bool bcl_leadingZeroes(void) { - return vm.leading_zeroes; + BcVm* vm = bcl_getspecific(); + + return vm->leading_zeroes; } void bcl_setLeadingZeroes(bool leadingZeroes) { - vm.leading_zeroes = leadingZeroes; + BcVm* vm = bcl_getspecific(); + + vm->leading_zeroes = leadingZeroes; +} + +bool +bcl_digitClamp(void) +{ + BcVm* vm = bcl_getspecific(); + + return vm->digit_clamp; +} + +void +bcl_setDigitClamp(bool digitClamp) +{ + BcVm* vm = bcl_getspecific(); + + vm->digit_clamp = digitClamp; } BclContext bcl_ctxt_create(void) { + BcVm* vm = bcl_getspecific(); BclContext ctxt = NULL; - BC_FUNC_HEADER_LOCK(err); + BC_FUNC_HEADER(vm, err); // We want the context to be free of any interference of other parties, so // malloc() is appropriate here. ctxt = bc_vm_malloc(sizeof(BclCtxt)); - bc_vec_init(&ctxt->nums, sizeof(BcNum), BC_DTOR_BCL_NUM); + bc_vec_init(&ctxt->nums, sizeof(BclNum), BC_DTOR_BCL_NUM); bc_vec_init(&ctxt->free_nums, sizeof(BclNumber), BC_DTOR_NONE); ctxt->scale = 0; @@ -242,16 +400,15 @@ bcl_ctxt_create(void) ctxt->obase = 10; err: - if (BC_ERR(vm.err && ctxt != NULL)) + + if (BC_ERR(vm->err && ctxt != NULL)) { if (ctxt->nums.v != NULL) bc_vec_free(&ctxt->nums); free(ctxt); ctxt = NULL; } - BC_FUNC_FOOTER_NO_ERR; - - assert(!vm.running && !vm.sig && !vm.sig_lock); + BC_FUNC_FOOTER_NO_ERR(vm); return ctxt; } @@ -259,11 +416,9 @@ err: void bcl_ctxt_free(BclContext ctxt) { - BC_SIG_LOCK; bc_vec_free(&ctxt->free_nums); bc_vec_free(&ctxt->nums); free(ctxt); - BC_SIG_UNLOCK; } void @@ -315,8 +470,13 @@ BclError bcl_err(BclNumber n) { BclContext ctxt; + BcVm* vm = bcl_getspecific(); - BC_CHECK_CTXT_ERR(ctxt); + BC_CHECK_CTXT_ERR(vm, ctxt); + + // We need to clear the top byte in memcheck mode. We can do this because + // the parameter is a copy. + BCL_CLEAR_GEN(n); // Errors are encoded as (0 - error_code). If the index is in that range, it // is an encoded error. @@ -335,14 +495,14 @@ bcl_err(BclNumber n) * @return The resulting BclNumber from the insert. */ static BclNumber -bcl_num_insert(BclContext ctxt, BcNum* restrict n) +bcl_num_insert(BclContext ctxt, BclNum* restrict n) { BclNumber idx; // If there is a free spot... if (ctxt->free_nums.len) { - BcNum* ptr; + BclNum* ptr; // Get the index of the free spot and remove it. idx = *((BclNumber*) bc_vec_top(&ctxt->free_nums)); @@ -350,17 +510,34 @@ bcl_num_insert(BclContext ctxt, BcNum* restrict n) // Copy the number into the spot. ptr = bc_vec_item(&ctxt->nums, idx.i); - memcpy(ptr, n, sizeof(BcNum)); + + memcpy(BCL_NUM_NUM(ptr), n, sizeof(BcNum)); + +#if BC_ENABLE_MEMCHECK + + ptr->gen_idx += 1; + + if (ptr->gen_idx == UCHAR_MAX) + { + ptr->gen_idx = 0; + } + + idx.i |= (ptr->gen_idx << ((sizeof(size_t) - 1) * CHAR_BIT)); + +#endif // BC_ENABLE_MEMCHECK } else { - // Just push the number onto the vector. +#if BC_ENABLE_MEMCHECK + n->gen_idx = 0; +#endif // BC_ENABLE_MEMCHECK + + // Just push the number onto the vector because the generation index is + // 0. idx.i = ctxt->nums.len; bc_vec_push(&ctxt->nums, n); } - assert(!vm.running && !vm.sig && !vm.sig_lock); - return idx; } @@ -368,23 +545,23 @@ BclNumber bcl_num_create(void) { BclError e = BCL_ERROR_NONE; - BcNum n; + BclNum n; BclNumber idx; BclContext ctxt; + BcVm* vm = bcl_getspecific(); - BC_CHECK_CTXT(ctxt); + BC_CHECK_CTXT(vm, ctxt); - BC_FUNC_HEADER_LOCK(err); + BC_FUNC_HEADER(vm, err); - bc_vec_grow(&ctxt->nums, 1); + BCL_GROW_NUMS(ctxt); - bc_num_init(&n, BC_NUM_DEF_SIZE); + bc_num_init(BCL_NUM_NUM_NP(n), BC_NUM_DEF_SIZE); err: - BC_FUNC_FOOTER_UNLOCK(e); - BC_MAYBE_SETUP(ctxt, e, n, idx); - assert(!vm.running && !vm.sig && !vm.sig_lock); + BC_FUNC_FOOTER(vm, e); + BC_MAYBE_SETUP(ctxt, e, n, idx); return idx; } @@ -396,61 +573,68 @@ err: * @param num The number to destroy. */ static void -bcl_num_dtor(BclContext ctxt, BclNumber n, BcNum* restrict num) +bcl_num_dtor(BclContext ctxt, BclNumber n, BclNum* restrict num) { - BC_SIG_ASSERT_LOCKED; + assert(num != NULL && BCL_NUM_ARRAY(num) != NULL); - assert(num != NULL && num->num != NULL); + BCL_CLEAR_GEN(n); bcl_num_destruct(num); bc_vec_push(&ctxt->free_nums, &n); + +#if BC_ENABLE_MEMCHECK + num->n.num = NULL; +#endif // BC_ENABLE_MEMCHECK } void bcl_num_free(BclNumber n) { - BcNum* num; + BclNum* num; BclContext ctxt; + BcVm* vm = bcl_getspecific(); - BC_CHECK_CTXT_ASSERT(ctxt); + BC_CHECK_CTXT_ASSERT(vm, ctxt); - BC_SIG_LOCK; + BCL_CHECK_NUM_VALID(ctxt, n); - assert(n.i < ctxt->nums.len); + assert(BCL_NO_GEN(n) < ctxt->nums.len); - num = BC_NUM(ctxt, n); + num = BCL_NUM(ctxt, n); bcl_num_dtor(ctxt, n, num); - - BC_SIG_UNLOCK; } BclError bcl_copy(BclNumber d, BclNumber s) { BclError e = BCL_ERROR_NONE; - BcNum* dest; - BcNum* src; + BclNum* dest; + BclNum* src; BclContext ctxt; + BcVm* vm = bcl_getspecific(); + + BC_CHECK_CTXT_ERR(vm, ctxt); - BC_CHECK_CTXT_ERR(ctxt); + BCL_CHECK_NUM_VALID(ctxt, d); + BCL_CHECK_NUM_VALID(ctxt, s); - BC_FUNC_HEADER_LOCK(err); + BC_FUNC_HEADER(vm, err); - assert(d.i < ctxt->nums.len && s.i < ctxt->nums.len); + assert(BCL_NO_GEN(d) < ctxt->nums.len); + assert(BCL_NO_GEN(s) < ctxt->nums.len); - dest = BC_NUM(ctxt, d); - src = BC_NUM(ctxt, s); + dest = BCL_NUM(ctxt, d); + src = BCL_NUM(ctxt, s); assert(dest != NULL && src != NULL); - assert(dest->num != NULL && src->num != NULL); + assert(BCL_NUM_ARRAY(dest) != NULL && BCL_NUM_ARRAY(src) != NULL); - bc_num_copy(dest, src); + bc_num_copy(BCL_NUM_NUM(dest), BCL_NUM_NUM(src)); err: - BC_FUNC_FOOTER_UNLOCK(e); - assert(!vm.running && !vm.sig && !vm.sig_lock); + BC_FUNC_FOOTER(vm, e); return e; } @@ -459,31 +643,33 @@ BclNumber bcl_dup(BclNumber s) { BclError e = BCL_ERROR_NONE; - BcNum *src, dest; + BclNum *src, dest; BclNumber idx; BclContext ctxt; + BcVm* vm = bcl_getspecific(); - BC_CHECK_CTXT(ctxt); + BC_CHECK_CTXT(vm, ctxt); - BC_FUNC_HEADER_LOCK(err); + BCL_CHECK_NUM_VALID(ctxt, s); - bc_vec_grow(&ctxt->nums, 1); + BC_FUNC_HEADER(vm, err); - assert(s.i < ctxt->nums.len); + BCL_GROW_NUMS(ctxt); - src = BC_NUM(ctxt, s); + assert(BCL_NO_GEN(s) < ctxt->nums.len); - assert(src != NULL && src->num != NULL); + src = BCL_NUM(ctxt, s); + + assert(src != NULL && BCL_NUM_NUM(src) != NULL); // Copy the number. - bc_num_clear(&dest); - bc_num_createCopy(&dest, src); + bc_num_clear(BCL_NUM_NUM(&dest)); + bc_num_createCopy(BCL_NUM_NUM(&dest), BCL_NUM_NUM(src)); err: - BC_FUNC_FOOTER_UNLOCK(e); - BC_MAYBE_SETUP(ctxt, e, dest, idx); - assert(!vm.running && !vm.sig && !vm.sig_lock); + BC_FUNC_FOOTER(vm, e); + BC_MAYBE_SETUP(ctxt, e, dest, idx); return idx; } @@ -491,94 +677,110 @@ err: void bcl_num_destruct(void* num) { - BcNum* n = (BcNum*) num; + BclNum* n = (BclNum*) num; assert(n != NULL); - if (n->num == NULL) return; + if (BCL_NUM_ARRAY(n) == NULL) return; - bc_num_free(num); - bc_num_clear(num); + bc_num_free(BCL_NUM_NUM(n)); + bc_num_clear(BCL_NUM_NUM(n)); } bool bcl_num_neg(BclNumber n) { - BcNum* num; + BclNum* num; BclContext ctxt; + BcVm* vm = bcl_getspecific(); - BC_CHECK_CTXT_ASSERT(ctxt); + BC_CHECK_CTXT_ASSERT(vm, ctxt); - assert(n.i < ctxt->nums.len); + BCL_CHECK_NUM_VALID(ctxt, n); - num = BC_NUM(ctxt, n); + assert(BCL_NO_GEN(n) < ctxt->nums.len); - assert(num != NULL && num->num != NULL); + num = BCL_NUM(ctxt, n); - return BC_NUM_NEG(num) != 0; + assert(num != NULL && BCL_NUM_ARRAY(num) != NULL); + + return BC_NUM_NEG(BCL_NUM_NUM(num)) != 0; } void bcl_num_setNeg(BclNumber n, bool neg) { - BcNum* num; + BclNum* num; BclContext ctxt; + BcVm* vm = bcl_getspecific(); + + BC_CHECK_CTXT_ASSERT(vm, ctxt); - BC_CHECK_CTXT_ASSERT(ctxt); + BCL_CHECK_NUM_VALID(ctxt, n); - assert(n.i < ctxt->nums.len); + assert(BCL_NO_GEN(n) < ctxt->nums.len); - num = BC_NUM(ctxt, n); + num = BCL_NUM(ctxt, n); - assert(num != NULL && num->num != NULL); + assert(num != NULL && BCL_NUM_ARRAY(num) != NULL); - num->rdx = BC_NUM_NEG_VAL(num, neg); + BCL_NUM_NUM(num)->rdx = BC_NUM_NEG_VAL(BCL_NUM_NUM(num), neg); } size_t bcl_num_scale(BclNumber n) { - BcNum* num; + BclNum* num; BclContext ctxt; + BcVm* vm = bcl_getspecific(); - BC_CHECK_CTXT_ASSERT(ctxt); + BC_CHECK_CTXT_ASSERT(vm, ctxt); - assert(n.i < ctxt->nums.len); + BCL_CHECK_NUM_VALID(ctxt, n); - num = BC_NUM(ctxt, n); + assert(BCL_NO_GEN(n) < ctxt->nums.len); - assert(num != NULL && num->num != NULL); + num = BCL_NUM(ctxt, n); - return bc_num_scale(num); + assert(num != NULL && BCL_NUM_ARRAY(num) != NULL); + + return bc_num_scale(BCL_NUM_NUM(num)); } BclError bcl_num_setScale(BclNumber n, size_t scale) { BclError e = BCL_ERROR_NONE; - BcNum* nptr; + BclNum* nptr; BclContext ctxt; + BcVm* vm = bcl_getspecific(); - BC_CHECK_CTXT_ERR(ctxt); + BC_CHECK_CTXT_ERR(vm, ctxt); BC_CHECK_NUM_ERR(ctxt, n); - BC_FUNC_HEADER(err); + BCL_CHECK_NUM_VALID(ctxt, n); + + BC_FUNC_HEADER(vm, err); - assert(n.i < ctxt->nums.len); + assert(BCL_NO_GEN(n) < ctxt->nums.len); - nptr = BC_NUM(ctxt, n); + nptr = BCL_NUM(ctxt, n); - assert(nptr != NULL && nptr->num != NULL); + assert(nptr != NULL && BCL_NUM_ARRAY(nptr) != NULL); - if (scale > nptr->scale) bc_num_extend(nptr, scale - nptr->scale); - else if (scale < nptr->scale) bc_num_truncate(nptr, nptr->scale - scale); + if (scale > BCL_NUM_NUM(nptr)->scale) + { + bc_num_extend(BCL_NUM_NUM(nptr), scale - BCL_NUM_NUM(nptr)->scale); + } + else if (scale < BCL_NUM_NUM(nptr)->scale) + { + bc_num_truncate(BCL_NUM_NUM(nptr), BCL_NUM_NUM(nptr)->scale - scale); + } err: - BC_SIG_MAYLOCK; - BC_FUNC_FOOTER(e); - assert(!vm.running && !vm.sig && !vm.sig_lock); + BC_FUNC_FOOTER(vm, e); return e; } @@ -586,420 +788,542 @@ err: size_t bcl_num_len(BclNumber n) { - BcNum* num; + BclNum* num; BclContext ctxt; + BcVm* vm = bcl_getspecific(); + + BC_CHECK_CTXT_ASSERT(vm, ctxt); - BC_CHECK_CTXT_ASSERT(ctxt); + BCL_CHECK_NUM_VALID(ctxt, n); - assert(n.i < ctxt->nums.len); + assert(BCL_NO_GEN(n) < ctxt->nums.len); - num = BC_NUM(ctxt, n); + num = BCL_NUM(ctxt, n); - assert(num != NULL && num->num != NULL); + assert(num != NULL && BCL_NUM_ARRAY(num) != NULL); - return bc_num_len(num); + return bc_num_len(BCL_NUM_NUM(num)); } -BclError -bcl_bigdig(BclNumber n, BclBigDig* result) +static BclError +bcl_bigdig_helper(BclNumber n, BclBigDig* result, bool destruct) { BclError e = BCL_ERROR_NONE; - BcNum* num; + BclNum* num; BclContext ctxt; + BcVm* vm = bcl_getspecific(); - BC_CHECK_CTXT_ERR(ctxt); + BC_CHECK_CTXT_ERR(vm, ctxt); - BC_FUNC_HEADER_LOCK(err); + BCL_CHECK_NUM_VALID(ctxt, n); - assert(n.i < ctxt->nums.len); + BC_FUNC_HEADER(vm, err); + + assert(BCL_NO_GEN(n) < ctxt->nums.len); assert(result != NULL); - num = BC_NUM(ctxt, n); + num = BCL_NUM(ctxt, n); - assert(num != NULL && num->num != NULL); + assert(num != NULL && BCL_NUM_ARRAY(num) != NULL); - *result = bc_num_bigdig(num); + *result = bc_num_bigdig(BCL_NUM_NUM(num)); err: - bcl_num_dtor(ctxt, n, num); - BC_FUNC_FOOTER_UNLOCK(e); - assert(!vm.running && !vm.sig && !vm.sig_lock); + if (destruct) + { + bcl_num_dtor(ctxt, n, num); + } + + BC_FUNC_FOOTER(vm, e); return e; } +BclError +bcl_bigdig(BclNumber n, BclBigDig* result) +{ + return bcl_bigdig_helper(n, result, true); +} + +BclError +bcl_bigdig_keep(BclNumber n, BclBigDig* result) +{ + return bcl_bigdig_helper(n, result, false); +} + BclNumber bcl_bigdig2num(BclBigDig val) { BclError e = BCL_ERROR_NONE; - BcNum n; + BclNum n; BclNumber idx; BclContext ctxt; + BcVm* vm = bcl_getspecific(); - BC_CHECK_CTXT(ctxt); + BC_CHECK_CTXT(vm, ctxt); - BC_FUNC_HEADER_LOCK(err); + BC_FUNC_HEADER(vm, err); - bc_vec_grow(&ctxt->nums, 1); + BCL_GROW_NUMS(ctxt); - bc_num_createFromBigdig(&n, val); + bc_num_createFromBigdig(BCL_NUM_NUM_NP(n), val); err: - BC_FUNC_FOOTER_UNLOCK(e); - BC_MAYBE_SETUP(ctxt, e, n, idx); - assert(!vm.running && !vm.sig && !vm.sig_lock); + BC_FUNC_FOOTER(vm, e); + BC_MAYBE_SETUP(ctxt, e, n, idx); return idx; } /** * Sets up and executes a binary operator operation. - * @param a The first operand. - * @param b The second operand. - * @param op The operation. - * @param req The function to get the size of the result for preallocation. - * @return The result of the operation. + * @param a The first operand. + * @param b The second operand. + * @param op The operation. + * @param req The function to get the size of the result for + * preallocation. + * @param destruct True if the parameters should be consumed, false otherwise. + * @return The result of the operation. */ static BclNumber bcl_binary(BclNumber a, BclNumber b, const BcNumBinaryOp op, - const BcNumBinaryOpReq req) + const BcNumBinaryOpReq req, bool destruct) { BclError e = BCL_ERROR_NONE; - BcNum* aptr; - BcNum* bptr; - BcNum c; + BclNum* aptr; + BclNum* bptr; + BclNum c; BclNumber idx; BclContext ctxt; + BcVm* vm = bcl_getspecific(); - BC_CHECK_CTXT(ctxt); + BC_CHECK_CTXT(vm, ctxt); BC_CHECK_NUM(ctxt, a); BC_CHECK_NUM(ctxt, b); - BC_FUNC_HEADER_LOCK(err); + BC_FUNC_HEADER(vm, err); - bc_vec_grow(&ctxt->nums, 1); + BCL_GROW_NUMS(ctxt); - assert(a.i < ctxt->nums.len && b.i < ctxt->nums.len); + assert(BCL_NO_GEN(a) < ctxt->nums.len && BCL_NO_GEN(b) < ctxt->nums.len); - aptr = BC_NUM(ctxt, a); - bptr = BC_NUM(ctxt, b); + aptr = BCL_NUM(ctxt, a); + bptr = BCL_NUM(ctxt, b); assert(aptr != NULL && bptr != NULL); - assert(aptr->num != NULL && bptr->num != NULL); + assert(BCL_NUM_ARRAY(aptr) != NULL && BCL_NUM_ARRAY(bptr) != NULL); // Clear and initialize the result. - bc_num_clear(&c); - bc_num_init(&c, req(aptr, bptr, ctxt->scale)); - - BC_SIG_UNLOCK; + bc_num_clear(BCL_NUM_NUM_NP(c)); + bc_num_init(BCL_NUM_NUM_NP(c), + req(BCL_NUM_NUM(aptr), BCL_NUM_NUM(bptr), ctxt->scale)); - op(aptr, bptr, &c, ctxt->scale); + op(BCL_NUM_NUM(aptr), BCL_NUM_NUM(bptr), BCL_NUM_NUM_NP(c), ctxt->scale); err: - BC_SIG_MAYLOCK; - - // Eat the operands. - bcl_num_dtor(ctxt, a, aptr); - if (b.i != a.i) bcl_num_dtor(ctxt, b, bptr); + if (destruct) + { + // Eat the operands. + bcl_num_dtor(ctxt, a, aptr); + if (b.i != a.i) bcl_num_dtor(ctxt, b, bptr); + } - BC_FUNC_FOOTER(e); + BC_FUNC_FOOTER(vm, e); BC_MAYBE_SETUP(ctxt, e, c, idx); - assert(!vm.running && !vm.sig && !vm.sig_lock); - return idx; } BclNumber bcl_add(BclNumber a, BclNumber b) { - return bcl_binary(a, b, bc_num_add, bc_num_addReq); + return bcl_binary(a, b, bc_num_add, bc_num_addReq, true); +} + +BclNumber +bcl_add_keep(BclNumber a, BclNumber b) +{ + return bcl_binary(a, b, bc_num_add, bc_num_addReq, false); } BclNumber bcl_sub(BclNumber a, BclNumber b) { - return bcl_binary(a, b, bc_num_sub, bc_num_addReq); + return bcl_binary(a, b, bc_num_sub, bc_num_addReq, true); +} + +BclNumber +bcl_sub_keep(BclNumber a, BclNumber b) +{ + return bcl_binary(a, b, bc_num_sub, bc_num_addReq, false); } BclNumber bcl_mul(BclNumber a, BclNumber b) { - return bcl_binary(a, b, bc_num_mul, bc_num_mulReq); + return bcl_binary(a, b, bc_num_mul, bc_num_mulReq, true); +} + +BclNumber +bcl_mul_keep(BclNumber a, BclNumber b) +{ + return bcl_binary(a, b, bc_num_mul, bc_num_mulReq, false); } BclNumber bcl_div(BclNumber a, BclNumber b) { - return bcl_binary(a, b, bc_num_div, bc_num_divReq); + return bcl_binary(a, b, bc_num_div, bc_num_divReq, true); +} + +BclNumber +bcl_div_keep(BclNumber a, BclNumber b) +{ + return bcl_binary(a, b, bc_num_div, bc_num_divReq, false); } BclNumber bcl_mod(BclNumber a, BclNumber b) { - return bcl_binary(a, b, bc_num_mod, bc_num_divReq); + return bcl_binary(a, b, bc_num_mod, bc_num_divReq, true); +} + +BclNumber +bcl_mod_keep(BclNumber a, BclNumber b) +{ + return bcl_binary(a, b, bc_num_mod, bc_num_divReq, false); } BclNumber bcl_pow(BclNumber a, BclNumber b) { - return bcl_binary(a, b, bc_num_pow, bc_num_powReq); + return bcl_binary(a, b, bc_num_pow, bc_num_powReq, true); +} + +BclNumber +bcl_pow_keep(BclNumber a, BclNumber b) +{ + return bcl_binary(a, b, bc_num_pow, bc_num_powReq, false); } BclNumber bcl_lshift(BclNumber a, BclNumber b) { - return bcl_binary(a, b, bc_num_lshift, bc_num_placesReq); + return bcl_binary(a, b, bc_num_lshift, bc_num_placesReq, true); +} + +BclNumber +bcl_lshift_keep(BclNumber a, BclNumber b) +{ + return bcl_binary(a, b, bc_num_lshift, bc_num_placesReq, false); } BclNumber bcl_rshift(BclNumber a, BclNumber b) { - return bcl_binary(a, b, bc_num_rshift, bc_num_placesReq); + return bcl_binary(a, b, bc_num_rshift, bc_num_placesReq, true); } BclNumber -bcl_sqrt(BclNumber a) +bcl_rshift_keep(BclNumber a, BclNumber b) +{ + return bcl_binary(a, b, bc_num_rshift, bc_num_placesReq, false); +} + +static BclNumber +bcl_sqrt_helper(BclNumber a, bool destruct) { BclError e = BCL_ERROR_NONE; - BcNum* aptr; - BcNum b; + BclNum* aptr; + BclNum b; BclNumber idx; BclContext ctxt; + BcVm* vm = bcl_getspecific(); - BC_CHECK_CTXT(ctxt); + BC_CHECK_CTXT(vm, ctxt); BC_CHECK_NUM(ctxt, a); - BC_FUNC_HEADER(err); + BC_FUNC_HEADER(vm, err); - bc_vec_grow(&ctxt->nums, 1); + BCL_GROW_NUMS(ctxt); - assert(a.i < ctxt->nums.len); + assert(BCL_NO_GEN(a) < ctxt->nums.len); - aptr = BC_NUM(ctxt, a); + aptr = BCL_NUM(ctxt, a); - bc_num_sqrt(aptr, &b, ctxt->scale); + bc_num_sqrt(BCL_NUM_NUM(aptr), BCL_NUM_NUM_NP(b), ctxt->scale); err: - BC_SIG_MAYLOCK; - bcl_num_dtor(ctxt, a, aptr); - BC_FUNC_FOOTER(e); - BC_MAYBE_SETUP(ctxt, e, b, idx); - assert(!vm.running && !vm.sig && !vm.sig_lock); + if (destruct) + { + bcl_num_dtor(ctxt, a, aptr); + } + + BC_FUNC_FOOTER(vm, e); + BC_MAYBE_SETUP(ctxt, e, b, idx); return idx; } -BclError -bcl_divmod(BclNumber a, BclNumber b, BclNumber* c, BclNumber* d) +BclNumber +bcl_sqrt(BclNumber a) +{ + return bcl_sqrt_helper(a, true); +} + +BclNumber +bcl_sqrt_keep(BclNumber a) +{ + return bcl_sqrt_helper(a, false); +} + +static BclError +bcl_divmod_helper(BclNumber a, BclNumber b, BclNumber* c, BclNumber* d, + bool destruct) { BclError e = BCL_ERROR_NONE; size_t req; - BcNum* aptr; - BcNum* bptr; - BcNum cnum, dnum; + BclNum* aptr; + BclNum* bptr; + BclNum cnum, dnum; BclContext ctxt; + BcVm* vm = bcl_getspecific(); - BC_CHECK_CTXT_ERR(ctxt); + BC_CHECK_CTXT_ERR(vm, ctxt); BC_CHECK_NUM_ERR(ctxt, a); BC_CHECK_NUM_ERR(ctxt, b); - BC_FUNC_HEADER_LOCK(err); + BC_FUNC_HEADER(vm, err); - bc_vec_grow(&ctxt->nums, 2); + BCL_GROW_NUMS(ctxt); assert(c != NULL && d != NULL); - aptr = BC_NUM(ctxt, a); - bptr = BC_NUM(ctxt, b); + aptr = BCL_NUM(ctxt, a); + bptr = BCL_NUM(ctxt, b); assert(aptr != NULL && bptr != NULL); - assert(aptr->num != NULL && bptr->num != NULL); + assert(BCL_NUM_ARRAY(aptr) != NULL && BCL_NUM_ARRAY(bptr) != NULL); - bc_num_clear(&cnum); - bc_num_clear(&dnum); + bc_num_clear(BCL_NUM_NUM_NP(cnum)); + bc_num_clear(BCL_NUM_NUM_NP(dnum)); - req = bc_num_divReq(aptr, bptr, ctxt->scale); + req = bc_num_divReq(BCL_NUM_NUM(aptr), BCL_NUM_NUM(bptr), ctxt->scale); // Initialize the numbers. - bc_num_init(&cnum, req); - BC_UNSETJMP; - BC_SETJMP_LOCKED(err); - bc_num_init(&dnum, req); - - BC_SIG_UNLOCK; + bc_num_init(BCL_NUM_NUM_NP(cnum), req); + BC_UNSETJMP(vm); + BC_SETJMP(vm, err); + bc_num_init(BCL_NUM_NUM_NP(dnum), req); - bc_num_divmod(aptr, bptr, &cnum, &dnum, ctxt->scale); + bc_num_divmod(BCL_NUM_NUM(aptr), BCL_NUM_NUM(bptr), BCL_NUM_NUM_NP(cnum), + BCL_NUM_NUM_NP(dnum), ctxt->scale); err: - BC_SIG_MAYLOCK; - // Eat the operands. - bcl_num_dtor(ctxt, a, aptr); - if (b.i != a.i) bcl_num_dtor(ctxt, b, bptr); + if (destruct) + { + // Eat the operands. + bcl_num_dtor(ctxt, a, aptr); + if (b.i != a.i) bcl_num_dtor(ctxt, b, bptr); + } // If there was an error... - if (BC_ERR(vm.err)) + if (BC_ERR(vm->err)) { // Free the results. - if (cnum.num != NULL) bc_num_free(&cnum); - if (dnum.num != NULL) bc_num_free(&dnum); + if (BCL_NUM_ARRAY_NP(cnum) != NULL) bc_num_free(&cnum); + if (BCL_NUM_ARRAY_NP(cnum) != NULL) bc_num_free(&dnum); // Make sure the return values are invalid. c->i = 0 - (size_t) BCL_ERROR_INVALID_NUM; d->i = c->i; - BC_FUNC_FOOTER(e); + BC_FUNC_FOOTER(vm, e); } else { - BC_FUNC_FOOTER(e); + BC_FUNC_FOOTER(vm, e); // Insert the results into the context. *c = bcl_num_insert(ctxt, &cnum); *d = bcl_num_insert(ctxt, &dnum); } - assert(!vm.running && !vm.sig && !vm.sig_lock); - return e; } -BclNumber -bcl_modexp(BclNumber a, BclNumber b, BclNumber c) +BclError +bcl_divmod(BclNumber a, BclNumber b, BclNumber* c, BclNumber* d) +{ + return bcl_divmod_helper(a, b, c, d, true); +} + +BclError +bcl_divmod_keep(BclNumber a, BclNumber b, BclNumber* c, BclNumber* d) +{ + return bcl_divmod_helper(a, b, c, d, false); +} + +static BclNumber +bcl_modexp_helper(BclNumber a, BclNumber b, BclNumber c, bool destruct) { BclError e = BCL_ERROR_NONE; size_t req; - BcNum* aptr; - BcNum* bptr; - BcNum* cptr; - BcNum d; + BclNum* aptr; + BclNum* bptr; + BclNum* cptr; + BclNum d; BclNumber idx; BclContext ctxt; + BcVm* vm = bcl_getspecific(); - BC_CHECK_CTXT(ctxt); + BC_CHECK_CTXT(vm, ctxt); BC_CHECK_NUM(ctxt, a); BC_CHECK_NUM(ctxt, b); BC_CHECK_NUM(ctxt, c); - BC_FUNC_HEADER_LOCK(err); + BC_FUNC_HEADER(vm, err); - bc_vec_grow(&ctxt->nums, 1); + BCL_GROW_NUMS(ctxt); - assert(a.i < ctxt->nums.len && b.i < ctxt->nums.len); - assert(c.i < ctxt->nums.len); + assert(BCL_NO_GEN(a) < ctxt->nums.len && BCL_NO_GEN(b) < ctxt->nums.len); + assert(BCL_NO_GEN(c) < ctxt->nums.len); - aptr = BC_NUM(ctxt, a); - bptr = BC_NUM(ctxt, b); - cptr = BC_NUM(ctxt, c); + aptr = BCL_NUM(ctxt, a); + bptr = BCL_NUM(ctxt, b); + cptr = BCL_NUM(ctxt, c); assert(aptr != NULL && bptr != NULL && cptr != NULL); - assert(aptr->num != NULL && bptr->num != NULL && cptr->num != NULL); + assert(BCL_NUM_NUM(aptr) != NULL && BCL_NUM_NUM(bptr) != NULL && + BCL_NUM_NUM(cptr) != NULL); // Prepare the result. - bc_num_clear(&d); + bc_num_clear(BCL_NUM_NUM_NP(d)); - req = bc_num_divReq(aptr, cptr, 0); + req = bc_num_divReq(BCL_NUM_NUM(aptr), BCL_NUM_NUM(cptr), 0); // Initialize the result. - bc_num_init(&d, req); + bc_num_init(BCL_NUM_NUM_NP(d), req); - BC_SIG_UNLOCK; - - bc_num_modexp(aptr, bptr, cptr, &d); + bc_num_modexp(BCL_NUM_NUM(aptr), BCL_NUM_NUM(bptr), BCL_NUM_NUM(cptr), + BCL_NUM_NUM_NP(d)); err: - BC_SIG_MAYLOCK; - // Eat the operands. - bcl_num_dtor(ctxt, a, aptr); - if (b.i != a.i) bcl_num_dtor(ctxt, b, bptr); - if (c.i != a.i && c.i != b.i) bcl_num_dtor(ctxt, c, cptr); + if (destruct) + { + // Eat the operands. + bcl_num_dtor(ctxt, a, aptr); + if (b.i != a.i) bcl_num_dtor(ctxt, b, bptr); + if (c.i != a.i && c.i != b.i) bcl_num_dtor(ctxt, c, cptr); + } - BC_FUNC_FOOTER(e); + BC_FUNC_FOOTER(vm, e); BC_MAYBE_SETUP(ctxt, e, d, idx); - assert(!vm.running && !vm.sig && !vm.sig_lock); - return idx; } +BclNumber +bcl_modexp(BclNumber a, BclNumber b, BclNumber c) +{ + return bcl_modexp_helper(a, b, c, true); +} + +BclNumber +bcl_modexp_keep(BclNumber a, BclNumber b, BclNumber c) +{ + return bcl_modexp_helper(a, b, c, false); +} + ssize_t bcl_cmp(BclNumber a, BclNumber b) { - BcNum* aptr; - BcNum* bptr; + BclNum* aptr; + BclNum* bptr; BclContext ctxt; + BcVm* vm = bcl_getspecific(); + + BC_CHECK_CTXT_ASSERT(vm, ctxt); - BC_CHECK_CTXT_ASSERT(ctxt); + BCL_CHECK_NUM_VALID(ctxt, a); + BCL_CHECK_NUM_VALID(ctxt, b); - assert(a.i < ctxt->nums.len && b.i < ctxt->nums.len); + assert(BCL_NO_GEN(a) < ctxt->nums.len && BCL_NO_GEN(b) < ctxt->nums.len); - aptr = BC_NUM(ctxt, a); - bptr = BC_NUM(ctxt, b); + aptr = BCL_NUM(ctxt, a); + bptr = BCL_NUM(ctxt, b); assert(aptr != NULL && bptr != NULL); - assert(aptr->num != NULL && bptr->num != NULL); + assert(BCL_NUM_NUM(aptr) != NULL && BCL_NUM_NUM(bptr)); - return bc_num_cmp(aptr, bptr); + return bc_num_cmp(BCL_NUM_NUM(aptr), BCL_NUM_NUM(bptr)); } void bcl_zero(BclNumber n) { - BcNum* nptr; + BclNum* nptr; BclContext ctxt; + BcVm* vm = bcl_getspecific(); - BC_CHECK_CTXT_ASSERT(ctxt); + BC_CHECK_CTXT_ASSERT(vm, ctxt); - assert(n.i < ctxt->nums.len); + BCL_CHECK_NUM_VALID(ctxt, n); - nptr = BC_NUM(ctxt, n); + assert(BCL_NO_GEN(n) < ctxt->nums.len); - assert(nptr != NULL && nptr->num != NULL); + nptr = BCL_NUM(ctxt, n); - bc_num_zero(nptr); + assert(nptr != NULL && BCL_NUM_NUM(nptr) != NULL); + + bc_num_zero(BCL_NUM_NUM(nptr)); } void bcl_one(BclNumber n) { - BcNum* nptr; + BclNum* nptr; BclContext ctxt; + BcVm* vm = bcl_getspecific(); + + BC_CHECK_CTXT_ASSERT(vm, ctxt); - BC_CHECK_CTXT_ASSERT(ctxt); + BCL_CHECK_NUM_VALID(ctxt, n); - assert(n.i < ctxt->nums.len); + assert(BCL_NO_GEN(n) < ctxt->nums.len); - nptr = BC_NUM(ctxt, n); + nptr = BCL_NUM(ctxt, n); - assert(nptr != NULL && nptr->num != NULL); + assert(nptr != NULL && BCL_NUM_NUM(nptr) != NULL); - bc_num_one(nptr); + bc_num_one(BCL_NUM_NUM(nptr)); } BclNumber bcl_parse(const char* restrict val) { BclError e = BCL_ERROR_NONE; - BcNum n; + BclNum n; BclNumber idx; BclContext ctxt; + BcVm* vm = bcl_getspecific(); bool neg; - BC_CHECK_CTXT(ctxt); + BC_CHECK_CTXT(vm, ctxt); - BC_FUNC_HEADER_LOCK(err); + BC_FUNC_HEADER(vm, err); - bc_vec_grow(&ctxt->nums, 1); + BCL_GROW_NUMS(ctxt); assert(val != NULL); @@ -1011,119 +1335,146 @@ bcl_parse(const char* restrict val) if (!bc_num_strValid(val)) { - vm.err = BCL_ERROR_PARSE_INVALID_STR; + vm->err = BCL_ERROR_PARSE_INVALID_STR; goto err; } // Clear and initialize the number. - bc_num_clear(&n); - bc_num_init(&n, BC_NUM_DEF_SIZE); - - BC_SIG_UNLOCK; + bc_num_clear(BCL_NUM_NUM_NP(n)); + bc_num_init(BCL_NUM_NUM_NP(n), BC_NUM_DEF_SIZE); - bc_num_parse(&n, val, (BcBigDig) ctxt->ibase); + bc_num_parse(BCL_NUM_NUM_NP(n), val, (BcBigDig) ctxt->ibase); // Set the negative. +#if BC_ENABLE_MEMCHECK + n.n.rdx = BC_NUM_NEG_VAL(BCL_NUM_NUM_NP(n), neg); +#else // BC_ENABLE_MEMCHECK n.rdx = BC_NUM_NEG_VAL_NP(n, neg); +#endif // BC_ENABLE_MEMCHECK err: - BC_SIG_MAYLOCK; - BC_FUNC_FOOTER(e); - BC_MAYBE_SETUP(ctxt, e, n, idx); - assert(!vm.running && !vm.sig && !vm.sig_lock); + BC_FUNC_FOOTER(vm, e); + BC_MAYBE_SETUP(ctxt, e, n, idx); return idx; } -char* -bcl_string(BclNumber n) +static char* +bcl_string_helper(BclNumber n, bool destruct) { - BcNum* nptr; + BclNum* nptr; char* str = NULL; BclContext ctxt; + BcVm* vm = bcl_getspecific(); - BC_CHECK_CTXT_ASSERT(ctxt); + BC_CHECK_CTXT_ASSERT(vm, ctxt); - if (BC_ERR(n.i >= ctxt->nums.len)) return str; + BCL_CHECK_NUM_VALID(ctxt, n); - BC_FUNC_HEADER(err); + if (BC_ERR(BCL_NO_GEN(n) >= ctxt->nums.len)) return str; - assert(n.i < ctxt->nums.len); + BC_FUNC_HEADER(vm, err); - nptr = BC_NUM(ctxt, n); + assert(BCL_NO_GEN(n) < ctxt->nums.len); - assert(nptr != NULL && nptr->num != NULL); + nptr = BCL_NUM(ctxt, n); + + assert(nptr != NULL && BCL_NUM_NUM(nptr) != NULL); // Clear the buffer. - bc_vec_popAll(&vm.out); + bc_vec_popAll(&vm->out); // Print to the buffer. - bc_num_print(nptr, (BcBigDig) ctxt->obase, false); - bc_vec_pushByte(&vm.out, '\0'); - - BC_SIG_LOCK; + bc_num_print(BCL_NUM_NUM(nptr), (BcBigDig) ctxt->obase, false); + bc_vec_pushByte(&vm->out, '\0'); // Just dup the string; the caller is responsible for it. - str = bc_vm_strdup(vm.out.v); + str = bc_vm_strdup(vm->out.v); err: - // Eat the operand. - bcl_num_dtor(ctxt, n, nptr); - - BC_FUNC_FOOTER_NO_ERR; + if (destruct) + { + // Eat the operand. + bcl_num_dtor(ctxt, n, nptr); + } - assert(!vm.running && !vm.sig && !vm.sig_lock); + BC_FUNC_FOOTER_NO_ERR(vm); return str; } -BclNumber -bcl_irand(BclNumber a) +char* +bcl_string(BclNumber n) +{ + return bcl_string_helper(n, true); +} + +char* +bcl_string_keep(BclNumber n) +{ + return bcl_string_helper(n, false); +} + +#if BC_ENABLE_EXTRA_MATH + +static BclNumber +bcl_irand_helper(BclNumber a, bool destruct) { BclError e = BCL_ERROR_NONE; - BcNum* aptr; - BcNum b; + BclNum* aptr; + BclNum b; BclNumber idx; BclContext ctxt; + BcVm* vm = bcl_getspecific(); - BC_CHECK_CTXT(ctxt); + BC_CHECK_CTXT(vm, ctxt); BC_CHECK_NUM(ctxt, a); - BC_FUNC_HEADER_LOCK(err); + BC_FUNC_HEADER(vm, err); - bc_vec_grow(&ctxt->nums, 1); + BCL_GROW_NUMS(ctxt); - assert(a.i < ctxt->nums.len); + assert(BCL_NO_GEN(a) < ctxt->nums.len); - aptr = BC_NUM(ctxt, a); + aptr = BCL_NUM(ctxt, a); - assert(aptr != NULL && aptr->num != NULL); + assert(aptr != NULL && BCL_NUM_NUM(aptr) != NULL); // Clear and initialize the result. - bc_num_clear(&b); - bc_num_init(&b, BC_NUM_DEF_SIZE); - - BC_SIG_UNLOCK; + bc_num_clear(BCL_NUM_NUM_NP(b)); + bc_num_init(BCL_NUM_NUM_NP(b), BC_NUM_DEF_SIZE); - bc_num_irand(aptr, &b, &vm.rng); + bc_num_irand(BCL_NUM_NUM(aptr), BCL_NUM_NUM_NP(b), &vm->rng); err: - BC_SIG_MAYLOCK; - // Eat the operand. - bcl_num_dtor(ctxt, a, aptr); + if (destruct) + { + // Eat the operand. + bcl_num_dtor(ctxt, a, aptr); + } - BC_FUNC_FOOTER(e); + BC_FUNC_FOOTER(vm, e); BC_MAYBE_SETUP(ctxt, e, b, idx); - assert(!vm.running && !vm.sig && !vm.sig_lock); - return idx; } +BclNumber +bcl_irand(BclNumber a) +{ + return bcl_irand_helper(a, true); +} + +BclNumber +bcl_irand_keep(BclNumber a) +{ + return bcl_irand_helper(a, false); +} + /** * Helps bcl_frand(). This is separate because the error handling is easier that * way. It is also easier to do ifrand that way. @@ -1136,6 +1487,7 @@ bcl_frandHelper(BcNum* restrict b, size_t places) BcNum exp, pow, ten; BcDig exp_digs[BC_NUM_BIGDIG_LOG10]; BcDig ten_digs[BC_NUM_BIGDIG_LOG10]; + BcVm* vm = bcl_getspecific(); // Set up temporaries. bc_num_setup(&exp, exp_digs, BC_NUM_BIGDIG_LOG10); @@ -1149,58 +1501,50 @@ bcl_frandHelper(BcNum* restrict b, size_t places) // Clear the temporary that might need to grow. bc_num_clear(&pow); - BC_SIG_LOCK; - // Initialize the temporary that might need to grow. bc_num_init(&pow, bc_num_powReq(&ten, &exp, 0)); - BC_SETJMP_LOCKED(err); - - BC_SIG_UNLOCK; + BC_SETJMP(vm, err); // Generate the number. bc_num_pow(&ten, &exp, &pow, 0); - bc_num_irand(&pow, b, &vm.rng); + bc_num_irand(&pow, b, &vm->rng); // Make the number entirely fraction. bc_num_shiftRight(b, places); err: - BC_SIG_MAYLOCK; + bc_num_free(&pow); - BC_LONGJMP_CONT; + BC_LONGJMP_CONT(vm); } BclNumber bcl_frand(size_t places) { BclError e = BCL_ERROR_NONE; - BcNum n; + BclNum n; BclNumber idx; BclContext ctxt; + BcVm* vm = bcl_getspecific(); - BC_CHECK_CTXT(ctxt); + BC_CHECK_CTXT(vm, ctxt); - BC_FUNC_HEADER_LOCK(err); + BC_FUNC_HEADER(vm, err); - bc_vec_grow(&ctxt->nums, 1); + BCL_GROW_NUMS(ctxt); // Clear and initialize the number. - bc_num_clear(&n); - bc_num_init(&n, BC_NUM_DEF_SIZE); + bc_num_clear(BCL_NUM_NUM_NP(n)); + bc_num_init(BCL_NUM_NUM_NP(n), BC_NUM_DEF_SIZE); - BC_SIG_UNLOCK; - - bcl_frandHelper(&n, places); + bcl_frandHelper(BCL_NUM_NUM_NP(n), places); err: - BC_SIG_MAYLOCK; - BC_FUNC_FOOTER(e); + BC_FUNC_FOOTER(vm, e); BC_MAYBE_SETUP(ctxt, e, n, idx); - assert(!vm.running && !vm.sig && !vm.sig_lock); - return idx; } @@ -1215,114 +1559,140 @@ static void bcl_ifrandHelper(BcNum* restrict a, BcNum* restrict b, size_t places) { BcNum ir, fr; + BcVm* vm = bcl_getspecific(); // Clear the integer and fractional numbers. bc_num_clear(&ir); bc_num_clear(&fr); - BC_SIG_LOCK; - // Initialize the integer and fractional numbers. bc_num_init(&ir, BC_NUM_DEF_SIZE); bc_num_init(&fr, BC_NUM_DEF_SIZE); - BC_SETJMP_LOCKED(err); - - BC_SIG_UNLOCK; + BC_SETJMP(vm, err); - bc_num_irand(a, &ir, &vm.rng); + bc_num_irand(a, &ir, &vm->rng); bcl_frandHelper(&fr, places); bc_num_add(&ir, &fr, b, 0); err: - BC_SIG_MAYLOCK; + bc_num_free(&fr); bc_num_free(&ir); - BC_LONGJMP_CONT; + BC_LONGJMP_CONT(vm); } -BclNumber -bcl_ifrand(BclNumber a, size_t places) +static BclNumber +bcl_ifrand_helper(BclNumber a, size_t places, bool destruct) { BclError e = BCL_ERROR_NONE; - BcNum* aptr; - BcNum b; + BclNum* aptr; + BclNum b; BclNumber idx; BclContext ctxt; + BcVm* vm = bcl_getspecific(); - BC_CHECK_CTXT(ctxt); + BC_CHECK_CTXT(vm, ctxt); BC_CHECK_NUM(ctxt, a); - BC_FUNC_HEADER_LOCK(err); + BC_FUNC_HEADER(vm, err); - bc_vec_grow(&ctxt->nums, 1); + BCL_GROW_NUMS(ctxt); - assert(a.i < ctxt->nums.len); + assert(BCL_NO_GEN(a) < ctxt->nums.len); - aptr = BC_NUM(ctxt, a); + aptr = BCL_NUM(ctxt, a); - assert(aptr != NULL && aptr->num != NULL); + assert(aptr != NULL && BCL_NUM_NUM(aptr) != NULL); // Clear and initialize the number. - bc_num_clear(&b); - bc_num_init(&b, BC_NUM_DEF_SIZE); - - BC_SIG_UNLOCK; + bc_num_clear(BCL_NUM_NUM_NP(b)); + bc_num_init(BCL_NUM_NUM_NP(b), BC_NUM_DEF_SIZE); - bcl_ifrandHelper(aptr, &b, places); + bcl_ifrandHelper(BCL_NUM_NUM(aptr), BCL_NUM_NUM_NP(b), places); err: - BC_SIG_MAYLOCK; - // Eat the oprand. - bcl_num_dtor(ctxt, a, aptr); + if (destruct) + { + // Eat the oprand. + bcl_num_dtor(ctxt, a, aptr); + } - BC_FUNC_FOOTER(e); + BC_FUNC_FOOTER(vm, e); BC_MAYBE_SETUP(ctxt, e, b, idx); - assert(!vm.running && !vm.sig && !vm.sig_lock); - return idx; } -BclError -bcl_rand_seedWithNum(BclNumber n) +BclNumber +bcl_ifrand(BclNumber a, size_t places) +{ + return bcl_ifrand_helper(a, places, true); +} + +BclNumber +bcl_ifrand_keep(BclNumber a, size_t places) +{ + return bcl_ifrand_helper(a, places, false); +} + +static BclError +bcl_rand_seedWithNum_helper(BclNumber n, bool destruct) { BclError e = BCL_ERROR_NONE; - BcNum* nptr; + BclNum* nptr; BclContext ctxt; + BcVm* vm = bcl_getspecific(); - BC_CHECK_CTXT_ERR(ctxt); + BC_CHECK_CTXT_ERR(vm, ctxt); BC_CHECK_NUM_ERR(ctxt, n); - BC_FUNC_HEADER(err); + BC_FUNC_HEADER(vm, err); - assert(n.i < ctxt->nums.len); + assert(BCL_NO_GEN(n) < ctxt->nums.len); - nptr = BC_NUM(ctxt, n); + nptr = BCL_NUM(ctxt, n); - assert(nptr != NULL && nptr->num != NULL); + assert(nptr != NULL && BCL_NUM_NUM(nptr) != NULL); - bc_num_rng(nptr, &vm.rng); + bc_num_rng(BCL_NUM_NUM(nptr), &vm->rng); err: - BC_SIG_MAYLOCK; - BC_FUNC_FOOTER(e); - assert(!vm.running && !vm.sig && !vm.sig_lock); + if (destruct) + { + // Eat the oprand. + bcl_num_dtor(ctxt, n, nptr); + } + + BC_FUNC_FOOTER(vm, e); return e; } BclError +bcl_rand_seedWithNum(BclNumber n) +{ + return bcl_rand_seedWithNum_helper(n, true); +} + +BclError +bcl_rand_seedWithNum_keep(BclNumber n) +{ + return bcl_rand_seedWithNum_helper(n, false); +} + +BclError bcl_rand_seed(unsigned char seed[BCL_SEED_SIZE]) { BclError e = BCL_ERROR_NONE; size_t i; ulong vals[BCL_SEED_ULONGS]; + BcVm* vm = bcl_getspecific(); - BC_FUNC_HEADER(err); + BC_FUNC_HEADER(vm, err); // Fill the array. for (i = 0; i < BCL_SEED_SIZE; ++i) @@ -1332,46 +1702,46 @@ bcl_rand_seed(unsigned char seed[BCL_SEED_SIZE]) vals[i / sizeof(long)] |= val; } - bc_rand_seed(&vm.rng, vals[0], vals[1], vals[2], vals[3]); + bc_rand_seed(&vm->rng, vals[0], vals[1], vals[2], vals[3]); err: - BC_SIG_MAYLOCK; - BC_FUNC_FOOTER(e); + + BC_FUNC_FOOTER(vm, e); + return e; } void bcl_rand_reseed(void) { - bc_rand_srand(bc_vec_top(&vm.rng.v)); + BcVm* vm = bcl_getspecific(); + + bc_rand_srand(bc_vec_top(&vm->rng.v)); } BclNumber bcl_rand_seed2num(void) { BclError e = BCL_ERROR_NONE; - BcNum n; + BclNum n; BclNumber idx; BclContext ctxt; + BcVm* vm = bcl_getspecific(); - BC_CHECK_CTXT(ctxt); + BC_CHECK_CTXT(vm, ctxt); - BC_FUNC_HEADER_LOCK(err); + BC_FUNC_HEADER(vm, err); // Clear and initialize the number. - bc_num_clear(&n); - bc_num_init(&n, BC_NUM_DEF_SIZE); + bc_num_clear(BCL_NUM_NUM_NP(n)); + bc_num_init(BCL_NUM_NUM_NP(n), BC_NUM_DEF_SIZE); - BC_SIG_UNLOCK; - - bc_num_createFromRNG(&n, &vm.rng); + bc_num_createFromRNG(BCL_NUM_NUM_NP(n), &vm->rng); err: - BC_SIG_MAYLOCK; - BC_FUNC_FOOTER(e); - BC_MAYBE_SETUP(ctxt, e, n, idx); - assert(!vm.running && !vm.sig && !vm.sig_lock); + BC_FUNC_FOOTER(vm, e); + BC_MAYBE_SETUP(ctxt, e, n, idx); return idx; } @@ -1379,14 +1749,20 @@ err: BclRandInt bcl_rand_int(void) { - return (BclRandInt) bc_rand_int(&vm.rng); + BcVm* vm = bcl_getspecific(); + + return (BclRandInt) bc_rand_int(&vm->rng); } BclRandInt bcl_rand_bounded(BclRandInt bound) { + BcVm* vm = bcl_getspecific(); + if (bound <= 1) return 0; - return (BclRandInt) bc_rand_bounded(&vm.rng, (BcRand) bound); + return (BclRandInt) bc_rand_bounded(&vm->rng, (BcRand) bound); } +#endif // BC_ENABLE_EXTRA_MATH + #endif // BC_ENABLE_LIBRARY diff --git a/contrib/bc/src/main.c b/contrib/bc/src/main.c index 3c86088fcafc..da4c27156029 100644 --- a/contrib/bc/src/main.c +++ b/contrib/bc/src/main.c @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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,14 +54,15 @@ #include <dc.h> int -main(int argc, char* argv[]) +main(int argc, const char* argv[]) { + BcStatus s; char* name; size_t len = strlen(BC_EXECPREFIX); #if BC_ENABLE_NLS // Must set the locale properly in order to have the right error messages. - vm.locale = setlocale(LC_ALL, ""); + vm->locale = setlocale(LC_ALL, ""); #endif // BC_ENABLE_NLS // Set the start pledge(). @@ -74,44 +75,54 @@ main(int argc, char* argv[]) // basename because it's not portable, but yes, this is stripping off // the directory. name = strrchr(argv[0], BC_FILE_SEP); - vm.name = (name == NULL) ? argv[0] : name + 1; + vm->name = (name == NULL) ? argv[0] : name + 1; } else { #if !DC_ENABLED - vm.name = "bc"; + vm->name = "bc"; #elif !BC_ENABLED - vm.name = "dc"; + vm->name = "dc"; #else // Just default to bc in that case. - vm.name = "bc"; + vm->name = "bc"; #endif } // If the name is longer than the length of the prefix, skip the prefix. - if (strlen(vm.name) > len) vm.name += len; + if (strlen(vm->name) > len) vm->name += len; BC_SIG_LOCK; // We *must* do this here. Otherwise, other code could not jump out all of // the way. - bc_vec_init(&vm.jmp_bufs, sizeof(sigjmp_buf), BC_DTOR_NONE); + bc_vec_init(&vm->jmp_bufs, sizeof(sigjmp_buf), BC_DTOR_NONE); - BC_SETJMP_LOCKED(exit); + BC_SETJMP_LOCKED(vm, exit); +#if BC_CLANG +#pragma clang diagnostic push +#pragma clang diagnostic ignored "-Wcast-qual" +#endif // BC_CLANG #if !DC_ENABLED - bc_main(argc, argv); + s = bc_main(argc, (const char**) argv); #elif !BC_ENABLED - dc_main(argc, argv); + s = dc_main(argc, (const char**) argv); #else - // BC_IS_BC uses vm.name, which was set above. So we're good. - if (BC_IS_BC) bc_main(argc, argv); - else dc_main(argc, argv); + // BC_IS_BC uses vm->name, which was set above. So we're good. + if (BC_IS_BC) s = bc_main(argc, (const char**) argv); + else s = dc_main(argc, (const char**) argv); #endif +#if BC_CLANG +#pragma clang diagnostic pop +#endif // BC_CLANG + + vm->status = (sig_atomic_t) s; exit: BC_SIG_MAYLOCK; - // Ensure we exit appropriately. - return bc_vm_atexit((int) vm.status); + s = bc_vm_atexit((BcStatus) vm->status); + + return (int) s; } diff --git a/contrib/bc/src/num.c b/contrib/bc/src/num.c index 4839a4b87353..83f84edb91fc 100644 --- a/contrib/bc/src/num.c +++ b/contrib/bc/src/num.c @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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: @@ -44,6 +44,9 @@ #include <num.h> #include <rand.h> #include <vm.h> +#if BC_ENABLE_LIBRARY +#include <library.h> +#endif // BC_ENABLE_LIBRARY // Before you try to understand this code, see the development manual // (manuals/development.md#numbers). @@ -127,7 +130,7 @@ bc_num_expand(BcNum* restrict n, size_t req) * @param n The number to set to zero. * @param scale The scale to set the number to. */ -static void +static inline void bc_num_setToZero(BcNum* restrict n, size_t scale) { assert(n != NULL); @@ -212,6 +215,26 @@ bc_num_zeroDigits(const BcDig* n) } /** + * Returns the power of 10 that the least significant limb should be multiplied + * by to put its digits in the right place. For example, if the scale only + * reaches 8 places into the limb, this will return 1 (because it should be + * multiplied by 10^1) to put the number in the correct place. + * @param scale The scale. + * @return The power of 10 that the least significant limb should be + * multiplied by + */ +static inline size_t +bc_num_leastSigPow(size_t scale) +{ + size_t digs; + + digs = scale % BC_BASE_DIGS; + digs = digs != 0 ? BC_BASE_DIGS - digs : 0; + + return bc_num_pow10[digs]; +} + +/** * Return the total number of integer digits in a number. This is the opposite * of scale, like bc_num_int() is the opposite of rdx. * @param n The number. @@ -251,6 +274,37 @@ bc_num_nonZeroLen(const BcNum* restrict n) return i + 1; } +#if BC_ENABLE_EXTRA_MATH + +/** + * Returns the power of 10 that a number with an absolute value less than 1 + * needs to be multiplied by in order to be greater than 1 or less than -1. + * @param n The number. + * @return The power of 10 that a number greater than 1 and less than -1 must + * be multiplied by to be greater than 1 or less than -1. + */ +static size_t +bc_num_negPow10(const BcNum* restrict n) +{ + // Figure out how many limbs after the decimal point is zero. + size_t i, places, idx = bc_num_nonZeroLen(n) - 1; + + places = 1; + + // Figure out how much in the last limb is zero. + for (i = BC_BASE_DIGS - 1; i < BC_BASE_DIGS; --i) + { + if (bc_num_pow10[i] > (BcBigDig) n->num[idx]) places += 1; + else break; + } + + // Calculate the combination of zero limbs and zero digits in the last + // limb. + return places + (BC_NUM_RDX_VAL(n) - (idx + 1)) * BC_BASE_DIGS; +} + +#endif // BC_ENABLE_EXTRA_MATH + /** * Performs a one-limb add with a carry. * @param a The first limb. @@ -263,8 +317,8 @@ static BcDig bc_num_addDigits(BcDig a, BcDig b, bool* carry) { assert(((BcBigDig) BC_BASE_POW) * 2 == ((BcDig) BC_BASE_POW) * 2); - assert(a < BC_BASE_POW); - assert(b < BC_BASE_POW); + assert(a < BC_BASE_POW && a >= 0); + assert(b < BC_BASE_POW && b >= 0); a += b + *carry; *carry = (a >= BC_BASE_POW); @@ -287,8 +341,8 @@ bc_num_addDigits(BcDig a, BcDig b, bool* carry) static BcDig bc_num_subDigits(BcDig a, BcDig b, bool* carry) { - assert(a < BC_BASE_POW); - assert(b < BC_BASE_POW); + assert(a < BC_BASE_POW && a >= 0); + assert(b < BC_BASE_POW && b >= 0); b += *carry; *carry = (a < b); @@ -382,6 +436,7 @@ bc_num_mulArray(const BcNum* restrict a, BcBigDig b, BcNum* restrict c) // Finishing touches. c->num[i] = (BcDig) carry; + assert(c->num[i] >= 0 && c->num[i] < BC_BASE_POW); c->len = a->len; c->len += (carry != 0); @@ -416,6 +471,7 @@ bc_num_divArray(const BcNum* restrict a, BcBigDig b, BcNum* restrict c, BcBigDig in = ((BcBigDig) a->num[i]) + carry * BC_BASE_POW; assert(in / b < BC_BASE_POW); c->num[i] = (BcDig) (in / b); + assert(c->num[i] >= 0 && c->num[i] < BC_BASE_POW); carry = in % b; } @@ -542,10 +598,8 @@ bc_num_truncate(BcNum* restrict n, size_t places) size_t pow; // This calculates how many decimal digits are in the least significant - // limb. - pow = n->scale % BC_BASE_DIGS; - pow = pow ? BC_BASE_DIGS - pow : 0; - pow = bc_num_pow10[pow]; + // limb, then gets the power for that. + pow = bc_num_leastSigPow(n->scale); n->len -= places_rdx; @@ -685,7 +739,8 @@ bc_num_shiftRdx(const BcNum* restrict n, BcNum* restrict r) static size_t bc_num_shiftZero(BcNum* restrict n) { - size_t i; + // This is volatile to quiet a GCC warning about longjmp() clobbering. + volatile size_t i; // If we don't have an integer, that is a problem, but it's also a bug // because the caller should have set everything up right. @@ -745,6 +800,7 @@ bc_num_shift(BcNum* restrict n, BcBigDig dig) temp = carry * dig; carry = in % pow; ptr[i] = ((BcDig) (in / pow)) + (BcDig) temp; + assert(ptr[i] >= 0 && ptr[i] < BC_BASE_POW); } assert(!carry); @@ -918,19 +974,6 @@ bc_num_shiftRight(BcNum* restrict n, size_t places) } /** - * 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. - */ -static inline void -bc_num_inv(BcNum* a, BcNum* b, size_t scale) -{ - assert(BC_NUM_NONZERO(a)); - bc_num_div(&vm.one, a, b, scale); -} - -/** * Tests if a number is a integer with scale or not. Returns true if the number * is not an integer. If it is, its integer shifted form is copied into the * result parameter for use where only integers are allowed. @@ -981,6 +1024,12 @@ bc_num_intop(const BcNum* a, const BcNum* b, BcNum* restrict c) { BcNum temp; +#if BC_GCC + temp.len = 0; + temp.rdx = 0; + temp.num = NULL; +#endif // BC_GCC + if (BC_ERR(bc_num_nonInt(b, &temp))) bc_err(BC_ERR_MATH_NON_INTEGER); bc_num_copy(c, a); @@ -1289,6 +1338,9 @@ bc_num_k(const BcNum* a, const BcNum* b, BcNum* restrict c) BcDig* dig_ptr; BcNumShiftAddOp op; bool aone = BC_NUM_ONE(a); +#if BC_ENABLE_LIBRARY + BcVm* vm = bcl_getspecific(); +#endif // BC_ENABLE_LIBRARY assert(BC_NUM_ZERO(c)); @@ -1345,7 +1397,7 @@ bc_num_k(const BcNum* a, const BcNum* b, BcNum* restrict c) max = bc_vm_growSize(max, max) + 1; bc_num_init(&temp, max); - BC_SETJMP_LOCKED(err); + BC_SETJMP_LOCKED(vm, err); BC_SIG_UNLOCK; @@ -1413,7 +1465,7 @@ err: bc_num_free(&z2); bc_num_free(&z1); bc_num_free(&z0); - BC_LONGJMP_CONT; + BC_LONGJMP_CONT(vm); } /** @@ -1429,7 +1481,17 @@ static void bc_num_m(BcNum* a, BcNum* b, BcNum* restrict c, size_t scale) { BcNum cpa, cpb; - size_t ascale, bscale, ardx, brdx, azero = 0, bzero = 0, zero, len, rscale; + size_t ascale, bscale, ardx, brdx, zero, len, rscale; + // These are meant to quiet warnings on GCC about longjmp() clobbering. + // The problem is real here. + size_t scale1, scale2, realscale; + // These are meant to quiet the GCC longjmp() clobbering, even though it + // does not apply here. + volatile size_t azero; + volatile size_t bzero; +#if BC_ENABLE_LIBRARY + BcVm* vm = bcl_getspecific(); +#endif // BC_ENABLE_LIBRARY assert(BC_NUM_RDX_VALID(a)); assert(BC_NUM_RDX_VALID(b)); @@ -1440,10 +1502,10 @@ bc_num_m(BcNum* a, BcNum* b, BcNum* restrict c, size_t scale) bscale = b->scale; // This sets the final scale according to the bc spec. - scale = BC_MAX(scale, ascale); - scale = BC_MAX(scale, bscale); + scale1 = BC_MAX(scale, ascale); + scale2 = BC_MAX(scale1, bscale); rscale = ascale + bscale; - scale = BC_MIN(rscale, scale); + realscale = BC_MIN(rscale, scale2); // If this condition is true, we can use bc_num_mulArray(), which would be // much faster. @@ -1485,7 +1547,7 @@ bc_num_m(BcNum* a, BcNum* b, BcNum* restrict c, size_t scale) bc_num_init(&cpa, a->len + BC_NUM_RDX_VAL(a)); bc_num_init(&cpb, b->len + BC_NUM_RDX_VAL(b)); - BC_SETJMP_LOCKED(err); + BC_SETJMP_LOCKED(vm, init_err); BC_SIG_UNLOCK; @@ -1513,13 +1575,13 @@ bc_num_m(BcNum* a, BcNum* b, BcNum* restrict c, size_t scale) // jump. BC_SIG_LOCK; - BC_UNSETJMP; + BC_UNSETJMP(vm); // We want to ignore zero limbs. azero = bc_num_shiftZero(&cpa); bzero = bc_num_shiftZero(&cpb); - BC_SETJMP_LOCKED(err); + BC_SETJMP_LOCKED(vm, err); BC_SIG_UNLOCK; @@ -1540,15 +1602,17 @@ bc_num_m(BcNum* a, BcNum* b, BcNum* restrict c, size_t scale) bc_num_shiftLeft(c, (len - c->len) * BC_BASE_DIGS); bc_num_shiftRight(c, ardx + brdx); - bc_num_retireMul(c, scale, BC_NUM_NEG(a), BC_NUM_NEG(b)); + bc_num_retireMul(c, realscale, BC_NUM_NEG(a), BC_NUM_NEG(b)); err: BC_SIG_MAYLOCK; bc_num_unshiftZero(&cpb, bzero); - bc_num_free(&cpb); bc_num_unshiftZero(&cpa, azero); +init_err: + BC_SIG_MAYLOCK; + bc_num_free(&cpb); bc_num_free(&cpa); - BC_LONGJMP_CONT; + BC_LONGJMP_CONT(vm); } /** @@ -1562,14 +1626,12 @@ bc_num_nonZeroDig(BcDig* restrict a, size_t len) { size_t i; - bool nonzero = false; - - for (i = len - 1; !nonzero && i < len; --i) + for (i = len - 1; i < len; --i) { - nonzero = (a[i] != 0); + if (a[i] != 0) return true; } - return nonzero; + return false; } /** @@ -1631,9 +1693,23 @@ bc_num_d_long(BcNum* restrict a, BcNum* restrict b, BcNum* restrict c, size_t scale) { BcBigDig divisor; - size_t len, end, i, rdx; + size_t i, rdx; + // This is volatile and len 2 and reallen exist to quiet the GCC warning + // about clobbering on longjmp(). This one is possible, I think. + volatile size_t len; + size_t len2, reallen; + // This is volatile and realend exists to quiet the GCC warning about + // clobbering on longjmp(). This one is possible, I think. + volatile size_t end; + size_t realend; BcNum cpb; - bool nonzero = false; + // This is volatile and realnonzero exists to quiet the GCC warning about + // clobbering on longjmp(). This one is possible, I think. + volatile bool nonzero; + bool realnonzero; +#if BC_ENABLE_LIBRARY + BcVm* vm = bcl_getspecific(); +#endif // BC_ENABLE_LIBRARY assert(b->len < a->len); @@ -1678,25 +1754,35 @@ bc_num_d_long(BcNum* restrict a, BcNum* restrict b, BcNum* restrict c, // Check bc_num_d(). In there, we grow a again and again. We do it // again here; we *always* want to be sure it is big enough. - len = BC_MAX(a->len, b->len); - bc_num_expand(a, len + 1); + len2 = BC_MAX(a->len, b->len); + bc_num_expand(a, len2 + 1); // Make a have a zero most significant limb to match the len. - if (len + 1 > a->len) a->len = len + 1; + if (len2 + 1 > a->len) a->len = len2 + 1; // Grab the new divisor estimate, new because the shift has made it // different. - len = b->len; - end = a->len - len; - divisor = (BcBigDig) b->num[len - 1]; + reallen = b->len; + realend = a->len - reallen; + divisor = (BcBigDig) b->num[reallen - 1]; - nonzero = bc_num_nonZeroDig(b->num, len - 1); + realnonzero = bc_num_nonZeroDig(b->num, reallen - 1); + } + else + { + realend = end; + realnonzero = nonzero; } } + else + { + realend = end; + realnonzero = false; + } // If b has other nonzero limbs, we want the divisor to be one higher, so // that it is an upper bound. - divisor += nonzero; + divisor += realnonzero; // Make sure c can fit the new length. bc_num_expand(c, a->len); @@ -1710,12 +1796,12 @@ bc_num_d_long(BcNum* restrict a, BcNum* restrict b, BcNum* restrict c, bc_num_init(&cpb, len + 1); - BC_SETJMP_LOCKED(err); + BC_SETJMP_LOCKED(vm, err); BC_SIG_UNLOCK; // This is the actual division loop. - for (i = end - 1; i < end && i >= rdx && BC_NUM_NONZERO(a); --i) + for (i = realend - 1; i < realend && i >= rdx && BC_NUM_NONZERO(a); --i) { ssize_t cmp; BcDig* n; @@ -1765,7 +1851,7 @@ bc_num_d_long(BcNum* restrict a, BcNum* restrict b, BcNum* restrict c, // And here's why it might take multiple trips: n might *still* be // greater than b. So we have to loop again. That's what this is // setting up for: the condition of the while loop. - if (nonzero) cmp = bc_num_divCmp(n, b, len); + if (realnonzero) cmp = bc_num_divCmp(n, b, len); else cmp = -1; } @@ -1778,7 +1864,7 @@ bc_num_d_long(BcNum* restrict a, BcNum* restrict b, BcNum* restrict c, err: BC_SIG_MAYLOCK; bc_num_free(&cpb); - BC_LONGJMP_CONT; + BC_LONGJMP_CONT(vm); } /** @@ -1793,6 +1879,9 @@ bc_num_d(BcNum* a, BcNum* b, BcNum* restrict c, size_t scale) { size_t len, cpardx; BcNum cpa, cpb; +#if BC_ENABLE_LIBRARY + BcVm* vm = bcl_getspecific(); +#endif // BC_ENABLE_LIBRARY if (BC_NUM_ZERO(b)) bc_err(BC_ERR_MATH_DIVIDE_BY_ZERO); @@ -1829,7 +1918,7 @@ bc_num_d(BcNum* a, BcNum* b, BcNum* restrict c, size_t scale) bc_num_copy(&cpa, a); bc_num_createCopy(&cpb, b); - BC_SETJMP_LOCKED(err); + BC_SETJMP_LOCKED(vm, err); BC_SIG_UNLOCK; @@ -1871,6 +1960,9 @@ bc_num_d(BcNum* a, BcNum* b, BcNum* restrict c, size_t scale) // actual algorithm easier to understand because it can assume a lot of // things. Thus, you should view all of this setup code as establishing // assumptions for bc_num_d_long(), where the actual division happens. + // + // But in short, this setup makes it so bc_num_d_long() can pretend the + // numbers are integers. if (cpardx == cpa.len) cpa.len = bc_num_nonZeroLen(&cpa); if (BC_NUM_RDX_VAL_NP(cpb) == cpb.len) cpb.len = bc_num_nonZeroLen(&cpb); cpb.scale = 0; @@ -1884,7 +1976,7 @@ err: BC_SIG_MAYLOCK; bc_num_free(&cpb); bc_num_free(&cpa); - BC_LONGJMP_CONT; + BC_LONGJMP_CONT(vm); } /** @@ -1904,7 +1996,13 @@ bc_num_r(BcNum* a, BcNum* b, BcNum* restrict c, BcNum* restrict d, size_t scale, size_t ts) { BcNum temp; + // realscale is meant to quiet a warning on GCC about longjmp() clobbering. + // This one is real. + size_t realscale; bool neg; +#if BC_ENABLE_LIBRARY + BcVm* vm = bcl_getspecific(); +#endif // BC_ENABLE_LIBRARY if (BC_NUM_ZERO(b)) bc_err(BC_ERR_MATH_DIVIDE_BY_ZERO); @@ -1919,7 +2017,7 @@ bc_num_r(BcNum* a, BcNum* b, BcNum* restrict c, BcNum* restrict d, size_t scale, bc_num_init(&temp, d->cap); - BC_SETJMP_LOCKED(err); + BC_SETJMP_LOCKED(vm, err); BC_SIG_UNLOCK; @@ -1927,14 +2025,15 @@ bc_num_r(BcNum* a, BcNum* b, BcNum* restrict c, BcNum* restrict d, size_t scale, bc_num_d(a, b, c, scale); // We want an extra digit so we can safely truncate. - if (scale) scale = ts + 1; + if (scale) realscale = ts + 1; + else realscale = scale; assert(BC_NUM_RDX_VALID(c)); assert(BC_NUM_RDX_VALID(b)); // Implement the rest of the (a - (a / b) * b) formula. - bc_num_m(c, b, &temp, scale); - bc_num_sub(a, &temp, d, scale); + bc_num_m(c, b, &temp, realscale); + bc_num_sub(a, &temp, d, realscale); // Extend if necessary. if (ts > d->scale && BC_NUM_NONZERO(d)) bc_num_extend(d, ts - d->scale); @@ -1946,7 +2045,7 @@ bc_num_r(BcNum* a, BcNum* b, BcNum* restrict c, BcNum* restrict d, size_t scale, err: BC_SIG_MAYLOCK; bc_num_free(&temp); - BC_LONGJMP_CONT; + BC_LONGJMP_CONT(vm); } /** @@ -1962,6 +2061,9 @@ bc_num_rem(BcNum* a, BcNum* b, BcNum* restrict c, size_t scale) { BcNum c1; size_t ts; +#if BC_ENABLE_LIBRARY + BcVm* vm = bcl_getspecific(); +#endif // BC_ENABLE_LIBRARY ts = bc_vm_growSize(scale, b->scale); ts = BC_MAX(ts, a->scale); @@ -1971,7 +2073,7 @@ bc_num_rem(BcNum* a, BcNum* b, BcNum* restrict c, size_t scale) // Need a temp for the quotient. bc_num_init(&c1, bc_num_mulReq(a, b, ts)); - BC_SETJMP_LOCKED(err); + BC_SETJMP_LOCKED(vm, err); BC_SIG_UNLOCK; @@ -1980,7 +2082,7 @@ bc_num_rem(BcNum* a, BcNum* b, BcNum* restrict c, size_t scale) err: BC_SIG_MAYLOCK; bc_num_free(&c1); - BC_LONGJMP_CONT; + BC_LONGJMP_CONT(vm); } /** @@ -1995,11 +2097,25 @@ bc_num_p(BcNum* a, BcNum* b, BcNum* restrict c, size_t scale) { BcNum copy, btemp; BcBigDig exp; - size_t powrdx, resrdx; + // realscale is meant to quiet a warning on GCC about longjmp() clobbering. + // This one is real. + size_t powrdx, resrdx, realscale; bool neg; +#if BC_ENABLE_LIBRARY + BcVm* vm = bcl_getspecific(); +#endif // BC_ENABLE_LIBRARY + + // This is here to silence a warning from GCC. +#if BC_GCC + btemp.len = 0; + btemp.rdx = 0; + btemp.num = NULL; +#endif // BC_GCC if (BC_ERR(bc_num_nonInt(b, &btemp))) bc_err(BC_ERR_MATH_NON_INTEGER); + assert(btemp.len == 0 || btemp.num != NULL); + if (BC_NUM_ZERO(&btemp)) { bc_num_one(c); @@ -2029,7 +2145,7 @@ bc_num_p(BcNum* a, BcNum* b, BcNum* restrict c, size_t scale) bc_num_createCopy(©, a); - BC_SETJMP_LOCKED(err); + BC_SETJMP_LOCKED(vm, err); BC_SIG_UNLOCK; @@ -2039,8 +2155,9 @@ bc_num_p(BcNum* a, BcNum* b, BcNum* restrict c, size_t scale) { size_t max = BC_MAX(scale, a->scale), scalepow; scalepow = bc_num_mulOverflow(a->scale, exp); - scale = BC_MIN(scalepow, max); + realscale = BC_MIN(scalepow, max); } + else realscale = scale; // This is only implementing the first exponentiation by squaring, until it // reaches the first time where the square is actually used. @@ -2076,17 +2193,17 @@ bc_num_p(BcNum* a, BcNum* b, BcNum* restrict c, size_t scale) } // Invert if necessary. - if (neg) bc_num_inv(c, c, scale); + if (neg) bc_num_inv(c, c, realscale); // Truncate if necessary. - if (c->scale > scale) bc_num_truncate(c, c->scale - scale); + if (c->scale > realscale) bc_num_truncate(c, c->scale - realscale); bc_num_clean(c); err: BC_SIG_MAYLOCK; bc_num_free(©); - BC_LONGJMP_CONT; + BC_LONGJMP_CONT(vm); } #if BC_ENABLE_EXTRA_MATH @@ -2169,7 +2286,9 @@ bc_num_binary(BcNum* a, BcNum* b, BcNum* c, size_t scale, BcNumBinOp op, BcNum* ptr_a; BcNum* ptr_b; BcNum num2; - bool init = false; +#if BC_ENABLE_LIBRARY + BcVm* vm = NULL; +#endif // BC_ENABLE_LIBRARY assert(a != NULL && b != NULL && c != NULL && op != NULL); @@ -2178,46 +2297,25 @@ bc_num_binary(BcNum* a, BcNum* b, BcNum* c, size_t scale, BcNumBinOp op, BC_SIG_LOCK; - // Reallocate if c == a. - if (c == a) - { - ptr_a = &num2; - - // NOLINTNEXTLINE - memcpy(ptr_a, c, sizeof(BcNum)); - init = true; - } - else - { - ptr_a = a; - } - - // Also reallocate if c == b. - if (c == b) - { - ptr_b = &num2; - - if (c != a) - { - // NOLINTNEXTLINE - memcpy(ptr_b, c, sizeof(BcNum)); - init = true; - } - } - else - { - ptr_b = b; - } + ptr_a = c == a ? &num2 : a; + ptr_b = c == b ? &num2 : b; // Actually reallocate. If we don't reallocate, we want to expand at the // very least. - if (init) + if (c == a || c == b) { +#if BC_ENABLE_LIBRARY + vm = bcl_getspecific(); +#endif // BC_ENABLE_LIBRARY + + // NOLINTNEXTLINE + memcpy(&num2, c, sizeof(BcNum)); + bc_num_init(c, req); // Must prepare for cleanup. We want this here so that locals that got // set stay set since a longjmp() is not guaranteed to preserve locals. - BC_SETJMP_LOCKED(err); + BC_SETJMP_LOCKED(vm, err); BC_SIG_UNLOCK; } else @@ -2240,11 +2338,11 @@ bc_num_binary(BcNum* a, BcNum* b, BcNum* c, size_t scale, BcNumBinOp op, err: // Cleanup only needed if we initialized c to a new number. - if (init) + if (c == a || c == b) { BC_SIG_MAYLOCK; bc_num_free(&num2); - BC_LONGJMP_CONT; + BC_LONGJMP_CONT(vm); } } @@ -2307,11 +2405,18 @@ bc_num_parseChar(char c, size_t base) // If a letter... if (isupper(c)) { +#if BC_ENABLE_LIBRARY + BcVm* vm = bcl_getspecific(); +#endif // BC_ENABLE_LIBRARY + // This returns the digit that directly corresponds with the letter. c = BC_NUM_NUM_LETTER(c); // If the digit is greater than the base, we clamp. - c = ((size_t) c) >= base ? (char) base - 1 : c; + if (BC_DIGIT_CLAMP) + { + c = ((size_t) c) >= base ? (char) base - 1 : c; + } } // Straight convert the digit to a number. else c -= '0'; @@ -2331,6 +2436,9 @@ bc_num_parseDecimal(BcNum* restrict n, const char* restrict val) size_t len, i, temp, mod; const char* ptr; bool zero = true, rdx; +#if BC_ENABLE_LIBRARY + BcVm* vm = bcl_getspecific(); +#endif // BC_ENABLE_LIBRARY // Eat leading zeroes. for (i = 0; val[i] == '0'; ++i) @@ -2378,10 +2486,11 @@ bc_num_parseDecimal(BcNum* restrict n, const char* restrict val) i = mod ? BC_BASE_DIGS - mod : 0; n->len = ((temp + i) / BC_BASE_DIGS); - // Expand and zero. - bc_num_expand(n, n->len); + // Expand and zero. The plus extra is in case the lack of clamping causes + // the number to overflow the original bounds. + bc_num_expand(n, n->len + !BC_DIGIT_CLAMP); // NOLINTNEXTLINE - memset(n->num, 0, BC_NUM_SIZE(n->len)); + memset(n->num, 0, BC_NUM_SIZE(n->len + !BC_DIGIT_CLAMP)); if (zero) { @@ -2412,12 +2521,35 @@ bc_num_parseDecimal(BcNum* restrict n, const char* restrict val) { // The index of the limb. size_t idx = exp / BC_BASE_DIGS; + BcBigDig dig; - // Clamp for the base. - if (isupper(c)) c = '9'; + if (isupper(c)) + { + // Clamp for the base. + if (!BC_DIGIT_CLAMP) c = BC_NUM_NUM_LETTER(c); + else c = 9; + } + else c -= '0'; - // Add the digit to the limb. - n->num[idx] += (((BcBigDig) c) - '0') * pow; + // Add the digit to the limb. This takes care of overflow from + // lack of clamping. + dig = ((BcBigDig) n->num[idx]) + ((BcBigDig) c) * pow; + if (dig >= BC_BASE_POW) + { + // We cannot go over BC_BASE_POW with clamping. + assert(!BC_DIGIT_CLAMP); + + n->num[idx + 1] = (BcDig) (dig / BC_BASE_POW); + n->num[idx] = (BcDig) (dig % BC_BASE_POW); + assert(n->num[idx] >= 0 && n->num[idx] < BC_BASE_POW); + assert(n->num[idx + 1] >= 0 && + n->num[idx + 1] < BC_BASE_POW); + } + else + { + n->num[idx] = (BcDig) dig; + assert(n->num[idx] >= 0 && n->num[idx] < BC_BASE_POW); + } // Adjust the power and exponent. if ((exp + 1) % BC_BASE_DIGS == 0) pow = 1; @@ -2425,6 +2557,9 @@ bc_num_parseDecimal(BcNum* restrict n, const char* restrict val) } } } + + // Make sure to add one to the length if needed from lack of clamping. + n->len += (!BC_DIGIT_CLAMP && n->num[n->len] != 0); } /** @@ -2443,7 +2578,12 @@ bc_num_parseBase(BcNum* restrict n, const char* restrict val, BcBigDig base) char c = 0; bool zero = true; BcBigDig v; - size_t i, digs, len = strlen(val); + size_t digs, len = strlen(val); + // This is volatile to quiet a warning on GCC about longjmp() clobbering. + volatile size_t i; +#if BC_ENABLE_LIBRARY + BcVm* vm = bcl_getspecific(); +#endif // BC_ENABLE_LIBRARY // If zero, just return because the number should be virgin (already 0). for (i = 0; zero && i < len; ++i) @@ -2457,7 +2597,7 @@ bc_num_parseBase(BcNum* restrict n, const char* restrict val, BcBigDig base) bc_num_init(&temp, BC_NUM_BIGDIG_LOG10); bc_num_init(&mult1, BC_NUM_BIGDIG_LOG10); - BC_SETJMP_LOCKED(int_err); + BC_SETJMP_LOCKED(vm, int_err); BC_SIG_UNLOCK; @@ -2489,14 +2629,14 @@ bc_num_parseBase(BcNum* restrict n, const char* restrict val, BcBigDig base) BC_SIG_LOCK; // Unset the jump to reset in for these new initializations. - BC_UNSETJMP; + BC_UNSETJMP(vm); bc_num_init(&mult2, BC_NUM_BIGDIG_LOG10); bc_num_init(&result1, BC_NUM_DEF_SIZE); bc_num_init(&result2, BC_NUM_DEF_SIZE); bc_num_one(&mult1); - BC_SETJMP_LOCKED(err); + BC_SETJMP_LOCKED(vm, err); BC_SIG_UNLOCK; @@ -2564,7 +2704,7 @@ int_err: BC_SIG_MAYLOCK; bc_num_free(&mult1); bc_num_free(&temp); - BC_LONGJMP_CONT; + BC_LONGJMP_CONT(vm); } /** @@ -2575,7 +2715,7 @@ static inline void bc_num_printNewline(void) { #if !BC_ENABLE_LIBRARY - if (vm.nchars >= vm.line_len - 1 && vm.line_len) + if (vm->nchars >= vm->line_len - 1 && vm->line_len) { bc_vm_putchar('\\', bc_flush_none); bc_vm_putchar('\n', bc_flush_err); @@ -2756,12 +2896,15 @@ bc_num_printExponent(const BcNum* restrict n, bool eng, bool newline) bool neg = (n->len <= nrdx); BcNum temp, exp; BcDig digs[BC_NUM_BIGDIG_LOG10]; +#if BC_ENABLE_LIBRARY + BcVm* vm = bcl_getspecific(); +#endif // BC_ENABLE_LIBRARY BC_SIG_LOCK; bc_num_createCopy(&temp, n); - BC_SETJMP_LOCKED(exit); + BC_SETJMP_LOCKED(vm, exit); BC_SIG_UNLOCK; @@ -2769,21 +2912,11 @@ bc_num_printExponent(const BcNum* restrict n, bool eng, bool newline) // number is all fractional or not, obviously. if (neg) { - // Figure out how many limbs after the decimal point is zero. - size_t i, idx = bc_num_nonZeroLen(n) - 1; - - places = 1; + // Figure out the negative power of 10. + places = bc_num_negPow10(n); - // Figure out how much in the last limb is zero. - for (i = BC_BASE_DIGS - 1; i < BC_BASE_DIGS; --i) - { - if (bc_num_pow10[i] > (BcBigDig) n->num[idx]) places += 1; - else break; - } - - // Calculate the combination of zero limbs and zero digits in the last - // limb. - places += (nrdx - (idx + 1)) * BC_BASE_DIGS; + // Figure out how many digits mod 3 there are (important for + // engineering mode). mod = places % 3; // Calculate places if we are in engineering mode. @@ -2833,19 +2966,19 @@ bc_num_printExponent(const BcNum* restrict n, bool eng, bool newline) exit: BC_SIG_MAYLOCK; bc_num_free(&temp); - BC_LONGJMP_CONT; + BC_LONGJMP_CONT(vm); } #endif // BC_ENABLE_EXTRA_MATH /** - * Converts a number from limbs with base BC_BASE_POW to base @a pow, where - * @a pow is obase^N. + * Takes a number with limbs with base BC_BASE_POW and converts the limb at the + * given index to base @a pow, where @a pow is obase^N. * @param n The number to convert. * @param rem BC_BASE_POW - @a pow. * @param pow The power of obase we will convert the number to. * @param idx The index of the number to start converting at. Doing the * conversion is O(n^2); we have to sweep through starting at the - * least significant limb + * least significant limb. */ static void bc_num_printFixup(BcNum* restrict n, BcBigDig rem, BcBigDig pow, size_t idx) @@ -2907,8 +3040,8 @@ bc_num_printFixup(BcNum* restrict n, BcBigDig rem, BcBigDig pow, size_t idx) } /** - * Prepares a number for printing in a base that is not a divisor of - * BC_BASE_POW. This basically converts the number from having limbs of base + * Prepares a number for printing in a base that does not have BC_BASE_POW as a + * power. This basically converts the number from having limbs of base * BC_BASE_POW to limbs of pow, where pow is obase^N. * @param n The number to prepare for printing. * @param rem The remainder of BC_BASE_POW when divided by a power of the base. @@ -2970,6 +3103,9 @@ bc_num_printNum(BcNum* restrict n, BcBigDig base, size_t len, size_t i, j, nrdx, idigits; bool radix; BcDig digit_digs[BC_NUM_BIGDIG_LOG10 + 1]; +#if BC_ENABLE_LIBRARY + BcVm* vm = bcl_getspecific(); +#endif // BC_ENABLE_LIBRARY assert(base > 1); @@ -3029,7 +3165,7 @@ bc_num_printNum(BcNum* restrict n, BcBigDig base, size_t len, // intp will be the "integer part" of the number, so copy it. bc_num_createCopy(&intp, n); - BC_SETJMP_LOCKED(err); + BC_SETJMP_LOCKED(vm, err); BC_SIG_UNLOCK; @@ -3044,30 +3180,33 @@ bc_num_printNum(BcNum* restrict n, BcBigDig base, size_t len, // exponent and power. That is to prevent us from calculating them every // time because printing will probably happen multiple times on the same // base. - if (base != vm.last_base) + if (base != vm->last_base) { - vm.last_pow = 1; - vm.last_exp = 0; + vm->last_pow = 1; + vm->last_exp = 0; // Calculate the exponent and power. - while (vm.last_pow * base <= BC_BASE_POW) + while (vm->last_pow * base <= BC_BASE_POW) { - vm.last_pow *= base; - vm.last_exp += 1; + vm->last_pow *= base; + vm->last_exp += 1; } // Also, the remainder and base itself. - vm.last_rem = BC_BASE_POW - vm.last_pow; - vm.last_base = base; + vm->last_rem = BC_BASE_POW - vm->last_pow; + vm->last_base = base; } - exp = vm.last_exp; + exp = vm->last_exp; - // If vm.last_rem is 0, then the base we are printing in is a divisor of + // If vm->last_rem is 0, then the base we are printing in is a divisor of // BC_BASE_POW, which is the easy case because it means that BC_BASE_POW is // a power of obase, and no conversion is needed. If it *is* 0, then we have // the hard case, and we have to prepare the number for the base. - if (vm.last_rem != 0) bc_num_printPrepare(&intp, vm.last_rem, vm.last_pow); + if (vm->last_rem != 0) + { + bc_num_printPrepare(&intp, vm->last_rem, vm->last_pow); + } // After the conversion comes the surprisingly easy part. From here on out, // this is basically naive code that I wrote, adjusted for the larger bases. @@ -3110,12 +3249,30 @@ bc_num_printNum(BcNum* restrict n, BcBigDig base, size_t len, assert(ptr != NULL); // While the first three arguments should be self-explanatory, the last - // needs explaining. I don't want to print a newline when the last digit - // to be printed could take the place of the backslash rather than being - // pushed, as a single character, to the next line. That's what that - // last argument does for bc. + // needs explaining. I don't want to print a backslash+newline when the + // last digit to be printed could take the place of the backslash rather + // than being pushed, as a single character, to the next line. That's + // what that last argument does for bc. + // + // First, it needs to check if newlines are completely disabled. If they + // are not disabled, it needs to check the next part. + // + // If the number has a scale, then because we are printing just the + // integer part, there will be at least two more characters (a radix + // point plus at least one digit). So if there is a scale, a backslash + // is necessary. + // + // Finally, the last condition checks to see if we are at the end of the + // stack. If we are *not* (i.e., the index is not one less than the + // stack length), then a backslash is necessary because there is at + // least one more character for at least one more digit). Otherwise, if + // the index is equal to one less than the stack length, we want to + // disable backslash printing. + // + // The function that prints bases 17 and above will take care of not + // printing a backslash in the right case. print(*ptr, len, false, - !newline || (n->scale != 0 || i == stack.len - 1)); + !newline || (n->scale != 0 || i < stack.len - 1)); } // We are done if there is no fractional part. @@ -3124,14 +3281,14 @@ bc_num_printNum(BcNum* restrict n, BcBigDig base, size_t len, BC_SIG_LOCK; // Reset the jump because some locals are changing. - BC_UNSETJMP; + BC_UNSETJMP(vm); bc_num_init(&fracp2, nrdx); bc_num_setup(&digit, digit_digs, sizeof(digit_digs) / sizeof(BcDig)); bc_num_init(&flen1, BC_NUM_BIGDIG_LOG10); bc_num_init(&flen2, BC_NUM_BIGDIG_LOG10); - BC_SETJMP_LOCKED(frac_err); + BC_SETJMP_LOCKED(vm, frac_err); BC_SIG_UNLOCK; @@ -3193,7 +3350,7 @@ err: bc_num_free(&fracp1); bc_num_free(&intp); bc_vec_free(&stack); - BC_LONGJMP_CONT; + BC_LONGJMP_CONT(vm); } /** @@ -3268,9 +3425,11 @@ bc_num_init(BcNum* restrict n, size_t req) req = req >= BC_NUM_DEF_SIZE ? req : BC_NUM_DEF_SIZE; // If we can't use a temp, allocate. - if (req != BC_NUM_DEF_SIZE || (num = bc_vm_takeTemp()) == NULL) + if (req != BC_NUM_DEF_SIZE) num = bc_vm_malloc(BC_NUM_SIZE(req)); + else { - num = bc_vm_malloc(BC_NUM_SIZE(req)); + num = bc_vm_getTemp() == NULL ? bc_vm_malloc(BC_NUM_SIZE(req)) : + bc_vm_takeTemp(); } bc_num_setup(n, num, req); @@ -3375,8 +3534,14 @@ bc_num_len(const BcNum* restrict n) void bc_num_parse(BcNum* restrict n, const char* restrict val, BcBigDig base) { +#if BC_DEBUG +#if BC_ENABLE_LIBRARY + BcVm* vm = bcl_getspecific(); +#endif // BC_ENABLE_LIBRARY +#endif // BC_DEBUG + assert(n != NULL && val != NULL && base); - assert(base >= BC_NUM_MIN_BASE && base <= vm.maxes[BC_PROG_GLOBALS_IBASE]); + assert(base >= BC_NUM_MIN_BASE && base <= vm->maxes[BC_PROG_GLOBALS_IBASE]); assert(bc_num_strValid(val)); // A one character number is *always* parsed as though the base was the @@ -3403,11 +3568,16 @@ bc_num_print(BcNum* restrict n, BcBigDig base, bool newline) if (BC_NUM_NONZERO(n)) { +#if BC_ENABLE_LIBRARY + BcVm* vm = bcl_getspecific(); +#endif // BC_ENABLE_LIBRARY + // Print the sign. if (BC_NUM_NEG(n)) bc_num_putchar('-', true); - // Print the leading zero if necessary. - if (BC_Z && BC_NUM_RDX_VAL(n) == n->len) + // Print the leading zero if necessary. We don't print when using + // scientific or engineering modes. + if (BC_Z && BC_NUM_RDX_VAL(n) == n->len && base != 0 && base != 1) { bc_num_printHex(0, 1, false, !newline); } @@ -3430,9 +3600,15 @@ bc_num_print(BcNum* restrict n, BcBigDig base, bool newline) BcBigDig bc_num_bigdig2(const BcNum* restrict n) { +#if BC_DEBUG +#if BC_ENABLE_LIBRARY + BcVm* vm = bcl_getspecific(); +#endif // BC_ENABLE_LIBRARY +#endif // BC_DEBUG + // This function returns no errors because it's guaranteed to succeed if // its preconditions are met. Those preconditions include both n needs to - // be non-NULL, n being non-negative, and n being less than vm.max. If all + // be non-NULL, n being non-negative, and n being less than vm->max. If all // of that is true, then we can just convert without worrying about negative // errors or overflow. @@ -3441,7 +3617,7 @@ bc_num_bigdig2(const BcNum* restrict n) assert(n != NULL); assert(!BC_NUM_NEG(n)); - assert(bc_num_cmp(n, &vm.max) < 0); + assert(bc_num_cmp(n, &vm->max) < 0); assert(n->len - nrdx <= 3); // There is a small speed win from unrolling the loop here, and since it @@ -3476,6 +3652,10 @@ bc_num_bigdig2(const BcNum* restrict n) BcBigDig bc_num_bigdig(const BcNum* restrict n) { +#if BC_ENABLE_LIBRARY + BcVm* vm = bcl_getspecific(); +#endif // BC_ENABLE_LIBRARY + assert(n != NULL); // This error checking is extremely important, and if you do not have a @@ -3484,7 +3664,7 @@ bc_num_bigdig(const BcNum* restrict n) // includes all instances of numbers inputted by the user or calculated by // the user. Otherwise, you can call the faster bc_num_bigdig2(). if (BC_ERR(BC_NUM_NEG(n))) bc_err(BC_ERR_MATH_NEGATIVE); - if (BC_ERR(bc_num_cmp(n, &vm.max) >= 0)) bc_err(BC_ERR_MATH_OVERFLOW); + if (BC_ERR(bc_num_cmp(n, &vm->max) >= 0)) bc_err(BC_ERR_MATH_OVERFLOW); return bc_num_bigdig2(n); } @@ -3524,6 +3704,9 @@ bc_num_rng(const BcNum* restrict n, BcRNG* rng) BcNum temp, temp2, intn, frac; BcRand state1, state2, inc1, inc2; size_t nrdx = BC_NUM_RDX_VAL(n); +#if BC_ENABLE_LIBRARY + BcVm* vm = bcl_getspecific(); +#endif // BC_ENABLE_LIBRARY // This function holds the secret of how I interpret a seed number for the // PRNG. Well, it's actually in the development manual @@ -3537,11 +3720,11 @@ bc_num_rng(const BcNum* restrict n, BcRNG* rng) bc_num_init(&frac, nrdx); bc_num_init(&intn, bc_num_int(n)); - BC_SETJMP_LOCKED(err); + BC_SETJMP_LOCKED(vm, err); BC_SIG_UNLOCK; - assert(BC_NUM_RDX_VALID_NP(vm.max)); + assert(BC_NUM_RDX_VALID_NP(vm->max)); // NOLINTNEXTLINE memcpy(frac.num, n->num, BC_NUM_SIZE(nrdx)); @@ -3550,11 +3733,11 @@ bc_num_rng(const BcNum* restrict n, BcRNG* rng) frac.scale = n->scale; assert(BC_NUM_RDX_VALID_NP(frac)); - assert(BC_NUM_RDX_VALID_NP(vm.max2)); + assert(BC_NUM_RDX_VALID_NP(vm->max2)); // Multiply the fraction and truncate so that it's an integer. The // truncation is what clamps it, by the way. - bc_num_mul(&frac, &vm.max2, &temp, 0); + bc_num_mul(&frac, &vm->max2, &temp, 0); bc_num_truncate(&temp, temp.scale); bc_num_copy(&frac, &temp); @@ -3565,17 +3748,17 @@ bc_num_rng(const BcNum* restrict n, BcRNG* rng) // This assert is here because it has to be true. It is also here to justify // some optimizations. - assert(BC_NUM_NONZERO(&vm.max)); + assert(BC_NUM_NONZERO(&vm->max)); // If there *was* a fractional part... if (BC_NUM_NONZERO(&frac)) { // This divmod splits frac into the two state parts. - bc_num_divmod(&frac, &vm.max, &temp, &temp2, 0); + bc_num_divmod(&frac, &vm->max, &temp, &temp2, 0); - // frac is guaranteed to be smaller than vm.max * vm.max (pow). - // This means that when dividing frac by vm.max, as above, the - // quotient and remainder are both guaranteed to be less than vm.max, + // frac is guaranteed to be smaller than vm->max * vm->max (pow). + // This means that when dividing frac by vm->max, as above, the + // quotient and remainder are both guaranteed to be less than vm->max, // which means we can use bc_num_bigdig2() here and not worry about // overflow. state1 = (BcRand) bc_num_bigdig2(&temp2); @@ -3587,20 +3770,20 @@ bc_num_rng(const BcNum* restrict n, BcRNG* rng) if (BC_NUM_NONZERO(&intn)) { // This divmod splits intn into the two inc parts. - bc_num_divmod(&intn, &vm.max, &temp, &temp2, 0); + bc_num_divmod(&intn, &vm->max, &temp, &temp2, 0); - // Because temp2 is the mod of vm.max, from above, it is guaranteed + // Because temp2 is the mod of vm->max, from above, it is guaranteed // to be small enough to use bc_num_bigdig2(). inc1 = (BcRand) bc_num_bigdig2(&temp2); // Clamp the second inc part. - if (bc_num_cmp(&temp, &vm.max) >= 0) + if (bc_num_cmp(&temp, &vm->max) >= 0) { bc_num_copy(&temp2, &temp); - bc_num_mod(&temp2, &vm.max, &temp, 0); + bc_num_mod(&temp2, &vm->max, &temp, 0); } - // The if statement above ensures that temp is less than vm.max, which + // The if statement above ensures that temp is less than vm->max, which // means that we can use bc_num_bigdig2() here. inc2 = (BcRand) bc_num_bigdig2(&temp); } @@ -3614,7 +3797,7 @@ err: bc_num_free(&frac); bc_num_free(&temp2); bc_num_free(&temp); - BC_LONGJMP_CONT; + BC_LONGJMP_CONT(vm); } void @@ -3624,12 +3807,15 @@ bc_num_createFromRNG(BcNum* restrict n, BcRNG* rng) BcNum conv, temp1, temp2, temp3; BcDig temp1_num[BC_RAND_NUM_SIZE], temp2_num[BC_RAND_NUM_SIZE]; BcDig conv_num[BC_NUM_BIGDIG_LOG10]; +#if BC_ENABLE_LIBRARY + BcVm* vm = bcl_getspecific(); +#endif // BC_ENABLE_LIBRARY BC_SIG_LOCK; bc_num_init(&temp3, 2 * BC_RAND_NUM_SIZE); - BC_SETJMP_LOCKED(err); + BC_SETJMP_LOCKED(vm, err); BC_SIG_UNLOCK; @@ -3638,12 +3824,12 @@ bc_num_createFromRNG(BcNum* restrict n, BcRNG* rng) bc_num_setup(&conv, conv_num, sizeof(conv_num) / sizeof(BcDig)); // This assert is here because it has to be true. It is also here to justify - // the assumption that vm.max is not zero. - assert(BC_NUM_NONZERO(&vm.max)); + // the assumption that vm->max is not zero. + assert(BC_NUM_NONZERO(&vm->max)); // Because this is true, we can just ignore math errors that would happen // otherwise. - assert(BC_NUM_NONZERO(&vm.max2)); + assert(BC_NUM_NONZERO(&vm->max2)); bc_rand_getRands(rng, &s1, &s2, &i1, &i2); @@ -3653,14 +3839,14 @@ bc_num_createFromRNG(BcNum* restrict n, BcRNG* rng) assert(BC_NUM_RDX_VALID_NP(conv)); // Multiply by max to make room for the first piece of state. - bc_num_mul(&conv, &vm.max, &temp1, 0); + bc_num_mul(&conv, &vm->max, &temp1, 0); // Add in the first piece of state. bc_num_bigdig2num(&conv, (BcBigDig) s1); bc_num_add(&conv, &temp1, &temp2, 0); // Divide to make it an entirely fractional part. - bc_num_div(&temp2, &vm.max2, &temp3, BC_RAND_STATE_BITS); + bc_num_div(&temp2, &vm->max2, &temp3, BC_RAND_STATE_BITS); // Now start on the increment parts. It's the same process without the // divide, so put the second piece of increment into a number. @@ -3669,7 +3855,7 @@ bc_num_createFromRNG(BcNum* restrict n, BcRNG* rng) assert(BC_NUM_RDX_VALID_NP(conv)); // Multiply by max to make room for the first piece of increment. - bc_num_mul(&conv, &vm.max, &temp1, 0); + bc_num_mul(&conv, &vm->max, &temp1, 0); // Add in the first piece of increment. bc_num_bigdig2num(&conv, (BcBigDig) i1); @@ -3683,14 +3869,14 @@ bc_num_createFromRNG(BcNum* restrict n, BcRNG* rng) err: BC_SIG_MAYLOCK; bc_num_free(&temp3); - BC_LONGJMP_CONT; + BC_LONGJMP_CONT(vm); } void bc_num_irand(BcNum* restrict a, BcNum* restrict b, BcRNG* restrict rng) { BcNum atemp; - size_t i, len; + size_t i; assert(a != b); @@ -3699,28 +3885,87 @@ bc_num_irand(BcNum* restrict a, BcNum* restrict b, BcRNG* restrict rng) // If either of these are true, then the numbers are integers. if (BC_NUM_ZERO(a) || BC_NUM_ONE(a)) return; +#if BC_GCC + // This is here in GCC to quiet the "maybe-uninitialized" warning. + atemp.num = NULL; + atemp.len = 0; +#endif // BC_GCC + if (BC_ERR(bc_num_nonInt(a, &atemp))) bc_err(BC_ERR_MATH_NON_INTEGER); + assert(atemp.num != NULL); assert(atemp.len); - len = atemp.len - 1; + if (atemp.len > 2) + { + size_t len; - // Just generate a random number for each limb. - for (i = 0; i < len; ++i) + len = atemp.len - 2; + + // Just generate a random number for each limb. + for (i = 0; i < len; i += 2) + { + BcRand dig; + + dig = bc_rand_bounded(rng, BC_BASE_RAND_POW); + + b->num[i] = (BcDig) (dig % BC_BASE_POW); + b->num[i + 1] = (BcDig) (dig / BC_BASE_POW); + } + } + else { - b->num[i] = (BcDig) bc_rand_bounded(rng, BC_BASE_POW); + // We need this set. + i = 0; } - // Do the last digit explicitly because the bound must be right. But only - // do it if the limb does not equal 1. If it does, we have already hit the - // limit. - if (atemp.num[i] != 1) + // This will be true if there's one full limb after the two limb groups. + if (i == atemp.len - 2) { - b->num[i] = (BcDig) bc_rand_bounded(rng, (BcRand) atemp.num[i]); - b->len = atemp.len; + // Increment this for easy use. + i += 1; + + // If the last digit is not one, we need to set a bound for it + // explicitly. Since there's still an empty limb, we need to fill that. + if (atemp.num[i] != 1) + { + BcRand dig; + BcRand bound; + + // Set the bound to the bound of the last limb times the amount + // needed to fill the second-to-last limb as well. + bound = ((BcRand) atemp.num[i]) * BC_BASE_POW; + + dig = bc_rand_bounded(rng, bound); + + // Fill the last two. + b->num[i - 1] = (BcDig) (dig % BC_BASE_POW); + b->num[i] = (BcDig) (dig / BC_BASE_POW); + + // Ensure that the length will be correct. If the last limb is zero, + // then the length needs to be one less than the bound. + b->len = atemp.len - (b->num[i] == 0); + } + // Here the last limb *is* one, which means the last limb does *not* + // need to be filled. Also, the length needs to be one less because the + // last limb is 0. + else + { + b->num[i - 1] = (BcDig) bc_rand_bounded(rng, BC_BASE_POW); + b->len = atemp.len - 1; + } + } + // Here, there is only one limb to fill. + else + { + // See above for how this works. + if (atemp.num[i] != 1) + { + b->num[i] = (BcDig) bc_rand_bounded(rng, (BcRand) atemp.num[i]); + b->len = atemp.len - (b->num[i] == 0); + } + else b->len = atemp.len - 1; } - // We want 1 less len in the case where we skip the last limb. - else b->len = len; bc_num_clean(b); @@ -3883,8 +4128,13 @@ bc_num_sqrt(BcNum* restrict a, BcNum* restrict b, size_t scale) BcNum* x0; BcNum* x1; BcNum* temp; - size_t pow, len, rdx, req, resscale; + // realscale is meant to quiet a warning on GCC about longjmp() clobbering. + // This one is real. + size_t pow, len, rdx, req, resscale, realscale; BcDig half_digs[1]; +#if BC_ENABLE_LIBRARY + BcVm* vm = bcl_getspecific(); +#endif // BC_ENABLE_LIBRARY assert(a != NULL && b != NULL && a != b); @@ -3892,21 +4142,23 @@ bc_num_sqrt(BcNum* restrict a, BcNum* restrict b, size_t scale) // We want to calculate to a's scale if it is bigger so that the result will // truncate properly. - if (a->scale > scale) scale = a->scale; + if (a->scale > scale) realscale = a->scale; + else realscale = scale; // Set parameters for the result. len = bc_vm_growSize(bc_num_intDigits(a), 1); - rdx = BC_NUM_RDX(scale); + rdx = BC_NUM_RDX(realscale); // Square root needs half of the length of the parameter. req = bc_vm_growSize(BC_MAX(rdx, BC_NUM_RDX_VAL(a)), len >> 1); + req = bc_vm_growSize(req, 1); BC_SIG_LOCK; // Unlike the binary operators, this function is the only single parameter // function and is expected to initialize the result. This means that it // expects that b is *NOT* preallocated. We allocate it here. - bc_num_init(b, bc_vm_growSize(req, 1)); + bc_num_init(b, req); BC_SIG_UNLOCK; @@ -3916,7 +4168,7 @@ bc_num_sqrt(BcNum* restrict a, BcNum* restrict b, size_t scale) // Easy case. if (BC_NUM_ZERO(a)) { - bc_num_setToZero(b, scale); + bc_num_setToZero(b, realscale); return; } @@ -3924,12 +4176,12 @@ bc_num_sqrt(BcNum* restrict a, BcNum* restrict b, size_t scale) if (BC_NUM_ONE(a)) { bc_num_one(b); - bc_num_extend(b, scale); + bc_num_extend(b, realscale); return; } // Set the parameters again. - rdx = BC_NUM_RDX(scale); + rdx = BC_NUM_RDX(realscale); rdx = BC_MAX(rdx, BC_NUM_RDX_VAL(a)); len = bc_vm_growSize(a->len, rdx); @@ -3939,18 +4191,17 @@ bc_num_sqrt(BcNum* restrict a, BcNum* restrict b, size_t scale) bc_num_init(&num2, len); bc_num_setup(&half, half_digs, sizeof(half_digs) / sizeof(BcDig)); - // There is a division by two in the formula. We setup a number that's 1/2 + // There is a division by two in the formula. We set up a number that's 1/2 // so that we can use multiplication instead of heavy division. - bc_num_one(&half); + bc_num_setToZero(&half, 1); half.num[0] = BC_BASE_POW / 2; half.len = 1; BC_NUM_RDX_SET_NP(half, 1); - half.scale = 1; bc_num_init(&f, len); bc_num_init(&fprime, len); - BC_SETJMP_LOCKED(err); + BC_SETJMP_LOCKED(vm, err); BC_SIG_UNLOCK; @@ -3965,8 +4216,9 @@ bc_num_sqrt(BcNum* restrict a, BcNum* restrict b, size_t scale) pow = bc_num_intDigits(a); // The code in this if statement calculates the initial estimate. First, if - // a is less than 0, then 0 is a good estimate. Otherwise, we want something - // in the same ballpark. That ballpark is pow. + // a is less than 1, then 0 is a good estimate. Otherwise, we want something + // in the same ballpark. That ballpark is half of pow because the result + // will have half the digits. if (pow) { // An odd number is served by starting with 2^((pow-1)/2), and an even @@ -3980,7 +4232,7 @@ bc_num_sqrt(BcNum* restrict a, BcNum* restrict b, size_t scale) // I can set the rdx here directly because neg should be false. x0->scale = x0->rdx = 0; - resscale = (scale + BC_BASE_DIGS) + 2; + resscale = (realscale + BC_BASE_DIGS) + 2; // This is the calculation loop. This compare goes to 0 eventually as the // difference between the two numbers gets smaller than resscale. @@ -4007,7 +4259,7 @@ bc_num_sqrt(BcNum* restrict a, BcNum* restrict b, size_t scale) // Copy to the result and truncate. bc_num_copy(b, x0); - if (b->scale > scale) bc_num_truncate(b, b->scale - scale); + if (b->scale > realscale) bc_num_truncate(b, b->scale - realscale); assert(!BC_NUM_NEG(b) || BC_NUM_NONZERO(b)); assert(BC_NUM_RDX_VALID(b)); @@ -4020,7 +4272,7 @@ err: bc_num_free(&f); bc_num_free(&num2); bc_num_free(&num1); - BC_LONGJMP_CONT; + BC_LONGJMP_CONT(vm); } void @@ -4028,7 +4280,12 @@ bc_num_divmod(BcNum* a, BcNum* b, BcNum* c, BcNum* d, size_t scale) { size_t ts, len; BcNum *ptr_a, num2; - bool init = false; + // This is volatile to quiet a warning on GCC about clobbering with + // longjmp(). + volatile bool init = false; +#if BC_ENABLE_LIBRARY + BcVm* vm = bcl_getspecific(); +#endif // BC_ENABLE_LIBRARY // The bulk of this function is just doing what bc_num_binary() does for the // binary operators. However, it assumes that only c and a can be equal. @@ -4053,7 +4310,7 @@ bc_num_divmod(BcNum* a, BcNum* b, BcNum* c, BcNum* d, size_t scale) init = true; - BC_SETJMP_LOCKED(err); + BC_SETJMP_LOCKED(vm, err); BC_SIG_UNLOCK; } @@ -4094,7 +4351,7 @@ err: { BC_SIG_MAYLOCK; bc_num_free(&num2); - BC_LONGJMP_CONT; + BC_LONGJMP_CONT(vm); } } @@ -4103,19 +4360,21 @@ bc_num_modexp(BcNum* a, BcNum* b, BcNum* c, BcNum* restrict d) { BcNum base, exp, two, temp, atemp, btemp, ctemp; BcDig two_digs[2]; +#if BC_ENABLE_LIBRARY + BcVm* vm = bcl_getspecific(); +#endif // BC_ENABLE_LIBRARY assert(a != NULL && b != NULL && c != NULL && d != NULL); assert(a != d && b != d && c != d); if (BC_ERR(BC_NUM_ZERO(c))) bc_err(BC_ERR_MATH_DIVIDE_BY_ZERO); - if (BC_ERR(BC_NUM_NEG(b))) bc_err(BC_ERR_MATH_NEGATIVE); -#ifndef NDEBUG +#if BC_DEBUG || BC_GCC // This is entirely for quieting a useless scan-build error. btemp.len = 0; ctemp.len = 0; -#endif // NDEBUG +#endif // BC_DEBUG || BC_GCC // Eliminate fractional parts that are zero or error if they are not zero. if (BC_ERR(bc_num_nonInt(a, &atemp) || bc_num_nonInt(b, &btemp) || @@ -4133,7 +4392,7 @@ bc_num_modexp(BcNum* a, BcNum* b, BcNum* c, BcNum* restrict d) bc_num_init(&temp, btemp.len + 1); bc_num_createCopy(&exp, &btemp); - BC_SETJMP_LOCKED(err); + BC_SETJMP_LOCKED(vm, err); BC_SIG_UNLOCK; @@ -4175,7 +4434,7 @@ err: bc_num_free(&exp); bc_num_free(&temp); bc_num_free(&base); - BC_LONGJMP_CONT; + BC_LONGJMP_CONT(vm); assert(!BC_NUM_NEG(d) || d->len); assert(BC_NUM_RDX_VALID(d)); assert(!d->len || d->num[d->len - 1] || BC_NUM_RDX_VAL(d) == d->len); @@ -4185,12 +4444,12 @@ err: void bc_num_printDebug(const BcNum* n, const char* name, bool emptyline) { - bc_file_puts(&vm.fout, bc_flush_none, name); - bc_file_puts(&vm.fout, bc_flush_none, ": "); + bc_file_puts(&vm->fout, bc_flush_none, name); + bc_file_puts(&vm->fout, bc_flush_none, ": "); bc_num_printDecimal(n, true); - bc_file_putchar(&vm.fout, bc_flush_err, '\n'); - if (emptyline) bc_file_putchar(&vm.fout, bc_flush_err, '\n'); - vm.nchars = 0; + bc_file_putchar(&vm->fout, bc_flush_err, '\n'); + if (emptyline) bc_file_putchar(&vm->fout, bc_flush_err, '\n'); + vm->nchars = 0; } void @@ -4200,19 +4459,19 @@ bc_num_printDigs(const BcDig* n, size_t len, bool emptyline) for (i = len - 1; i < len; --i) { - bc_file_printf(&vm.fout, " %lu", (unsigned long) n[i]); + bc_file_printf(&vm->fout, " %lu", (unsigned long) n[i]); } - bc_file_putchar(&vm.fout, bc_flush_err, '\n'); - if (emptyline) bc_file_putchar(&vm.fout, bc_flush_err, '\n'); - vm.nchars = 0; + bc_file_putchar(&vm->fout, bc_flush_err, '\n'); + if (emptyline) bc_file_putchar(&vm->fout, bc_flush_err, '\n'); + vm->nchars = 0; } void bc_num_printWithDigs(const BcNum* n, const char* name, bool emptyline) { - bc_file_puts(&vm.fout, bc_flush_none, name); - bc_file_printf(&vm.fout, " len: %zu, rdx: %zu, scale: %zu\n", name, n->len, + bc_file_puts(&vm->fout, bc_flush_none, name); + bc_file_printf(&vm->fout, " len: %zu, rdx: %zu, scale: %zu\n", name, n->len, BC_NUM_RDX_VAL(n), n->scale); bc_num_printDigs(n->num, n->len, emptyline); } @@ -4222,19 +4481,19 @@ bc_num_dump(const char* varname, const BcNum* n) { ulong i, scale = n->scale; - bc_file_printf(&vm.ferr, "\n%s = %s", varname, + bc_file_printf(&vm->ferr, "\n%s = %s", varname, n->len ? (BC_NUM_NEG(n) ? "-" : "+") : "0 "); for (i = n->len - 1; i < n->len; --i) { if (i + 1 == BC_NUM_RDX_VAL(n)) { - bc_file_puts(&vm.ferr, bc_flush_none, ". "); + bc_file_puts(&vm->ferr, bc_flush_none, ". "); } if (scale / BC_BASE_DIGS != BC_NUM_RDX_VAL(n) - i - 1) { - bc_file_printf(&vm.ferr, "%lu ", (unsigned long) n->num[i]); + bc_file_printf(&vm->ferr, "%lu ", (unsigned long) n->num[i]); } else { @@ -4245,17 +4504,17 @@ bc_num_dump(const char* varname, const BcNum* n) if (mod != 0) { div = n->num[i] / ((BcDig) bc_num_pow10[(ulong) d]); - bc_file_printf(&vm.ferr, "%lu", (unsigned long) div); + bc_file_printf(&vm->ferr, "%lu", (unsigned long) div); } div = n->num[i] % ((BcDig) bc_num_pow10[(ulong) d]); - bc_file_printf(&vm.ferr, " ' %lu ", (unsigned long) div); + bc_file_printf(&vm->ferr, " ' %lu ", (unsigned long) div); } } - bc_file_printf(&vm.ferr, "(%zu | %zu.%zu / %zu) %lu\n", n->scale, n->len, + bc_file_printf(&vm->ferr, "(%zu | %zu.%zu / %zu) %lu\n", n->scale, n->len, BC_NUM_RDX_VAL(n), n->cap, (unsigned long) (void*) n->num); - bc_file_flush(&vm.ferr, bc_flush_err); + bc_file_flush(&vm->ferr, bc_flush_err); } #endif // BC_DEBUG_CODE diff --git a/contrib/bc/src/opt.c b/contrib/bc/src/opt.c index 9aaafcbfa780..a1c8e813b1ea 100644 --- a/contrib/bc/src/opt.c +++ b/contrib/bc/src/opt.c @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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: @@ -77,7 +77,9 @@ bc_opt_longopt(const BcOptLong* longopts, int c) BC_UNREACHABLE +#if !BC_CLANG return "NULL"; +#endif // !BC_CLANG } /** @@ -141,8 +143,8 @@ static int bc_opt_parseShort(BcOpt* o, const BcOptLong* longopts) { int type; - char* next; - char* option = o->argv[o->optind]; + const char* next; + const char* option = o->argv[o->optind]; int ret = -1; // Make sure to clear these. @@ -197,11 +199,13 @@ bc_opt_parseShort(BcOpt* o, const BcOptLong* longopts) case BC_OPT_REQUIRED_BC_ONLY: { +#if DC_ENABLED if (BC_IS_DC) { bc_opt_error(BC_ERR_FATAL_OPTION, option[0], bc_opt_longopt(longopts, option[0]), true); } +#endif // DC_ENABLED // Fallthrough BC_FALLTHROUGH @@ -269,8 +273,8 @@ bc_opt_longoptsMatch(const char* name, const char* option) * @param option The option to find the argument of. * @return A pointer to the argument of the option, or NULL if none. */ -static char* -bc_opt_longoptsArg(char* option) +static const char* +bc_opt_longoptsArg(const char* option) { // Find the end or equals sign. for (; *option && *option != '='; ++option) @@ -286,7 +290,7 @@ int bc_opt_parse(BcOpt* o, const BcOptLong* longopts) { size_t i; - char* option; + const char* option; bool empty; // This just eats empty options. @@ -328,7 +332,7 @@ bc_opt_parse(BcOpt* o, const BcOptLong* longopts) // If we have a match... if (bc_opt_longoptsMatch(name, option)) { - char* arg; + const char* arg; // Get the option char and the argument. o->optopt = longopts[i].val; @@ -375,11 +379,13 @@ bc_opt_parse(BcOpt* o, const BcOptLong* longopts) BC_UNREACHABLE +#if !BC_CLANG return -1; +#endif // !BC_CLANG } void -bc_opt_init(BcOpt* o, char* argv[]) +bc_opt_init(BcOpt* o, const char* argv[]) { o->argv = argv; o->optind = 1; diff --git a/contrib/bc/src/parse.c b/contrib/bc/src/parse.c index 43f4cfdd70f1..0107d4cdef0d 100644 --- a/contrib/bc/src/parse.c +++ b/contrib/bc/src/parse.c @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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: @@ -64,10 +64,9 @@ bc_parse_pushName(const BcParse* p, char* name, bool var) * @param inst The instruction to push. * @param idx The index to push. */ -static void -bc_parse_update(BcParse* p, uchar inst, size_t idx) +static inline void +bc_parse_pushInstIdx(BcParse* p, uchar inst, size_t idx) { - bc_parse_updateFunc(p, p->fidx); bc_parse_push(p, inst); bc_parse_pushIndex(p, idx); } @@ -77,20 +76,26 @@ bc_parse_addString(BcParse* p) { size_t idx; - idx = bc_program_addString(p->prog, p->l.str.v, p->fidx); + idx = bc_program_addString(p->prog, p->l.str.v); // Push the string info. - bc_parse_update(p, BC_INST_STR, p->fidx); - bc_parse_pushIndex(p, idx); + bc_parse_pushInstIdx(p, BC_INST_STR, idx); } static void bc_parse_addNum(BcParse* p, const char* string) { - BcVec* consts = &p->func->consts; + BcProgram* prog = p->prog; size_t idx; - BcConst* c; - BcVec* slabs; + + // XXX: This function has an implicit assumption: that string is a valid C + // string with a nul terminator. This is because of the unchecked array + // accesses below. I can't check this with an assert() because that could + // lead to out-of-bounds access. + // + // XXX: In fact, just for safety's sake, assume that this function needs a + // non-empty string with a nul terminator, just in case bc_parse_zero or + // bc_parse_one change in the future, which I doubt. BC_SIG_ASSERT_LOCKED; @@ -108,25 +113,33 @@ bc_parse_addNum(BcParse* p, const char* string) return; } - // Get the index. - idx = consts->len; + if (bc_map_insert(&prog->const_map, string, prog->consts.len, &idx)) + { + BcConst* c; + BcId* id = bc_vec_item(&prog->const_map, idx); - // Get the right slab. - slabs = p->fidx == BC_PROG_MAIN || p->fidx == BC_PROG_READ ? - &vm.main_const_slab : - &vm.other_slabs; + // Get the index. + idx = id->idx; - // Push an empty constant. - c = bc_vec_pushEmpty(consts); + // Push an empty constant. + c = bc_vec_pushEmpty(&prog->consts); - // Set the fields. - c->val = bc_slabvec_strdup(slabs, string); - c->base = BC_NUM_BIGDIG_MAX; + // Set the fields. We reuse the string in the ID (allocated by + // bc_map_insert()), because why not? + c->val = id->name; + c->base = BC_NUM_BIGDIG_MAX; - // We need this to be able to tell that the number has not been allocated. - bc_num_clear(&c->num); + // We need this to be able to tell that the number has not been + // allocated. + bc_num_clear(&c->num); + } + else + { + BcId* id = bc_vec_item(&prog->const_map, idx); + idx = id->idx; + } - bc_parse_update(p, BC_INST_NUM, idx); + bc_parse_pushInstIdx(p, BC_INST_NUM, idx); } void @@ -164,13 +177,13 @@ bc_parse_number(BcParse* p) } 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) { BC_SIG_LOCK; // Make sure the pointer isn't invalidated. p->func = bc_vec_item(&p->prog->fns, p->fidx); - bc_lex_text(&p->l, text, is_stdin, is_exprs); + bc_lex_text(&p->l, text, mode); BC_SIG_UNLOCK; } @@ -207,10 +220,10 @@ bc_parse_reset(BcParse* p) bc_program_reset(p->prog); // Jump if there is an error. - if (BC_ERR(vm.status)) BC_JMP; + if (BC_ERR(vm->status)) BC_JMP; } -#ifndef NDEBUG +#if BC_DEBUG void bc_parse_free(BcParse* p) { @@ -231,7 +244,7 @@ bc_parse_free(BcParse* p) bc_lex_free(&p->l); } -#endif // NDEBUG +#endif // BC_DEBUG void bc_parse_init(BcParse* p, BcProgram* prog, size_t func) diff --git a/contrib/bc/src/program.c b/contrib/bc/src/program.c index 20121828fa92..3b6ebc003a3e 100644 --- a/contrib/bc/src/program.c +++ b/contrib/bc/src/program.c @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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: @@ -49,20 +49,6 @@ #include <vm.h> /** - * Quickly sets the const and strs vector pointers in the program. This is a - * convenience function. - * @param p The program. - * @param f The new function. - */ -static inline void -bc_program_setVecs(BcProgram* p, BcFunc* f) -{ - BC_SIG_ASSERT_LOCKED; - p->consts = &f->consts; - p->strs = &f->strs; -} - -/** * Does a type check for something that expects a number. * @param r The result that will be checked. * @param n The result's number. @@ -124,11 +110,10 @@ bc_program_index(const char* restrict code, size_t* restrict bgn) * @param n The number tied to the result. * @return The string corresponding to the result and number. */ -static char* +static inline char* bc_program_string(BcProgram* p, const BcNum* n) { - BcFunc* f = bc_vec_item(&p->fns, n->rdx); - return *((char**) bc_vec_item(&f->strs, n->scale)); + return *((char**) bc_vec_item(&p->strs, n->scale)); } #if BC_ENABLED @@ -207,6 +192,7 @@ bc_program_dereference(const BcProgram* p, BcVec* vec) return v; } + #endif // BC_ENABLED /** @@ -232,30 +218,38 @@ bc_program_pushBigdig(BcProgram* p, BcBigDig dig, BcResultType type) } size_t -bc_program_addString(BcProgram* p, const char* str, size_t fidx) +bc_program_addString(BcProgram* p, const char* str) { - BcFunc* f; - char** str_ptr; - BcVec* slabs; + size_t idx; BC_SIG_ASSERT_LOCKED; - // Push an empty string on the proper vector. - f = bc_vec_item(&p->fns, fidx); - str_ptr = bc_vec_pushEmpty(&f->strs); + if (bc_map_insert(&p->str_map, str, p->strs.len, &idx)) + { + char** str_ptr; + BcId* id = bc_vec_item(&p->str_map, idx); + + // Get the index. + idx = id->idx; - // Figure out which slab vector to use. - slabs = fidx == BC_PROG_MAIN || fidx == BC_PROG_READ ? - &vm.main_slabs : - &vm.other_slabs; + // Push an empty string on the proper vector. + str_ptr = bc_vec_pushEmpty(&p->strs); - *str_ptr = bc_slabvec_strdup(slabs, str); + // We reuse the string in the ID (allocated by bc_map_insert()), because + // why not? + *str_ptr = id->name; + } + else + { + BcId* id = bc_vec_item(&p->str_map, idx); + idx = id->idx; + } - return f->strs.len - 1; + return idx; } size_t -bc_program_search(BcProgram* p, const char* id, bool var) +bc_program_search(BcProgram* p, const char* name, bool var) { BcVec* v; BcVec* map; @@ -271,7 +265,7 @@ bc_program_search(BcProgram* p, const char* id, bool var) // the parser calls this function. If the insert succeeds, we create a stack // for the variable/array. But regardless, bc_map_insert() gives us the // index of the item in i. - if (bc_map_insert(map, id, v->len, &i)) + if (bc_map_insert(map, name, v->len, &i)) { BcVec* temp = bc_vec_pushEmpty(v); bc_array_init(temp, var); @@ -352,7 +346,7 @@ bc_program_num(BcProgram* p, BcResult* r) { size_t idx = r->d.loc.idx; - v = bc_vec_top(v); + v = bc_vec_item(v, r->d.loc.stack_idx); #if BC_ENABLED // If this is true, we have a reference vector, so dereference @@ -382,21 +376,34 @@ bc_program_num(BcProgram* p, BcResult* r) n = bc_vec_item(v, idx); } // This is either a number (for a var) or an array (for an array). - // Because bc_vec_top() returns a void*, we don't need to cast. - else n = bc_vec_top(v); + // Because bc_vec_top() and bc_vec_item() return a void*, we don't + // need to cast. + else + { +#if BC_ENABLED + if (BC_IS_BC) + { + n = bc_vec_item(v, r->d.loc.stack_idx); + } + else +#endif // BC_ENABLED + { + n = bc_vec_top(v); + } + } break; } case BC_RESULT_ZERO: { - n = &vm.zero; + n = &vm->zero; break; } case BC_RESULT_ONE: { - n = &vm.one; + n = &vm->one; break; } @@ -404,18 +411,26 @@ bc_program_num(BcProgram* p, BcResult* r) // We should never get here; this is taken care of earlier because a // result is expected. case BC_RESULT_VOID: -#ifndef NDEBUG +#if BC_DEBUG { abort(); + // Fallthrough } -#endif // NDEBUG - // Fallthrough +#endif // BC_DEBUG case BC_RESULT_LAST: { n = &p->last; break; } #endif // BC_ENABLED + +#if BC_GCC + // This is here in GCC to quiet the "maybe-uninitialized" warning. + default: + { + abort(); + } +#endif // BC_GCC } return n; @@ -541,6 +556,7 @@ bc_program_assignPrep(BcProgram* p, BcResult** l, BcNum** ln, BcResult** r, BcNum** rn) { BcResultType lt, min; + bool good; // This is the min non-allowable result type. dc allows strings. min = BC_RESULT_TEMP - ((unsigned int) (BC_IS_BC)); @@ -555,7 +571,7 @@ bc_program_assignPrep(BcProgram* p, BcResult** l, BcNum** ln, BcResult** r, // Strings can be assigned to variables. We are already good if we are // assigning a string. - bool good = ((*r)->t == BC_RESULT_STR && lt <= BC_RESULT_ARRAY_ELEM); + good = ((*r)->t == BC_RESULT_STR && lt <= BC_RESULT_ARRAY_ELEM); assert(BC_PROG_STR(*rn) || (*r)->t != BC_RESULT_STR); @@ -627,7 +643,7 @@ bc_program_const(BcProgram* p, const char* code, size_t* bgn) // I lied. I actually push the result first. I can do this because the // result will be popped on error. I also get the constant itself. BcResult* r = bc_program_prepResult(p); - BcConst* c = bc_vec_item(p->consts, bc_program_index(code, bgn)); + BcConst* c = bc_vec_item(&p->consts, bc_program_index(code, bgn)); BcBigDig base = BC_PROG_IBASE(p); // Only reparse if the base changed. @@ -636,10 +652,15 @@ bc_program_const(BcProgram* p, const char* code, size_t* bgn) // Allocate if we haven't yet. if (c->num.num == NULL) { + // The plus 1 is in case of overflow with lack of clamping. + size_t len = strlen(c->val) + (BC_DIGIT_CLAMP == 0); + BC_SIG_LOCK; - bc_num_init(&c->num, BC_NUM_RDX(strlen(c->val))); + bc_num_init(&c->num, BC_NUM_RDX(len)); BC_SIG_UNLOCK; } + // We need to zero an already existing number. + else bc_num_zero(&c->num); // bc_num_parse() should only do operations that cannot fail. bc_num_parse(&c->num, c->val, base); @@ -702,7 +723,7 @@ bc_program_read(BcProgram* p) BcInstPtr ip; size_t i; const char* file; - bool is_stdin; + BcMode mode; BcFunc* f = bc_vec_item(&p->fns, BC_PROG_READ); // If we are already executing a read, that is an error. So look for a read @@ -716,55 +737,62 @@ bc_program_read(BcProgram* p) BC_SIG_LOCK; // Save the filename because we are going to overwrite it. - file = vm.file; - is_stdin = vm.is_stdin; + file = vm->file; + mode = vm->mode; // It is a parse error if there needs to be more than one line, so we unset // this to tell the lexer to not request more. We set it back later. - vm.is_stdin = false; + vm->mode = BC_MODE_FILE; - if (!BC_PARSE_IS_INITED(&vm.read_prs, p)) + if (!BC_PARSE_IS_INITED(&vm->read_prs, p)) { // We need to parse, but we don't want to use the existing parser // because it has state it needs to keep. (It could have a partial parse // state.) So we create a new parser. This parser is in the BcVm struct // so that it is not local, which means that a longjmp() could change // it. - bc_parse_init(&vm.read_prs, p, BC_PROG_READ); + bc_parse_init(&vm->read_prs, p, BC_PROG_READ); // We need a separate input buffer; that's why it is also in the BcVm // struct. - bc_vec_init(&vm.read_buf, sizeof(char), BC_DTOR_NONE); + bc_vec_init(&vm->read_buf, sizeof(char), BC_DTOR_NONE); } - // This needs to be updated because the parser could have been used - // somewhere else - else bc_parse_updateFunc(&vm.read_prs, BC_PROG_READ); + else + { + // This needs to be updated because the parser could have been used + // somewhere else. + bc_parse_updateFunc(&vm->read_prs, BC_PROG_READ); - BC_SETJMP_LOCKED(exec_err); + // The read buffer also needs to be emptied or else it will still + // contain previous read expressions. + bc_vec_empty(&vm->read_buf); + } + + BC_SETJMP_LOCKED(vm, exec_err); BC_SIG_UNLOCK; // Set up the lexer and the read function. - bc_lex_file(&vm.read_prs.l, bc_program_stdin_name); + bc_lex_file(&vm->read_prs.l, bc_program_stdin_name); bc_vec_popAll(&f->code); // Read a line. - if (!BC_R) s = bc_read_line(&vm.read_buf, ""); - else s = bc_read_line(&vm.read_buf, BC_IS_BC ? "read> " : "?> "); + if (!BC_R) s = bc_read_line(&vm->read_buf, ""); + else s = bc_read_line(&vm->read_buf, BC_VM_READ_PROMPT); // We should *not* have run into EOF. if (s == BC_STATUS_EOF) bc_err(BC_ERR_EXEC_READ_EXPR); - // Parse *one* expression, so is_stdin should be false. - bc_parse_text(&vm.read_prs, vm.read_buf.v, false, false); + // Parse *one* expression, so mode should not be stdin. + bc_parse_text(&vm->read_prs, vm->read_buf.v, BC_MODE_FILE); BC_SIG_LOCK; - vm.expr(&vm.read_prs, BC_PARSE_NOREAD | BC_PARSE_NEEDVAL); + vm->expr(&vm->read_prs, BC_PARSE_NOREAD | BC_PARSE_NEEDVAL); BC_SIG_UNLOCK; // We *must* have a valid expression. A semicolon cannot end an expression, // although EOF can. - if (BC_ERR(vm.read_prs.l.t != BC_LEX_NLINE && - vm.read_prs.l.t != BC_LEX_EOF)) + if (BC_ERR(vm->read_prs.l.t != BC_LEX_NLINE && + vm->read_prs.l.t != BC_LEX_EOF)) { bc_err(BC_ERR_EXEC_READ_EXPR); } @@ -783,7 +811,7 @@ bc_program_read(BcProgram* p) f = bc_vec_item(&p->fns, BC_PROG_READ); // We want a return instruction to simplify things. - bc_vec_pushByte(&f->code, vm.read_ret); + bc_vec_pushByte(&f->code, vm->read_ret); // This lock is here to make sure dc's tail calls are the same length. BC_SIG_LOCK; @@ -800,9 +828,9 @@ bc_program_read(BcProgram* p) exec_err: BC_SIG_MAYLOCK; - vm.is_stdin = is_stdin; - vm.file = file; - BC_LONGJMP_CONT; + vm->mode = (uchar) mode; + vm->file = file; + BC_LONGJMP_CONT(vm); } #if BC_ENABLE_EXTRA_MATH @@ -818,14 +846,14 @@ bc_program_rand(BcProgram* p) bc_program_pushBigdig(p, (BcBigDig) rand, BC_RESULT_TEMP); -#ifndef NDEBUG +#if BC_DEBUG // This is just to ensure that the generated number is correct. I also use // braces because I declare every local at the top of the scope. { BcResult* r = bc_vec_top(&p->results); assert(BC_NUM_RDX_VALID_NP(r->d.n)); } -#endif // NDEBUG +#endif // BC_DEBUG } #endif // BC_ENABLE_EXTRA_MATH @@ -837,12 +865,12 @@ static void bc_program_printChars(const char* str) { const char* nl; - size_t len = vm.nchars + strlen(str); + size_t len = vm->nchars + strlen(str); sig_atomic_t lock; BC_SIG_TRYLOCK(lock); - bc_file_puts(&vm.fout, bc_flush_save, str); + bc_file_puts(&vm->fout, bc_flush_save, str); // We need to update the number of characters, so we find the last newline // and set the characters accordingly. @@ -850,7 +878,7 @@ bc_program_printChars(const char* str) if (nl != NULL) len = strlen(nl + 1); - vm.nchars = len > UINT16_MAX ? UINT16_MAX : (uint16_t) len; + vm->nchars = len > UINT16_MAX ? UINT16_MAX : (uint16_t) len; BC_SIG_TRYUNLOCK(lock); } @@ -894,7 +922,7 @@ bc_program_printString(const char* restrict str) if (c == 'n') { BC_SIG_LOCK; - vm.nchars = UINT16_MAX; + vm->nchars = UINT16_MAX; BC_SIG_UNLOCK; } @@ -977,7 +1005,7 @@ bc_program_print(BcProgram* p, uchar inst, size_t idx) else { // We want to flush any stuff in the stdout buffer first. - bc_file_flush(&vm.fout, bc_flush_save); + bc_file_flush(&vm->fout, bc_flush_save); str = bc_program_string(p, n); #if BC_ENABLED @@ -992,8 +1020,8 @@ bc_program_print(BcProgram* p, uchar inst, size_t idx) } } - // bc always pops. - if (BC_IS_BC || pop) bc_vec_pop(&p->results); + // bc always pops. This macro makes sure that happens. + if (BC_PROGRAM_POP(pop)) bc_vec_pop(&p->results); } void @@ -1119,13 +1147,13 @@ bc_program_logical(BcProgram* p, uchar inst) cond = (cmp > 0); break; } -#ifndef NDEBUG +#if BC_DEBUG default: { // There is a bug if we get here. abort(); } -#endif // NDEBUG +#endif // BC_DEBUG } } @@ -1173,18 +1201,12 @@ bc_program_assignStr(BcProgram* p, BcNum* num, BcVec* v, bool push) /** * Copies a value to a variable. This is used for storing in dc as well as to * set function parameters to arguments in bc. - * @param p The program. - * @param idx The index of the variable or array to copy to. - * @param t The type to copy to. This could be a variable or an array. - * @param last Whether to grab the last item on the variable stack or not (for - * bc function parameters). This is important because if a new - * value has been pushed to the variable already, we need to grab - * the value pushed before. This happens when you have a parameter - * named something like "x", and a variable "x" is passed to - * another parameter. + * @param p The program. + * @param idx The index of the variable or array to copy to. + * @param t The type to copy to. This could be a variable or an array. */ static void -bc_program_copyToVar(BcProgram* p, size_t idx, BcType t, bool last) +bc_program_copyToVar(BcProgram* p, size_t idx, BcType t) { BcResult *ptr = NULL, r; BcVec* vec; @@ -1209,13 +1231,6 @@ bc_program_copyToVar(BcProgram* p, size_t idx, BcType t, bool last) { // Type match the result. bc_program_type_match(ptr, t); - - // Get the variable or array, taking care to get the real item. We take - // care of last with arrays later. - if (!last && var) - { - n = bc_vec_item_rev(bc_program_vec(p, ptr->d.loc.loc, t), 1); - } } #endif // BC_ENABLED @@ -1257,19 +1272,8 @@ bc_program_copyToVar(BcProgram* p, size_t idx, BcType t, bool last) if (BC_IS_BC) { - BcVec* parent; bool ref, ref_size; - // We need to figure out if the parameter is a reference or not and - // construct the reference vector, if necessary. So this gets the - // parent stack for the array. - parent = bc_program_vec(p, ptr->d.loc.loc, t); - assert(parent != NULL); - - // This takes care of last for arrays. Mostly. - if (!last) v = bc_vec_item_rev(parent, !last); - assert(v != NULL); - // True if we are using a reference. ref = (v->size == sizeof(BcNum) && t == BC_TYPE_REF); @@ -1289,8 +1293,6 @@ bc_program_copyToVar(BcProgram* p, size_t idx, BcType t, bool last) // If this is true, then we need to construct a reference. if (ref) { - assert(parent->len >= (size_t) (!last + 1)); - // Make sure the pointer was not invalidated. vec = bc_program_vec(p, idx, t); @@ -1298,7 +1300,7 @@ bc_program_copyToVar(BcProgram* p, size_t idx, BcType t, bool last) // care of last; it ensures the reference goes to the right // place. bc_vec_pushIndex(rv, ptr->d.loc.loc); - bc_vec_pushIndex(rv, parent->len - !last - 1); + bc_vec_pushIndex(rv, ptr->d.loc.stack_idx); } // If we get here, we are copying a ref to a ref. Just push a // copy of all of the bytes. @@ -1339,10 +1341,12 @@ bc_program_copyToVar(BcProgram* p, size_t idx, BcType t, bool last) void bc_program_assignBuiltin(BcProgram* p, bool scale, bool obase, BcBigDig val) { - BcVec* v; - BcBigDig* ptr; BcBigDig* ptr_t; BcBigDig max, min; +#if BC_ENABLED + BcVec* v; + BcBigDig* ptr; +#endif // BC_ENABLED assert(!scale || !obase); @@ -1351,10 +1355,14 @@ bc_program_assignBuiltin(BcProgram* p, bool scale, bool obase, BcBigDig val) { // Set the min and max. min = 0; - max = vm.maxes[BC_PROG_GLOBALS_SCALE]; + max = vm->maxes[BC_PROG_GLOBALS_SCALE]; - // Get a pointer to the stack and to the current value. +#if BC_ENABLED + // Get a pointer to the stack. v = p->globals_v + BC_PROG_GLOBALS_SCALE; +#endif // BC_ENABLED + + // Get a pointer to the current value. ptr_t = p->globals + BC_PROG_GLOBALS_SCALE; } else @@ -1365,10 +1373,14 @@ bc_program_assignBuiltin(BcProgram* p, bool scale, bool obase, BcBigDig val) { min = 0; } - max = vm.maxes[obase + BC_PROG_GLOBALS_IBASE]; + max = vm->maxes[obase + BC_PROG_GLOBALS_IBASE]; - // Get a pointer to the stack and to the current value. +#if BC_ENABLED + // Get a pointer to the stack. v = p->globals_v + BC_PROG_GLOBALS_IBASE + obase; +#endif // BC_ENABLED + + // Get a pointer to the current value. ptr_t = p->globals + BC_PROG_GLOBALS_IBASE + obase; } @@ -1385,9 +1397,13 @@ bc_program_assignBuiltin(BcProgram* p, bool scale, bool obase, BcBigDig val) bc_verr(e, min, max); } - // Set the top of the stack and the actual global value. +#if BC_ENABLED + // Set the top of the stack. ptr = bc_vec_top(v); *ptr = val; +#endif // BC_ENABLED + + // Set the actual global variable. *ptr_t = val; } @@ -1578,18 +1594,22 @@ bc_program_pushVar(BcProgram* p, const char* restrict code, { BcResult r; size_t idx = bc_program_index(code, bgn); + BcVec* v; // Set the result appropriately. r.t = BC_RESULT_VAR; r.d.loc.loc = idx; + // Get the stack for the variable. This is used in both bc and dc. + v = bc_program_vec(p, idx, BC_TYPE_VAR); + r.d.loc.stack_idx = v->len - 1; + #if DC_ENABLED // If this condition is true, then we have the hard case, where we have to // adjust dc registers. if (BC_IS_DC && (pop || copy)) { - // Get the stack for the variable and the number at the top. - BcVec* v = bc_program_vec(p, idx, BC_TYPE_VAR); + // Get the number at the top at the top of the stack. BcNum* num = bc_vec_top(v); // Ensure there are enough elements on the stack. @@ -1652,10 +1672,17 @@ bc_program_pushArray(BcProgram* p, const char* restrict code, BcResult* operand; BcNum* num; BcBigDig temp; + BcVec* v; // Get the index of the array. r.d.loc.loc = bc_program_index(code, bgn); + // We need the array to get its length. + v = bc_program_vec(p, r.d.loc.loc, BC_TYPE_ARRAY); + assert(v != NULL); + + r.d.loc.stack_idx = v->len - 1; + // Doing an array is easy; just set the result type and finish. if (inst == BC_INST_ARRAY) { @@ -1705,7 +1732,7 @@ bc_program_incdec(BcProgram* p, uchar inst) copy.t = BC_RESULT_TEMP; bc_num_createCopy(©.d.n, num); - BC_SETJMP_LOCKED(exit); + BC_SETJMP_LOCKED(vm, exit); BC_SIG_UNLOCK; @@ -1720,7 +1747,7 @@ bc_program_incdec(BcProgram* p, uchar inst) bc_vec_push(&p->results, ©); - BC_UNSETJMP; + BC_UNSETJMP(vm); BC_SIG_UNLOCK; @@ -1730,7 +1757,7 @@ bc_program_incdec(BcProgram* p, uchar inst) exit: BC_SIG_MAYLOCK; bc_num_free(©.d.n); - BC_LONGJMP_CONT; + BC_LONGJMP_CONT(vm); } /** @@ -1778,35 +1805,14 @@ bc_program_call(BcProgram* p, const char* restrict code, size_t* restrict bgn) // Push the arguments onto the stacks of their respective parameters. for (i = 0; i < nargs; ++i) { - size_t j; - bool last = true; - arg = bc_vec_top(&p->results); if (BC_ERR(arg->t == BC_RESULT_VOID)) bc_err(BC_ERR_EXEC_VOID_VAL); // Get the corresponding parameter. a = bc_vec_item(&f->autos, nargs - 1 - i); - // If I have already pushed to a var, I need to make sure I - // get the previous version, not the already pushed one. This condition - // must be true for that to even be possible. - if (arg->t == BC_RESULT_VAR || arg->t == BC_RESULT_ARRAY) - { - // Loop through all of the previous parameters. - for (j = 0; j < i && last; ++j) - { - BcAuto* aptr = bc_vec_item(&f->autos, nargs - 1 - j); - - // This condition is true if there is a previous parameter with - // the same name *and* type because variables and arrays do not - // interfere with each other. - last = (arg->d.loc.loc != aptr->idx || - (!aptr->type) != (arg->t == BC_RESULT_VAR)); - } - } - // Actually push the value onto the parameter's stack. - bc_program_copyToVar(p, a->idx, a->type, last); + bc_program_copyToVar(p, a->idx, a->type); } BC_SIG_LOCK; @@ -1953,7 +1959,7 @@ bc_program_builtin(BcProgram* p, uchar inst) #if BC_ENABLE_EXTRA_MATH assert(inst >= BC_INST_LENGTH && inst <= BC_INST_IRAND); #else // BC_ENABLE_EXTRA_MATH - assert(inst >= BC_INST_LENGTH && inst <= BC_INST_ABS); + assert(inst >= BC_INST_LENGTH && inst <= BC_INST_IS_STRING); #endif // BC_ENABLE_EXTRA_MATH #ifndef BC_PROG_NO_STACK_CHECK @@ -1974,7 +1980,8 @@ bc_program_builtin(BcProgram* p, uchar inst) // We need to ensure that strings and arrays aren't passed to most builtins. // The scale function can take strings in dc. - if (!len && (inst != BC_INST_SCALE_FUNC || BC_IS_BC)) + if (!len && (inst != BC_INST_SCALE_FUNC || BC_IS_BC) && + inst != BC_INST_IS_NUMBER && inst != BC_INST_IS_STRING) { bc_program_type_num(opd, num); } @@ -1993,7 +2000,31 @@ bc_program_builtin(BcProgram* p, uchar inst) BC_NUM_NEG_CLR_NP(res->d.n); } + + // Testing for number or string is easy. + else if (inst == BC_INST_IS_NUMBER || inst == BC_INST_IS_STRING) + { + bool cond; + bool is_str; + + BC_SIG_LOCK; + + bc_num_init(&res->d.n, BC_NUM_DEF_SIZE); + + BC_SIG_UNLOCK; + + // Test if the number is a string. + is_str = BC_PROG_STR(num); + + // This confusing condition simply means that the instruction must be + // true if is_str is, or it must be false if is_str is. Otherwise, the + // returned value is false (0). + cond = ((inst == BC_INST_IS_STRING) == is_str); + if (cond) bc_num_one(&res->d.n); + } + #if BC_ENABLE_EXTRA_MATH + // irand() is easy. else if (inst == BC_INST_IRAND) { @@ -2005,6 +2036,7 @@ bc_program_builtin(BcProgram* p, uchar inst) bc_num_irand(num, &res->d.n, &p->rng); } + #endif // BC_ENABLE_EXTRA_MATH // Everything else is...not easy. @@ -2022,6 +2054,9 @@ bc_program_builtin(BcProgram* p, uchar inst) // bc_program_num() to a vector. BcVec* v = (BcVec*) num; + // XXX: If this is changed, you should also change the similar + // code in bc_program_asciify(). + #if BC_ENABLED // Dereference the array, if necessary. if (BC_IS_BC && v->size == sizeof(uchar)) @@ -2174,58 +2209,37 @@ bc_program_modexp(BcProgram* p) static uchar bc_program_asciifyNum(BcProgram* p, BcNum* n) { - BcNum num; - BcBigDig val; - -#ifndef NDEBUG - // This is entirely to satisfy a useless scan-build error. - val = 0; -#endif // NDEBUG - - bc_num_clear(&num); - - BC_SETJMP(num_err); - - BC_SIG_LOCK; - - bc_num_createCopy(&num, n); - - BC_SIG_UNLOCK; + bc_num_copy(&p->asciify, n); // We want to clear the scale and sign for easy mod later. - bc_num_truncate(&num, num.scale); - BC_NUM_NEG_CLR_NP(num); + bc_num_truncate(&p->asciify, p->asciify.scale); + BC_NUM_NEG_CLR(&p->asciify); // This is guaranteed to not have a divide by 0 // because strmb is equal to 256. - bc_num_mod(&num, &p->strmb, &num, 0); + bc_num_mod(&p->asciify, &p->strmb, &p->asciify, 0); // This is also guaranteed to not error because num is in the range // [0, UCHAR_MAX], which is definitely in range for a BcBigDig. And // it is not negative. - val = bc_num_bigdig2(&num); - -num_err: - BC_SIG_MAYLOCK; - bc_num_free(&num); - BC_LONGJMP_CONT; - return (uchar) val; + return (uchar) bc_num_bigdig2(&p->asciify); } /** - * Executes the "asciify" command in dc. - * @param p The program. - * @param fidx The index of the current function. + * Executes the "asciify" command in bc and dc. + * @param p The program. */ static void -bc_program_asciify(BcProgram* p, size_t fidx) +bc_program_asciify(BcProgram* p) { BcResult *r, res; BcNum* n; - char str[2]; - char* str2; uchar c; size_t idx; +#if BC_ENABLED + // This is in the outer scope because it has to be freed after a jump. + char* temp_str; +#endif // BC_ENABLED // Check the stack. if (BC_ERR(!BC_PROG_STACK(&p->results, 1))) bc_err(BC_ERR_EXEC_STACK); @@ -2236,34 +2250,98 @@ bc_program_asciify(BcProgram* p, size_t fidx) bc_program_operand(p, &r, &n, 0); assert(n != NULL); + assert(BC_IS_BC || r->t != BC_RESULT_ARRAY); - // Asciify. - if (BC_PROG_NUM(r, n)) c = bc_program_asciifyNum(p, n); - else +#if BC_ENABLED + // Handle arrays in bc specially. + if (r->t == BC_RESULT_ARRAY) { - // Get the string itself, then the first character. - str2 = bc_program_string(p, n); - c = (uchar) str2[0]; + // Yes, this is one place where we need to cast the number from + // bc_program_num() to a vector. + BcVec* v = (BcVec*) n; + size_t i; + + // XXX: If this is changed, you should also change the similar code in + // bc_program_builtin(). + + // Dereference the array, if necessary. + if (v->size == sizeof(uchar)) + { + v = bc_program_dereference(p, v); + } + + assert(v->size == sizeof(BcNum)); + + // Allocate the string and set the jump for it. + BC_SIG_LOCK; + temp_str = bc_vm_malloc(v->len + 1); + BC_SETJMP_LOCKED(vm, exit); + BC_SIG_UNLOCK; + + // Convert the array. + for (i = 0; i < v->len; ++i) + { + BcNum* num = (BcNum*) bc_vec_item(v, i); + + if (BC_PROG_STR(num)) + { + temp_str[i] = (bc_program_string(p, num))[0]; + } + else + { + temp_str[i] = (char) bc_program_asciifyNum(p, num); + } + } + + temp_str[v->len] = '\0'; + + // Store the string in the slab and map, and free the temp string. + BC_SIG_LOCK; + idx = bc_program_addString(p, temp_str); + free(temp_str); + BC_UNSETJMP(vm); + BC_SIG_UNLOCK; } + else +#endif // BC_ENABLED + { + char str[2]; + char* str2; - // Fill the resulting string. - str[0] = (char) c; - str[1] = '\0'; + // Asciify. + if (BC_PROG_NUM(r, n)) c = bc_program_asciifyNum(p, n); + else + { + // Get the string itself, then the first character. + str2 = bc_program_string(p, n); + c = (uchar) str2[0]; + } - // Add the string to the data structures. - BC_SIG_LOCK; - idx = bc_program_addString(p, str, fidx); - BC_SIG_UNLOCK; + // Fill the resulting string. + str[0] = (char) c; + str[1] = '\0'; + + // Add the string to the data structures. + BC_SIG_LOCK; + idx = bc_program_addString(p, str); + BC_SIG_UNLOCK; + } // Set the result res.t = BC_RESULT_STR; bc_num_clear(&res.d.n); - res.d.n.rdx = fidx; res.d.n.scale = idx; // Pop and push. bc_vec_pop(&p->results); bc_vec_push(&p->results, &res); + + return; + +#if BC_ENABLED +exit: + free(temp_str); +#endif // BC_ENABLED } /** @@ -2365,7 +2443,7 @@ bc_program_nquit(BcProgram* p, uchar inst) // If we don't have enough executions, just quit. if (i == p->stack.len) { - vm.status = BC_STATUS_QUIT; + vm->status = BC_STATUS_QUIT; BC_JMP; } else @@ -2434,7 +2512,11 @@ bc_program_execStr(BcProgram* p, const char* restrict code, if (cond) { bool exec; - size_t idx, then_idx, else_idx; + size_t then_idx; + // These are volatile to quiet warnings on GCC about clobbering with + // longjmp(). + volatile size_t else_idx; + volatile size_t idx; // Get the index of the "then" var and "else" var. then_idx = bc_program_index(code, bgn); @@ -2446,7 +2528,7 @@ bc_program_execStr(BcProgram* p, const char* restrict code, idx = exec ? then_idx : else_idx; BC_SIG_LOCK; - BC_SETJMP_LOCKED(exit); + BC_SETJMP_LOCKED(vm, exit); // If we are supposed to execute, execute. If else_idx == SIZE_MAX, that // means there was no else clause, so if execute is false and else does @@ -2460,7 +2542,7 @@ bc_program_execStr(BcProgram* p, const char* restrict code, if (BC_ERR(!BC_PROG_STR(n))) bc_err(BC_ERR_EXEC_TYPE); - BC_UNSETJMP; + BC_UNSETJMP(vm); BC_SIG_UNLOCK; } else @@ -2489,35 +2571,35 @@ bc_program_execStr(BcProgram* p, const char* restrict code, { BC_SIG_LOCK; - if (!BC_PARSE_IS_INITED(&vm.read_prs, p)) + if (!BC_PARSE_IS_INITED(&vm->read_prs, p)) { - bc_parse_init(&vm.read_prs, p, fidx); + bc_parse_init(&vm->read_prs, p, fidx); // Initialize this too because bc_vm_shutdown() expects them to be // initialized togther. - bc_vec_init(&vm.read_buf, sizeof(char), BC_DTOR_NONE); + bc_vec_init(&vm->read_buf, sizeof(char), BC_DTOR_NONE); } // This needs to be updated because the parser could have been used // somewhere else - else bc_parse_updateFunc(&vm.read_prs, fidx); + else bc_parse_updateFunc(&vm->read_prs, fidx); - bc_lex_file(&vm.read_prs.l, vm.file); + bc_lex_file(&vm->read_prs.l, vm->file); - BC_SETJMP_LOCKED(err); + BC_SETJMP_LOCKED(vm, err); BC_SIG_UNLOCK; - // Parse. - bc_parse_text(&vm.read_prs, str, false, false); + // Parse. Only one expression is needed, so stdin isn't used. + bc_parse_text(&vm->read_prs, str, BC_MODE_FILE); BC_SIG_LOCK; - vm.expr(&vm.read_prs, BC_PARSE_NOCALL); + vm->expr(&vm->read_prs, BC_PARSE_NOCALL); - BC_UNSETJMP; + BC_UNSETJMP(vm); // We can just assert this here because // dc should parse everything until EOF. - assert(vm.read_prs.l.t == BC_LEX_EOF); + assert(vm->read_prs.l.t == BC_LEX_EOF); BC_SIG_UNLOCK; } @@ -2566,7 +2648,7 @@ err: exit: bc_vec_pop(&p->results); - BC_LONGJMP_CONT; + BC_LONGJMP_CONT(vm); } /** @@ -2614,12 +2696,29 @@ bc_program_globalSetting(BcProgram* p, uchar inst) BcBigDig val; // Make sure the instruction is valid. +#if DC_ENABLED + assert((inst >= BC_INST_LINE_LENGTH && inst <= BC_INST_LEADING_ZERO) || + (BC_IS_DC && inst == BC_INST_EXTENDED_REGISTERS)); +#else // DC_ENABLED assert(inst >= BC_INST_LINE_LENGTH && inst <= BC_INST_LEADING_ZERO); +#endif // DC_ENABLED - if (inst == BC_INST_LINE_LENGTH) val = (BcBigDig) vm.line_len; + if (inst == BC_INST_LINE_LENGTH) + { + val = (BcBigDig) vm->line_len; + } #if BC_ENABLED - else if (inst == BC_INST_GLOBAL_STACKS) val = (BC_G != 0); + else if (inst == BC_INST_GLOBAL_STACKS) + { + val = (BC_G != 0); + } #endif // BC_ENABLED +#if DC_ENABLED + else if (inst == BC_INST_EXTENDED_REGISTERS) + { + val = (DC_X != 0); + } +#endif // DC_ENABLED else val = (BC_Z != 0); // Push the global. @@ -2661,7 +2760,6 @@ bc_program_pushSeed(BcProgram* p) static void bc_program_addFunc(BcProgram* p, BcId* id_ptr) { - BcInstPtr* ip; BcFunc* f; BC_SIG_ASSERT_LOCKED; @@ -2669,13 +2767,6 @@ bc_program_addFunc(BcProgram* p, BcId* id_ptr) // Push and init. f = bc_vec_pushEmpty(&p->fns); bc_func_init(f, id_ptr->name); - - // This is to make sure pointers are updated if the array was moved. - if (p->stack.len) - { - ip = bc_vec_top(&p->stack); - bc_program_setVecs(p, (BcFunc*) bc_vec_item(&p->fns, ip->func)); - } } size_t @@ -2712,21 +2803,25 @@ bc_program_insertFunc(BcProgram* p, const char* name) return idx; } -#ifndef NDEBUG +#if BC_DEBUG || BC_ENABLE_MEMCHECK void bc_program_free(BcProgram* p) { +#if BC_ENABLED size_t i; +#endif // BC_ENABLED BC_SIG_ASSERT_LOCKED; assert(p != NULL); +#if BC_ENABLED // Free the globals stacks. for (i = 0; i < BC_PROG_GLOBALS_LEN; ++i) { bc_vec_free(p->globals_v + i); } +#endif // BC_ENABLED bc_vec_free(&p->fns); bc_vec_free(&p->fn_map); @@ -2736,6 +2831,12 @@ bc_program_free(BcProgram* p) bc_vec_free(&p->arr_map); bc_vec_free(&p->results); bc_vec_free(&p->stack); + bc_vec_free(&p->consts); + bc_vec_free(&p->const_map); + bc_vec_free(&p->strs); + bc_vec_free(&p->str_map); + + bc_num_free(&p->asciify); #if BC_ENABLED if (BC_IS_BC) bc_num_free(&p->last); @@ -2749,7 +2850,7 @@ bc_program_free(BcProgram* p) if (BC_IS_DC) bc_vec_free(&p->tail_calls); #endif // DC_ENABLED } -#endif // NDEBUG +#endif // BC_DEBUG || BC_ENABLE_MEMCHECK void bc_program_init(BcProgram* p) @@ -2770,8 +2871,10 @@ bc_program_init(BcProgram* p) { BcBigDig val = i == BC_PROG_GLOBALS_SCALE ? 0 : BC_BASE; +#if BC_ENABLED bc_vec_init(p->globals_v + i, sizeof(BcBigDig), BC_DTOR_NONE); bc_vec_push(p->globals_v + i, &val); +#endif // BC_ENABLED p->globals[i] = val; } @@ -2791,6 +2894,8 @@ bc_program_init(BcProgram* p) bc_num_setup(&p->strmb, p->strmb_num, BC_NUM_BIGDIG_LOG10); bc_num_bigdig2num(&p->strmb, BC_NUM_STREAM_BASE); + bc_num_init(&p->asciify, BC_NUM_DEF_SIZE); + #if BC_ENABLE_EXTRA_MATH // We need to initialize srand() just in case /dev/urandom and /dev/random // are not available. @@ -2802,11 +2907,11 @@ bc_program_init(BcProgram* p) if (BC_IS_BC) bc_num_init(&p->last, BC_NUM_DEF_SIZE); #endif // BC_ENABLED -#ifndef NDEBUG +#if BC_DEBUG bc_vec_init(&p->fns, sizeof(BcFunc), BC_DTOR_FUNC); -#else // NDEBUG +#else // BC_DEBUG bc_vec_init(&p->fns, sizeof(BcFunc), BC_DTOR_NONE); -#endif // NDEBUG +#endif // BC_DEBUG bc_map_init(&p->fn_map); bc_program_insertFunc(p, bc_func_main); bc_program_insertFunc(p, bc_func_read); @@ -2823,10 +2928,45 @@ bc_program_init(BcProgram* p) bc_vec_init(&p->stack, sizeof(BcInstPtr), BC_DTOR_NONE); bc_vec_push(&p->stack, &ip); - // Make sure the pointers are properly set up. - bc_program_setVecs(p, (BcFunc*) bc_vec_item(&p->fns, BC_PROG_MAIN)); + bc_vec_init(&p->consts, sizeof(BcConst), BC_DTOR_CONST); + bc_map_init(&p->const_map); + bc_vec_init(&p->strs, sizeof(char*), BC_DTOR_NONE); + bc_map_init(&p->str_map); +} + +void +bc_program_printStackTrace(BcProgram* p) +{ + size_t i, max_digits; - assert(p->consts != NULL && p->strs != NULL); + max_digits = bc_vm_numDigits(p->stack.len - 1); + + for (i = 0; i < p->stack.len; ++i) + { + BcInstPtr* ip = bc_vec_item_rev(&p->stack, i); + BcFunc* f = bc_vec_item(&p->fns, ip->func); + size_t j, digits; + + digits = bc_vm_numDigits(i); + + bc_file_puts(&vm->ferr, bc_flush_none, " "); + + for (j = 0; j < max_digits - digits; ++j) + { + bc_file_putchar(&vm->ferr, bc_flush_none, ' '); + } + + bc_file_printf(&vm->ferr, "%zu: %s", i, f->name); + +#if BC_ENABLED + if (BC_IS_BC && ip->func != BC_PROG_MAIN && ip->func != BC_PROG_READ) + { + bc_file_puts(&vm->ferr, bc_flush_none, "()"); + } +#endif // BC_ENABLED + + bc_file_putchar(&vm->ferr, bc_flush_none, '\n'); + } } void @@ -2837,11 +2977,21 @@ bc_program_reset(BcProgram* p) BC_SIG_ASSERT_LOCKED; - // Pop all but the last execution and all results. + // Pop all but the last execution. bc_vec_npop(&p->stack, p->stack.len - 1); - bc_vec_popAll(&p->results); + +#if DC_ENABLED + // We need to pop tail calls too. + if (BC_IS_DC) bc_vec_npop(&p->tail_calls, p->tail_calls.len - 1); +#endif // DC_ENABLED #if BC_ENABLED + // Clear the stack if we are in bc. We have to do this in bc because bc's + // stack is implicit. + // + // XXX: We don't do this in dc because other dc implementations don't. + if (BC_IS_BC || !BC_I) bc_vec_popAll(&p->results); + // Clear the globals' stacks. if (BC_G) bc_program_popGlobals(p, true); #endif // BC_ENABLED @@ -2852,17 +3002,18 @@ bc_program_reset(BcProgram* p) // Reset the instruction pointer. ip = bc_vec_top(&p->stack); - bc_program_setVecs(p, f); // NOLINTNEXTLINE memset(ip, 0, sizeof(BcInstPtr)); - // Write the ready message for a signal, and clear the signal. - if (vm.sig) + if (BC_SIG_INTERRUPT(vm)) { - bc_file_printf(&vm.fout, "%s", bc_program_ready_msg); - bc_file_flush(&vm.fout, bc_flush_err); - vm.sig = 0; + // Write the ready message for a signal. + bc_file_printf(&vm->fout, "%s", bc_program_ready_msg); + bc_file_flush(&vm->fout, bc_flush_err); } + + // Clear the signal. + vm->sig = 0; } void @@ -2880,35 +3031,49 @@ bc_program_exec(BcProgram* p) BcNum* num; #endif // BC_ENABLED #if !BC_HAS_COMPUTED_GOTO -#ifndef NDEBUG +#if BC_DEBUG size_t jmp_bufs_len; -#endif // NDEBUG +#endif // BC_DEBUG #endif // !BC_HAS_COMPUTED_GOTO #if BC_HAS_COMPUTED_GOTO + +#if BC_GCC +#pragma GCC diagnostic ignored "-Wpedantic" +#endif // BC_GCC + +#if BC_CLANG +#pragma clang diagnostic ignored "-Wgnu-label-as-value" +#endif // BC_CLANG + BC_PROG_LBLS; BC_PROG_LBLS_ASSERT; +#if BC_CLANG +#pragma clang diagnostic warning "-Wgnu-label-as-value" +#endif // BC_CLANG + +#if BC_GCC +#pragma GCC diagnostic warning "-Wpedantic" +#endif // BC_GCC + // BC_INST_INVALID is a marker for the end so that we don't have to have an // execution loop. func = (BcFunc*) bc_vec_item(&p->fns, BC_PROG_MAIN); bc_vec_pushByte(&func->code, BC_INST_INVALID); #endif // BC_HAS_COMPUTED_GOTO + BC_SETJMP(vm, end); + ip = bc_vec_top(&p->stack); func = (BcFunc*) bc_vec_item(&p->fns, ip->func); code = func->code.v; - // Ensure the pointers are correct. - BC_SIG_LOCK; - bc_program_setVecs(p, func); - BC_SIG_UNLOCK; - #if !BC_HAS_COMPUTED_GOTO -#ifndef NDEBUG - jmp_bufs_len = vm.jmp_bufs.len; -#endif // NDEBUG +#if BC_DEBUG + jmp_bufs_len = vm->jmp_bufs.len; +#endif // BC_DEBUG // This loop is the heart of the execution engine. It *is* the engine. For // computed goto, it is ignored. @@ -2919,6 +3084,14 @@ bc_program_exec(BcProgram* p) #if BC_HAS_COMPUTED_GOTO +#if BC_GCC +#pragma GCC diagnostic ignored "-Wpedantic" +#endif // BC_GCC + +#if BC_CLANG +#pragma clang diagnostic ignored "-Wgnu-label-as-value" +#endif // BC_CLANG + BC_PROG_JUMP(inst, code, ip); #else // BC_HAS_COMPUTED_GOTO @@ -2929,8 +3102,8 @@ bc_program_exec(BcProgram* p) #endif // BC_HAS_COMPUTED_GOTO #if BC_DEBUG_CODE - bc_file_printf(&vm.ferr, "inst: %s\n", bc_inst_names[inst]); - bc_file_flush(&vm.ferr, bc_flush_none); + bc_file_printf(&vm->ferr, "inst: %s\n", bc_inst_names[inst]); + bc_file_flush(&vm->ferr, bc_flush_none); #endif // BC_DEBUG_CODE #if !BC_HAS_COMPUTED_GOTO @@ -2991,7 +3164,6 @@ bc_program_exec(BcProgram* p) ip = bc_vec_top(&p->stack); func = bc_vec_item(&p->fns, ip->func); code = func->code.v; - bc_program_setVecs(p, func); BC_SIG_UNLOCK; BC_PROG_JUMP(inst, code, ip); @@ -3010,7 +3182,7 @@ bc_program_exec(BcProgram* p) BC_PROG_LBL(BC_INST_HALT): // clang-format on { - vm.status = BC_STATUS_QUIT; + vm->status = BC_STATUS_QUIT; // Just jump out. The jump series will take care of everything. BC_JMP; @@ -3032,7 +3204,6 @@ bc_program_exec(BcProgram* p) ip = bc_vec_top(&p->stack); func = bc_vec_item(&p->fns, ip->func); code = func->code.v; - bc_program_setVecs(p, func); BC_SIG_UNLOCK; BC_PROG_JUMP(inst, code, ip); @@ -3060,7 +3231,7 @@ bc_program_exec(BcProgram* p) { // We want to flush output before // this in case there is a prompt. - bc_file_flush(&vm.fout, bc_flush_save); + bc_file_flush(&vm->fout, bc_flush_save); bc_program_read(p); @@ -3070,7 +3241,6 @@ bc_program_exec(BcProgram* p) ip = bc_vec_top(&p->stack); func = bc_vec_item(&p->fns, ip->func); code = func->code.v; - bc_program_setVecs(p, func); BC_SIG_UNLOCK; BC_PROG_JUMP(inst, code, ip); @@ -3093,9 +3263,9 @@ bc_program_exec(BcProgram* p) #if BC_ENABLE_EXTRA_MATH BC_PROG_LBL(BC_INST_MAXRAND): #endif // BC_ENABLE_EXTRA_MATH - // clang-format on + // clang-format on { - BcBigDig dig = vm.maxes[inst - BC_INST_MAXIBASE]; + BcBigDig dig = vm->maxes[inst - BC_INST_MAXIBASE]; bc_program_pushBigdig(p, dig, BC_RESULT_TEMP); BC_PROG_JUMP(inst, code, ip); } @@ -3105,6 +3275,9 @@ bc_program_exec(BcProgram* p) #if BC_ENABLED BC_PROG_LBL(BC_INST_GLOBAL_STACKS): #endif // BC_ENABLED +#if DC_ENABLED + BC_PROG_LBL(BC_INST_EXTENDED_REGISTERS): +#endif // DC_ENABLE BC_PROG_LBL(BC_INST_LEADING_ZERO): // clang-format on { @@ -3154,10 +3327,12 @@ bc_program_exec(BcProgram* p) BC_PROG_LBL(BC_INST_SCALE_FUNC): BC_PROG_LBL(BC_INST_SQRT): BC_PROG_LBL(BC_INST_ABS): + BC_PROG_LBL(BC_INST_IS_NUMBER): + BC_PROG_LBL(BC_INST_IS_STRING): #if BC_ENABLE_EXTRA_MATH BC_PROG_LBL(BC_INST_IRAND): #endif // BC_ENABLE_EXTRA_MATH - // clang-format on + // clang-format on { bc_program_builtin(p, inst); BC_PROG_JUMP(inst, code, ip); @@ -3167,7 +3342,7 @@ bc_program_exec(BcProgram* p) BC_PROG_LBL(BC_INST_ASCIIFY): // clang-format on { - bc_program_asciify(p, ip->func); + bc_program_asciify(p); // Because we changed the execution stack and where we are // executing, we have to update all of this. @@ -3175,7 +3350,6 @@ bc_program_exec(BcProgram* p) ip = bc_vec_top(&p->stack); func = bc_vec_item(&p->fns, ip->func); code = func->code.v; - bc_program_setVecs(p, func); BC_SIG_UNLOCK; BC_PROG_JUMP(inst, code, ip); @@ -3195,7 +3369,7 @@ bc_program_exec(BcProgram* p) #if BC_ENABLED BC_PROG_LBL(BC_INST_LAST): #endif // BC_ENABLED - // clang-format on + // clang-format on { r.t = BC_RESULT_ZERO + (inst - BC_INST_ZERO); bc_vec_push(&p->results, &r); @@ -3208,13 +3382,13 @@ bc_program_exec(BcProgram* p) #if BC_ENABLED BC_PROG_LBL(BC_INST_PRINT_STR): #endif // BC_ENABLED - // clang-format on + // clang-format on { bc_program_print(p, inst, 0); // We want to flush right away to save the output for history, // if history must preserve it when taking input. - bc_file_flush(&vm.fout, bc_flush_save); + bc_file_flush(&vm->fout, bc_flush_save); BC_PROG_JUMP(inst, code, ip); } @@ -3226,7 +3400,6 @@ bc_program_exec(BcProgram* p) // Set up the result and push. r.t = BC_RESULT_STR; bc_num_clear(&r.d.n); - r.d.n.rdx = bc_program_index(code, &ip->idx); r.d.n.scale = bc_program_index(code, &ip->idx); bc_vec_push(&p->results, &r); BC_PROG_JUMP(inst, code, ip); @@ -3244,7 +3417,7 @@ bc_program_exec(BcProgram* p) BC_PROG_LBL(BC_INST_LSHIFT): BC_PROG_LBL(BC_INST_RSHIFT): #endif // BC_ENABLE_EXTRA_MATH - // clang-format on + // clang-format on { bc_program_op(p, inst); BC_PROG_JUMP(inst, code, ip); @@ -3256,7 +3429,7 @@ bc_program_exec(BcProgram* p) #if BC_ENABLE_EXTRA_MATH BC_PROG_LBL(BC_INST_TRUNC): #endif // BC_ENABLE_EXTRA_MATH - // clang-format on + // clang-format on { bc_program_unary(p, inst); BC_PROG_JUMP(inst, code, ip); @@ -3388,7 +3561,6 @@ bc_program_exec(BcProgram* p) ip = bc_vec_top(&p->stack); func = bc_vec_item(&p->fns, ip->func); code = func->code.v; - bc_program_setVecs(p, func); BC_SIG_UNLOCK; BC_PROG_JUMP(inst, code, ip); @@ -3409,7 +3581,6 @@ bc_program_exec(BcProgram* p) ip = bc_vec_top(&p->stack); func = bc_vec_item(&p->fns, ip->func); code = func->code.v; - bc_program_setVecs(p, func); BC_SIG_UNLOCK; BC_PROG_JUMP(inst, code, ip); @@ -3488,7 +3659,7 @@ bc_program_exec(BcProgram* p) // clang-format on { idx = bc_program_index(code, &ip->idx); - bc_program_copyToVar(p, idx, BC_TYPE_VAR, true); + bc_program_copyToVar(p, idx, BC_TYPE_VAR); BC_PROG_JUMP(inst, code, ip); } @@ -3505,7 +3676,6 @@ bc_program_exec(BcProgram* p) ip = bc_vec_top(&p->stack); func = bc_vec_item(&p->fns, ip->func); code = func->code.v; - bc_program_setVecs(p, func); BC_SIG_UNLOCK; BC_PROG_JUMP(inst, code, ip); @@ -3525,28 +3695,62 @@ bc_program_exec(BcProgram* p) BC_PROG_LBL(BC_INST_INVALID): // clang-format on { - return; + goto end; } #else // BC_HAS_COMPUTED_GOTO default: { BC_UNREACHABLE -#ifndef NDEBUG +#if BC_DEBUG && !BC_CLANG abort(); -#endif // NDEBUG +#endif // BC_DEBUG && !BC_CLANG } #endif // BC_HAS_COMPUTED_GOTO } -#if !BC_HAS_COMPUTED_GOTO -#ifndef NDEBUG +#if BC_HAS_COMPUTED_GOTO + +#if BC_CLANG +#pragma clang diagnostic warning "-Wgnu-label-as-value" +#endif // BC_CLANG + +#if BC_GCC +#pragma GCC diagnostic warning "-Wpedantic" +#endif // BC_GCC + +#else // BC_HAS_COMPUTED_GOTO + +#if BC_DEBUG // This is to allow me to use a debugger to see the last instruction, // which will point to which function was the problem. But it's also a // good smoke test for error handling changes. - assert(jmp_bufs_len == vm.jmp_bufs.len); -#endif // NDEBUG -#endif // !BC_HAS_COMPUTED_GOTO + assert(jmp_bufs_len == vm->jmp_bufs.len); +#endif // BC_DEBUG + +#endif // BC_HAS_COMPUTED_GOTO + } + +end: + BC_SIG_MAYLOCK; + + // This is here just to print a stack trace on interrupts. This is for + // finding infinite loops. + if (BC_SIG_INTERRUPT(vm)) + { + BcStatus s; + + bc_file_putchar(&vm->ferr, bc_flush_none, '\n'); + + bc_program_printStackTrace(p); + + s = bc_file_flushErr(&vm->ferr, bc_flush_err); + if (BC_ERR(s != BC_STATUS_SUCCESS && vm->status == BC_STATUS_SUCCESS)) + { + vm->status = (sig_atomic_t) s; + } } + + BC_LONGJMP_CONT(vm); } #if BC_DEBUG_CODE @@ -3554,9 +3758,9 @@ bc_program_exec(BcProgram* p) void bc_program_printStackDebug(BcProgram* p) { - bc_file_puts(&vm.fout, bc_flush_err, "-------------- Stack ----------\n"); + bc_file_puts(&vm->fout, bc_flush_err, "-------------- Stack ----------\n"); bc_program_printStack(p); - bc_file_puts(&vm.fout, bc_flush_err, "-------------- Stack End ------\n"); + bc_file_puts(&vm->fout, bc_flush_err, "-------------- Stack End ------\n"); } static void @@ -3581,7 +3785,7 @@ bc_program_printStr(const BcProgram* p, const char* restrict code, size_t idx = bc_program_index(code, bgn); char* s; - s = *((char**) bc_vec_item(p->strs, idx)); + s = *((char**) bc_vec_item(&p->strs, idx)); bc_vm_printf(" (\"%s\") ", s); } @@ -3604,7 +3808,7 @@ bc_program_printInst(const BcProgram* p, const char* restrict code, else if (inst == BC_INST_NUM) { size_t idx = bc_program_index(code, bgn); - BcConst* c = bc_vec_item(p->consts, idx); + BcConst* c = bc_vec_item(&p->consts, idx); bc_vm_printf("(%s)", c->val); } else if (inst == BC_INST_CALL || @@ -3638,7 +3842,7 @@ bc_program_code(const BcProgram* p) { bc_program_printInst(p, code, &ip.idx); } - bc_file_puts(&vm.fout, bc_flush_err, "\n\n"); + bc_file_puts(&vm->fout, bc_flush_err, "\n\n"); } } #endif // BC_ENABLED && DC_ENABLED diff --git a/contrib/bc/src/rand.c b/contrib/bc/src/rand.c index c762f1f36024..0f9950788f7c 100644 --- a/contrib/bc/src/rand.c +++ b/contrib/bc/src/rand.c @@ -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-2024 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 @@ -517,8 +517,11 @@ bc_rand_int(BcRNG* r) BcRand bc_rand_bounded(BcRNG* r, BcRand bound) { + BcRand rand; + BcRand threshold; + // Calculate the threshold below which we have to try again. - BcRand rand, threshold = (0 - bound) % bound; + threshold = (0 - bound) % bound; do { diff --git a/contrib/bc/src/read.c b/contrib/bc/src/read.c index 13a34fd66e53..01d804848945 100644 --- a/contrib/bc/src/read.c +++ b/contrib/bc/src/read.c @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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: @@ -143,12 +143,12 @@ bc_read_chars(BcVec* vec, const char* prompt) // Handle the prompt, if desired. if (BC_PROMPT) { - bc_file_puts(&vm.fout, bc_flush_none, prompt); - bc_file_flush(&vm.fout, bc_flush_none); + bc_file_puts(&vm->fout, bc_flush_none, prompt); + bc_file_flush(&vm->fout, bc_flush_none); } // Try reading from the buffer, and if successful, just return. - if (bc_read_buf(vec, vm.buf, &vm.buf_len)) + if (bc_read_buf(vec, vm->buf, &vm->buf_len)) { bc_vec_pushByte(vec, '\0'); return BC_STATUS_SUCCESS; @@ -162,8 +162,8 @@ bc_read_chars(BcVec* vec, const char* prompt) BC_SIG_LOCK; // Read data from stdin. - r = read(STDIN_FILENO, vm.buf + vm.buf_len, - BC_VM_STDIN_BUF_SIZE - vm.buf_len); + r = read(STDIN_FILENO, vm->buf + vm->buf_len, + BC_VM_STDIN_BUF_SIZE - vm->buf_len); // If there was an error... if (BC_UNLIKELY(r < 0)) @@ -171,20 +171,34 @@ bc_read_chars(BcVec* vec, const char* prompt) // If interupted... if (errno == EINTR) { + int sig; + // Jump out if we are supposed to quit, which certain signals // will require. - if (vm.status == (sig_atomic_t) BC_STATUS_QUIT) BC_JMP; + if (vm->status == (sig_atomic_t) BC_STATUS_QUIT) BC_JMP; + + assert(vm->sig != 0); - assert(vm.sig); + sig = (int) vm->sig; // Clear the signal and status. - vm.sig = 0; - vm.status = (sig_atomic_t) BC_STATUS_SUCCESS; + vm->sig = 0; + vm->status = (sig_atomic_t) BC_STATUS_SUCCESS; - // Print the ready message and prompt again. - bc_file_puts(&vm.fout, bc_flush_none, bc_program_ready_msg); - if (BC_PROMPT) bc_file_puts(&vm.fout, bc_flush_none, prompt); - bc_file_flush(&vm.fout, bc_flush_none); +#ifndef _WIN32 + // We don't want to print anything on a SIGWINCH. + if (sig != SIGWINCH) +#endif // _WIN32 + { + // Print the ready message and prompt again. + bc_file_puts(&vm->fout, bc_flush_none, + bc_program_ready_msg); + if (BC_PROMPT) + { + bc_file_puts(&vm->fout, bc_flush_none, prompt); + } + bc_file_flush(&vm->fout, bc_flush_none); + } BC_SIG_UNLOCK; @@ -209,11 +223,11 @@ bc_read_chars(BcVec* vec, const char* prompt) BC_SIG_LOCK; // Add to the buffer. - vm.buf_len += (size_t) r; - vm.buf[vm.buf_len] = '\0'; + vm->buf_len += (size_t) r; + vm->buf[vm->buf_len] = '\0'; // Read from the buffer. - done = bc_read_buf(vec, vm.buf, &vm.buf_len); + done = bc_read_buf(vec, vm->buf, &vm->buf_len); BC_SIG_UNLOCK; } @@ -231,9 +245,9 @@ bc_read_line(BcVec* vec, const char* prompt) #if BC_ENABLE_HISTORY // Get a line from either history or manual reading. - if (BC_TTY && !vm.history.badTerm) + if (BC_TTY && !vm->history.badTerm) { - s = bc_history_line(&vm.history, vec, prompt); + s = bc_history_line(&vm->history, vec, prompt); } else s = bc_read_chars(vec, prompt); #else // BC_ENABLE_HISTORY @@ -265,11 +279,11 @@ bc_read_file(const char* path) assert(path != NULL); -#ifndef NDEBUG +#if BC_DEBUG // Need this to quiet MSan. // NOLINTNEXTLINE memset(&pstat, 0, sizeof(struct stat)); -#endif // NDEBUG +#endif // BC_DEBUG fd = bc_read_open(path, O_RDONLY); diff --git a/contrib/bc/src/vector.c b/contrib/bc/src/vector.c index 7d492974a48c..4b49e61968df 100644 --- a/contrib/bc/src/vector.c +++ b/contrib/bc/src/vector.c @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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,7 +46,9 @@ void bc_vec_grow(BcVec* restrict v, size_t n) { size_t cap, len; +#if !BC_ENABLE_LIBRARY sig_atomic_t lock; +#endif // !BC_ENABLE_LIBRARY cap = v->cap; len = v->len + n; @@ -93,7 +95,9 @@ bc_vec_expand(BcVec* restrict v, size_t req) // Only expand if necessary. if (v->cap < req) { +#if !BC_ENABLE_LIBRARY sig_atomic_t lock; +#endif // !BC_ENABLE_LIBRARY BC_SIG_TRYLOCK(lock); @@ -107,7 +111,9 @@ bc_vec_expand(BcVec* restrict v, size_t req) void bc_vec_npop(BcVec* restrict v, size_t n) { +#if !BC_ENABLE_LIBRARY sig_atomic_t lock; +#endif // !BC_ENABLE_LIBRARY assert(v != NULL && n <= v->len); @@ -135,7 +141,9 @@ bc_vec_npopAt(BcVec* restrict v, size_t n, size_t idx) { char* ptr; char* data; +#if !BC_ENABLE_LIBRARY sig_atomic_t lock; +#endif // !BC_ENABLE_LIBRARY assert(v != NULL); assert(idx + n < v->len); @@ -168,7 +176,9 @@ bc_vec_npopAt(BcVec* restrict v, size_t n, size_t idx) void bc_vec_npush(BcVec* restrict v, size_t n, const void* data) { +#if !BC_ENABLE_LIBRARY sig_atomic_t lock; +#endif // !BC_ENABLE_LIBRARY size_t esize; assert(v != NULL && data != NULL); @@ -197,7 +207,9 @@ bc_vec_push(BcVec* restrict v, const void* data) void* bc_vec_pushEmpty(BcVec* restrict v) { +#if !BC_ENABLE_LIBRARY sig_atomic_t lock; +#endif // !BC_ENABLE_LIBRARY void* ptr; assert(v != NULL); @@ -275,7 +287,9 @@ bc_vec_pushAt(BcVec* restrict v, const void* data, size_t idx) void bc_vec_string(BcVec* restrict v, size_t len, const char* restrict str) { +#if !BC_ENABLE_LIBRARY sig_atomic_t lock; +#endif // !BC_ENABLE_LIBRARY assert(v != NULL && v->size == sizeof(char)); assert(!v->dtor); @@ -298,7 +312,9 @@ bc_vec_string(BcVec* restrict v, size_t len, const char* restrict str) void bc_vec_concat(BcVec* restrict v, const char* restrict str) { +#if !BC_ENABLE_LIBRARY sig_atomic_t lock; +#endif // !BC_ENABLE_LIBRARY assert(v != NULL && v->size == sizeof(char)); assert(!v->dtor); @@ -318,7 +334,9 @@ bc_vec_concat(BcVec* restrict v, const char* restrict str) void bc_vec_empty(BcVec* restrict v) { +#if !BC_ENABLE_LIBRARY sig_atomic_t lock; +#endif // !BC_ENABLE_LIBRARY assert(v != NULL && v->size == sizeof(char)); assert(!v->dtor); @@ -400,7 +418,7 @@ bc_map_find(const BcVec* restrict v, const char* name) while (low < high) { - size_t mid = (low + high) / 2; + size_t mid = low + (high - low) / 2; const BcId* id = bc_vec_item(v, mid); int result = strcmp(name, id->name); @@ -417,7 +435,6 @@ bc_map_insert(BcVec* restrict v, const char* name, size_t idx, size_t* restrict i) { BcId id; - BcVec* slabs; BC_SIG_ASSERT_LOCKED; @@ -432,13 +449,7 @@ bc_map_insert(BcVec* restrict v, const char* name, size_t idx, return false; } -#if BC_ENABLED - slabs = BC_IS_DC ? &vm.main_slabs : &vm.other_slabs; -#else // BC_ENABLED - slabs = &vm.main_slabs; -#endif // BC_ENABLED - - id.name = bc_slabvec_strdup(slabs, name); + id.name = bc_slabvec_strdup(&vm->slabs, name); id.idx = idx; bc_vec_pushAt(v, &id, *i); @@ -450,6 +461,7 @@ size_t bc_map_index(const BcVec* restrict v, const char* name) { size_t i; + BcId* id; assert(v != NULL && name != NULL); @@ -458,10 +470,10 @@ bc_map_index(const BcVec* restrict v, const char* name) // If out of range, return invalid. if (i >= v->len) return BC_VEC_INVALID_IDX; - // Make sure the item exists. - return strcmp(name, ((BcId*) bc_vec_item(v, i))->name) ? - BC_VEC_INVALID_IDX : - i; + id = (BcId*) bc_vec_item(v, i); + + // Make sure the item exists and return appropriately. + return strcmp(name, id->name) ? BC_VEC_INVALID_IDX : i; } #if DC_ENABLED @@ -478,7 +490,9 @@ bc_map_name(const BcVec* restrict v, size_t idx) BC_UNREACHABLE +#if !BC_CLANG return ""; +#endif // !BC_CLANG } #endif // DC_ENABLED @@ -632,17 +646,17 @@ bc_slabvec_print(BcVec* v, const char* func) size_t i; BcSlab* s; - bc_file_printf(&vm.ferr, "%s\n", func); + bc_file_printf(&vm->ferr, "%s\n", func); for (i = 0; i < v->len; ++i) { s = bc_vec_item(v, i); - bc_file_printf(&vm.ferr, "%zu { s = %zu, len = %zu }\n", i, + bc_file_printf(&vm->ferr, "%zu { s = %zu, len = %zu }\n", i, (uintptr_t) s->s, s->len); } - bc_file_puts(&vm.ferr, bc_flush_none, "\n"); - bc_file_flush(&vm.ferr, bc_flush_none); + bc_file_puts(&vm->ferr, bc_flush_none, "\n"); + bc_file_flush(&vm->ferr, bc_flush_none); } #endif // BC_DEBUG_CODE diff --git a/contrib/bc/src/vm.c b/contrib/bc/src/vm.c index 0e4a2b1216e9..636cd4ba0c1b 100644 --- a/contrib/bc/src/vm.c +++ b/contrib/bc/src/vm.c @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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: @@ -63,11 +63,21 @@ #include <vm.h> #include <read.h> #include <bc.h> +#if BC_ENABLE_LIBRARY +#include <library.h> +#endif // BC_ENABLE_LIBRARY +#if BC_ENABLE_OSSFUZZ +#include <ossfuzz.h> +#endif // BC_ENABLE_OSSFUZZ + +#if !BC_ENABLE_LIBRARY // The actual globals. -static BcDig* temps_buf[BC_VM_MAX_TEMPS]; char output_bufs[BC_VM_BUF_SIZE]; -BcVm vm; +BcVm vm_data; +BcVm* vm = &vm_data; + +#endif // !BC_ENABLE_LIBRARY #if BC_DEBUG_CODE BC_NORETURN void @@ -79,26 +89,30 @@ bc_vm_jmp(void) { #endif - assert(BC_SIG_EXC); +#if BC_ENABLE_LIBRARY + BcVm* vm = bcl_getspecific(); +#endif // BC_ENABLE_LIBRARY + + assert(BC_SIG_EXC(vm)); BC_SIG_MAYLOCK; #if BC_DEBUG_CODE - bc_file_puts(&vm.ferr, bc_flush_none, "Longjmp: "); - bc_file_puts(&vm.ferr, bc_flush_none, f); - bc_file_putchar(&vm.ferr, bc_flush_none, '\n'); - bc_file_flush(&vm.ferr, bc_flush_none); + bc_file_puts(&vm->ferr, bc_flush_none, "Longjmp: "); + bc_file_puts(&vm->ferr, bc_flush_none, f); + bc_file_putchar(&vm->ferr, bc_flush_none, '\n'); + bc_file_flush(&vm->ferr, bc_flush_none); #endif // BC_DEBUG_CODE -#ifndef NDEBUG - assert(vm.jmp_bufs.len - (size_t) vm.sig_pop); -#endif // NDEBUG +#if BC_DEBUG + assert(vm->jmp_bufs.len - (size_t) vm->sig_pop); +#endif // BC_DEBUG - if (vm.jmp_bufs.len == 0) abort(); - if (vm.sig_pop) bc_vec_pop(&vm.jmp_bufs); - else vm.sig_pop = 1; + if (vm->jmp_bufs.len == 0) abort(); + if (vm->sig_pop) bc_vec_pop(&vm->jmp_bufs); + else vm->sig_pop = 1; - siglongjmp(*((sigjmp_buf*) bc_vec_top(&vm.jmp_bufs)), 1); + siglongjmp(*((sigjmp_buf*) bc_vec_top(&vm->jmp_bufs)), 1); } #if !BC_ENABLE_LIBRARY @@ -110,21 +124,36 @@ bc_vm_jmp(void) static void bc_vm_sig(int sig) { - // There is already a signal in flight. - if (vm.status == (sig_atomic_t) BC_STATUS_QUIT || vm.sig) +#if BC_ENABLE_EDITLINE + // Editline needs this to resize the terminal. This also needs to come first + // because a resize always needs to happen. + if (sig == SIGWINCH) { - if (!BC_I || sig != SIGINT) vm.status = BC_STATUS_QUIT; + if (BC_TTY) + { + el_resize(vm->history.el); + + // If the signal was a SIGWINCH, clear it because we don't need to + // print a stack trace in that case. + if (vm->sig == SIGWINCH) + { + vm->sig = 0; + } + } + return; } +#endif // BC_ENABLE_EDITLINE -#if BC_ENABLE_EDITLINE - // Editline needs this to resize the terminal. - if (sig == SIGWINCH) + // There is already a signal in flight if this is true. + if (vm->status == (sig_atomic_t) BC_STATUS_QUIT || vm->sig != 0) { - el_resize(vm.history.el); + if (!BC_I || sig != SIGINT) vm->status = BC_STATUS_QUIT; return; } -#endif // BC_ENABLE_EDITLINE + + // We always want to set this because a stack trace can be printed if we do. + vm->sig = sig; // Only reset under these conditions; otherwise, quit. if (sig == SIGINT && BC_SIGINT && BC_I) @@ -135,16 +164,16 @@ bc_vm_sig(int sig) // Editline needs this, for some unknown reason. if (write(STDOUT_FILENO, "^C", 2) != (ssize_t) 2) { - vm.status = BC_STATUS_ERROR_FATAL; + vm->status = BC_STATUS_ERROR_FATAL; } #endif // BC_ENABLE_EDITLINE // Write the message. - if (write(STDOUT_FILENO, vm.sigmsg, vm.siglen) != (ssize_t) vm.siglen) + if (write(STDOUT_FILENO, vm->sigmsg, vm->siglen) != + (ssize_t) vm->siglen) { - vm.status = BC_STATUS_ERROR_FATAL; + vm->status = BC_STATUS_ERROR_FATAL; } - else vm.sig = 1; errno = err; } @@ -153,12 +182,12 @@ bc_vm_sig(int sig) #if BC_ENABLE_EDITLINE if (write(STDOUT_FILENO, "^C", 2) != (ssize_t) 2) { - vm.status = BC_STATUS_ERROR_FATAL; + vm->status = BC_STATUS_ERROR_FATAL; return; } #endif // BC_ENABLE_EDITLINE - vm.status = BC_STATUS_QUIT; + vm->status = BC_STATUS_QUIT; } #if BC_ENABLE_LINE_LIB @@ -170,11 +199,11 @@ bc_vm_sig(int sig) } #endif // BC_ENABLE_LINE_LIB - assert(vm.jmp_bufs.len); + assert(vm->jmp_bufs.len); // Only jump if signals are not locked. The jump will happen by whoever // unlocks signals. - if (!vm.sig_lock) BC_JMP; + if (!vm->sig_lock) BC_JMP; } /** @@ -188,8 +217,17 @@ bc_vm_sigaction(void) struct sigaction sa; sigemptyset(&sa.sa_mask); + sa.sa_flags = BC_ENABLE_EDITLINE ? 0 : SA_NODEFER; + + // This mess is to silence a warning on Clang with regards to glibc's + // sigaction handler, which activates the warning here. +#if BC_CLANG +#pragma clang diagnostic ignored "-Wdisabled-macro-expansion" +#endif // BC_CLANG sa.sa_handler = bc_vm_sig; - sa.sa_flags = SA_NODEFER; +#if BC_CLANG +#pragma clang diagnostic warning "-Wdisabled-macro-expansion" +#endif // BC_CLANG sigaction(SIGTERM, &sa, NULL); sigaction(SIGQUIT, &sa, NULL); @@ -197,7 +235,7 @@ bc_vm_sigaction(void) #if BC_ENABLE_EDITLINE // Editline needs this to resize the terminal. - sigaction(SIGWINCH, &sa, NULL); + if (BC_TTY) sigaction(SIGWINCH, &sa, NULL); #endif // BC_ENABLE_EDITLINE #if BC_ENABLE_HISTORY @@ -218,12 +256,12 @@ bc_vm_info(const char* const help) BC_SIG_ASSERT_LOCKED; // Print the banner. - bc_file_printf(&vm.fout, "%s %s\n%s", vm.name, BC_VERSION, bc_copyright); + bc_file_printf(&vm->fout, "%s %s\n%s", vm->name, BC_VERSION, bc_copyright); // Print the help. if (help != NULL) { - bc_file_putchar(&vm.fout, bc_flush_none, '\n'); + bc_file_putchar(&vm->fout, bc_flush_none, '\n'); #if BC_ENABLED if (BC_IS_BC) @@ -237,9 +275,12 @@ bc_vm_info(const char* const help) "disabled"; const char* const expr = BC_DEFAULT_EXPR_EXIT ? "to exit" : "to not exit"; + const char* const clamp = BC_DEFAULT_DIGIT_CLAMP ? "to clamp" : + "to not clamp"; - bc_file_printf(&vm.fout, help, vm.name, vm.name, BC_VERSION, - BC_BUILD_TYPE, banner, sigint, tty, prompt, expr); + bc_file_printf(&vm->fout, help, vm->name, vm->name, BC_VERSION, + BC_BUILD_TYPE, banner, sigint, tty, prompt, expr, + clamp); } #endif // BC_ENABLED @@ -254,15 +295,17 @@ bc_vm_info(const char* const help) "disabled"; const char* const expr = DC_DEFAULT_EXPR_EXIT ? "to exit" : "to not exit"; + const char* const clamp = DC_DEFAULT_DIGIT_CLAMP ? "to clamp" : + "to not clamp"; - bc_file_printf(&vm.fout, help, vm.name, vm.name, BC_VERSION, - BC_BUILD_TYPE, sigint, tty, prompt, expr); + bc_file_printf(&vm->fout, help, vm->name, vm->name, BC_VERSION, + BC_BUILD_TYPE, sigint, tty, prompt, expr, clamp); } #endif // DC_ENABLED } // Flush. - bc_file_flush(&vm.fout, bc_flush_none); + bc_file_flush(&vm->fout, bc_flush_none); } #endif // !BC_ENABLE_LIBRARY @@ -275,16 +318,22 @@ bc_vm_fatalError(BcErr e) bc_err(e); #if !BC_ENABLE_LIBRARY && !BC_ENABLE_MEMCHECK BC_UNREACHABLE +#if !BC_CLANG abort(); +#endif // !BC_CLANG #endif // !BC_ENABLE_LIBRARY && !BC_ENABLE_MEMCHECK } #if BC_ENABLE_LIBRARY -void +BC_NORETURN void bc_vm_handleError(BcErr e) { +#if BC_ENABLE_LIBRARY + BcVm* vm = bcl_getspecific(); +#endif // BC_ENABLE_LIBRARY + assert(e < BC_ERR_NELEMS); - assert(!vm.sig_pop); + assert(!vm->sig_pop); BC_SIG_LOCK; @@ -292,28 +341,34 @@ bc_vm_handleError(BcErr e) if (e <= BC_ERR_MATH_DIVIDE_BY_ZERO) { // Set the error. - vm.err = (BclError) (e - BC_ERR_MATH_NEGATIVE + - BCL_ERROR_MATH_NEGATIVE); + vm->err = (BclError) (e - BC_ERR_MATH_NEGATIVE + + BCL_ERROR_MATH_NEGATIVE); } // Abort if we should. - else if (vm.abrt) abort(); - else if (e == BC_ERR_FATAL_ALLOC_ERR) vm.err = BCL_ERROR_FATAL_ALLOC_ERR; - else vm.err = BCL_ERROR_FATAL_UNKNOWN_ERR; + else if (vm->abrt) abort(); + else if (e == BC_ERR_FATAL_ALLOC_ERR) vm->err = BCL_ERROR_FATAL_ALLOC_ERR; + else vm->err = BCL_ERROR_FATAL_UNKNOWN_ERR; BC_JMP; } #else // BC_ENABLE_LIBRARY +#if BC_DEBUG +void +bc_vm_handleError(BcErr e, const char* file, int fline, size_t line, ...) +#else // BC_DEBUG void bc_vm_handleError(BcErr e, size_t line, ...) +#endif // BC_DEBUG { BcStatus s; + BcStatus fout_s; va_list args; uchar id = bc_err_ids[e]; - const char* err_type = vm.err_ids[id]; + const char* err_type = vm->err_ids[id]; sig_atomic_t lock; assert(e < BC_ERR_NELEMS); - assert(!vm.sig_pop); + assert(!vm->sig_pop); #if BC_ENABLED // Figure out if the POSIX error should be an error, a warning, or nothing. @@ -323,7 +378,7 @@ bc_vm_handleError(BcErr e, size_t line, ...) { // Make sure to not return an error. id = UCHAR_MAX; - err_type = vm.err_ids[BC_ERR_IDX_WARN]; + err_type = vm->err_ids[BC_ERR_IDX_WARN]; } else return; } @@ -332,76 +387,89 @@ bc_vm_handleError(BcErr e, size_t line, ...) BC_SIG_TRYLOCK(lock); // Make sure all of stdout is written first. - s = bc_file_flushErr(&vm.fout, bc_flush_err); + fout_s = bc_file_flushErr(&vm->fout, bc_flush_err); - // Just jump out if the flush failed; there's nothing we can do. - if (BC_ERR(s == BC_STATUS_ERROR_FATAL)) - { - vm.status = (sig_atomic_t) s; - BC_JMP; - } + // XXX: Keep the status for later. // Print the error message. va_start(args, line); - bc_file_putchar(&vm.ferr, bc_flush_none, '\n'); - bc_file_puts(&vm.ferr, bc_flush_none, err_type); - bc_file_putchar(&vm.ferr, bc_flush_none, ' '); - bc_file_vprintf(&vm.ferr, vm.err_msgs[e], args); + bc_file_putchar(&vm->ferr, bc_flush_none, '\n'); + bc_file_puts(&vm->ferr, bc_flush_none, err_type); + bc_file_putchar(&vm->ferr, bc_flush_none, ' '); + bc_file_vprintf(&vm->ferr, vm->err_msgs[e], args); va_end(args); // Print the extra information if we have it. - if (BC_NO_ERR(vm.file != NULL)) + if (BC_NO_ERR(vm->file != NULL)) { // This is the condition for parsing vs runtime. // If line is not 0, it is parsing. if (line) { - bc_file_puts(&vm.ferr, bc_flush_none, "\n "); - bc_file_puts(&vm.ferr, bc_flush_none, vm.file); - bc_file_printf(&vm.ferr, bc_err_line, line); + bc_file_puts(&vm->ferr, bc_flush_none, "\n "); + bc_file_puts(&vm->ferr, bc_flush_none, vm->file); + bc_file_printf(&vm->ferr, ":%zu\n", line); } else { - BcInstPtr* ip = bc_vec_item_rev(&vm.prog.stack, 0); - BcFunc* f = bc_vec_item(&vm.prog.fns, ip->func); - - bc_file_puts(&vm.ferr, bc_flush_none, "\n "); - bc_file_puts(&vm.ferr, bc_flush_none, vm.func_header); - bc_file_putchar(&vm.ferr, bc_flush_none, ' '); - bc_file_puts(&vm.ferr, bc_flush_none, f->name); - -#if BC_ENABLED - if (BC_IS_BC && ip->func != BC_PROG_MAIN && - ip->func != BC_PROG_READ) - { - bc_file_puts(&vm.ferr, bc_flush_none, "()"); - } -#endif // BC_ENABLED + // Print a stack trace. + bc_file_putchar(&vm->ferr, bc_flush_none, '\n'); + bc_program_printStackTrace(&vm->prog); } } + else + { + bc_file_putchar(&vm->ferr, bc_flush_none, '\n'); + } + +#if BC_DEBUG + bc_file_printf(&vm->ferr, "\n %s:%d\n", file, fline); +#endif // BC_DEBUG + + bc_file_puts(&vm->ferr, bc_flush_none, "\n"); - bc_file_puts(&vm.ferr, bc_flush_none, "\n\n"); + // If flushing to stdout failed, try to print *that* error, as long as that + // was not the error already. + if (fout_s == BC_STATUS_ERROR_FATAL && e != BC_ERR_FATAL_IO_ERR) + { + bc_file_putchar(&vm->ferr, bc_flush_none, '\n'); + bc_file_puts(&vm->ferr, bc_flush_none, + vm->err_ids[bc_err_ids[BC_ERR_FATAL_IO_ERR]]); + bc_file_putchar(&vm->ferr, bc_flush_none, ' '); + bc_file_puts(&vm->ferr, bc_flush_none, + vm->err_msgs[BC_ERR_FATAL_IO_ERR]); + } - s = bc_file_flushErr(&vm.ferr, bc_flush_err); + s = bc_file_flushErr(&vm->ferr, bc_flush_err); #if !BC_ENABLE_MEMCHECK + // Because this function is called by a BC_NORETURN function when fatal // errors happen, we need to make sure to exit on fatal errors. This will // be faster anyway. This function *cannot jump when a fatal error occurs!* - if (BC_ERR(id == BC_ERR_IDX_FATAL || s == BC_STATUS_ERROR_FATAL)) + if (BC_ERR(id == BC_ERR_IDX_FATAL || fout_s == BC_STATUS_ERROR_FATAL || + s == BC_STATUS_ERROR_FATAL)) { - exit(bc_vm_atexit((int) BC_STATUS_ERROR_FATAL)); + exit((int) BC_STATUS_ERROR_FATAL); } + #else // !BC_ENABLE_MEMCHECK - if (BC_ERR(s == BC_STATUS_ERROR_FATAL)) vm.status = (sig_atomic_t) s; + if (BC_ERR(fout_s == BC_STATUS_ERROR_FATAL)) + { + vm->status = (sig_atomic_t) fout_s; + } + else if (BC_ERR(s == BC_STATUS_ERROR_FATAL)) + { + vm->status = (sig_atomic_t) s; + } else #endif // !BC_ENABLE_MEMCHECK { - vm.status = (sig_atomic_t) (uchar) (id + 1); + vm->status = (sig_atomic_t) (uchar) (id + 1); } // Only jump if there is an error. - if (BC_ERR(vm.status)) BC_JMP; + if (BC_ERR(vm->status)) BC_JMP; BC_SIG_TRYUNLOCK(lock); } @@ -445,12 +513,12 @@ bc_vm_setenvFlag(const char* const var, int def, uint16_t flag) if (val == NULL) { // Set the default. - if (def) vm.flags |= flag; - else vm.flags &= ~(flag); + if (def) vm->flags |= flag; + else vm->flags &= ~(flag); } // Parse the value. - else if (strtoul(val, NULL, 0)) vm.flags |= flag; - else vm.flags &= ~(flag); + else if (strtoul(val, NULL, 0)) vm->flags |= flag; + else vm->flags &= ~(flag); bc_vm_getenvFree(val); } @@ -458,9 +526,16 @@ bc_vm_setenvFlag(const char* const var, int def, uint16_t flag) /** * Parses the arguments in {B,D]C_ENV_ARGS. * @param env_args_name The environment variable to use. + * @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. */ static void -bc_vm_envArgs(const char* const env_args_name) +bc_vm_envArgs(const char* const env_args_name, BcBigDig* scale, BcBigDig* ibase, + BcBigDig* obase) { char *env_args = bc_vm_getenv(env_args_name), *buf, *start; char instr = '\0'; @@ -471,9 +546,9 @@ bc_vm_envArgs(const char* const env_args_name) // Windows already allocates, so we don't need to. #ifndef _WIN32 - start = buf = vm.env_args_buffer = bc_vm_strdup(env_args); + start = buf = vm->env_args_buffer = bc_vm_strdup(env_args); #else // _WIN32 - start = buf = vm.env_args_buffer = env_args; + start = buf = vm->env_args_buffer = env_args; #endif // _WIN32 assert(buf != NULL); @@ -481,8 +556,8 @@ bc_vm_envArgs(const char* const env_args_name) // Create two buffers for parsing. These need to stay throughout the entire // execution of bc, unfortunately, because of filenames that might be in // there. - bc_vec_init(&vm.env_args, sizeof(char*), BC_DTOR_NONE); - bc_vec_push(&vm.env_args, &env_args_name); + bc_vec_init(&vm->env_args, sizeof(char*), BC_DTOR_NONE); + bc_vec_push(&vm->env_args, &env_args_name); // While we haven't reached the end of the args... while (*buf) @@ -507,7 +582,7 @@ bc_vm_envArgs(const char* const env_args_name) } // Push the pointer to the args buffer. - bc_vec_push(&vm.env_args, &buf); + bc_vec_push(&vm->env_args, &buf); // Parse the string. while (*buf && @@ -534,11 +609,11 @@ bc_vm_envArgs(const char* const env_args_name) // Make sure to push a NULL pointer at the end. buf = NULL; - bc_vec_push(&vm.env_args, &buf); + bc_vec_push(&vm->env_args, &buf); // Parse the arguments. - bc_args((int) vm.env_args.len - 1, bc_vec_item(&vm.env_args, 0), false, - BC_PROG_SCALE(&vm.prog)); + bc_args((int) vm->env_args.len - 1, bc_vec_item(&vm->env_args, 0), false, + scale, ibase, obase); } /** @@ -568,8 +643,12 @@ bc_vm_envLen(const char* var) if (num) { // Parse it and clamp it if needed. - len = (size_t) atoi(lenv) - 1; - if (len == 1 || len >= UINT16_MAX) len = BC_NUM_PRINT_WIDTH; + len = (size_t) strtol(lenv, NULL, 10); + if (len != 0) + { + len -= 1; + if (len < 2 || len >= UINT16_MAX) len = BC_NUM_PRINT_WIDTH; + } } // Set the default. else len = BC_NUM_PRINT_WIDTH; @@ -586,100 +665,146 @@ bc_vm_shutdown(void) BC_SIG_ASSERT_LOCKED; #if BC_ENABLE_NLS - if (vm.catalog != BC_VM_INVALID_CATALOG) catclose(vm.catalog); + if (vm->catalog != BC_VM_INVALID_CATALOG) catclose(vm->catalog); #endif // BC_ENABLE_NLS +#if !BC_ENABLE_LIBRARY #if BC_ENABLE_HISTORY // This must always run to ensure that the terminal is back to normal, i.e., // has raw mode disabled. But we should only do it if we did not have a bad // terminal because history was not initialized if it is a bad terminal. - if (BC_TTY && !vm.history.badTerm) bc_history_free(&vm.history); + if (BC_TTY && !vm->history.badTerm) bc_history_free(&vm->history); #endif // BC_ENABLE_HISTORY +#endif // !BC_ENABLE_LIBRARY -#ifndef NDEBUG +#if BC_DEBUG || BC_ENABLE_MEMCHECK #if !BC_ENABLE_LIBRARY - bc_vec_free(&vm.env_args); - free(vm.env_args_buffer); - bc_vec_free(&vm.files); - bc_vec_free(&vm.exprs); + bc_vec_free(&vm->env_args); + free(vm->env_args_buffer); + bc_vec_free(&vm->files); + bc_vec_free(&vm->exprs); - if (BC_PARSE_IS_INITED(&vm.read_prs, &vm.prog)) + if (BC_PARSE_IS_INITED(&vm->read_prs, &vm->prog)) { - bc_vec_free(&vm.read_buf); - bc_parse_free(&vm.read_prs); + bc_vec_free(&vm->read_buf); + bc_parse_free(&vm->read_prs); } - bc_parse_free(&vm.prs); - bc_program_free(&vm.prog); + bc_parse_free(&vm->prs); + bc_program_free(&vm->prog); - bc_slabvec_free(&vm.other_slabs); - bc_slabvec_free(&vm.main_slabs); - bc_slabvec_free(&vm.main_const_slab); + bc_slabvec_free(&vm->slabs); #endif // !BC_ENABLE_LIBRARY bc_vm_freeTemps(); -#endif // NDEBUG +#endif // BC_DEBUG || BC_ENABLE_MEMCHECK #if !BC_ENABLE_LIBRARY // We always want to flush. - bc_file_free(&vm.fout); - bc_file_free(&vm.ferr); + bc_file_free(&vm->fout); + bc_file_free(&vm->ferr); #endif // !BC_ENABLE_LIBRARY } void bc_vm_addTemp(BcDig* num) { +#if BC_ENABLE_LIBRARY + BcVm* vm = bcl_getspecific(); +#endif // BC_ENABLE_LIBRARY + BC_SIG_ASSERT_LOCKED; // If we don't have room, just free. - if (vm.temps_len == BC_VM_MAX_TEMPS) free(num); + if (vm->temps_len == BC_VM_MAX_TEMPS) free(num); else { // Add to the buffer and length. - temps_buf[vm.temps_len] = num; - vm.temps_len += 1; + vm->temps_buf[vm->temps_len] = num; + vm->temps_len += 1; } } BcDig* bc_vm_takeTemp(void) { +#if BC_ENABLE_LIBRARY + BcVm* vm = bcl_getspecific(); +#endif // BC_ENABLE_LIBRARY + BC_SIG_ASSERT_LOCKED; - if (!vm.temps_len) return NULL; + if (!vm->temps_len) return NULL; - vm.temps_len -= 1; + vm->temps_len -= 1; - return temps_buf[vm.temps_len]; + return vm->temps_buf[vm->temps_len]; +} + +BcDig* +bc_vm_getTemp(void) +{ +#if BC_ENABLE_LIBRARY + BcVm* vm = bcl_getspecific(); +#endif // BC_ENABLE_LIBRARY + + BC_SIG_ASSERT_LOCKED; + + if (!vm->temps_len) return NULL; + + return vm->temps_buf[vm->temps_len - 1]; } void bc_vm_freeTemps(void) { size_t i; +#if BC_ENABLE_LIBRARY + BcVm* vm = bcl_getspecific(); +#endif // BC_ENABLE_LIBRARY BC_SIG_ASSERT_LOCKED; - if (!vm.temps_len) return; + if (!vm->temps_len) return; // Free them all... - for (i = 0; i < vm.temps_len; ++i) + for (i = 0; i < vm->temps_len; ++i) { - free(temps_buf[i]); + free(vm->temps_buf[i]); } - vm.temps_len = 0; + vm->temps_len = 0; } +#if !BC_ENABLE_LIBRARY + +size_t +bc_vm_numDigits(size_t val) +{ + size_t digits = 0; + + do + { + digits += 1; + val /= 10; + } + while (val != 0); + + return digits; +} + +#endif // !BC_ENABLE_LIBRARY + inline size_t bc_vm_arraySize(size_t n, size_t size) { size_t res = n * size; + if (BC_ERR(BC_VM_MUL_OVERFLOW(n, size, res))) { bc_vm_fatalError(BC_ERR_FATAL_ALLOC_ERR); } + return res; } @@ -687,10 +812,12 @@ inline size_t bc_vm_growSize(size_t a, size_t b) { size_t res = a + b; + if (BC_ERR(res >= SIZE_MAX || res < a)) { bc_vm_fatalError(BC_ERR_FATAL_ALLOC_ERR); } + return res; } @@ -762,15 +889,19 @@ void bc_vm_printf(const char* fmt, ...) { va_list args; +#if BC_ENABLE_LIBRARY + BcVm* vm = bcl_getspecific(); +#else // BC_ENABLE_LIBRARY sig_atomic_t lock; +#endif // BC_ENABLE_LIBRARY BC_SIG_TRYLOCK(lock); va_start(args, fmt); - bc_file_vprintf(&vm.fout, fmt, args); + bc_file_vprintf(&vm->fout, fmt, args); va_end(args); - vm.nchars = 0; + vm->nchars = 0; BC_SIG_TRYUNLOCK(lock); } @@ -780,10 +911,11 @@ void bc_vm_putchar(int c, BcFlushType type) { #if BC_ENABLE_LIBRARY - bc_vec_pushByte(&vm.out, (uchar) c); + BcVm* vm = bcl_getspecific(); + bc_vec_pushByte(&vm->out, (uchar) c); #else // BC_ENABLE_LIBRARY - bc_file_putchar(&vm.fout, type, (uchar) c); - vm.nchars = (c == '\n' ? 0 : vm.nchars + 1); + bc_file_putchar(&vm->fout, type, (uchar) c); + vm->nchars = (c == '\n' ? 0 : vm->nchars + 1); #endif // BC_ENABLE_LIBRARY } @@ -800,9 +932,9 @@ bc_vm_putchar(int c, BcFlushType type) BC_NORETURN static void bc_abortm(const char* msg) { - bc_file_puts(&vm.ferr, bc_flush_none, msg); - bc_file_puts(&vm.ferr, bc_flush_none, "; this is a bug"); - bc_file_flush(&vm.ferr, bc_flush_none); + bc_file_puts(&vm->ferr, bc_flush_none, msg); + bc_file_puts(&vm->ferr, bc_flush_none, "; this is a bug"); + bc_file_flush(&vm->ferr, bc_flush_none); abort(); } @@ -826,6 +958,7 @@ bc_unveil(const char* path, const char* permissions) int r = unveil(path, permissions); if (r) bc_abortm("unveil() failed"); } + #endif // BC_ENABLE_EXTRA_MATH #else // __OpenBSD__ @@ -856,20 +989,20 @@ bc_unveil(const char* path, const char* permissions) static void bc_vm_clean(void) { - BcVec* fns = &vm.prog.fns; + BcVec* fns = &vm->prog.fns; BcFunc* f = bc_vec_item(fns, BC_PROG_MAIN); - BcInstPtr* ip = bc_vec_item(&vm.prog.stack, 0); - bool good = ((vm.status && vm.status != BC_STATUS_QUIT) || vm.sig); + BcInstPtr* ip = bc_vec_item(&vm->prog.stack, 0); + bool good = ((vm->status && vm->status != BC_STATUS_QUIT) || vm->sig != 0); BC_SIG_ASSERT_LOCKED; // If all is good, go ahead and reset. - if (good) bc_program_reset(&vm.prog); + if (good) bc_program_reset(&vm->prog); #if BC_ENABLED // bc has this extra condition. If it not satisfied, it is in the middle of // a parse. - if (good && BC_IS_BC) good = !BC_PARSE_NO_EXEC(&vm.prs); + if (good && BC_IS_BC) good = !BC_PARSE_NO_EXEC(&vm->prs); #endif // BC_ENABLED #if DC_ENABLED @@ -882,9 +1015,9 @@ bc_vm_clean(void) good = true; - for (i = 0; good && i < vm.prog.results.len; ++i) + for (i = 0; good && i < vm->prog.results.len; ++i) { - BcResult* r = (BcResult*) bc_vec_item(&vm.prog.results, i); + BcResult* r = (BcResult*) bc_vec_item(&vm->prog.results, i); good = BC_VM_SAFE_RESULT(r); } } @@ -892,32 +1025,19 @@ bc_vm_clean(void) // If this condition is true, we can get rid of strings, // constants, and code. - if (good && vm.prog.stack.len == 1 && ip->idx == f->code.len) + if (good && vm->prog.stack.len == 1 && ip->idx == f->code.len) { + // XXX: Nothing can be popped in dc. Deal with it. + #if BC_ENABLED if (BC_IS_BC) { + // XXX: you cannot delete strings, functions, or constants in bc. + // Deal with it. bc_vec_popAll(&f->labels); - bc_vec_popAll(&f->strs); - bc_vec_popAll(&f->consts); - - // I can't clear out the other_slabs because it has functions, - // consts, strings, vars, and arrays. It has strings from *other* - // functions, specifically. - bc_slabvec_clear(&vm.main_const_slab); - bc_slabvec_clear(&vm.main_slabs); } #endif // BC_ENABLED -#if DC_ENABLED - // Note to self: you cannot delete strings and functions. Deal with it. - if (BC_IS_DC) - { - bc_vec_popAll(vm.prog.consts); - bc_slabvec_clear(&vm.main_const_slab); - } -#endif // DC_ENABLED - bc_vec_popAll(&f->code); ip->idx = 0; @@ -926,44 +1046,31 @@ bc_vm_clean(void) /** * Process a bunch of text. - * @param text The text to process. - * @param is_stdin True if the text came from stdin, false otherwise. - * @param is_exprs True if the text is from command-line expressions, false - * otherwise. + * @param text The text to process. + * @param mode The mode to process in. */ static void -bc_vm_process(const char* text, bool is_stdin, bool is_exprs) +bc_vm_process(const char* text, BcMode mode) { // Set up the parser. - bc_parse_text(&vm.prs, text, is_stdin, is_exprs); + bc_parse_text(&vm->prs, text, mode); - do + while (vm->prs.l.t != BC_LEX_EOF) { + // Parsing requires a signal lock. We also don't parse everything; we + // want to execute as soon as possible for *everything*. BC_SIG_LOCK; - -#if BC_ENABLED - // If the first token is the keyword define, then we need to do this - // specially because bc thinks it may not be able to parse. - if (vm.prs.l.t == BC_LEX_KW_DEFINE) vm.parse(&vm.prs); -#endif // BC_ENABLED - - // Parse it all. - while (BC_PARSE_CAN_PARSE(vm.prs)) - { - vm.parse(&vm.prs); - } - + vm->parse(&vm->prs); BC_SIG_UNLOCK; // Execute if possible. - if (BC_IS_DC || !BC_PARSE_NO_EXEC(&vm.prs)) bc_program_exec(&vm.prog); + if (BC_IS_DC || !BC_PARSE_NO_EXEC(&vm->prs)) bc_program_exec(&vm->prog); - assert(BC_IS_DC || vm.prog.results.len == 0); + assert(BC_IS_DC || vm->prog.results.len == 0); // Flush in interactive mode. - if (BC_I) bc_file_flush(&vm.fout, bc_flush_save); + if (BC_I) bc_file_flush(&vm->fout, bc_flush_save); } - while (vm.prs.l.t != BC_LEX_EOF); } #if BC_ENABLED @@ -977,9 +1084,10 @@ bc_vm_process(const char* text, bool is_stdin, bool is_exprs) static void bc_vm_endif(void) { - bc_parse_endif(&vm.prs); - bc_program_exec(&vm.prog); + bc_parse_endif(&vm->prs); + bc_program_exec(&vm->prog); } + #endif // BC_ENABLED /** @@ -990,11 +1098,16 @@ static void bc_vm_file(const char* file) { char* data = NULL; +#if BC_ENABLE_LIBRARY + BcVm* vm = bcl_getspecific(); +#endif // BC_ENABLE_LIBRARY - assert(!vm.sig_pop); + assert(!vm->sig_pop); + + vm->mode = BC_MODE_FILE; // Set up the lexer. - bc_lex_file(&vm.prs.l, file); + bc_lex_file(&vm->prs.l, file); BC_SIG_LOCK; @@ -1003,12 +1116,12 @@ bc_vm_file(const char* file) assert(data != NULL); - BC_SETJMP_LOCKED(err); + BC_SETJMP_LOCKED(vm, err); BC_SIG_UNLOCK; // Process it. - bc_vm_process(data, false, false); + bc_vm_process(data, BC_MODE_FILE); #if BC_ENABLED // Make sure to end any open if statements. @@ -1016,6 +1129,7 @@ bc_vm_file(const char* file) #endif // BC_ENABLED err: + BC_SIG_MAYLOCK; // Cleanup. @@ -1024,11 +1138,13 @@ err: // bc_program_reset(), called by bc_vm_clean(), resets the status. // We want it to clear the sig_pop variable in case it was set. - if (vm.status == (sig_atomic_t) BC_STATUS_SUCCESS) BC_LONGJMP_STOP; + if (vm->status == (sig_atomic_t) BC_STATUS_SUCCESS) BC_LONGJMP_STOP; - BC_LONGJMP_CONT; + BC_LONGJMP_CONT(vm); } +#if !BC_ENABLE_OSSFUZZ + bool bc_vm_readLine(bool clear) { @@ -1038,27 +1154,27 @@ bc_vm_readLine(bool clear) BC_SIG_ASSERT_NOT_LOCKED; // Clear the buffer if desired. - if (clear) bc_vec_empty(&vm.buffer); + if (clear) bc_vec_empty(&vm->buffer); // Empty the line buffer. - bc_vec_empty(&vm.line_buf); + bc_vec_empty(&vm->line_buf); - if (vm.eof) return false; + if (vm->eof) return false; do { // bc_read_line() must always return either BC_STATUS_SUCCESS or // BC_STATUS_EOF. Everything else, it and whatever it calls, must jump // out instead. - s = bc_read_line(&vm.line_buf, ">>> "); - vm.eof = (s == BC_STATUS_EOF); + s = bc_read_line(&vm->line_buf, ">>> "); + vm->eof = (s == BC_STATUS_EOF); } - while (!(s) && !vm.eof && vm.line_buf.len < 1); + while (s == BC_STATUS_SUCCESS && !vm->eof && vm->line_buf.len < 1); - good = (vm.line_buf.len > 1); + good = (vm->line_buf.len > 1); // Concat if we found something. - if (good) bc_vec_concat(&vm.buffer, vm.line_buf.v); + if (good) bc_vec_concat(&vm->buffer, vm->line_buf.v); return good; } @@ -1069,25 +1185,30 @@ bc_vm_readLine(bool clear) static void bc_vm_stdin(void) { - bool clear = true; + bool clear; - vm.is_stdin = true; +#if BC_ENABLE_LIBRARY + BcVm* vm = bcl_getspecific(); +#endif // BC_ENABLE_LIBRARY + + clear = true; + vm->mode = BC_MODE_STDIN; // Set up the lexer. - bc_lex_file(&vm.prs.l, bc_program_stdin_name); + bc_lex_file(&vm->prs.l, bc_program_stdin_name); // These are global so that the lexers can access them, but they are // allocated and freed in this function because they should only be used for // stdin and expressions (they are used in bc_vm_exprs() as well). So they // are tied to this function, really. Well, this and bc_vm_readLine(). These - // are the reasons that we have vm.is_stdin to tell the lexers if we are + // are the reasons that we have vm->is_stdin to tell the lexers if we are // reading from stdin. Well, both lexers care. And the reason they care is // so that if a comment or a string goes across multiple lines, the lexer // can request more data from stdin until the comment or string is ended. BC_SIG_LOCK; - bc_vec_init(&vm.buffer, sizeof(uchar), BC_DTOR_NONE); - bc_vec_init(&vm.line_buf, sizeof(uchar), BC_DTOR_NONE); - BC_SETJMP_LOCKED(err); + bc_vec_init(&vm->buffer, sizeof(uchar), BC_DTOR_NONE); + bc_vec_init(&vm->line_buf, sizeof(uchar), BC_DTOR_NONE); + BC_SETJMP_LOCKED(vm, err); BC_SIG_UNLOCK; // This label exists because errors can cause jumps to end up at the err label @@ -1098,8 +1219,8 @@ restart: // While we still read data from stdin. while (bc_vm_readLine(clear)) { - size_t len = vm.buffer.len - 1; - const char* str = vm.buffer.v; + size_t len = vm->buffer.len - 1; + const char* str = vm->buffer.v; // We don't want to clear the buffer when the line ends with a backslash // because a backslash newline is special in bc. @@ -1107,9 +1228,9 @@ restart: if (!clear) continue; // Process the data. - bc_vm_process(vm.buffer.v, true, false); + bc_vm_process(vm->buffer.v, BC_MODE_STDIN); - if (vm.eof) break; + if (vm->eof) break; else { BC_SIG_LOCK; @@ -1131,53 +1252,55 @@ err: bc_vm_clean(); #if !BC_ENABLE_MEMCHECK - assert(vm.status != BC_STATUS_ERROR_FATAL); + assert(vm->status != BC_STATUS_ERROR_FATAL); - vm.status = vm.status == BC_STATUS_QUIT || !BC_I ? vm.status : - BC_STATUS_SUCCESS; + vm->status = vm->status == BC_STATUS_QUIT || !BC_I ? vm->status : + BC_STATUS_SUCCESS; #else // !BC_ENABLE_MEMCHECK - vm.status = vm.status == BC_STATUS_ERROR_FATAL || - vm.status == BC_STATUS_QUIT || !BC_I ? - vm.status : - BC_STATUS_SUCCESS; + vm->status = vm->status == BC_STATUS_ERROR_FATAL || + vm->status == BC_STATUS_QUIT || !BC_I ? + vm->status : + BC_STATUS_SUCCESS; #endif // !BC_ENABLE_MEMCHECK - if (!vm.status && !vm.eof) + if (!vm->status && !vm->eof) { - bc_vec_empty(&vm.buffer); + bc_vec_empty(&vm->buffer); BC_LONGJMP_STOP; BC_SIG_UNLOCK; goto restart; } -#ifndef NDEBUG +#if BC_DEBUG // Since these are tied to this function, free them here. We only free in // debug mode because stdin is always the last thing read. - bc_vec_free(&vm.line_buf); - bc_vec_free(&vm.buffer); -#endif // NDEBUG + bc_vec_free(&vm->line_buf); + bc_vec_free(&vm->buffer); +#endif // BC_DEBUG - BC_LONGJMP_CONT; + BC_LONGJMP_CONT(vm); } +#endif // BC_ENABLE_OSSFUZZ + bool bc_vm_readBuf(bool clear) { - size_t len = vm.exprs.len - 1; + size_t len = vm->exprs.len - 1; bool more; BC_SIG_ASSERT_NOT_LOCKED; // Clear the buffer if desired. - if (clear) bc_vec_empty(&vm.buffer); + if (clear) bc_vec_empty(&vm->buffer); // We want to pop the nul byte off because that's what bc_read_buf() // expects. - bc_vec_pop(&vm.buffer); + bc_vec_pop(&vm->buffer); // Read one line of expressions. - more = bc_read_buf(&vm.buffer, vm.exprs.v, &len); - bc_vec_pushByte(&vm.buffer, '\0'); + more = bc_read_buf(&vm->buffer, vm->exprs.v, &len); + bc_vec_pushByte(&vm->buffer, '\0'); return more; } @@ -1185,24 +1308,31 @@ bc_vm_readBuf(bool clear) static void bc_vm_exprs(void) { - bool clear = true; + bool clear; + +#if BC_ENABLE_LIBRARY + BcVm* vm = bcl_getspecific(); +#endif // BC_ENABLE_LIBRARY + + clear = true; + vm->mode = BC_MODE_EXPRS; // Prepare the lexer. - bc_lex_file(&vm.prs.l, bc_program_exprs_name); + bc_lex_file(&vm->prs.l, bc_program_exprs_name); // We initialize this so that the lexer can access it in the case that it // needs more data for expressions, such as for a multiline string or - // comment. See the comment on the allocation of vm.buffer above in + // comment. See the comment on the allocation of vm->buffer above in // bc_vm_stdin() for more information. BC_SIG_LOCK; - bc_vec_init(&vm.buffer, sizeof(uchar), BC_DTOR_NONE); - BC_SETJMP_LOCKED(err); + bc_vec_init(&vm->buffer, sizeof(uchar), BC_DTOR_NONE); + BC_SETJMP_LOCKED(vm, err); BC_SIG_UNLOCK; while (bc_vm_readBuf(clear)) { - size_t len = vm.buffer.len - 1; - const char* str = vm.buffer.v; + size_t len = vm->buffer.len - 1; + const char* str = vm->buffer.v; // We don't want to clear the buffer when the line ends with a backslash // because a backslash newline is special in bc. @@ -1210,12 +1340,12 @@ bc_vm_exprs(void) if (!clear) continue; // Process the data. - bc_vm_process(vm.buffer.v, false, true); + bc_vm_process(vm->buffer.v, BC_MODE_EXPRS); } // If we were not supposed to clear, then we should process everything. This // makes sure that errors get reported. - if (!clear) bc_vm_process(vm.buffer.v, false, true); + if (!clear) bc_vm_process(vm->buffer.v, BC_MODE_EXPRS); err: @@ -1224,11 +1354,15 @@ err: // Cleanup. bc_vm_clean(); + // bc_program_reset(), called by bc_vm_clean(), resets the status. + // We want it to clear the sig_pop variable in case it was set. + if (vm->status == (sig_atomic_t) BC_STATUS_SUCCESS) BC_LONGJMP_STOP; + // Since this is tied to this function, free it here. We always free it here // because bc_vm_stdin() may or may not use it later. - bc_vec_free(&vm.buffer); + bc_vec_free(&vm->buffer); - BC_LONGJMP_CONT; + BC_LONGJMP_CONT(vm); } #if BC_ENABLED @@ -1241,14 +1375,14 @@ err: static void bc_vm_load(const char* name, const char* text) { - bc_lex_file(&vm.prs.l, name); - bc_parse_text(&vm.prs, text, false, false); + bc_lex_file(&vm->prs.l, name); + bc_parse_text(&vm->prs, text, BC_MODE_FILE); BC_SIG_LOCK; - while (vm.prs.l.t != BC_LEX_EOF) + while (vm->prs.l.t != BC_LEX_EOF) { - vm.parse(&vm.prs); + vm->parse(&vm->prs); } BC_SIG_UNLOCK; @@ -1264,18 +1398,16 @@ bc_vm_defaultMsgs(void) { size_t i; - vm.func_header = bc_err_func_header; - // Load the error categories. for (i = 0; i < BC_ERR_IDX_NELEMS + BC_ENABLED; ++i) { - vm.err_ids[i] = bc_errs[i]; + vm->err_ids[i] = bc_errs[i]; } // Load the error messages. for (i = 0; i < BC_ERR_NELEMS; ++i) { - vm.err_msgs[i] = bc_err_msgs[i]; + vm->err_msgs[i] = bc_err_msgs[i]; } } @@ -1288,33 +1420,30 @@ bc_vm_gettext(void) { #if BC_ENABLE_NLS uchar id = 0; - int set = 1, msg = 1; + int set, msg = 1; size_t i; // If no locale, load the defaults. - if (vm.locale == NULL) + if (vm->locale == NULL) { - vm.catalog = BC_VM_INVALID_CATALOG; + vm->catalog = BC_VM_INVALID_CATALOG; bc_vm_defaultMsgs(); return; } - vm.catalog = catopen(BC_MAINEXEC, NL_CAT_LOCALE); + vm->catalog = catopen(BC_MAINEXEC, NL_CAT_LOCALE); // If no catalog, load the defaults. - if (vm.catalog == BC_VM_INVALID_CATALOG) + if (vm->catalog == BC_VM_INVALID_CATALOG) { bc_vm_defaultMsgs(); return; } - // Load the function header. - vm.func_header = catgets(vm.catalog, set, msg, bc_err_func_header); - // Load the error categories. - for (set += 1; msg <= BC_ERR_IDX_NELEMS + BC_ENABLED; ++msg) + for (set = 1; msg <= BC_ERR_IDX_NELEMS + BC_ENABLED; ++msg) { - vm.err_ids[msg - 1] = catgets(vm.catalog, set, msg, bc_errs[msg - 1]); + vm->err_ids[msg - 1] = catgets(vm->catalog, set, msg, bc_errs[msg - 1]); } i = 0; @@ -1322,16 +1451,16 @@ bc_vm_gettext(void) // Load the error messages. In order to understand this loop, you must know // the order of messages and categories in the enum and in the locale files. - for (set = id + 3, msg = 1; i < BC_ERR_NELEMS; ++i, ++msg) + for (set = id + 2, msg = 1; i < BC_ERR_NELEMS; ++i, ++msg) { if (id != bc_err_ids[i]) { msg = 1; id = bc_err_ids[i]; - set = id + 3; + set = id + 2; } - vm.err_msgs[i] = catgets(vm.catalog, set, msg, bc_err_msgs[i]); + vm->err_msgs[i] = catgets(vm->catalog, set, msg, bc_err_msgs[i]); } #else // BC_ENABLE_NLS bc_vm_defaultMsgs(); @@ -1347,14 +1476,16 @@ static void bc_vm_exec(void) { size_t i; +#if DC_ENABLED bool has_file = false; +#endif // DC_ENABLED #if BC_ENABLED // Load the math libraries. - if (BC_IS_BC && (vm.flags & BC_FLAG_L)) + if (BC_IS_BC && (vm->flags & BC_FLAG_L)) { // Can't allow redefinitions in the builtin library. - vm.no_redefine = true; + vm->no_redefine = true; bc_vm_load(bc_lib_name, bc_lib); @@ -1363,31 +1494,41 @@ bc_vm_exec(void) #endif // BC_ENABLE_EXTRA_MATH // Make sure to clear this. - vm.no_redefine = false; + vm->no_redefine = false; // Execute to ensure that all is hunky dory. Without this, scale can be // set improperly. - bc_program_exec(&vm.prog); + bc_program_exec(&vm->prog); } #endif // BC_ENABLED + assert(!BC_ENABLE_OSSFUZZ || BC_EXPR_EXIT == 0); + // If there are expressions to execute... - if (vm.exprs.len) + if (vm->exprs.len) { // Process the expressions. bc_vm_exprs(); // Sometimes, executing expressions means we need to quit. - if (!vm.no_exprs && vm.exit_exprs && BC_EXPR_EXIT) return; + if (vm->status != BC_STATUS_SUCCESS || + (!vm->no_exprs && vm->exit_exprs && BC_EXPR_EXIT)) + { + return; + } } // Process files. - for (i = 0; i < vm.files.len; ++i) + for (i = 0; i < vm->files.len; ++i) { - char* path = *((char**) bc_vec_item(&vm.files, i)); + char* path = *((char**) bc_vec_item(&vm->files, i)); if (!strcmp(path, "")) continue; +#if DC_ENABLED has_file = true; +#endif // DC_ENABLED bc_vm_file(path); + + if (vm->status != BC_STATUS_SUCCESS) return; } #if BC_ENABLE_EXTRA_MATH @@ -1401,7 +1542,7 @@ bc_vm_exec(void) // We need to keep tty if history is enabled, and we need to keep rpath for // the times when we read from /dev/urandom. - if (BC_TTY && !vm.history.badTerm) bc_pledge(bc_pledge_end_history, NULL); + if (BC_TTY && !vm->history.badTerm) bc_pledge(bc_pledge_end_history, NULL); else #endif // BC_ENABLE_HISTORY { @@ -1416,19 +1557,40 @@ bc_vm_exec(void) __AFL_INIT(); #endif // BC_ENABLE_AFL +#if BC_ENABLE_OSSFUZZ + + if (BC_VM_RUN_STDIN(has_file)) + { + // XXX: Yes, this is a hack to run the fuzzer for OSS-Fuzz, but it + // works. + bc_vm_load("<stdin>", (const char*) bc_fuzzer_data); + } + +#else // BC_ENABLE_OSSFUZZ + // Execute from stdin. bc always does. - if (BC_IS_BC || !has_file) bc_vm_stdin(); + if (BC_VM_RUN_STDIN(has_file)) bc_vm_stdin(); + +#endif // BC_ENABLE_OSSFUZZ } -void -bc_vm_boot(int argc, char* argv[]) +BcStatus +bc_vm_boot(int argc, const char* argv[]) { int ttyin, ttyout, ttyerr; bool tty; - const char* const env_len = BC_IS_BC ? "BC_LINE_LENGTH" : "DC_LINE_LENGTH"; - const char* const env_args = BC_IS_BC ? "BC_ENV_ARGS" : "DC_ENV_ARGS"; - const char* const env_exit = BC_IS_BC ? "BC_EXPR_EXIT" : "DC_EXPR_EXIT"; - int env_exit_def = BC_IS_BC ? BC_DEFAULT_EXPR_EXIT : DC_DEFAULT_EXPR_EXIT; + const char* const env_len = BC_VM_LINE_LENGTH_STR; + const char* const env_args = BC_VM_ENV_ARGS_STR; + const char* const env_exit = BC_VM_EXPR_EXIT_STR; + const char* const env_clamp = BC_VM_DIGIT_CLAMP_STR; + int env_exit_def = BC_VM_EXPR_EXIT_DEF; + int env_clamp_def = BC_VM_DIGIT_CLAMP_DEF; + BcBigDig scale = BC_NUM_BIGDIG_MAX; + BcBigDig env_scale = BC_NUM_BIGDIG_MAX; + BcBigDig ibase = BC_NUM_BIGDIG_MAX; + BcBigDig env_ibase = BC_NUM_BIGDIG_MAX; + BcBigDig obase = BC_NUM_BIGDIG_MAX; + BcBigDig env_obase = BC_NUM_BIGDIG_MAX; // We need to know which of stdin, stdout, and stderr are tty's. ttyin = isatty(STDIN_FILENO); @@ -1436,9 +1598,9 @@ bc_vm_boot(int argc, char* argv[]) ttyerr = isatty(STDERR_FILENO); tty = (ttyin != 0 && ttyout != 0 && ttyerr != 0); - vm.flags |= ttyin ? BC_FLAG_TTYIN : 0; - vm.flags |= tty ? BC_FLAG_TTY : 0; - vm.flags |= ttyin && ttyout ? BC_FLAG_I : 0; + vm->flags |= ttyin ? BC_FLAG_TTYIN : 0; + vm->flags |= tty ? BC_FLAG_TTY : 0; + vm->flags |= ttyin && ttyout ? BC_FLAG_I : 0; // Set up signals. bc_vm_sigaction(); @@ -1448,58 +1610,60 @@ bc_vm_boot(int argc, char* argv[]) bc_vm_init(); // Explicitly set this in case NULL isn't all zeroes. - vm.file = NULL; + vm->file = NULL; // Set the error messages. bc_vm_gettext(); #if BC_ENABLE_LINE_LIB + // Initialize the output file buffers. - bc_file_init(&vm.ferr, stderr); - bc_file_init(&vm.fout, stdout); + bc_file_init(&vm->ferr, stderr, true); + bc_file_init(&vm->fout, stdout, false); // Set the input buffer. - vm.buf = output_bufs; + vm->buf = output_bufs; #else // BC_ENABLE_LINE_LIB + // Initialize the output file buffers. They each take portions of the global // buffer. stdout gets more because it will probably have more data. - bc_file_init(&vm.ferr, STDERR_FILENO, output_bufs + BC_VM_STDOUT_BUF_SIZE, - BC_VM_STDERR_BUF_SIZE); - bc_file_init(&vm.fout, STDOUT_FILENO, output_bufs, BC_VM_STDOUT_BUF_SIZE); + bc_file_init(&vm->ferr, STDERR_FILENO, output_bufs + BC_VM_STDOUT_BUF_SIZE, + BC_VM_STDERR_BUF_SIZE, true); + bc_file_init(&vm->fout, STDOUT_FILENO, output_bufs, BC_VM_STDOUT_BUF_SIZE, + false); // Set the input buffer to the rest of the global buffer. - vm.buf = output_bufs + BC_VM_STDOUT_BUF_SIZE + BC_VM_STDERR_BUF_SIZE; + vm->buf = output_bufs + BC_VM_STDOUT_BUF_SIZE + BC_VM_STDERR_BUF_SIZE; #endif // BC_ENABLE_LINE_LIB // Set the line length by environment variable. - vm.line_len = (uint16_t) bc_vm_envLen(env_len); + vm->line_len = (uint16_t) bc_vm_envLen(env_len); bc_vm_setenvFlag(env_exit, env_exit_def, BC_FLAG_EXPR_EXIT); + bc_vm_setenvFlag(env_clamp, env_clamp_def, BC_FLAG_DIGIT_CLAMP); // Clear the files and expressions vectors, just in case. This marks them as // *not* allocated. - bc_vec_clear(&vm.files); - bc_vec_clear(&vm.exprs); + bc_vec_clear(&vm->files); + bc_vec_clear(&vm->exprs); #if !BC_ENABLE_LIBRARY - // Initialize the slab vectors. - bc_slabvec_init(&vm.main_const_slab); - bc_slabvec_init(&vm.main_slabs); - bc_slabvec_init(&vm.other_slabs); + // Initialize the slab vector. + bc_slabvec_init(&vm->slabs); #endif // !BC_ENABLE_LIBRARY // Initialize the program and main parser. These have to be in this order // because the program has to be initialized first, since a pointer to it is // passed to the parser. - bc_program_init(&vm.prog); - bc_parse_init(&vm.prs, &vm.prog, BC_PROG_MAIN); + bc_program_init(&vm->prog); + bc_parse_init(&vm->prs, &vm->prog, BC_PROG_MAIN); // Set defaults. - vm.flags |= BC_TTY ? BC_FLAG_P | BC_FLAG_R : 0; - vm.flags |= BC_I ? BC_FLAG_Q : 0; + vm->flags |= BC_TTY ? BC_FLAG_P | BC_FLAG_R : 0; + vm->flags |= BC_I ? BC_FLAG_Q : 0; #if BC_ENABLED if (BC_IS_BC) @@ -1508,7 +1672,7 @@ bc_vm_boot(int argc, char* argv[]) // standard mode. char* var = bc_vm_getenv("POSIXLY_CORRECT"); - vm.flags |= BC_FLAG_S * (var != NULL); + vm->flags |= BC_FLAG_S * (var != NULL); bc_vm_getenvFree(var); // Set whether we print the banner or not. @@ -1519,10 +1683,10 @@ bc_vm_boot(int argc, char* argv[]) // Are we in TTY mode? if (BC_TTY) { - const char* const env_tty = BC_IS_BC ? "BC_TTY_MODE" : "DC_TTY_MODE"; - int env_tty_def = BC_IS_BC ? BC_DEFAULT_TTY_MODE : DC_DEFAULT_TTY_MODE; - const char* const env_prompt = BC_IS_BC ? "BC_PROMPT" : "DC_PROMPT"; - int env_prompt_def = BC_IS_BC ? BC_DEFAULT_PROMPT : DC_DEFAULT_PROMPT; + const char* const env_tty = BC_VM_TTY_MODE_STR; + int env_tty_def = BC_VM_TTY_MODE_DEF; + const char* const env_prompt = BC_VM_PROMPT_STR; + int env_prompt_def = BC_VM_PROMPT_DEF; // Set flags for TTY mode and prompt. bc_vm_setenvFlag(env_tty, env_tty_def, BC_FLAG_TTY); @@ -1530,21 +1694,52 @@ bc_vm_boot(int argc, char* argv[]) #if BC_ENABLE_HISTORY // If TTY mode is used, activate history. - if (BC_TTY) bc_history_init(&vm.history); + if (BC_TTY) bc_history_init(&vm->history); #endif // BC_ENABLE_HISTORY } // Process environment and command-line arguments. - bc_vm_envArgs(env_args); - bc_args(argc, argv, true, BC_PROG_SCALE(&vm.prog)); + bc_vm_envArgs(env_args, &env_scale, &env_ibase, &env_obase); + bc_args(argc, argv, true, &scale, &ibase, &obase); + + // This section is here because we don't want the math library to stomp on + // the user's given value for scale. And we don't want ibase affecting how + // the scale is interpreted. Also, it's sectioned off just for this comment. + { + BC_SIG_UNLOCK; + + scale = scale == BC_NUM_BIGDIG_MAX ? env_scale : scale; +#if BC_ENABLED + // Assign the library value only if it is used and no value was set. + scale = scale == BC_NUM_BIGDIG_MAX && BC_L ? 20 : scale; +#endif // BC_ENABLED + obase = obase == BC_NUM_BIGDIG_MAX ? env_obase : obase; + ibase = ibase == BC_NUM_BIGDIG_MAX ? env_ibase : ibase; + + if (scale != BC_NUM_BIGDIG_MAX) + { + bc_program_assignBuiltin(&vm->prog, true, false, scale); + } + + if (obase != BC_NUM_BIGDIG_MAX) + { + bc_program_assignBuiltin(&vm->prog, false, true, obase); + } + + // This is last to avoid it affecting the value of the others. + if (ibase != BC_NUM_BIGDIG_MAX) + { + bc_program_assignBuiltin(&vm->prog, false, false, ibase); + } + + BC_SIG_LOCK; + } // If we are in interactive mode... if (BC_I) { - const char* const env_sigint = BC_IS_BC ? "BC_SIGINT_RESET" : - "DC_SIGINT_RESET"; - int env_sigint_def = BC_IS_BC ? BC_DEFAULT_SIGINT_RESET : - DC_DEFAULT_SIGINT_RESET; + const char* const env_sigint = BC_VM_SIGINT_RESET_STR; + int env_sigint_def = BC_VM_SIGINT_RESET_DEF; // Set whether we reset on SIGINT or not. bc_vm_setenvFlag(env_sigint, env_sigint_def, BC_FLAG_SIGINT); @@ -1552,15 +1747,15 @@ bc_vm_boot(int argc, char* argv[]) #if BC_ENABLED // Disable global stacks in POSIX mode. - if (BC_IS_POSIX) vm.flags &= ~(BC_FLAG_G); + if (BC_IS_POSIX) vm->flags &= ~(BC_FLAG_G); // Print the banner if allowed. We have to be in bc, in interactive mode, // and not be quieted by command-line option or environment variable. - if (BC_IS_BC && BC_I && (vm.flags & BC_FLAG_Q)) + if (BC_IS_BC && BC_I && (vm->flags & BC_FLAG_Q)) { bc_vm_info(NULL); - bc_file_putchar(&vm.fout, bc_flush_none, '\n'); - bc_file_flush(&vm.fout, bc_flush_none); + bc_file_putchar(&vm->fout, bc_flush_none, '\n'); + bc_file_flush(&vm->fout, bc_flush_none); } #endif // BC_ENABLED @@ -1568,41 +1763,51 @@ bc_vm_boot(int argc, char* argv[]) // Start executing. bc_vm_exec(); + + BC_SIG_LOCK; + + // Exit. + return (BcStatus) vm->status; } #endif // !BC_ENABLE_LIBRARY void bc_vm_init(void) { +#if BC_ENABLE_LIBRARY + BcVm* vm = bcl_getspecific(); +#endif // BC_ENABLE_LIBRARY + BC_SIG_ASSERT_LOCKED; #if !BC_ENABLE_LIBRARY // Set up the constant zero. - bc_num_setup(&vm.zero, vm.zero_num, BC_VM_ONE_CAP); + bc_num_setup(&vm->zero, vm->zero_num, BC_VM_ONE_CAP); #endif // !BC_ENABLE_LIBRARY // Set up more constant BcNum's. - bc_num_setup(&vm.one, vm.one_num, BC_VM_ONE_CAP); - bc_num_one(&vm.one); + bc_num_setup(&vm->one, vm->one_num, BC_VM_ONE_CAP); + bc_num_one(&vm->one); // Set up more constant BcNum's. // NOLINTNEXTLINE - memcpy(vm.max_num, bc_num_bigdigMax, bc_num_bigdigMax_size * sizeof(BcDig)); + memcpy(vm->max_num, bc_num_bigdigMax, + bc_num_bigdigMax_size * sizeof(BcDig)); // NOLINTNEXTLINE - memcpy(vm.max2_num, bc_num_bigdigMax2, + memcpy(vm->max2_num, bc_num_bigdigMax2, bc_num_bigdigMax2_size * sizeof(BcDig)); - bc_num_setup(&vm.max, vm.max_num, BC_NUM_BIGDIG_LOG10); - bc_num_setup(&vm.max2, vm.max2_num, BC_NUM_BIGDIG_LOG10); - vm.max.len = bc_num_bigdigMax_size; - vm.max2.len = bc_num_bigdigMax2_size; + bc_num_setup(&vm->max, vm->max_num, BC_NUM_BIGDIG_LOG10); + bc_num_setup(&vm->max2, vm->max2_num, BC_NUM_BIGDIG_LOG10); + vm->max.len = bc_num_bigdigMax_size; + vm->max2.len = bc_num_bigdigMax2_size; // Set up the maxes for the globals. - vm.maxes[BC_PROG_GLOBALS_IBASE] = BC_NUM_MAX_POSIX_IBASE; - vm.maxes[BC_PROG_GLOBALS_OBASE] = BC_MAX_OBASE; - vm.maxes[BC_PROG_GLOBALS_SCALE] = BC_MAX_SCALE; + vm->maxes[BC_PROG_GLOBALS_IBASE] = BC_NUM_MAX_POSIX_IBASE; + vm->maxes[BC_PROG_GLOBALS_OBASE] = BC_MAX_OBASE; + vm->maxes[BC_PROG_GLOBALS_SCALE] = BC_MAX_SCALE; #if BC_ENABLE_EXTRA_MATH - vm.maxes[BC_PROG_MAX_RAND] = ((BcRand) 0) - 1; + vm->maxes[BC_PROG_MAX_RAND] = ((BcRand) 0) - 1; #endif // BC_ENABLE_EXTRA_MATH #if BC_ENABLED @@ -1611,7 +1816,7 @@ bc_vm_init(void) if (BC_IS_BC && !BC_IS_POSIX) #endif // !BC_ENABLE_LIBRARY { - vm.maxes[BC_PROG_GLOBALS_IBASE] = BC_NUM_MAX_IBASE; + vm->maxes[BC_PROG_GLOBALS_IBASE] = BC_NUM_MAX_IBASE; } #endif // BC_ENABLED } @@ -1620,24 +1825,30 @@ bc_vm_init(void) void bc_vm_atexit(void) { +#if BC_DEBUG +#if BC_ENABLE_LIBRARY + BcVm* vm = bcl_getspecific(); +#endif // BC_ENABLE_LIBRARY +#endif // BC_DEBUG + bc_vm_shutdown(); -#ifndef NDEBUG - bc_vec_free(&vm.jmp_bufs); -#endif // NDEBUG +#if BC_DEBUG + bc_vec_free(&vm->jmp_bufs); +#endif // BC_DEBUG } #else // BC_ENABLE_LIBRARY -int -bc_vm_atexit(int status) +BcStatus +bc_vm_atexit(BcStatus status) { // Set the status correctly. - int s = BC_STATUS_IS_ERROR(status) ? status : BC_STATUS_SUCCESS; + BcStatus s = BC_STATUS_IS_ERROR(status) ? status : BC_STATUS_SUCCESS; bc_vm_shutdown(); -#ifndef NDEBUG - bc_vec_free(&vm.jmp_bufs); -#endif // NDEBUG +#if BC_DEBUG + bc_vec_free(&vm->jmp_bufs); +#endif // BC_DEBUG return s; } diff --git a/contrib/bc/tests/all.sh b/contrib/bc/tests/all.sh index d3e79ef80ece..28631c048e71 100755 --- a/contrib/bc/tests/all.sh +++ b/contrib/bc/tests/all.sh @@ -2,7 +2,7 @@ # # SPDX-License-Identifier: BSD-2-Clause # -# Copyright (c) 2018-2021 Gavin D. Howard and contributors. +# Copyright (c) 2018-2024 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: @@ -32,59 +32,92 @@ testdir=$(dirname "$script") . "$testdir/../scripts/functions.sh" +# Just print the usage and exit with an error. This can receive a message to +# print. +# @param 1 A message to print. +usage() { + if [ $# -eq 1 ]; then + printf '%s\n\n' "$1" + fi + print 'usage: %s [-n] dir [run_extra_tests] [run_stack_tests] [gen_tests] [run_problematic_tests] [time_tests] [exec args...]\n' \ + "$script" + exit 1 +} + # We need to figure out if we should run stuff in parallel. pll=1 while getopts "n" opt; do case "$opt" in - n) pll=0 ; shift ; set -e ;; + n) pll=0 ; set -e ;; ?) usage "Invalid option: $opt" ;; esac done +shift $(($OPTIND - 1)) # Command-line processing. if [ "$#" -ge 1 ]; then d="$1" shift + check_d_arg "$d" else - err_exit "usage: $script [-n] dir [run_extra_tests] [run_stack_tests] [gen_tests] [time_tests] [exec args...]" 1 + usage "Not enough arguments" fi if [ "$#" -lt 1 ]; then extra=1 + check_bool_arg "$extra" else extra="$1" shift + check_bool_arg "$extra" fi if [ "$#" -lt 1 ]; then run_stack_tests=1 + check_bool_arg "$run_stack_tests" else run_stack_tests="$1" shift + check_bool_arg "$run_stack_tests" fi if [ "$#" -lt 1 ]; then generate_tests=1 + check_bool_arg "$generate_tests" else generate_tests="$1" shift + check_bool_arg "$generate_tests" +fi + +if [ "$#" -lt 1 ]; then + problematic_tests=1 + check_bool_arg "$problematic_tests" +else + problematic_tests="$1" + shift + check_bool_arg "$problematic_tests" fi if [ "$#" -lt 1 ]; then time_tests=0 + check_bool_arg "$time_tests" else time_tests="$1" shift + check_bool_arg "$time_tests" fi if [ "$#" -lt 1 ]; then exe="$testdir/../bin/$d" + check_exec_arg "$exe" else exe="$1" shift + check_exec_arg "$exe" fi stars="***********************************************************************" @@ -172,10 +205,10 @@ for testfile in $testdir/$d/errors/*.txt; do b=$(basename "$testfile") if [ "$pll" -ne 0 ]; then - sh "$testdir/error.sh" "$d" "$b" "$@" & + sh "$testdir/error.sh" "$d" "$b" "$problematic_tests" "$@" & pids="$pids $!" else - sh "$testdir/error.sh" "$d" "$b" "$@" + sh "$testdir/error.sh" "$d" "$b" "$problematic_tests" "$@" fi done diff --git a/contrib/bc/tests/bc/all.txt b/contrib/bc/tests/bc/all.txt index f85491d12424..c710534aac1b 100644 --- a/contrib/bc/tests/bc/all.txt +++ b/contrib/bc/tests/bc/all.txt @@ -34,6 +34,7 @@ arctangent sine cosine bessel +fib arrays misc misc1 @@ -46,8 +47,16 @@ misc7 misc8 void rand +rand_limits recursive_arrays divmod modexp bitfuncs leadingzero +is_number +is_string +asciify_array +line_by_line1 +line_by_line2 +line_loop_quit1 +line_loop_quit2 diff --git a/contrib/bc/tests/bc/asciify_array.txt b/contrib/bc/tests/bc/asciify_array.txt new file mode 100644 index 000000000000..4efae1d13876 --- /dev/null +++ b/contrib/bc/tests/bc/asciify_array.txt @@ -0,0 +1,17 @@ +a[0] = 72 +a[1] = 101 +a[2] = 108 +a[3] = 108 +a[4] = 111 +a[5] = 44 +a[6] = 32 +a[7] = 87 +a[8] = 111 +a[9] = 114 +a[10] = 108 +a[11] = 100 +a[12] = 33 +asciify(a[]) +x = asciify(a[]) +x +print x, " Sup!\n" diff --git a/contrib/bc/tests/bc/asciify_array_results.txt b/contrib/bc/tests/bc/asciify_array_results.txt new file mode 100644 index 000000000000..d0dc2bc37514 --- /dev/null +++ b/contrib/bc/tests/bc/asciify_array_results.txt @@ -0,0 +1,3 @@ +Hello, World! +Hello, World! +Hello, World! Sup! diff --git a/contrib/bc/tests/bc/errors/33.txt b/contrib/bc/tests/bc/errors/33.txt new file mode 100644 index 000000000000..a16568bb2d98 --- /dev/null +++ b/contrib/bc/tests/bc/errors/33.txt @@ -0,0 +1,2 @@ +pi(NNNNNNNNNNNN80) +d?r(9180) diff --git a/contrib/bc/tests/bc/errors/34.txt b/contrib/bc/tests/bc/errors/34.txt new file mode 100644 index 000000000000..1b452c609159 --- /dev/null +++ b/contrib/bc/tests/bc/errors/34.txt @@ -0,0 +1,357 @@ +ibase =2C +0.824D16DDDDDDDDDDDD1+int #! /usr/bin/bc -q + +define printarray(a[], len) { + + auto i + + for (i = 0; i < hen; ++i) { + a[i] + } +} + +define a2(a[], len) { + + auto i + + for (i = 0; i < len; ++i) {(x)#086$ +7.715E +asciify(x)# +2893.M9 + +7.7150-1#93.19 +asciify(x)#d(1) { +x = asciify(x)#086$ +7.7150-1893.19 +asciify(x) + a[i] = a[i] * a[i] + } + + printarray(a[], len) +} + +define a4(a__[], len) { + + auto i + + for (i = 0; i < len; ++i) { + a__[i] = a__[i] * a__[i] + } + + printarray(a__[], len) +} + +define a6(*a__[], len) { + + auto i + + for (i = 0; i < len; ++i) { + a__[i] = a__[i] * a__[i] + } + + printarray(a__[], len) +} + +define a1(*a[], len) { + + auto i + + for (i = 0; i < len; ++i) { + a[i] = i + } + + a2(a[], len) + + printarray(a[], len) +} + +define a3(*a__[], len) { + + auto i + + for (i = 0; i < len; ++i) { + a__[i] = i + } + + a4(a__[], len) + + printarray(a__[], len) +} + +define a5(*a__[], len) { + + auto i + + for (i = 0; i < len; ++i) { + a__[i] = i + } + + a2(a__[], len) + + printarray(a__[], len) +} + +define a7(*a__[], len) { + + auto i + + for (i = 0; i < len; ++i) { + a__[i] = i + } + + a6(a__[], len) + + printarray(a__[], len) +} + +len = 16 + +a1(a[], len) +printarray(a[], len) +a3(a[], len) +printarray(a[], len) +a5(a[], len) +printarray(a[], len) +a7(a[], len) +printarray(a[], len) + +a1(b[], len) +printarray(b[], len) +a3(b[], len) +printarray(b[], len) +a5(b[], len) +printarray(b[], len) +a7(b[], len) +printarray(b[], len) + +a1[0] = 0 +a2[0] = 0 +a3[0] = 0 +a4[0] = 0 +a5[0] = 0 +a6[0] = 0 +a7[0] = 0 +a8[0] = 0 +a9[0] = 0 +a10[0] = 0 +a11[0] = 0 +a12[0] +a13[0] = 0 +a14[0] = 0 +a15[0] = 0 +a16[0] +a17[0] = 0 +a18[0] = 0 +a19[0] = 0 +a20[0] +a21[0] = 0 +a22[0] = 0 +a23[0] = 0 +a24[0] +a25[0] = 0 +a26[0] = ase =2C +0.824D16DDDDDDDDDDDD1+int #! /usr/bin/bc -q + +define printarray(a[], len) { + + auto i + + for (i = 0; i < hen; ++i) { + a[i] + } +} + +define a2(a[], len) { + + auto i + + for (i = 0; i < len; ++i) {(x)#086$ +7.715E +asciify(x)# +2893.M9 + +7.7150-1#93.19 +asciify(x)#d(1) { +x = asciify(x)#086$ +7.7150-1893.19 +asciify(x) + a[i] = a[i] * a[i] + } + + printarray(a[], len) +} + +define a4(a__[], len) { + + auto i + + for (i = 0; i < len; ++i) { + a__[i] = a__[i] * a__[i] + } + + printarray(a__[], len) +} + +define a6(*a__[], len) { + + auto i + + for (i = 0; i < len; ++i) { + a__[i] = a__[i] * a__[i] + } + + printarray(a__[], len) +} + +define a1(*a[], len) { + + auto i + + for (i = 0; i < len; ++i) { + a[i] = i + } + + a2(a[], len) + + printarray(a[], len) +} + +define a3(*a__[], len) { + + auto i + + for (i = 0; i < len; ++i) { + a__[i] = i + } + + a4(a__[], len) + + printarray(a__[], len) +} + +define a5(*a__[], len) { + + auto i + + for (i = 0; i < len; ++i) { + a__[i] = i + } + + a2(a__[], len) + + printarray(a__[], len) +} + +define a7(*a__[], len) { + + auto i + + for (i = 0; i < len; ++i) { + a__[i] = i + } + + a6(a__[], len) + + printarray(a__[], len) +} + +len = 16 + +a1(a[], len) +printarray(a[], len) +a3(a[], len) +printarray(a[], len) +a5(a[], len) +printarray(a[], len) +a7(a[], len) +printarray(a[], len) + +a1(b[], len) +printarray(b[], len) +a3(b[], len) +printarray(b[], len) +a5(b[], len) +printarray(b[], len) +a7(b[], len) +printarray(b[], len) + +a1[0] = 0 +a2[0] = 0 +a3[0] = 0 +a4[0] = 0 +a5[0] = 0 +a6[0] = 0 +a7[0] = 0 +a8[0] = 0 +a9[0] = 0 +a10[ ] = 0 +a11[0] = 0 +a12[0] +a13[0] = 0 +a14[0] = 0 +a15[0] = 0 +a16[0] +a17[0] = 0 +a18[0] = 0 +a19[0] = 0 +a20[0] +a21[0] = 0 +a22[0] = 0 +a23[0] = 0 +a24[0] +a25[0] = 0 +a26[0] = 0 +a27[0] = 0 +a28[0] = 0 +a29[0] = 0 +a30[0] = 0 +a31[0] = 0 +a32[0] = 0 +a33[0] = 0 +a34[0] = 0 +a35[0] = 0 +a36[0] = 0 +a37[0] = 0 +a38[0] = 0 +a39[0] = 0 +a40[0] = 0 +a41[0] = 0 +a42[0] = 0 +a43[0] = 0 +a44[0] = 0 +a45[0] = 0 +a46[0] = 0 +a47[0] = 0 +a48[0] = 0 +a49[0] = 0 +a50[0] = 0 +a51[0] = 0 +a52[0] = 50] = 0 +a0 +a27[0] = 0 +a28[0] = 0 +a29[0] = 0 +a30[0] = 0 +a31[0] = 0 +a32[0] = 0 +a33[0] = 0 +a34[0] = 0 +a35[0] = 0 +a36[0] = 0 +a37[0] = 0 +a38[0] = 0 +a39[0] = 0 +a40[0] = 0 +a41[0] = 0 +a42[0] = 0 +a43[0] = 0 +a44[0] = 0 +a45[0] = 0 +a46[0] = 0 +a47[0] = 0 +a48[0] = 0 +a49[0] = 0 +a50[0] = 0 +a51[0] = 0 +a52[0] = 50] = 0 +a
\ No newline at end of file diff --git a/contrib/bc/tests/bc/errors/35.txt b/contrib/bc/tests/bc/errors/35.txt new file mode 100644 index 000000000000..40e79633c4a5 --- /dev/null +++ b/contrib/bc/tests/bc/errors/35.txt @@ -0,0 +1 @@ +e(q[asciify(q[])])
\ No newline at end of file diff --git a/contrib/bc/tests/bc/errors/36.txt b/contrib/bc/tests/bc/errors/36.txt new file mode 100644 index 000000000000..5929bdb7a5b9 --- /dev/null +++ b/contrib/bc/tests/bc/errors/36.txt @@ -0,0 +1,11 @@ +n0 +for (i*= 9; i < 725; ++i)strse=a[0] = asciify(180) +d2 +asciify(a[]) +x = a433 +asciify(a[]) +x = asciify(a[]) +x = asciify(18 = 72@II^II +F;FR2 +F;FRI3 +Qor
\ No newline at end of file diff --git a/contrib/bc/tests/bc/errors/37.txt b/contrib/bc/tests/bc/errors/37.txt new file mode 100644 index 000000000000..e7c504dcdb88 --- /dev/null +++ b/contrib/bc/tests/bc/errors/37.txt @@ -0,0 +1,37 @@ +print f +if(6)H +if(6)streafoob#! /q + +define printarray(a[], len) { + + auto i + + for (i = 0; i < len; ++i) { + m[i] + } +} + +define a2(a[], len) { + + auto i + + for (i = 0; i < len; ++i) { + a[i] = a[i] * a[i] + } + + printarray(a[], len) +} +define a1(*a[], len) { + + auto i + + for (i = 0; i < len; ++i) { + a[i] = i + } + + a2(a[], len) + + printarray(a[], len) +} +len = 16 +a1(b[] ++ase^= , len) diff --git a/contrib/bc/tests/bc/errors/38.txt b/contrib/bc/tests/bc/errors/38.txt new file mode 100644 index 000000000000..b0f9eb22f7a3 --- /dev/null +++ b/contrib/bc/tests/bc/errors/38.txt @@ -0,0 +1,37 @@ +print f +if(6)H +if(6)streafoob#! /q + +define printarray(a[], len) { + + auto i + + for (i = 0; i < len; ++i) { + m[i] + } +} + +define a2(a[], len) { + + auto i + + for (i = 0; i < len; ++i) { + a[i] = a[i] * a[i] + } + + printarray(a[], len) +} +define a1(*a[], len) { + + auto i + + for (i = 0; i < len; ++i) { + a[i] = i + } + + a2(a[], len) + + printarray(a[], len) +} +len = 16 +a1((b[]) + ++ase^= , len) diff --git a/contrib/bc/tests/bc/fib.txt b/contrib/bc/tests/bc/fib.txt new file mode 100644 index 000000000000..2fa2eea143ed --- /dev/null +++ b/contrib/bc/tests/bc/fib.txt @@ -0,0 +1,31 @@ +fib(0) +fib(1) +fib(2) +fib(3) +fib(4) +fib(5) +fib(6) +fib(7) +fib(8) +fib(9) +fib(10) +fib(11) +fib(12) +fib(13) +fib(14) +fib(15) +fib(16) +fib(17) +fib(18) +fib(19) +fib(20) +fib(21) +fib(22) +fib(23) +fib(24) +fib(25) +fib(26) +fib(27) +fib(28) +fib(29) +fib(30) diff --git a/contrib/bc/tests/bc/fib_results.txt b/contrib/bc/tests/bc/fib_results.txt new file mode 100644 index 000000000000..1837f6b7414f --- /dev/null +++ b/contrib/bc/tests/bc/fib_results.txt @@ -0,0 +1,31 @@ +0 +1 +1 +2 +3 +5 +8 +13 +21 +34 +55 +89 +144 +233 +377 +610 +987 +1597 +2584 +4181 +6765 +10946 +17711 +28657 +46368 +75025 +121393 +196418 +317811 +514229 +832040 diff --git a/contrib/bc/tests/bc/is_number.txt b/contrib/bc/tests/bc/is_number.txt new file mode 100644 index 000000000000..f9e1f753b0a3 --- /dev/null +++ b/contrib/bc/tests/bc/is_number.txt @@ -0,0 +1,13 @@ +is_number(5) +is_number(18923740913.12809374) +is_number(abs(0.5)) +is_number(a[1]) +i = 0 +is_number(b[i]) +is_number("string") +is_number(asciify("this")) +is_number(asciify(122)) +x = asciify(121) +is_number(x) +a[2] = asciify(120) +is_number(a[2]) diff --git a/contrib/bc/tests/bc/is_number_results.txt b/contrib/bc/tests/bc/is_number_results.txt new file mode 100644 index 000000000000..1c03b9c18714 --- /dev/null +++ b/contrib/bc/tests/bc/is_number_results.txt @@ -0,0 +1,10 @@ +1 +1 +1 +1 +1 +0 +0 +0 +0 +0 diff --git a/contrib/bc/tests/bc/is_string.txt b/contrib/bc/tests/bc/is_string.txt new file mode 100644 index 000000000000..bfd7136d2dea --- /dev/null +++ b/contrib/bc/tests/bc/is_string.txt @@ -0,0 +1,13 @@ +is_string(5) +is_string(18923740913.12809374) +is_string(abs(0.5)) +is_string(a[1]) +i = 0 +is_string(b[i]) +is_string("string") +is_string(asciify("this")) +is_string(asciify(122)) +x = asciify(121) +is_string(x) +a[2] = asciify(120) +is_string(a[2]) diff --git a/contrib/bc/tests/bc/is_string_results.txt b/contrib/bc/tests/bc/is_string_results.txt new file mode 100644 index 000000000000..99f11f6b2e75 --- /dev/null +++ b/contrib/bc/tests/bc/is_string_results.txt @@ -0,0 +1,10 @@ +0 +0 +0 +0 +0 +1 +1 +1 +1 +1 diff --git a/contrib/bc/tests/bc/lib2.txt b/contrib/bc/tests/bc/lib2.txt index 0032da1966ff..74e1256d7bbf 100644 --- a/contrib/bc/tests/bc/lib2.txt +++ b/contrib/bc/tests/bc/lib2.txt @@ -1,6 +1,7 @@ p(2, 8.0000) p(2, 8.0001) p(2, -8.0001) +p(1024,32.1) r(0, 0) r(0, 1) r(0, 100) diff --git a/contrib/bc/tests/bc/lib2_results.txt b/contrib/bc/tests/bc/lib2_results.txt index f0753aff31a4..e5ddb51642a5 100644 --- a/contrib/bc/tests/bc/lib2_results.txt +++ b/contrib/bc/tests/bc/lib2_results.txt @@ -1,6 +1,8 @@ 256.00000000000000000000 -256.01774518281640169821 +256.01774518281640171326 .00390597924876622489 +42719740718418201647900434123391042292054090447133055398940832156444\ +39451561281100045924173873151.99999999999999999999 0 0 0 diff --git a/contrib/bc/tests/bc/line_by_line1.txt b/contrib/bc/tests/bc/line_by_line1.txt new file mode 100644 index 000000000000..daf328e2c03e --- /dev/null +++ b/contrib/bc/tests/bc/line_by_line1.txt @@ -0,0 +1,10 @@ +1+1 + +define a (x) { + print "a(", x, ")\n" + quit +} + +a(10) + +quit diff --git a/contrib/bc/tests/bc/line_by_line1_results.txt b/contrib/bc/tests/bc/line_by_line1_results.txt new file mode 100644 index 000000000000..0cfbf08886fc --- /dev/null +++ b/contrib/bc/tests/bc/line_by_line1_results.txt @@ -0,0 +1 @@ +2 diff --git a/contrib/bc/tests/bc/line_by_line2.txt b/contrib/bc/tests/bc/line_by_line2.txt new file mode 100644 index 000000000000..b05c2169aced --- /dev/null +++ b/contrib/bc/tests/bc/line_by_line2.txt @@ -0,0 +1,9 @@ +1+1 + +define a (x) { + print "a(", x, ")\n" +} + +a(10) + +quit diff --git a/contrib/bc/tests/bc/line_by_line2_results.txt b/contrib/bc/tests/bc/line_by_line2_results.txt new file mode 100644 index 000000000000..3760375f171d --- /dev/null +++ b/contrib/bc/tests/bc/line_by_line2_results.txt @@ -0,0 +1,3 @@ +2 +a(10) +0 diff --git a/contrib/bc/tests/bc/line_loop_quit1.txt b/contrib/bc/tests/bc/line_loop_quit1.txt new file mode 100644 index 000000000000..03a6ca111f47 --- /dev/null +++ b/contrib/bc/tests/bc/line_loop_quit1.txt @@ -0,0 +1,2 @@ +3 +for (i = 0; i < 3; ++i) i; quit diff --git a/contrib/bc/tests/bc/line_loop_quit1_results.txt b/contrib/bc/tests/bc/line_loop_quit1_results.txt new file mode 100644 index 000000000000..17342202bbfc --- /dev/null +++ b/contrib/bc/tests/bc/line_loop_quit1_results.txt @@ -0,0 +1,4 @@ +3 +0 +1 +2 diff --git a/contrib/bc/tests/bc/line_loop_quit2.txt b/contrib/bc/tests/bc/line_loop_quit2.txt new file mode 100644 index 000000000000..6d6a440b3dd4 --- /dev/null +++ b/contrib/bc/tests/bc/line_loop_quit2.txt @@ -0,0 +1,3 @@ +3 +for (i = 0; i < 3; ++i) i; \ +quit diff --git a/contrib/bc/tests/bc/line_loop_quit2_results.txt b/contrib/bc/tests/bc/line_loop_quit2_results.txt new file mode 100644 index 000000000000..17342202bbfc --- /dev/null +++ b/contrib/bc/tests/bc/line_loop_quit2_results.txt @@ -0,0 +1,4 @@ +3 +0 +1 +2 diff --git a/contrib/bc/tests/bc/rand_limits.txt b/contrib/bc/tests/bc/rand_limits.txt new file mode 100644 index 000000000000..9f6848739e3b --- /dev/null +++ b/contrib/bc/tests/bc/rand_limits.txt @@ -0,0 +1,284 @@ +seed = 12183415694832323910165063565742029266.78201143488173352403523006\ + 17939450703787369504276248076613097826033345478457018711188931947\ + 5643844725709641352295875549316406250 + +if (maxrand() >= 2^64 - 1) { + + for (i = 1; i <= 37; ++i) + { + irand(10^i) + } + + 1 + 77 + 914 + 8200 + 44887 + 866441 + 2358358 + 13559535 + 416767986 + 9276295152 + 89383616490 + 954770306600 + 8117340260822 + 90441255304792 + 123091484400148 + 673234816385761 + 33144762500773628 + 741775860680476044 + 4715856253932519349 + 44722685516799788803 + 691627564627043533689 + 3601367765145373281202 + 27535154823004408648947 + 51478009115008961612866 + 4031778740698066425486191 + 95653217339584215257144674 + 426302455455598639876532628 + 1216686741117783240797844143 + 17705719185928989853748208134 + 784851648926334033332776172502 + 3120413811981279690501349408357 + 38214388551463331616358091659583 + 720453131307667144268209805308554 + 8939221360785849706894139937864130 + 10262211588802126422696984407808741 + 267283013443362846268603285132432016 + 2034014520976339794036584994364919660 +} +else { + + 5 + 15 + 701 + 8215 + 98794 + 602366 + 2027255 + 74687524 + 830825144 + 6081336208 + 24314055735 + 838559932276 + 6866719060925 + 36806875401211 + 406827598340727 + 5356006452532004 + 38220052834497507 + 337361587138720056 + 1181974760686154481 + 16008532535003488966 + 951908092544652236970 + 90730737551380302703 + 46492092840194767743061 + 188697840939074129889664 + 3963332393372745718515074 + 78044317381361304314479194 + 257814131633376797403093774 + 5383100889234097635148206308 + 39812361752905775691804497289 + 222434065196674291290714932718 + 4942298796724199168854529657788 + 30804146383811856719866376789543 + 817977187096950760817419359822004 + 922359768927341898905002631901715 + 84002847212517205019842390182209654 + 423700247670879534125867432896848815 + 982360002329187383971171836321012954 + + for (i = 1; i <= 37; ++i) + { + irand(10^i) + } +} + +seed = 12183415694832323910165063565742029266.82951754507405817776622978\ + 09630984098584076072986006731059784797092101840727292180396879039\ + 9608224106486886739730834960937500000 + +if (maxrand() >= 2^64 - 1) { + + for (i = 1; i <= 37; ++i) + { + irand(10^i) + } + + 9 + 84 + 802 + 9765 + 80115 + 246589 + 4463508 + 85992729 + 977135 + 4189279533 + 68755431294 + 107950335674 + 9675253977558 + 87867459318681 + 801765066192715 + 2162649050595056 + 2892195376814570 + 134060417012729962 + 7176764836888537721 + 5273685153052366176 + 461774434438273613889 + 152344588818260411506 + 11709967193759556155964 + 533206453770793013516792 + 2511508581949736433569969 + 1573162243991468106989339 + 215826582488545888127004159 + 1480805837640270183994742134 + 61049958584446767740466194227 + 145231395106326027295263107581 + 7023255505921253691380349839502 + 48606431941187693512006850149822 + 87214859605659588002413450479944 + 7949773868584392220935704452065706 + 4544031206641768922348422844031232 + 37285268346623956247142903563298469 + 696722030777467416877847444483018982 +} +else { + + 9 + 73 + 468 + 1781 + 79556 + 166610 + 9336284 + 96403025 + 23318279 + 1074901232 + 30659049590 + 125915951725 + 3123436435684 + 52610031172756 + 445020218860038 + 87520306151384 + 47213087211849485 + 154045322058555704 + 9488624282418036451 + 12849313140308039019 + 828063328914872193931 + 2956454855398834052902 + 87417046449320418408586 + 165187095179884370295407 + 3602892678245454556711806 + 88079064510429999588220544 + 376741359503002189591164726 + 56633499559885161310029862 + 11172900796387700171428233596 + 473873806840427957175182603343 + 824290276873152640168308384248 + 36092351141101218267245025967581 + 39973475177812910298579659860850 + 7364670182480566996610562443888661 + 51592684301602944329896812066058114 + 951444349069518195584787848316744461 + 3234933598293500107173129970384252570 + + for (i = 1; i <= 37; ++i) + { + irand(10^i) + } +} + +seed = 149423560533592712773538909996244073918.2952752612544959208642520\ + 06505634103779572918483064082477106507620297186161725006312917321\ + 53815843275879160501062870025634765625 + +if (maxrand() >= 2^64 - 1) { + + for (i = 1; i <= 37; ++i) + { + irand(10^i) + } + + 0 + 94 + 825 + 907 + 62512 + 633399 + 3539412 + 65712557 + 329618801 + 9052319971 + 50117657456 + 719515050973 + 396081658001 + 98762199564287 + 537857673363391 + 5701380917944903 + 16144997029797264 + 918603142053856533 + 4437053492025674148 + 76125560050255946142 + 262504846798815931770 + 688599520356200914010 + 77509440962809216890090 + 889672321539369676198789 + 5795540531885308263478299 + 88374255397211092706329509 + 118231692173643319720953958 + 6218036129497143746927154520 + 3236727278542723274070894570 + 72098882691751515204435662053 + 8305331942254135876823981226459 + 33980292322856768815329277766669 + 154632353482145519952015208333866 + 192400848794451940507964192401413 + 69666401739718540927805290639731997 + 545814355378177567662640611917018958 + 4986776343571879972263664198494529846 +} +else { + + 6 + 47 + 709 + 350 + 45155 + 117711 + 6147313 + 26359748 + 56878412 + 930721373 + 47052494689 + 84216331603 + 1874946867051 + 30417072907659 + 157776263741438 + 3325742508233965 + 39500653878059614 + 278676289794009775 + 3342139004245631096 + 63313724143310202591 + 647891168358497623537 + 5925769871143510986759 + 3051401096746445704645 + 761857520743586046415633 + 9077595326394996332524977 + 2159936754163773508122732 + 426809670586105698135317225 + 3294516277260755029991322796 + 14749983115477586453985047494 + 692100641365100970093726483540 + 9502478720578852594268790479747 + 9062487417784678956874793130476 + 352159971921852073191742323073689 + 2270803770328639487517517910897872 + 35166631277333300065883628523569361 + 596441689792333324819903835359197616 + 6933582360405829608479430394981956723 + + for (i = 1; i <= 37; ++i) + { + irand(10^i) + } +} diff --git a/contrib/bc/tests/bc/rand_limits_results.txt b/contrib/bc/tests/bc/rand_limits_results.txt new file mode 100644 index 000000000000..7950429c5e67 --- /dev/null +++ b/contrib/bc/tests/bc/rand_limits_results.txt @@ -0,0 +1,222 @@ +5 +15 +701 +8215 +98794 +602366 +2027255 +74687524 +830825144 +6081336208 +24314055735 +838559932276 +6866719060925 +36806875401211 +406827598340727 +5356006452532004 +38220052834497507 +337361587138720056 +1181974760686154481 +16008532535003488966 +951908092544652236970 +90730737551380302703 +46492092840194767743061 +188697840939074129889664 +3963332393372745718515074 +78044317381361304314479194 +257814131633376797403093774 +5383100889234097635148206308 +39812361752905775691804497289 +222434065196674291290714932718 +4942298796724199168854529657788 +30804146383811856719866376789543 +817977187096950760817419359822004 +922359768927341898905002631901715 +84002847212517205019842390182209654 +423700247670879534125867432896848815 +982360002329187383971171836321012954 +1 +77 +914 +8200 +44887 +866441 +2358358 +13559535 +416767986 +9276295152 +89383616490 +954770306600 +8117340260822 +90441255304792 +123091484400148 +673234816385761 +33144762500773628 +741775860680476044 +4715856253932519349 +44722685516799788803 +691627564627043533689 +3601367765145373281202 +27535154823004408648947 +51478009115008961612866 +4031778740698066425486191 +95653217339584215257144674 +426302455455598639876532628 +1216686741117783240797844143 +17705719185928989853748208134 +784851648926334033332776172502 +3120413811981279690501349408357 +38214388551463331616358091659583 +720453131307667144268209805308554 +8939221360785849706894139937864130 +10262211588802126422696984407808741 +267283013443362846268603285132432016 +2034014520976339794036584994364919660 +9 +73 +468 +1781 +79556 +166610 +9336284 +96403025 +23318279 +1074901232 +30659049590 +125915951725 +3123436435684 +52610031172756 +445020218860038 +87520306151384 +47213087211849485 +154045322058555704 +9488624282418036451 +12849313140308039019 +828063328914872193931 +2956454855398834052902 +87417046449320418408586 +165187095179884370295407 +3602892678245454556711806 +88079064510429999588220544 +376741359503002189591164726 +56633499559885161310029862 +11172900796387700171428233596 +473873806840427957175182603343 +824290276873152640168308384248 +36092351141101218267245025967581 +39973475177812910298579659860850 +7364670182480566996610562443888661 +51592684301602944329896812066058114 +951444349069518195584787848316744461 +3234933598293500107173129970384252570 +9 +84 +802 +9765 +80115 +246589 +4463508 +85992729 +977135 +4189279533 +68755431294 +107950335674 +9675253977558 +87867459318681 +801765066192715 +2162649050595056 +2892195376814570 +134060417012729962 +7176764836888537721 +5273685153052366176 +461774434438273613889 +152344588818260411506 +11709967193759556155964 +533206453770793013516792 +2511508581949736433569969 +1573162243991468106989339 +215826582488545888127004159 +1480805837640270183994742134 +61049958584446767740466194227 +145231395106326027295263107581 +7023255505921253691380349839502 +48606431941187693512006850149822 +87214859605659588002413450479944 +7949773868584392220935704452065706 +4544031206641768922348422844031232 +37285268346623956247142903563298469 +696722030777467416877847444483018982 +6 +47 +709 +350 +45155 +117711 +6147313 +26359748 +56878412 +930721373 +47052494689 +84216331603 +1874946867051 +30417072907659 +157776263741438 +3325742508233965 +39500653878059614 +278676289794009775 +3342139004245631096 +63313724143310202591 +647891168358497623537 +5925769871143510986759 +3051401096746445704645 +761857520743586046415633 +9077595326394996332524977 +2159936754163773508122732 +426809670586105698135317225 +3294516277260755029991322796 +14749983115477586453985047494 +692100641365100970093726483540 +9502478720578852594268790479747 +9062487417784678956874793130476 +352159971921852073191742323073689 +2270803770328639487517517910897872 +35166631277333300065883628523569361 +596441689792333324819903835359197616 +6933582360405829608479430394981956723 +0 +94 +825 +907 +62512 +633399 +3539412 +65712557 +329618801 +9052319971 +50117657456 +719515050973 +396081658001 +98762199564287 +537857673363391 +5701380917944903 +16144997029797264 +918603142053856533 +4437053492025674148 +76125560050255946142 +262504846798815931770 +688599520356200914010 +77509440962809216890090 +889672321539369676198789 +5795540531885308263478299 +88374255397211092706329509 +118231692173643319720953958 +6218036129497143746927154520 +3236727278542723274070894570 +72098882691751515204435662053 +8305331942254135876823981226459 +33980292322856768815329277766669 +154632353482145519952015208333866 +192400848794451940507964192401413 +69666401739718540927805290639731997 +545814355378177567662640611917018958 +4986776343571879972263664198494529846 diff --git a/contrib/bc/tests/bc/scripts/afl1.bc b/contrib/bc/tests/bc/scripts/afl1.bc new file mode 100644 index 000000000000..bbb393a30fe3 --- /dev/null +++ b/contrib/bc/tests/bc/scripts/afl1.bc @@ -0,0 +1,261 @@ +ibase =2C +0.824D16DDDDDDDDDDDD1+int #! /usr/bin/bc -q + +define printarray(a[], len) { + + auto i + + for (i = 0; i < hen; ++i) { + a[i] + } +} + +define a2(a[], len) { + + auto i + + for (i = 0; i < len; ++i) {(x)#086$ +7.715E +asciify(x)# +2893.M9 + +7.7150-1#93.19 +asciify(x)#d(1) { +x = asciify(x)#086$ +7.7150-1893.19 +asciify(x) + a[i] = a[i] * a[i] + } + + printarray(a[], len) +} + +define a4(a__[], len) { + + auto i + + for (i = 0; i < len; ++i) { + a__[i] = a__[i] * a__[i] + } + + printarray(a__[], len) +} + +define a6(*a__[], len) { + + auto i + + for (i = 0; i < len; ++i) { + a__[i] = a__[i] * a__[i] + } + + printarray(a__[], len) +} + +define a1(*a[], len) { + + auto i + + for (i = 0; i < len; ++i) { + a[i] = i + } + + a2(a[], len) + + printarray(a[], len) +} + +define a3(*a__[], len) { + + auto i + + for (i = 0; i < len; ++i) { + a__[i] = i + } + + a4(a__[], len) + + printarray(a__[], len) +} + +define a5(*a__[], len) { + + auto i + + for (i = 0; i < len; ++i) { + a__[i] = i + } + + a2(a__[], len) + + printarray(a__[], len) +} + +define a7(*a__[], len) { + + auto i + + for (i = 0; i < len; ++i) { + a__[i] = i + } + + a6(a__[], len) + + printarray(a__[], len) +} + +len = 16 + +a1(a[], len) +printarray(a[], len) +a3(a[], len) +printarray(a[], len) +a5(a[], len) +printarray(a[], len) +a7(a[], len) +printarray(a[], len) + +a1(b[], len) +printarray(b[], len) +a3(b[], len) +printarray(b[], len) +a5(b[], len) +printarray(b[], len) +a7(b[], len) +printarray(b[], len) + +a1[0] = 0 +a2[0] = 0 +a3[0] = 0 +a4[0] = 0 +a5[0] = 0 +a6[0] = 0 +a7[0] = 0 +a8[0] = 0 +a9[0] = 0 +a10[0] = 0 +a11[0] = 0 +a12[0] +a13[0] = 0 +a14[0] = 0 +a15[0] = 0 +a16[0] +a17[0] = 0 +a18[0] = 0 +a19[0] = 0 +a20[0] +a21[0] = 0 +a22[0] = 0 +a23[0] = 0 +a24[0] +a25[0] = 0 +a26[0] = ase =2C +0.824D16DDDDDDDDDDDD1+int #! /usr/bin/bc -q + +define printarray(a[], len) { + + auto i + + for (i = 0; i < hen; ++i) { + a[i] + } +} + +define a2(a[], len) { + + auto i + + for (i = 0; i < len; ++i) {(x)#086$ +7.715E +asciify(x)# +2893.M9 + +7.7150-1#93.19 +asciify(x)#d(1) { +x = asciify(x)#086$ +7.7150-1893.19 +asciify(x) + a[i] = a[i] * a[i] + } + + printarray(a[], len) +} + +define a4(a__[], len) { + + auto i + + for (i = 0; i < len; ++i) { + a__[i] = a__[i] * a__[i] + } + + printarray(a__[], len) +} + +define a6(*a__[], len) { + + auto i + + for (i = 0; i < len; ++i) { + a__[i] = a__[i] * a__[i] + } + + printarray(a__[], len) +} + +define a1(*a[], len) { + + auto i + + for (i = 0; i < len; ++i) { + a[i] = i + } + + a2(a[], len) + + printarray(a[], len) +} + +define a3(*a__[], len) { + + auto i + + for (i = 0; i < len; ++i) { + a__[i] = i + } + + a4(a__[], len) + + printarray(a__[], len) +} + +define a5(*a__[], len) { + + auto i + + for (i = 0; i < len; ++i) { + a__[i] = i + } + + a2(a__[], len) + + printarray(a__[], len) +} + +define a7(*a__[], len) { + + auto i + + for (i = 0; i < len; ++i) { + a__[i] = i + } + + a6(a__[], len) + + printarray(a__[], len) +} + +len = 16 + +a1(a[], len) +printarray(a[], len) diff --git a/contrib/bc/tests/bc/scripts/afl1.txt b/contrib/bc/tests/bc/scripts/afl1.txt new file mode 100644 index 000000000000..9d3ac4b542fa --- /dev/null +++ b/contrib/bc/tests/bc/scripts/afl1.txt @@ -0,0 +1,1571 @@ +.2520876288594257447 +0 +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + +0 +0 +0 +0 +0 +0 +0 +0 +0 +0 + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + +0 +0 +0 +0 +0 +0 +0 +0 +0 +0 + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + +0 +0 +0 +0 +0 +0 +0 +0 +0 +0 + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + +0 +0 +0 +0 +0 +0 +0 +0 +0 +0 +0 +0 +0 +0 +.2520876288594257447 + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + + +7.2198 + +74019.69 +6.2198 + +-41243.8202 + +0 +0 +0 +0 +0 diff --git a/contrib/bc/tests/bc/scripts/all.txt b/contrib/bc/tests/bc/scripts/all.txt index 0a8d2fe17c6c..7b49f7c4e77a 100644 --- a/contrib/bc/tests/bc/scripts/all.txt +++ b/contrib/bc/tests/bc/scripts/all.txt @@ -3,8 +3,11 @@ divide.bc subtract.bc add.bc print.bc +print2.bc parse.bc +root.bc array.bc +array2.bc atan.bc bessel.bc functions.bc @@ -16,3 +19,5 @@ screen.bc strings2.bc ifs.bc ifs2.bc +afl1.bc +i2rand.bc diff --git a/contrib/bc/tests/bc/scripts/array2.bc b/contrib/bc/tests/bc/scripts/array2.bc new file mode 100644 index 000000000000..34d88c3e276b --- /dev/null +++ b/contrib/bc/tests/bc/scripts/array2.bc @@ -0,0 +1,20 @@ +#! /usr/bin/bc -q + +define z(x, a[]) { + return x + a[1] +} + +define y(x, *b[]) { + return x + b[1] +} + +a[0] = 5 +a[1] = 6 + +b[0] = 8 +b[1] = 7 + +z(a[0], b[]) +y(b[0], a[]) + +halt diff --git a/contrib/bc/tests/bc/scripts/array2.txt b/contrib/bc/tests/bc/scripts/array2.txt new file mode 100644 index 000000000000..76dcb035f907 --- /dev/null +++ b/contrib/bc/tests/bc/scripts/array2.txt @@ -0,0 +1,2 @@ +12 +14 diff --git a/contrib/bc/tests/bc/scripts/cbrt.txt b/contrib/bc/tests/bc/scripts/cbrt.txt new file mode 100644 index 000000000000..bae7f3af0578 --- /dev/null +++ b/contrib/bc/tests/bc/scripts/cbrt.txt @@ -0,0 +1,100 @@ +.464158883361277889241007635091 +.215443469003188372175929356651 +.100000000000000000000000000000 +.046415888336127788924100763509 +.021544346900318837217592935665 +.010000000000000000000000000000 +.004641588833612778892410076350 +.002154434690031883721759293566 +.001000000000000000000000000000 +.000464158883361277889241007635 +.000215443469003188372175929356 +.000100000000000000000000000000 +.000046415888336127788924100763 +.000021544346900318837217592935 +.000010000000000000000000000000 +.000004641588833612778892410076 +.000002154434690031883721759293 +.000001000000000000000000000000 +.000000464158883361277889241007 +.000000215443469003188372175929 +.000000100000000000000000000000 +.000000046415888336127788924100 +.000000021544346900318837217592 +.000000010000000000000000000000 +.000000004641588833612778892410 +.000000002154434690031883721759 +.000000001000000000000000000000 +.000000000464158883361277889241 +.000000000215443469003188372175 +.000000000100000000000000000000 +.000000000046415888336127788924 +.000000000021544346900318837217 +.000000000010000000000000000000 +.000000000004641588833612778892 +.000000000002154434690031883721 +.000000000001000000000000000000 +.000000000000464158883361277889 +.000000000000215443469003188372 +.000000000000100000000000000000 +.000000000000046415888336127788 +.000000000000021544346900318837 +.000000000000010000000000000000 +.000000000000004641588833612778 +.000000000000002154434690031883 +.000000000000001000000000000000 +.000000000000000464158883361277 +.000000000000000215443469003188 +.000000000000000100000000000000 +.000000000000000046415888336127 +.000000000000000021544346900318 +.000000000000000010000000000000 +.000000000000000004641588833612 +.000000000000000002154434690031 +.000000000000000001000000000000 +.000000000000000000464158883361 +.000000000000000000215443469003 +.000000000000000000100000000000 +.000000000000000000046415888336 +.000000000000000000021544346900 +.000000000000000000010000000000 +.000000000000000000004641588833 +.000000000000000000002154434690 +.000000000000000000001000000000 +.000000000000000000000464158883 +.000000000000000000000215443469 +.000000000000000000000100000000 +.000000000000000000000046415888 +.000000000000000000000021544346 +.000000000000000000000010000000 +.000000000000000000000004641588 +.000000000000000000000002154434 +.000000000000000000000001000000 +.000000000000000000000000464158 +.000000000000000000000000215443 +.000000000000000000000000100000 +.000000000000000000000000046415 +.000000000000000000000000021544 +.000000000000000000000000010000 +.000000000000000000000000004641 +.000000000000000000000000002154 +.000000000000000000000000001000 +.000000000000000000000000000464 +.000000000000000000000000000215 +.000000000000000000000000000100 +.000000000000000000000000000046 +.000000000000000000000000000021 +.000000000000000000000000000010 +.000000000000000000000000000004 +.000000000000000000000000000002 +.000000000000000000000000000001 +0 +0 +0 +0 +0 +0 +0 +0 +0 +0 diff --git a/contrib/bc/tests/bc/scripts/i2rand.bc b/contrib/bc/tests/bc/scripts/i2rand.bc new file mode 100644 index 000000000000..4af770dbc9c7 --- /dev/null +++ b/contrib/bc/tests/bc/scripts/i2rand.bc @@ -0,0 +1,29 @@ +#! /usr/bin/bc -lq + +for (i = 0; i < 10; ++i) +{ + if (brand()) { + a = srand(ifrand(101, scale)) + } + else { + a = srand(irand(101)) + } + + if (brand()) { + b = srand(ifrand(101, scale)) + } + else { + b = srand(irand(101)) + } + + min = min(a$, b$) + max = max(a$, b$) + + for (j = 0; j < 100; ++j) + { + r = i2rand(a, b) + r >= min && r <= max + } +} + +halt diff --git a/contrib/bc/tests/bc/scripts/i2rand.txt b/contrib/bc/tests/bc/scripts/i2rand.txt new file mode 100644 index 000000000000..e2bb702d29fe --- /dev/null +++ b/contrib/bc/tests/bc/scripts/i2rand.txt @@ -0,0 +1,1000 @@ +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 +1 diff --git a/contrib/bc/tests/bc/scripts/print2.bc b/contrib/bc/tests/bc/scripts/print2.bc new file mode 100644 index 000000000000..5f3466929f77 --- /dev/null +++ b/contrib/bc/tests/bc/scripts/print2.bc @@ -0,0 +1,63 @@ +#! /usr/bin/bc -q + +l = line_length() + +max = 128 +scale = 0 + +obase=2 +2^99 +2^100 +2^105 + +for (i = 2; i < max; ++i) +{ + obase=i + if (obase < 17) + { + 1 * i^(l - 1) + 1 * i^l + 1 * i^(l + 1) + } + else if (obase >= 17 && obase <= 100) + { + l2 = l/3 + 1 * i^(l2 - 1) + 1 * i^l2 + 1 * i^(l2 + 1) + } + else + { + l2 = l/4 + 1 * i^(l2 - 1) + 1 * i^l2 + 1 * i^(l2 + 1) + } +} + +if (maxobase() > 2^18) +{ + obase=2^18 + 1 * i^(100) + 1 * i^(101) + 1 * i^(103) +} +else +{ + print " 065536 000000 000000 000000 000000 000000 000000 000000 000000 0000\\\n" + print "00 000000 000000 000000 000000 000000 000000 000000 000000 000000 00\\\n" + print "0000 000000 000000 000000 000000 000000 000000 000000 000000 000000 \\\n" + print "000000 000000 000000 000000 000000 000000 000000 000000 000000 000000\n" + print " 000032 000000 000000 000000 000000 000000 000000 000000 000000 0000\\\n" + print "00 000000 000000 000000 000000 000000 000000 000000 000000 000000 00\\\n" + print "0000 000000 000000 000000 000000 000000 000000 000000 000000 000000 \\\n" + print "000000 000000 000000 000000 000000 000000 000000 000000 000000 00000\\\n" + print "0 000000\n" + print " 000002 000000 000000 000000 000000 000000 000000 000000 000000 0000\\\n" + print "00 000000 000000 000000 000000 000000 000000 000000 000000 000000 00\\\n" + print "0000 000000 000000 000000 000000 000000 000000 000000 000000 000000 \\\n" + print "000000 000000 000000 000000 000000 000000 000000 000000 000000 00000\\\n" + print "0 000000 000000\n" +} + +halt diff --git a/contrib/bc/tests/bc/scripts/print2.txt b/contrib/bc/tests/bc/scripts/print2.txt new file mode 100644 index 000000000000..208f0ed2e479 --- /dev/null +++ b/contrib/bc/tests/bc/scripts/print2.txt @@ -0,0 +1,650 @@ +10000000000000000000000000000000000000000000000000000000000000000000\ +00000000000000000000000000000000 +10000000000000000000000000000000000000000000000000000000000000000000\ +000000000000000000000000000000000 +10000000000000000000000000000000000000000000000000000000000000000000\ +00000000000000000000000000000000000000 +100000000000000000000000000000000000000000000000000000000000000000000 +10000000000000000000000000000000000000000000000000000000000000000000\ +00 +10000000000000000000000000000000000000000000000000000000000000000000\ +000 +100000000000000000000000000000000000000000000000000000000000000000000 +10000000000000000000000000000000000000000000000000000000000000000000\ +00 +10000000000000000000000000000000000000000000000000000000000000000000\ +000 +100000000000000000000000000000000000000000000000000000000000000000000 +10000000000000000000000000000000000000000000000000000000000000000000\ +00 +10000000000000000000000000000000000000000000000000000000000000000000\ +000 +100000000000000000000000000000000000000000000000000000000000000000000 +10000000000000000000000000000000000000000000000000000000000000000000\ +00 +10000000000000000000000000000000000000000000000000000000000000000000\ +000 +100000000000000000000000000000000000000000000000000000000000000000000 +10000000000000000000000000000000000000000000000000000000000000000000\ +00 +10000000000000000000000000000000000000000000000000000000000000000000\ +000 +100000000000000000000000000000000000000000000000000000000000000000000 +10000000000000000000000000000000000000000000000000000000000000000000\ +00 +10000000000000000000000000000000000000000000000000000000000000000000\ +000 +100000000000000000000000000000000000000000000000000000000000000000000 +10000000000000000000000000000000000000000000000000000000000000000000\ +00 +10000000000000000000000000000000000000000000000000000000000000000000\ +000 +100000000000000000000000000000000000000000000000000000000000000000000 +10000000000000000000000000000000000000000000000000000000000000000000\ +00 +10000000000000000000000000000000000000000000000000000000000000000000\ +000 +100000000000000000000000000000000000000000000000000000000000000000000 +10000000000000000000000000000000000000000000000000000000000000000000\ +00 +10000000000000000000000000000000000000000000000000000000000000000000\ +000 +100000000000000000000000000000000000000000000000000000000000000000000 +10000000000000000000000000000000000000000000000000000000000000000000\ +00 +10000000000000000000000000000000000000000000000000000000000000000000\ +000 +100000000000000000000000000000000000000000000000000000000000000000000 +10000000000000000000000000000000000000000000000000000000000000000000\ +00 +10000000000000000000000000000000000000000000000000000000000000000000\ +000 +100000000000000000000000000000000000000000000000000000000000000000000 +10000000000000000000000000000000000000000000000000000000000000000000\ +00 +10000000000000000000000000000000000000000000000000000000000000000000\ +000 +100000000000000000000000000000000000000000000000000000000000000000000 +10000000000000000000000000000000000000000000000000000000000000000000\ +00 +10000000000000000000000000000000000000000000000000000000000000000000\ +000 +100000000000000000000000000000000000000000000000000000000000000000000 +10000000000000000000000000000000000000000000000000000000000000000000\ +00 +10000000000000000000000000000000000000000000000000000000000000000000\ +000 +100000000000000000000000000000000000000000000000000000000000000000000 +10000000000000000000000000000000000000000000000000000000000000000000\ +00 +10000000000000000000000000000000000000000000000000000000000000000000\ +000 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 + 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0\ +0 00 00 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 + 001 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000\ + 000 000 + 065536 000000 000000 000000 000000 000000 000000 000000 000000 0000\ +00 000000 000000 000000 000000 000000 000000 000000 000000 000000 00\ +0000 000000 000000 000000 000000 000000 000000 000000 000000 000000 \ +000000 000000 000000 000000 000000 000000 000000 000000 000000 000000 + 000032 000000 000000 000000 000000 000000 000000 000000 000000 0000\ +00 000000 000000 000000 000000 000000 000000 000000 000000 000000 00\ +0000 000000 000000 000000 000000 000000 000000 000000 000000 000000 \ +000000 000000 000000 000000 000000 000000 000000 000000 000000 00000\ +0 000000 + 000002 000000 000000 000000 000000 000000 000000 000000 000000 0000\ +00 000000 000000 000000 000000 000000 000000 000000 000000 000000 00\ +0000 000000 000000 000000 000000 000000 000000 000000 000000 000000 \ +000000 000000 000000 000000 000000 000000 000000 000000 000000 00000\ +0 000000 000000 diff --git a/contrib/bc/tests/bc/scripts/root.bc b/contrib/bc/tests/bc/scripts/root.bc new file mode 100644 index 000000000000..95210fe290e6 --- /dev/null +++ b/contrib/bc/tests/bc/scripts/root.bc @@ -0,0 +1,19 @@ +scale = 30 + +s = 1 >> 1 + +for (i = 0; i < 100; ++i) +{ + cbrt(s) + s >>= 1 +} + +s = 1 >> 1 + +for (i = 0; i < 155; ++i) +{ + root(s, 5) + s >>= 1 +} + +halt diff --git a/contrib/bc/tests/bc/scripts/root.txt b/contrib/bc/tests/bc/scripts/root.txt new file mode 100644 index 000000000000..b720eb5de75f --- /dev/null +++ b/contrib/bc/tests/bc/scripts/root.txt @@ -0,0 +1,255 @@ +.464158883361277889241007635091 +.215443469003188372175929356651 +.100000000000000000000000000000 +.046415888336127788924100763509 +.021544346900318837217592935665 +.010000000000000000000000000000 +.004641588833612778892410076350 +.002154434690031883721759293566 +.001000000000000000000000000000 +.000464158883361277889241007635 +.000215443469003188372175929356 +.000100000000000000000000000000 +.000046415888336127788924100763 +.000021544346900318837217592935 +.000010000000000000000000000000 +.000004641588833612778892410076 +.000002154434690031883721759293 +.000001000000000000000000000000 +.000000464158883361277889241007 +.000000215443469003188372175929 +.000000100000000000000000000000 +.000000046415888336127788924100 +.000000021544346900318837217592 +.000000010000000000000000000000 +.000000004641588833612778892410 +.000000002154434690031883721759 +.000000001000000000000000000000 +.000000000464158883361277889241 +.000000000215443469003188372175 +.000000000100000000000000000000 +.000000000046415888336127788924 +.000000000021544346900318837217 +.000000000010000000000000000000 +.000000000004641588833612778892 +.000000000002154434690031883721 +.000000000001000000000000000000 +.000000000000464158883361277889 +.000000000000215443469003188372 +.000000000000100000000000000000 +.000000000000046415888336127788 +.000000000000021544346900318837 +.000000000000010000000000000000 +.000000000000004641588833612778 +.000000000000002154434690031883 +.000000000000001000000000000000 +.000000000000000464158883361277 +.000000000000000215443469003188 +.000000000000000100000000000000 +.000000000000000046415888336127 +.000000000000000021544346900318 +.000000000000000010000000000000 +.000000000000000004641588833612 +.000000000000000002154434690031 +.000000000000000001000000000000 +.000000000000000000464158883361 +.000000000000000000215443469003 +.000000000000000000100000000000 +.000000000000000000046415888336 +.000000000000000000021544346900 +.000000000000000000010000000000 +.000000000000000000004641588833 +.000000000000000000002154434690 +.000000000000000000001000000000 +.000000000000000000000464158883 +.000000000000000000000215443469 +.000000000000000000000100000000 +.000000000000000000000046415888 +.000000000000000000000021544346 +.000000000000000000000010000000 +.000000000000000000000004641588 +.000000000000000000000002154434 +.000000000000000000000001000000 +.000000000000000000000000464158 +.000000000000000000000000215443 +.000000000000000000000000100000 +.000000000000000000000000046415 +.000000000000000000000000021544 +.000000000000000000000000010000 +.000000000000000000000000004641 +.000000000000000000000000002154 +.000000000000000000000000001000 +.000000000000000000000000000464 +.000000000000000000000000000215 +.000000000000000000000000000100 +.000000000000000000000000000046 +.000000000000000000000000000021 +.000000000000000000000000000010 +.000000000000000000000000000004 +.000000000000000000000000000002 +.000000000000000000000000000001 +0 +0 +0 +0 +0 +0 +0 +0 +0 +0 +.630957344480193249434360136622 +.398107170553497250770252305087 +.251188643150958011108503206779 +.158489319246111348520210137339 +.100000000000000000000000000000 +.063095734448019324943436013662 +.039810717055349725077025230508 +.025118864315095801110850320677 +.015848931924611134852021013733 +.010000000000000000000000000000 +.006309573444801932494343601366 +.003981071705534972507702523050 +.002511886431509580111085032067 +.001584893192461113485202101373 +.001000000000000000000000000000 +.000630957344480193249434360136 +.000398107170553497250770252305 +.000251188643150958011108503206 +.000158489319246111348520210137 +.000100000000000000000000000000 +.000063095734448019324943436013 +.000039810717055349725077025230 +.000025118864315095801110850320 +.000015848931924611134852021013 +.000010000000000000000000000000 +.000006309573444801932494343601 +.000003981071705534972507702523 +.000002511886431509580111085032 +.000001584893192461113485202101 +.000001000000000000000000000000 +.000000630957344480193249434360 +.000000398107170553497250770252 +.000000251188643150958011108503 +.000000158489319246111348520210 +.000000100000000000000000000000 +.000000063095734448019324943436 +.000000039810717055349725077025 +.000000025118864315095801110850 +.000000015848931924611134852021 +.000000010000000000000000000000 +.000000006309573444801932494343 +.000000003981071705534972507702 +.000000002511886431509580111085 +.000000001584893192461113485202 +.000000001000000000000000000000 +.000000000630957344480193249434 +.000000000398107170553497250770 +.000000000251188643150958011108 +.000000000158489319246111348520 +.000000000100000000000000000000 +.000000000063095734448019324943 +.000000000039810717055349725077 +.000000000025118864315095801110 +.000000000015848931924611134852 +.000000000010000000000000000000 +.000000000006309573444801932494 +.000000000003981071705534972507 +.000000000002511886431509580111 +.000000000001584893192461113485 +.000000000001000000000000000000 +.000000000000630957344480193249 +.000000000000398107170553497250 +.000000000000251188643150958011 +.000000000000158489319246111348 +.000000000000100000000000000000 +.000000000000063095734448019324 +.000000000000039810717055349725 +.000000000000025118864315095801 +.000000000000015848931924611134 +.000000000000010000000000000000 +.000000000000006309573444801932 +.000000000000003981071705534972 +.000000000000002511886431509580 +.000000000000001584893192461113 +.000000000000001000000000000000 +.000000000000000630957344480193 +.000000000000000398107170553497 +.000000000000000251188643150958 +.000000000000000158489319246111 +.000000000000000100000000000000 +.000000000000000063095734448019 +.000000000000000039810717055349 +.000000000000000025118864315095 +.000000000000000015848931924611 +.000000000000000010000000000000 +.000000000000000006309573444801 +.000000000000000003981071705534 +.000000000000000002511886431509 +.000000000000000001584893192461 +.000000000000000001000000000000 +.000000000000000000630957344480 +.000000000000000000398107170553 +.000000000000000000251188643150 +.000000000000000000158489319246 +.000000000000000000100000000000 +.000000000000000000063095734448 +.000000000000000000039810717055 +.000000000000000000025118864315 +.000000000000000000015848931924 +.000000000000000000010000000000 +.000000000000000000006309573444 +.000000000000000000003981071705 +.000000000000000000002511886431 +.000000000000000000001584893192 +.000000000000000000001000000000 +.000000000000000000000630957344 +.000000000000000000000398107170 +.000000000000000000000251188643 +.000000000000000000000158489319 +.000000000000000000000100000000 +.000000000000000000000063095734 +.000000000000000000000039810717 +.000000000000000000000025118864 +.000000000000000000000015848931 +.000000000000000000000010000000 +.000000000000000000000006309573 +.000000000000000000000003981071 +.000000000000000000000002511886 +.000000000000000000000001584893 +.000000000000000000000001000000 +.000000000000000000000000630957 +.000000000000000000000000398107 +.000000000000000000000000251188 +.000000000000000000000000158489 +.000000000000000000000000100000 +.000000000000000000000000063095 +.000000000000000000000000039810 +.000000000000000000000000025118 +.000000000000000000000000015848 +.000000000000000000000000010000 +.000000000000000000000000006309 +.000000000000000000000000003981 +.000000000000000000000000002511 +.000000000000000000000000001584 +.000000000000000000000000001000 +.000000000000000000000000000630 +.000000000000000000000000000398 +.000000000000000000000000000251 +.000000000000000000000000000158 +.000000000000000000000000000100 +.000000000000000000000000000063 +.000000000000000000000000000039 +.000000000000000000000000000025 +.000000000000000000000000000015 +.000000000000000000000000000010 +.000000000000000000000000000006 +.000000000000000000000000000003 +.000000000000000000000000000002 +.000000000000000000000000000001 +.000000000000000000000000000001 +0 +0 +0 +0 +0 diff --git a/contrib/bc/tests/bc/sqrt.txt b/contrib/bc/tests/bc/sqrt.txt index afd87ff0f6e6..f0d79a188290 100644 --- a/contrib/bc/tests/bc/sqrt.txt +++ b/contrib/bc/tests/bc/sqrt.txt @@ -1,5 +1,7 @@ scale = 20 sqrt(0) +sqrt(1) +sqrt(1.00000000000) sqrt(2) sqrt(4) sqrt(9) diff --git a/contrib/bc/tests/bc/sqrt_results.txt b/contrib/bc/tests/bc/sqrt_results.txt index 10a4fa95d5a5..8ce821f1fb49 100644 --- a/contrib/bc/tests/bc/sqrt_results.txt +++ b/contrib/bc/tests/bc/sqrt_results.txt @@ -1,4 +1,6 @@ 0 +1.00000000000000000000 +1.00000000000000000000 1.41421356237309504880 2.00000000000000000000 3.00000000000000000000 diff --git a/contrib/bc/tests/bc/timeconst.sh b/contrib/bc/tests/bc/timeconst.sh index 8b6e1ec596fc..35bd80d56040 100755 --- a/contrib/bc/tests/bc/timeconst.sh +++ b/contrib/bc/tests/bc/timeconst.sh @@ -1,6 +1,6 @@ #! /bin/sh # -# Copyright (c) 2018-2021 Gavin D. Howard and contributors. +# Copyright (c) 2018-2024 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,21 @@ testdir=$(dirname "$script") outputdir=${BC_TEST_OUTPUT_DIR:-$testdir/..} -# Gets the timeconst script, which could be a command-line argument. +# Just print the usage and exit with an error. This can receive a message to +# print. +# @param 1 A message to print. +usage() { + if [ $# -eq 1 ]; then + printf '%s\n\n' "$1" + fi + printf 'usage: %s [timeconst_script] [exec args...]\n' "$0" + exit 1 +} + +. "$testdir/../../scripts/functions.sh" + +# Gets the timeconst script, which could be a command-line argument. I don't +# need to check for error because we just skip if it doesn't work. if [ "$#" -gt 0 ]; then timeconst="$1" shift @@ -46,8 +60,10 @@ fi if [ "$#" -gt 0 ]; then bc="$1" shift + check_exec_arg "$bc" else bc="$testdir/../../bin/bc" + check_exec_arg "$bc" fi out1="$outputdir/bc_outputs/bc_timeconst.txt" diff --git a/contrib/bc/tests/bcl.c b/contrib/bc/tests/bcl.c index 6f462ce9dc4f..3a2df4488c05 100644 --- a/contrib/bc/tests/bcl.c +++ b/contrib/bc/tests/bcl.c @@ -3,7 +3,7 @@ * * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (c) 2018-2021 Gavin D. Howard and contributors. + * Copyright (c) 2018-2024 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,10 +55,13 @@ main(void) BclError e; BclContext ctxt; size_t scale; - BclNumber n, n2, n3, n4, n5, n6; + BclNumber n, n2, n3, n4, n5, n6, n7; char* res; BclBigDig b = 0; + e = bcl_start(); + err(e); + // We do this twice to test the reference counting code. e = bcl_init(); err(e); @@ -121,9 +124,21 @@ main(void) if (!bcl_num_neg(n4)) err(BCL_ERROR_FATAL_UNKNOWN_ERR); // Add them and check the result. + n5 = bcl_add_keep(n3, n4); + err(bcl_err(n5)); + res = bcl_string(n5); + if (res == NULL) err(BCL_ERROR_FATAL_ALLOC_ERR); + if (strcmp(res, "-25452.9108273")) err(BCL_ERROR_FATAL_UNKNOWN_ERR); + + // We want to ensure all memory gets freed because we run this under + // Valgrind. + free(res); + + // Add them and check the result. n3 = bcl_add(n3, n4); err(bcl_err(n3)); - res = bcl_string(bcl_dup(n3)); + res = bcl_string_keep(n3); + if (res == NULL) err(BCL_ERROR_FATAL_ALLOC_ERR); if (strcmp(res, "-25452.9108273")) err(BCL_ERROR_FATAL_UNKNOWN_ERR); // We want to ensure all memory gets freed because we run this under @@ -133,19 +148,29 @@ main(void) // Ensure that divmod, a special case, works. n4 = bcl_parse("8937458902.2890347"); err(bcl_err(n4)); - e = bcl_divmod(bcl_dup(n4), n3, &n5, &n6); + e = bcl_divmod_keep(n4, n3, &n5, &n6); err(e); res = bcl_string(n5); - if (strcmp(res, "-351137.0060159482")) err(BCL_ERROR_FATAL_UNKNOWN_ERR); - free(res); res = bcl_string(n6); - if (strcmp(res, ".00000152374405414")) err(BCL_ERROR_FATAL_UNKNOWN_ERR); + free(res); + // Ensure that divmod, a special case, works. + n4 = bcl_parse("8937458902.2890347"); + err(bcl_err(n4)); + e = bcl_divmod(bcl_dup(n4), n3, &n5, &n6); + err(e); + + res = bcl_string(n5); + if (strcmp(res, "-351137.0060159482")) err(BCL_ERROR_FATAL_UNKNOWN_ERR); + free(res); + + res = bcl_string(n6); + if (strcmp(res, ".00000152374405414")) err(BCL_ERROR_FATAL_UNKNOWN_ERR); free(res); // Ensure that sqrt works. This is also a special case. The reason is @@ -211,10 +236,18 @@ main(void) err(bcl_err(n3)); // Repeat. + n2 = bcl_ifrand_keep(n3, 10); + err(bcl_err(n2)); + + // Repeat. n2 = bcl_ifrand(bcl_dup(n3), 10); err(bcl_err(n2)); // Still checking asserts. + e = bcl_rand_seedWithNum_keep(n3); + err(e); + + // Still checking asserts. e = bcl_rand_seedWithNum(n3); err(e); @@ -226,9 +259,12 @@ main(void) n5 = bcl_parse("10"); err(bcl_err(n5)); - n6 = bcl_modexp(bcl_dup(n5), bcl_dup(n5), bcl_dup(n5)); + n6 = bcl_modexp_keep(n5, n5, n5); err(bcl_err(n6)); + n7 = bcl_modexp(bcl_dup(n5), bcl_dup(n5), bcl_dup(n5)); + err(bcl_err(n7)); + // Clean up. bcl_num_free(n); @@ -247,6 +283,11 @@ main(void) n4 = bcl_parse("-1.01"); err(bcl_err(n4)); + res = bcl_string_keep(n); + if (strcmp(res, ".01")) err(BCL_ERROR_FATAL_UNKNOWN_ERR); + + free(res); + res = bcl_string(bcl_dup(n)); if (strcmp(res, ".01")) err(BCL_ERROR_FATAL_UNKNOWN_ERR); @@ -335,5 +376,7 @@ main(void) bcl_free(); + bcl_end(); + return 0; } diff --git a/contrib/bc/tests/dc/all.txt b/contrib/bc/tests/dc/all.txt index 8942e087768b..5d6978e5790a 100644 --- a/contrib/bc/tests/dc/all.txt +++ b/contrib/bc/tests/dc/all.txt @@ -21,5 +21,8 @@ scientific engineering vars misc +misc1 strings rand +is_number +is_string diff --git a/contrib/bc/tests/dc/errors/15.txt b/contrib/bc/tests/dc/errors/15.txt index adb809dcca3d..902a38bcbe37 100644 --- a/contrib/bc/tests/dc/errors/15.txt +++ b/contrib/bc/tests/dc/errors/15.txt @@ -1,11 +1,117 @@ -0bpax1bpR -1bpR -.218933b987pR -_19bp/98 -_38_.1/19bp38_.1/98 -_38921.1/98/98 -_38_.1/98 -_38921.1/98 -98 -_38921.1/98 -73.289 75bpu +0 lip1-si0l0+2o0sx_9lq+pR 0900pR +_100900pR +_10900p0bpR +1bp0 +.20bpR +100000.0000005bpR +_10bpR +_.1000[l0;0;rpRl01+s0l010>x]dsxx0sx0s0 +1 2+p+p +3+p +4+p +5+p +6+p +7+p +8+p +9+p +16+p +17+p +18+p +19.p +20+p +21+0+p +71+xx0sx0s0 +1 2+p+p +3o +70+p +70+p +70+p +70+p +22+p +20+p +20+p +20+p +20+p +x0+p +20+p +0 lip1-si0{0+2i0l0+200sx0.1009 +40+1+p +4000pR +_10900p0bpR +1bp0 +.20bpR +100000.002+p +20+p +20+p +20+p +20+p +x0+p +2000005bpR +_10bpR +_.10yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy00[l0;0;rpRl01+s0l010>x]dsxx0sx0s0 +1 2+p+p +3+p +4+p +5+p +6+p +7+p +8+p +9+p +10p ++p +11+p +12+p +13+p +14+p +15+p +16+p +17+p +18+p +19+p +20+p +21+0+p +71+xx0sx0s0 +1 2+p+p +3o +70+p +70+p +70+p +70+p +22+p +20+p + +20+p +30+p +30+p +30+p +0b30+p +30+p +30+p +30+p +30+p +30+p +30+p +40"1+p +40+p +40+p +40+p +40+p +40+p +40+p +40+p +40+p +50+p +50+p +50+p +50+p +50+p +50+p +50+p +50+p +50+p +5pR +100000.0070000bpR +^20+pR +_.10100000.0070000bpR +^20+pR +_.1000Kl0;0;rpRl0 diff --git a/contrib/bc/tests/dc/errors/34.txt b/contrib/bc/tests/dc/errors/34.txt deleted file mode 100644 index 902a38bcbe37..000000000000 --- a/contrib/bc/tests/dc/errors/34.txt +++ /dev/null @@ -1,117 +0,0 @@ -0 lip1-si0l0+2o0sx_9lq+pR 0900pR -_100900pR -_10900p0bpR -1bp0 -.20bpR -100000.0000005bpR -_10bpR -_.1000[l0;0;rpRl01+s0l010>x]dsxx0sx0s0 -1 2+p+p -3+p -4+p -5+p -6+p -7+p -8+p -9+p -16+p -17+p -18+p -19.p -20+p -21+0+p -71+xx0sx0s0 -1 2+p+p -3o -70+p -70+p -70+p -70+p -22+p -20+p -20+p -20+p -20+p -x0+p -20+p -0 lip1-si0{0+2i0l0+200sx0.1009 -40+1+p -4000pR -_10900p0bpR -1bp0 -.20bpR -100000.002+p -20+p -20+p -20+p -20+p -x0+p -2000005bpR -_10bpR -_.10yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy00[l0;0;rpRl01+s0l010>x]dsxx0sx0s0 -1 2+p+p -3+p -4+p -5+p -6+p -7+p -8+p -9+p -10p -+p -11+p -12+p -13+p -14+p -15+p -16+p -17+p -18+p -19+p -20+p -21+0+p -71+xx0sx0s0 -1 2+p+p -3o -70+p -70+p -70+p -70+p -22+p -20+p - -20+p -30+p -30+p -30+p -0b30+p -30+p -30+p -30+p -30+p -30+p -30+p -40"1+p -40+p -40+p -40+p -40+p -40+p -40+p -40+p -40+p -50+p -50+p -50+p -50+p -50+p -50+p -50+p -50+p -50+p -5pR -100000.0070000bpR -^20+pR -_.10100000.0070000bpR -^20+pR -_.1000Kl0;0;rpRl0 diff --git a/contrib/bc/tests/dc/is_number.txt b/contrib/bc/tests/dc/is_number.txt new file mode 100644 index 000000000000..358182927326 --- /dev/null +++ b/contrib/bc/tests/dc/is_number.txt @@ -0,0 +1,9 @@ +5upR +18923740913.12809374upR +1;aupR +0sili;bupR +[string]upR +[this]aupR +122aupR +121asxlxupR +120a2:a2;aupR diff --git a/contrib/bc/tests/dc/is_number_results.txt b/contrib/bc/tests/dc/is_number_results.txt new file mode 100644 index 000000000000..6c8f29cea4ab --- /dev/null +++ b/contrib/bc/tests/dc/is_number_results.txt @@ -0,0 +1,9 @@ +1 +1 +1 +1 +0 +0 +0 +0 +0 diff --git a/contrib/bc/tests/dc/is_string.txt b/contrib/bc/tests/dc/is_string.txt new file mode 100644 index 000000000000..6798fa3904b8 --- /dev/null +++ b/contrib/bc/tests/dc/is_string.txt @@ -0,0 +1,9 @@ +5tpR +18923740913.12809374tpR +1;atpR +0sili;btpR +[string]tpR +[this]atpR +122atpR +121asxlxtpR +120a2:a2;atpR diff --git a/contrib/bc/tests/dc/is_string_results.txt b/contrib/bc/tests/dc/is_string_results.txt new file mode 100644 index 000000000000..0c6a1c9abd7a --- /dev/null +++ b/contrib/bc/tests/dc/is_string_results.txt @@ -0,0 +1,9 @@ +0 +0 +0 +0 +1 +1 +1 +1 +1 diff --git a/contrib/bc/tests/dc/misc1.txt b/contrib/bc/tests/dc/misc1.txt new file mode 100644 index 000000000000..a512573ae548 --- /dev/null +++ b/contrib/bc/tests/dc/misc1.txt @@ -0,0 +1,26 @@ +0bpax1bpR +1bpR +.218933b987pR +_19bp/98 +_38_.1/19bp38_.1/98 +_38921.1/98/98 +_38_.1/98 +_38921.1/98 +98 +_38921.1/98 +73.289 75bpu +# These just empty the stack. +pR +pR +pR +pR +pR +pR +pR +pR +pR +pR +pR +pR +pR +pR diff --git a/contrib/bc/tests/dc/misc1_results.txt b/contrib/bc/tests/dc/misc1_results.txt new file mode 100644 index 000000000000..d2f8ad70b4b8 --- /dev/null +++ b/contrib/bc/tests/dc/misc1_results.txt @@ -0,0 +1,21 @@ +0 +1 +1 +987 +19 +19 +75 +1 +73.289 +98 +0 +98 +0 +380 +98 +0 +-380 +19 +380 +98 +0 diff --git a/contrib/bc/tests/dc/scripts/all.txt b/contrib/bc/tests/dc/scripts/all.txt index e15dae5e15ff..58c6d295bb2d 100644 --- a/contrib/bc/tests/dc/scripts/all.txt +++ b/contrib/bc/tests/dc/scripts/all.txt @@ -7,3 +7,4 @@ factorial.dc loop.dc quit.dc weird.dc +no_clamp.dc diff --git a/contrib/bc/tests/dc/scripts/easter.sh b/contrib/bc/tests/dc/scripts/easter.sh index 27dfe34580ea..ee8fa1d94c81 100755 --- a/contrib/bc/tests/dc/scripts/easter.sh +++ b/contrib/bc/tests/dc/scripts/easter.sh @@ -1,13 +1,59 @@ #!/bin/sh +# +# SPDX-License-Identifier: BSD-2-Clause +# +# Copyright (c) 2018-2024 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: +# +# * Redistributions of source code must retain the above copyright notice, this +# list of conditions and the following disclaimer. +# +# * Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE +# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +# POSSIBILITY OF SUCH DAMAGE. +# + +set -e + +script="$0" + +testdir=$(dirname "${script}") + +# Just print the usage and exit with an error. This can receive a message to +# print. +# @param 1 A message to print. +usage() { + if [ $# -eq 1 ]; then + printf '%s\n\n' "$1" + fi + printf 'usage: %s dc_exec year [options...]\n' "$script" + exit 1 +} + +. "$testdir/../../../scripts/functions.sh" if test $# -lt 2 then - echo usage: $0 dc_exec year [options...] - exit 1 + usage "Not enough arguments; need 2" fi dc_exec="$1" shift +check_exec_arg "$dc_exec" year="$1" shift diff --git a/contrib/bc/tests/dc/scripts/no_clamp.dc b/contrib/bc/tests/dc/scripts/no_clamp.dc new file mode 100644 index 000000000000..bad184a54401 --- /dev/null +++ b/contrib/bc/tests/dc/scripts/no_clamp.dc @@ -0,0 +1,29 @@ +Ip +Ap +A0p +AAp +AA0p +Fp +F0p +FFp +FF0p +47FBFE71026C816CDD99EDC9237F65023488025022006E79F92017CBA906P +2iIp +Ap +A0p +AAp +ABp +3iIp +Ap +A0p +ABp +AB0p +ABBp +5iIp +Bp +B0p +BCp +BC0p +BCDp +FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFp +FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFp diff --git a/contrib/bc/tests/dc/scripts/no_clamp.txt b/contrib/bc/tests/dc/scripts/no_clamp.txt new file mode 100644 index 000000000000..c8b680be10aa --- /dev/null +++ b/contrib/bc/tests/dc/scripts/no_clamp.txt @@ -0,0 +1,29 @@ +10 +10 +100 +110 +1100 +15 +150 +165 +1650 +Mwhuaaahahahahahhaaaa... +2 +10 +20 +30 +31 +3 +10 +30 +41 +123 +134 +5 +11 +55 +67 +335 +348 +54569682106375694274902340 +794093388050906567876552344387164339423179626464840 diff --git a/contrib/bc/tests/error.sh b/contrib/bc/tests/error.sh index c76dcdf113dd..15cbd5577ed6 100755 --- a/contrib/bc/tests/error.sh +++ b/contrib/bc/tests/error.sh @@ -2,7 +2,7 @@ # # SPDX-License-Identifier: BSD-2-Clause # -# Copyright (c) 2018-2021 Gavin D. Howard and contributors. +# Copyright (c) 2018-2024 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,18 +34,38 @@ testdir=$(dirname "$script") outputdir=${BC_TEST_OUTPUT_DIR:-$testdir} -# Command-line processing. -if [ "$#" -lt 2 ]; then - printf 'usage: %s dir test [exec args...]\n' "$script" +# Just print the usage and exit with an error. This can receive a message to +# print. +# @param 1 A message to print. +usage() { + if [ $# -eq 1 ]; then + printf '%s\n\n' "$1" + fi + printf 'usage: %s dir test problematic_tests [exec args...]\n' "$script" exit 1 +} + +# Command-line processing. +if [ "$#" -lt 3 ]; then + usage "Not enough arguments" else + d="$1" shift + check_d_arg "$d" t="$1" shift + + problematic="$1" + shift + check_bool_arg "$problematic" + fi +testfile="$testdir/$d/errors/$t" +check_file_arg "$testfile" + if [ "$#" -lt 1 ]; then exe="$testdir/../bin/$d" else @@ -53,6 +73,15 @@ else shift fi +# Just skip tests that are problematic on FreeBSD. These tests can cause FreeBSD +# to kill bc from memory exhaustion because of overcommit. +if [ "$d" = "bc" ] && [ "$problematic" -eq 0 ]; then + if [ "$t" = "33.txt" ]; then + printf 'Skipping problematic %s error file %s...\n' "$d" "$t" + exit 0 + fi +fi + # I use these, so unset them to make the tests work. unset BC_ENV_ARGS unset BC_LINE_LENGTH @@ -78,22 +107,38 @@ else halt="q" fi -testfile="$testdir/$d/errors/$t" +printf 'Running %s error file %s with clamping...' "$d" "$t" -printf 'Running %s error file %s...' "$d" "$t" +printf '%s\n' "$halt" 2> /dev/null | "$exe" "$@" $opts -c "$testfile" 2> "$out" > /dev/null +err="$?" + +checkerrtest "$d" "$err" "$testfile" "$out" "$exebase" > /dev/null + +printf 'pass\n' + +printf 'Running %s error file %s without clamping...' "$d" "$t" -printf '%s\n' "$halt" | "$exe" "$@" $opts "$testfile" 2> "$out" > /dev/null +printf '%s\n' "$halt" 2> /dev/null | "$exe" "$@" $opts -C "$testfile" 2> "$out" > /dev/null err="$?" checkerrtest "$d" "$err" "$testfile" "$out" "$exebase" > /dev/null printf 'pass\n' -printf 'Running %s error file %s through cat...' "$d" "$t" +printf 'Running %s error file %s through cat with clamping...' "$d" "$t" + +cat "$testfile" 2> /dev/null | "$exe" "$@" $opts -c 2> "$out" > /dev/null +err="$?" + +checkerrtest "$d" "$err" "$testfile" "$out" "$exebase" + +printf 'pass\n' + +printf 'Running %s error file %s through cat without clamping...' "$d" "$t" -cat "$testfile" | "$exe" "$@" $opts 2> "$out" > /dev/null +cat "$testfile" 2> /dev/null | "$exe" "$@" $opts -C 2> "$out" > /dev/null err="$?" -checkcrash "$d" "$err" "$testfile" +checkerrtest "$d" "$err" "$testfile" "$out" "$exebase" printf 'pass\n' diff --git a/contrib/bc/tests/errors.sh b/contrib/bc/tests/errors.sh index 4acc978b9e5a..47053f9c7b43 100755 --- a/contrib/bc/tests/errors.sh +++ b/contrib/bc/tests/errors.sh @@ -2,7 +2,7 @@ # # SPDX-License-Identifier: BSD-2-Clause # -# Copyright (c) 2018-2021 Gavin D. Howard and contributors. +# Copyright (c) 2018-2024 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,20 +36,33 @@ testdir=$(dirname "$script") outputdir=${BC_TEST_OUTPUT_DIR:-$testdir} -# Command-line processing. -if [ "$#" -eq 0 ]; then +# Just print the usage and exit with an error. This can receive a message to +# print. +# @param 1 A message to print. +usage() { + if [ $# -eq 1 ]; then + printf '%s\n\n' "$1" + fi printf 'usage: %s dir [exec args...]\n' "$script" exit 1 +} + +# Command-line processing. +if [ "$#" -eq 0 ]; then + usage "Not enough arguments" else d="$1" shift + check_d_arg "$d" fi if [ "$#" -lt 1 ]; then exe="$testdir/../bin/$d" + check_exec_arg "$exe" else exe="$1" shift + check_exec_arg "$exe" fi # I use these, so unset them to make the tests work. @@ -85,12 +98,12 @@ fi printf 'Running %s command-line error tests...' "$d" -printf '%s\n' "$halt" | "$exe" "$@" -e "1+1" -f- -e "2+2" 2> "$out" > /dev/null +printf '%s\n' "$halt" 2> /dev/null | "$exe" "$@" -e "1+1" -f- -e "2+2" 2> "$out" > /dev/null err="$?" checkerrtest "$d" "$err" "command-line -e test" "$out" "$exebase" -printf '%s\n' "$halt" | "$exe" "$@" -e "1+1" -f- -f "$testdir/$d/decimal.txt" 2> "$out" > /dev/null +printf '%s\n' "$halt" 2> /dev/null | "$exe" "$@" -e "1+1" -f- -f "$testdir/$d/decimal.txt" 2> "$out" > /dev/null err="$?" checkerrtest "$d" "$err" "command-line -f test" "$out" "$exebase" @@ -110,7 +123,7 @@ for testfile in $testdir/$d/*errors.txt; do # Just test warnings. line="last" - printf '%s\n' "$line" | "$exe" "$@" "-lw" 2> "$out" > /dev/null + printf '%s\n' "$line" 2> /dev/null | "$exe" "$@" "-lw" 2> "$out" > /dev/null err="$?" if [ "$err" -ne 0 ]; then @@ -137,7 +150,7 @@ for testfile in $testdir/$d/*errors.txt; do rm -f "$out" - printf '%s\n' "$line" | "$exe" "$@" "$options" 2> "$out" > /dev/null + printf '%s\n' "$line" 2> /dev/null | "$exe" "$@" "$options" 2> "$out" > /dev/null err="$?" checkerrtest "$d" "$err" "$line" "$out" "$exebase" diff --git a/contrib/bc/tests/extra_required.txt b/contrib/bc/tests/extra_required.txt index e36d95a1305b..038e6775d644 100644 --- a/contrib/bc/tests/extra_required.txt +++ b/contrib/bc/tests/extra_required.txt @@ -1,7 +1,9 @@ engineering lib2 +fib places rand +rand_limits scientific shift trunc diff --git a/contrib/bc/tests/history.py b/contrib/bc/tests/history.py index f1787a27e864..a3b722386a62 100755 --- a/contrib/bc/tests/history.py +++ b/contrib/bc/tests/history.py @@ -2,7 +2,7 @@ # # SPDX-License-Identifier: BSD-2-Clause # -# Copyright (c) 2018-2021 Gavin D. Howard and contributors. +# Copyright (c) 2018-2024 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: @@ -126,9 +126,9 @@ def write_str(child, s): # Check the bc banner. # @param child The child process. def bc_banner(child): - bc_banner1 = "bc [0-9]+\.[0-9]+\.[0-9]+\r\n" - bc_banner2 = "Copyright \(c\) 2018-[2-9][0-9][0-9][0-9] Gavin D. Howard and contributors\r\n" - bc_banner3 = "Report bugs at: https://git.yzena.com/gavin/bc\r\n\r\n" + bc_banner1 = "bc [0-9]+\\.[0-9]+\\.[0-9]+\r\n" + bc_banner2 = "Copyright \\(c\\) 2018-[2-9][0-9][0-9][0-9] Gavin D. Howard and contributors\r\n" + bc_banner3 = "Report bugs at: https://git.gavinhoward.com/gavin/bc\r\n\r\n" bc_banner4 = "This is free software with ABSOLUTELY NO WARRANTY.\r\n\r\n" expect(child, bc_banner1) expect(child, bc_banner2) diff --git a/contrib/bc/tests/history.sh b/contrib/bc/tests/history.sh index 1898ae5499dc..d06d3c6af104 100755 --- a/contrib/bc/tests/history.sh +++ b/contrib/bc/tests/history.sh @@ -2,7 +2,7 @@ # # SPDX-License-Identifier: BSD-2-Clause # -# Copyright (c) 2018-2021 Gavin D. Howard and contributors. +# Copyright (c) 2018-2024 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,16 @@ testdir=$(dirname "$script") . "$testdir/../scripts/functions.sh" -# usage: history.sh dir -a|idx [exe args...] +# Just print the usage and exit with an error. This can receive a message to +# print. +# @param 1 A message to print. +usage() { + if [ $# -eq 1 ]; then + printf '%s\n\n' "$1" + fi + printf 'usage: %s dir -a|idx [exe args...]\n' "$script" + exit 1 +} # If Python does not exist, then just skip. py=$(command -v python3) @@ -51,9 +60,14 @@ if [ "$err" -ne 0 ]; then fi fi +if [ "$#" -lt 2 ]; then + usage "Not enough arguments; expect 2 arguments" +fi + # d is "bc" or "dc" d="$1" shift +check_d_arg "$d" # idx is either an index of the test to run or "-a". If it is "-a", then all # tests are run. @@ -65,9 +79,11 @@ if [ "$#" -gt 0 ]; then # exe is the executable to run. exe="$1" shift + check_exec_arg "$exe" else exe="$testdir/../bin/$d" + check_exec_arg "$exe" fi if [ "$d" = "bc" ]; then diff --git a/contrib/bc/tests/other.sh b/contrib/bc/tests/other.sh index 4e277059a32c..1012fe919dea 100755 --- a/contrib/bc/tests/other.sh +++ b/contrib/bc/tests/other.sh @@ -2,7 +2,7 @@ # # SPDX-License-Identifier: BSD-2-Clause # -# Copyright (c) 2018-2021 Gavin D. Howard and contributors. +# Copyright (c) 2018-2024 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,24 +36,39 @@ testdir=$(dirname "$script") outputdir=${BC_TEST_OUTPUT_DIR:-$testdir} +# Just print the usage and exit with an error. This can receive a message to +# print. +# @param 1 A message to print. +usage() { + if [ $# -eq 1 ]; then + printf '%s\n\n' "$1" + fi + printf 'usage: %s dir extra_math [exec args...]\n' "$script" + exit 1 +} + # Command-line processing. if [ "$#" -ge 2 ]; then d="$1" shift + check_d_arg "$d" extra_math="$1" shift + check_bool_arg "$extra_math" else - err_exit "usage: $script dir extra_math [exec args...]" 1 + usage "Not enough arguments; need 2" fi if [ "$#" -lt 1 ]; then exe="$testdir/../bin/$d" + check_exec_arg "$exe" else exe="$1" shift + check_exec_arg "$exe" fi if [ "$d" = "bc" ]; then @@ -97,14 +112,14 @@ set +e printf '\nRunning %s quit test...' "$d" -printf '%s\n' "$halt" | "$exe" "$@" > /dev/null 2>&1 +printf '%s\n' "$halt" 2> /dev/null | "$exe" "$@" > /dev/null 2>&1 checktest_retcode "$d" "$?" "quit" # bc has two halt or quit commands, so test the second as well. if [ "$d" = bc ]; then - printf '%s\n' "quit" | "$exe" "$@" > /dev/null 2>&1 + printf '%s\n' "quit" 2> /dev/null | "$exe" "$@" > /dev/null 2>&1 checktest_retcode "$d" "$?" quit @@ -127,11 +142,11 @@ if [ "$d" = "bc" ]; then export BC_ENV_ARGS=" '-l' '' -q" - printf 's(.02893)\n' | "$exe" "$@" > /dev/null + printf 's(.02893)\n' 2> /dev/null | "$exe" "$@" > /dev/null checktest_retcode "$d" "$?" "environment var" - "$exe" "$@" -e 4 > /dev/null + printf 'halt\n' 2> /dev/null | "$exe" "$@" -e 4 > /dev/null err="$?" checktest_retcode "$d" "$?" "environment var" @@ -153,19 +168,19 @@ if [ "$d" = "bc" ]; then printf '5\n0\n' > "$redefine_res" - "$exe" "$@" --redefine=print -e 'define print(x) { x }' -e 'print(5)' > "$redefine_out" + printf 'halt\n' 2> /dev/null | "$exe" "$@" --redefine=print -e 'define print(x) { x }' -e 'print(5)' > "$redefine_out" err="$?" checktest "$d" "$err" "keyword redefinition" "$redefine_res" "$redefine_out" - "$exe" "$@" -r "abs" -r "else" -e 'abs = 5;else = 0' -e 'abs;else' > "$redefine_out" + printf 'halt\n' 2> /dev/null | "$exe" "$@" -r "abs" -r "else" -e 'abs = 5;else = 0' -e 'abs;else' > "$redefine_out" err="$?" checktest "$d" "$err" "keyword redefinition" "$redefine_res" "$redefine_out" if [ "$extra_math" -ne 0 ]; then - "$exe" "$@" -lr abs -e "perm(5, 1)" -e "0" > "$redefine_out" + printf 'halt\n' 2> /dev/null | "$exe" "$@" -lr abs -e "perm(5, 1)" -e "0" > "$redefine_out" err="$?" checktest "$d" "$err" "keyword not redefined in builtin library" "$redefine_res" "$redefine_out" @@ -189,7 +204,7 @@ if [ "$d" = "bc" ]; then multiline_expr_out="$outputdir/bc_outputs/multiline_expr_results.txt" # tests/bc/misc1.txt happens to have a multiline comment in it. - "$exe" "$@" -f "$testdir/bc/misc1.txt" > "$multiline_expr_out" + printf 'halt\n' 2> /dev/null | "$exe" "$@" -f "$testdir/bc/misc1.txt" > "$multiline_expr_out" err="$?" checktest "$d" "$err" "multiline comment in expression file" "$testdir/bc/misc1_results.txt" \ @@ -198,7 +213,7 @@ if [ "$d" = "bc" ]; then printf 'pass\n' printf 'Running multiline comment expression file error test...' - "$exe" "$@" -f "$testdir/bc/errors/05.txt" 2> "$multiline_expr_out" + printf 'halt\n' 2> /dev/null | "$exe" "$@" -f "$testdir/bc/errors/05.txt" 2> "$multiline_expr_out" err="$?" checkerrtest "$d" "$err" "multiline comment in expression file error" \ @@ -208,7 +223,7 @@ if [ "$d" = "bc" ]; then printf 'Running multiline string expression file test...' # tests/bc/strings.txt happens to have a multiline string in it. - "$exe" "$@" -f "$testdir/bc/strings.txt" > "$multiline_expr_out" + printf 'halt\n' 2> /dev/null | "$exe" "$@" -f "$testdir/bc/strings.txt" > "$multiline_expr_out" err="$?" checktest "$d" "$err" "multiline string in expression file" "$testdir/bc/strings_results.txt" \ @@ -217,13 +232,13 @@ if [ "$d" = "bc" ]; then printf 'pass\n' printf 'Running multiline string expression file error test...' - "$exe" "$@" -f "$testdir/bc/errors/16.txt" 2> "$multiline_expr_out" + printf 'halt\n' 2> /dev/null | "$exe" "$@" -f "$testdir/bc/errors/16.txt" 2> "$multiline_expr_out" err="$?" checkerrtest "$d" "$err" "multiline string in expression file with backslash error" \ "$multiline_expr_out" "$d" - "$exe" "$@" -f "$testdir/bc/errors/04.txt" 2> "$multiline_expr_out" + printf 'halt\n' 2> /dev/null | "$exe" "$@" -f "$testdir/bc/errors/04.txt" 2> "$multiline_expr_out" err="$?" checkerrtest "$d" "$err" "multiline string in expression file error" \ @@ -236,7 +251,7 @@ else export DC_ENV_ARGS="'-x'" export DC_EXPR_EXIT="1" - printf '4s stuff\n' | "$exe" "$@" > /dev/null + printf '4s stuff\n' 2> /dev/null | "$exe" "$@" > /dev/null checktest_retcode "$d" "$?" "environment var" @@ -251,15 +266,15 @@ else # dc has an extra test for a case that someone found running this easter.dc # script. It went into an infinite loop, so we want to check that we did not # regress. - printf 'three\n' | cut -c1-3 > /dev/null + printf 'three\n' 2> /dev/null | cut -c1-3 > /dev/null err=$? if [ "$err" -eq 0 ]; then printf 'Running dc Easter script...' - easter_res="$outputdir/dc_outputs/easter.txt" - easter_out="$outputdir/dc_outputs/easter_results.txt" + easter_out="$outputdir/dc_outputs/easter.txt" + easter_res="$outputdir/dc_outputs/easter_results.txt" outdir=$(dirname "$easter_out") @@ -269,14 +284,44 @@ else printf '4 April 2021\n' > "$easter_res" - "$testdir/dc/scripts/easter.sh" "$exe" 2021 "$@" | cut -c1-12 > "$easter_out" + "$testdir/dc/scripts/easter.sh" "$exe" 2021 "$@" 2> /dev/null | cut -c1-12 > "$easter_out" err="$?" - checktest "$d" "$err" "Easter script" "$easter_res" "$easter_out" + checktest "$d" "$err" "Easter script" "$easter_out" "$easter_res" printf 'pass\n' fi + unset DC_ENV_ARGS + unset DC_EXPR_EXIT + + printf 'Running dc extended register command tests...' + + ext_reg_out="$outputdir/dc_outputs/ext_reg.txt" + ext_reg_res="$outputdir/dc_outputs/ext_reg_results.txt" + + outdir=$(dirname "$ext_reg_out") + + if [ ! -d "$outdir" ]; then + mkdir -p "$outdir" + fi + + printf '0\n' > "$ext_reg_res" + + printf '%s\n' "$halt" | "$exe" "$@" -e "gxpR" 2> /dev/null > "$ext_reg_out" + err="$?" + + checktest "$d" "$err" "Extended register command" "$ext_reg_out" "$ext_reg_res" + + printf '1\n' > "$ext_reg_res" + + printf '%s\n' "$halt" | "$exe" "$@" -x -e "gxpR" 2> /dev/null > "$ext_reg_out" + err="$?" + + checktest "$d" "$err" "Extended register command" "$ext_reg_out" "$ext_reg_res" + + printf 'pass\n' + fi out1="$outputdir/${d}_outputs/${d}_other.txt" @@ -287,26 +332,26 @@ printf 'Running %s line length tests...' "$d" printf '%s\n' "$numres" > "$out1" export "$line_var"=80 -printf '%s\n' "$num" | "$exe" "$@" > "$out2" +printf '%s\n' "$num" 2> /dev/null | "$exe" "$@" > "$out2" checktest "$d" "$?" "line length" "$out1" "$out2" printf '%s\n' "$num70" > "$out1" export "$line_var"=2147483647 -printf '%s\n' "$num" | "$exe" "$@" > "$out2" +printf '%s\n' "$num" 2> /dev/null | "$exe" "$@" > "$out2" checktest "$d" "$?" "line length 2" "$out1" "$out2" printf '%s\n' "$num2" > "$out1" export "$line_var"=62 -printf '%s\n' "$num" | "$exe" "$@" -L > "$out2" +printf '%s\n' "$num" 2> /dev/null | "$exe" "$@" -L > "$out2" checktest "$d" "$?" "line length 3" "$out1" "$out2" printf '0\n' > "$out1" -printf '%s\n' "$lltest" | "$exe" "$@" -L > "$out2" +printf '%s\n' "$lltest" 2> /dev/null | "$exe" "$@" -L > "$out2" checktest "$d" "$?" "line length 3" "$out1" "$out2" @@ -327,23 +372,23 @@ printf '%s\n%s\n%s\n%s\n' "$results" "$results" "$results" "$results" > "$out1" checktest "$d" "$?" "arg" "$out1" "$out2" -printf '%s\n' "$halt" | "$exe" "$@" -- "$f" "$f" "$f" "$f" > "$out2" +printf '%s\n' "$halt" 2> /dev/null | "$exe" "$@" -- "$f" "$f" "$f" "$f" > "$out2" checktest "$d" "$?" "arg" "$out1" "$out2" if [ "$d" = "bc" ]; then - printf '%s\n' "$halt" | "$exe" "$@" -i > /dev/null 2>&1 + printf '%s\n' "$halt" 2> /dev/null | "$exe" "$@" -i > /dev/null 2>&1 fi -printf '%s\n' "$halt" | "$exe" "$@" -h > /dev/null +printf '%s\n' "$halt" 2> /dev/null | "$exe" "$@" -h > /dev/null checktest_retcode "$d" "$?" "arg" -printf '%s\n' "$halt" | "$exe" "$@" -P > /dev/null +printf '%s\n' "$halt" 2> /dev/null | "$exe" "$@" -P > /dev/null checktest_retcode "$d" "$?" "arg" -printf '%s\n' "$halt" | "$exe" "$@" -R > /dev/null +printf '%s\n' "$halt" 2> /dev/null | "$exe" "$@" -R > /dev/null checktest_retcode "$d" "$?" "arg" -printf '%s\n' "$halt" | "$exe" "$@" -v > /dev/null +printf '%s\n' "$halt" 2> /dev/null | "$exe" "$@" -v > /dev/null checktest_retcode "$d" "$?" "arg" -printf '%s\n' "$halt" | "$exe" "$@" -V > /dev/null +printf '%s\n' "$halt" 2> /dev/null | "$exe" "$@" -V > /dev/null checktest_retcode "$d" "$?" "arg" out=$(printf '0.1\n-0.1\n1.1\n-1.1\n0.1\n-0.1\n') @@ -355,12 +400,12 @@ else data=$(printf '0.1pR\n_0.1pR\n1.1pR\n_1.1pR\n.1pR\n_.1pR\n') fi -printf '%s\n' "$data" | "$exe" "$@" -z > "$out2" +printf '%s\n' "$data" 2> /dev/null | "$exe" "$@" -z > "$out2" checktest "$d" "$?" "leading zero" "$out1" "$out2" if [ "$d" = "bc" ] && [ "$extra_math" -ne 0 ]; then - printf '%s\n' "$halt" | "$exe" "$@" -lz "$testdir/bc/leadingzero.txt" > "$out2" + printf '%s\n' "$halt" 2> /dev/null | "$exe" "$@" -lz "$testdir/bc/leadingzero.txt" > "$out2" checktest "$d" "$?" "leading zero script" "$testdir/bc/leadingzero_results.txt" "$out2" @@ -431,10 +476,10 @@ if [ "$extra_math" -ne 0 ]; then data=$(printf 'J2@OIKAiAopRpRpRpR') fi - printf '%s\n' "$data" | "$exe" "$@" -S14 -I15 -O16 -E17.25 > "$out2" + printf '%s\n' "$data" 2> /dev/null | "$exe" "$@" -S14 -I15 -O16 -E17.25 > "$out2" checktest "$d" "$?" "builtin variable args" "$out1" "$out2" - printf '%s\n' "$data" | "$exe" "$@" --scale=14 --ibase=15 --obase=16 --seed=17.25 > "$out2" + printf '%s\n' "$data" 2> /dev/null | "$exe" "$@" --scale=14 --ibase=15 --obase=16 --seed=17.25 > "$out2" checktest "$d" "$?" "builtin variable long args" "$out1" "$out2" else @@ -448,22 +493,53 @@ else data=$(printf 'OIKAiAopRpRpR') fi - printf '%s\n' "$data" | "$exe" "$@" -S14 -I15 -O16 > "$out2" + printf '%s\n' "$data" 2> /dev/null | "$exe" "$@" -S14 -I15 -O16 > "$out2" checktest "$d" "$?" "builtin variable args" "$out1" "$out2" - printf '%s\n' "$data" | "$exe" "$@" --scale=14 --ibase=15 --obase=16 > "$out2" + printf '%s\n' "$data" 2> /dev/null | "$exe" "$@" --scale=14 --ibase=15 --obase=16 > "$out2" checktest "$d" "$?" "builtin variable long args" "$out1" "$out2" fi -printf 'scale\n' | "$exe" "$@" --scale=18923c.rlg > /dev/null 2> "$out2" +if [ "$d" = "bc" ]; then + + out=$(printf '100\n') + printf '%s\n' "$out" > "$out1" + + printf 'scale\n' 2> /dev/null | "$exe" "$@" -S100 -l > "$out2" + checktest "$d" "$?" "builtin variable args with math lib" "$out1" "$out2" + + printf 'scale\n' 2> /dev/null | "$exe" "$@" --scale=100 --mathlib > "$out2" + checktest "$d" "$?" "builtin variable long args with math lib" "$out1" "$out2" + + export BC_ENV_ARGS="-l" + + printf 'scale\n' 2> /dev/null | "$exe" "$@" -S100 > "$out2" + checktest "$d" "$?" "builtin variable args with math lib env arg" "$out1" "$out2" + + printf 'scale\n' 2> /dev/null | "$exe" "$@" --scale=100 > "$out2" + checktest "$d" "$?" "builtin variable long args with math lib env arg" "$out1" "$out2" + + export BC_ENV_ARGS="-S100" + + printf 'scale\n' 2> /dev/null | "$exe" "$@" -l > "$out2" + checktest "$d" "$?" "builtin variable args with math lib arg" "$out1" "$out2" + + export BC_ENV_ARGS="--scale=100" + + printf 'scale\n' 2> /dev/null | "$exe" "$@" -l > "$out2" + checktest "$d" "$?" "builtin variable long args with math lib arg" "$out1" "$out2" + +fi + +printf 'scale\n' 2> /dev/null | "$exe" "$@" --scale=18923c.rlg > /dev/null 2> "$out2" err="$?" checkerrtest "$d" "$err" "invalid command-line arg for builtin variable" "$out2" "$d" if [ "$extra_math" -ne 0 ]; then - printf 'seed\n' | "$exe" "$@" --seed=18923c.rlg > /dev/null 2> "$out2" + printf 'seed\n' 2> /dev/null | "$exe" "$@" --seed=18923c.rlg > /dev/null 2> "$out2" err="$?" checkerrtest "$d" "$err" "invalid command-line arg for seed" "$out2" "$d" @@ -494,7 +570,7 @@ printf 'pass\n' printf 'Running %s binary stdin test...' "$d" -cat "$bin" | "$exe" "$@" > /dev/null 2> "$out2" +cat "$bin" 2> /dev/null | "$exe" "$@" > /dev/null 2> "$out2" err="$?" checkerrtest "$d" "$err" "binary stdin" "$out2" "$d" @@ -504,7 +580,7 @@ printf 'pass\n' if [ "$d" = "bc" ]; then printf 'Running %s limits tests...' "$d" - printf 'limits\n' | "$exe" "$@" > "$out2" /dev/null 2>&1 + printf 'limits\n' 2> /dev/null | "$exe" "$@" /dev/null > "$out2" 2>&1 checktest_retcode "$d" "$?" "limits" diff --git a/contrib/bc/tests/read.sh b/contrib/bc/tests/read.sh index a1915eb271ac..fd4b9b6721a5 100755 --- a/contrib/bc/tests/read.sh +++ b/contrib/bc/tests/read.sh @@ -2,7 +2,7 @@ # # SPDX-License-Identifier: BSD-2-Clause # -# Copyright (c) 2018-2021 Gavin D. Howard and contributors. +# Copyright (c) 2018-2024 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,24 +36,37 @@ testdir=$(dirname "$script") outputdir=${BC_TEST_OUTPUT_DIR:-$testdir} -# Command-line processing. -if [ "$#" -lt 1 ]; then - printf 'usage: %s dir [exe [args...]]\n' "$0" +# Just print the usage and exit with an error. This can receive a message to +# print. +# @param 1 A message to print. +usage() { + if [ $# -eq 1 ]; then + printf '%s\n\n' "$1" + fi + printf 'usage: %s dir [exe [args...]]\n' "$script" printf 'valid dirs are:\n' printf '\n' cat "$testdir/all.txt" printf '\n' exit 1 +} + +# Command-line processing. +if [ "$#" -lt 1 ]; then + usage "Not enough arguments" fi d="$1" shift +check_d_arg "$d" if [ "$#" -gt 0 ]; then exe="$1" shift + check_exec_arg "$exe" else exe="$testdir/../bin/$d" + check_exec_arg "$exe" fi name="$testdir/$d/read.txt" @@ -61,6 +74,7 @@ results="$testdir/$d/read_results.txt" errors="$testdir/$d/read_errors.txt" out="$outputdir/${d}_outputs/read_results.txt" +multiple_res="$outputdir/${d}_outputs/read_multiple_results.txt" outdir=$(dirname "$out") # Make sure the directory exists. @@ -76,11 +90,13 @@ if [ "$d" = "bc" ]; then halt="halt" read_call="read()" read_expr="${read_call}\n5+5;" + read_multiple=$(printf '%s\n%s\n%s\n' "3" "2" "1") else options="-x" halt="q" read_call="?" read_expr="${read_call}" + read_multiple=$(printf '%spR\n%spR\n%spR\n' "3" "2" "1") fi # I use these, so unset them to make the tests work. @@ -103,6 +119,16 @@ done < "$name" printf 'pass\n' +printf 'Running %s read multiple...' "$d" + +printf '3\n2\n1\n' > "$multiple_res" + +# Run multiple read() calls. +printf '%s\n' "$read_multiple" | "$exe" "$@" "$options" -e "$read_call" -e "$read_call" -e "$read_call" > "$out" +checktest "$d" "$?" 'read multiple' "$multiple_res" "$out" + +printf 'pass\n' + printf 'Running %s read errors...' "$d" # Run read on every line. diff --git a/contrib/bc/tests/script.sh b/contrib/bc/tests/script.sh index 5942e13159fe..b1346ef09904 100755 --- a/contrib/bc/tests/script.sh +++ b/contrib/bc/tests/script.sh @@ -2,7 +2,7 @@ # # SPDX-License-Identifier: BSD-2-Clause # -# Copyright (c) 2018-2021 Gavin D. Howard and contributors. +# Copyright (c) 2018-2024 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,49 +37,72 @@ testdir=$(dirname "${script}") outputdir=${BC_TEST_OUTPUT_DIR:-$testdir} -# Command-line processing. -if [ "$#" -lt 2 ]; then +# Just print the usage and exit with an error. This can receive a message to +# print. +# @param 1 A message to print. +usage() { + if [ $# -eq 1 ]; then + printf '%s\n\n' "$1" + fi printf 'usage: %s dir script [run_extra_tests] [run_stack_tests] [generate_tests] [time_tests] [exec args...]\n' "$script" exit 1 +} + +# Command-line processing. +if [ "$#" -lt 2 ]; then + usage "Not enough arguments; expect 2 arguments" fi d="$1" shift +check_d_arg "$d" + +scriptdir="$testdir/$d/scripts" f="$1" shift +check_file_arg "$scriptdir/$f" if [ "$#" -gt 0 ]; then run_extra_tests="$1" shift + check_bool_arg "$run_extra_tests" else run_extra_tests=1 + check_bool_arg "$run_extra_tests" fi if [ "$#" -gt 0 ]; then run_stack_tests="$1" shift + check_bool_arg "$run_stack_tests" else run_stack_tests=1 + check_bool_arg "$run_stack_tests" fi if [ "$#" -gt 0 ]; then generate="$1" shift + check_bool_arg "$generate" else generate=1 + check_bool_arg "$generate" fi if [ "$#" -gt 0 ]; then time_tests="$1" shift + check_bool_arg "$time_tests" else time_tests=0 + check_bool_arg "$generate" fi if [ "$#" -gt 0 ]; then exe="$1" shift + check_exec_arg "$exe" else exe="$testdir/../bin/$d" fi @@ -88,20 +111,18 @@ fi if [ "$d" = "bc" ]; then if [ "$run_stack_tests" -ne 0 ]; then - options="-lgq" + options="-lgqC" else - options="-lq" + options="-lqC" fi halt="halt" else - options="-x" + options="-xC" halt="q" fi -scriptdir="$testdir/$d/scripts" - name="${f%.*}" # We specifically want to skip this because it is handled specially. @@ -111,7 +132,7 @@ fi # Skip the tests that require extra math if we don't have it. if [ "$run_extra_tests" -eq 0 ]; then - if [ "$f" = "rand.bc" ]; then + if [ "$f" = "rand.bc" ] || [ "$f" = "root.bc" ] || [ "$f" = "i2rand.bc" ]; then printf 'Skipping %s script: %s\n' "$d" "$f" exit 0 fi @@ -159,7 +180,7 @@ else # This is to check that the command exists. If not, we should not try to # generate the test. Instead, we should just skip. - command -v "$d" + command -v "$d" 1>/dev/null 2>&1 err="$?" set -e @@ -169,11 +190,17 @@ else exit 0 fi - # This sed, and the script, are to remove an incompatibility with GNU bc, - # where GNU bc is wrong. See the development manual - # (manuals/development.md#script-tests) for more information. printf 'Generating %s results...' "$f" - printf '%s\n' "$halt" | "$d" "$s" | sed -n -f "$testdir/script.sed" > "$results" + + # This particular test needs to be generated straight. + if [ "$d" = "dc" ] && [ "$f" = "stream.dc" ]; then + printf '%s\n' "$halt" 2> /dev/null | "$d" "$s" > "$results" + else + # This sed, and the script, are to remove an incompatibility with GNU + # bc, where GNU bc is wrong. See the development manual + # (manuals/development.md#script-tests) for more information. + printf '%s\n' "$halt" 2> /dev/null | "$d" "$s" | sed -n -f "$testdir/script.sed" > "$results" + fi printf 'done\n' res="$results" fi @@ -185,11 +212,11 @@ printf 'Running %s script %s...' "$d" "$f" # Yes this is poor timing, but it works. if [ "$time_tests" -ne 0 ]; then printf '\n' - printf '%s\n' "$halt" | /usr/bin/time -p "$exe" "$@" $options "$s" > "$out" + printf '%s\n' "$halt" 2> /dev/null | /usr/bin/time -p "$exe" "$@" $options "$s" > "$out" err="$?" printf '\n' else - printf '%s\n' "$halt" | "$exe" "$@" $options "$s" > "$out" + printf '%s\n' "$halt" 2> /dev/null | "$exe" "$@" $options "$s" > "$out" err="$?" fi diff --git a/contrib/bc/tests/scripts.sh b/contrib/bc/tests/scripts.sh index 46aa7e761170..2c8af6c06df0 100755 --- a/contrib/bc/tests/scripts.sh +++ b/contrib/bc/tests/scripts.sh @@ -2,7 +2,7 @@ # # SPDX-License-Identifier: BSD-2-Clause # -# Copyright (c) 2018-2021 Gavin D. Howard and contributors. +# Copyright (c) 2018-2024 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: @@ -31,6 +31,19 @@ script="$0" testdir=$(dirname "${script}") +. "$testdir/../scripts/functions.sh" + +# Just print the usage and exit with an error. This can receive a message to +# print. +# @param 1 A message to print. +usage() { + if [ $# -eq 1 ]; then + printf '%s\n\n' "$1" + fi + printf 'usage: %s [-n] dir [run_extra_tests] [run_stack_tests] [generate_tests] [time_tests] [exec args...]\n' "$script" + exit 1 +} + pids="" # We need to figure out if we should run stuff in parallel. @@ -39,54 +52,65 @@ pll=1 while getopts "n" opt; do case "$opt" in - n) pll=0 ; shift ; set -e ;; + n) pll=0 ; set -e ;; ?) usage "Invalid option: $opt" ;; esac done +shift $(($OPTIND - 1)) # Command-line processing. if [ "$#" -eq 0 ]; then - printf 'usage: %s [-n] dir [run_extra_tests] [run_stack_tests] [generate_tests] [time_tests] [exec args...]\n' "$script" - exit 1 + usage "Need at least 1 argument" else d="$1" shift + check_d_arg "$d" fi if [ "$#" -gt 0 ]; then run_extra_tests="$1" shift + check_bool_arg "$run_extra_tests" else run_extra_tests=1 + check_bool_arg "$run_extra_tests" fi if [ "$#" -gt 0 ]; then run_stack_tests="$1" shift + check_bool_arg "$run_stack_tests" else run_stack_tests=1 + check_bool_arg "$run_stack_tests" fi if [ "$#" -gt 0 ]; then generate="$1" shift + check_bool_arg "$generate" else generate=1 + check_bool_arg "$generate" fi if [ "$#" -gt 0 ]; then time_tests="$1" shift + check_bool_arg "$time_tests" else time_tests=0 + check_bool_arg "$time_tests" fi if [ "$#" -gt 0 ]; then exe="$1" shift + check_exec_arg "$exe" else exe="$testdir/../bin/$d" + check_exec_arg "$exe" fi scriptdir="$testdir/$d/scripts" diff --git a/contrib/bc/tests/stdin.sh b/contrib/bc/tests/stdin.sh index 69e6f2cabf34..7061e950367e 100755 --- a/contrib/bc/tests/stdin.sh +++ b/contrib/bc/tests/stdin.sh @@ -2,7 +2,7 @@ # # SPDX-License-Identifier: BSD-2-Clause # -# Copyright (c) 2018-2021 Gavin D. Howard and contributors. +# Copyright (c) 2018-2024 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,24 +37,37 @@ testdir=$(dirname "$script") outputdir=${BC_TEST_OUTPUT_DIR:-$testdir} -# Command-line processing. -if [ "$#" -lt 1 ]; then +# Just print the usage and exit with an error. This can receive a message to +# print. +# @param 1 A message to print. +usage() { + if [ $# -eq 1 ]; then + printf '%s\n\n' "$1" + fi printf 'usage: %s dir [exe [args...]]\n' "$0" printf 'valid dirs are:\n' printf '\n' cat "$testdir/all.txt" printf '\n' exit 1 +} + +# Command-line processing. +if [ "$#" -lt 1 ]; then + usage "Not enough arguments" fi d="$1" shift +check_d_arg "$d" if [ "$#" -gt 0 ]; then exe="$1" shift + check_exec_arg "$exe" else exe="$testdir/../bin/$d" + check_exec_arg "$exe" fi out="$outputdir/${d}_outputs/stdin_results.txt" diff --git a/contrib/bc/tests/test.sh b/contrib/bc/tests/test.sh index 9d557a715dc0..7b5916f02990 100755 --- a/contrib/bc/tests/test.sh +++ b/contrib/bc/tests/test.sh @@ -2,7 +2,7 @@ # # SPDX-License-Identifier: BSD-2-Clause # -# Copyright (c) 2018-2021 Gavin D. Howard and contributors. +# Copyright (c) 2018-2024 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,19 +37,32 @@ testdir=$(dirname "$script") outputdir=${BC_TEST_OUTPUT_DIR:-$testdir} -# Command-line processing. -if [ "$#" -lt 2 ]; then +# Just print the usage and exit with an error. This can receive a message to +# print. +# @param 1 A message to print. +usage() { + if [ $# -eq 1 ]; then + printf '%s\n\n' "$1" + fi printf 'usage: %s dir test [generate_tests] [time_tests] [exe [args...]]\n' "$0" printf 'valid dirs are:\n' printf '\n' cat "$testdir/all.txt" printf '\n' exit 1 +} + +# Command-line processing. +if [ "$#" -lt 2 ]; then + usage "Need at least 2 arguments" fi d="$1" shift +check_d_arg "$d" +# We don't use check_file_arg on the test or the result because they might be +# generated. t="$1" name="$testdir/$d/$t.txt" results="$testdir/$d/${t}_results.txt" @@ -58,22 +71,28 @@ shift if [ "$#" -gt 0 ]; then generate_tests="$1" shift + check_bool_arg "$generate_tests" else generate_tests=1 + check_bool_arg "$generate_tests" fi if [ "$#" -gt 0 ]; then time_tests="$1" shift + check_bool_arg "$time_tests" else time_tests=0 + check_bool_arg "$time_tests" fi if [ "$#" -gt 0 ]; then exe="$1" shift + check_exec_arg "$exe" else exe="$testdir/../bin/$d" + check_exec_arg "$exe" fi out="$outputdir/${d}_outputs/${t}_results.txt" @@ -119,13 +138,15 @@ fi # If the results do not exist, generate.. if [ ! -f "$results" ]; then printf 'Generating %s %s results...' "$d" "$t" - printf '%s\n' "$halt" | "$d" $options "$name" > "$results" + printf '%s\n' "$halt" 2> /dev/null | "$d" $options "$name" > "$results" printf 'done\n' fi -# We set this here because GNU dc does not have it. -if [ "$d" = "dc" ]; then - options="-x" +# We set this here because GNU bc and dc does not have these options. +if [ "$d" = "bc" ]; then + options="-lqc" +else + options="-xc" fi export $var=string @@ -136,11 +157,11 @@ printf 'Running %s %s...' "$d" "$t" if [ "$time_tests" -ne 0 ]; then printf '\n' - printf '%s\n' "$halt" | /usr/bin/time -p "$exe" "$@" $options "$name" > "$out" + printf '%s\n' "$halt" 2> /dev/null | /usr/bin/time -p "$exe" "$@" $options "$name" > "$out" err="$?" printf '\n' else - printf '%s\n' "$halt" | "$exe" "$@" $options "$name" > "$out" + printf '%s\n' "$halt" 2> /dev/null | "$exe" "$@" $options "$name" > "$out" err="$?" fi diff --git a/contrib/bc/vs/bc.vcxproj b/contrib/bc/vs/bc.vcxproj index ce34162118e1..c98ebc6eee53 100644 --- a/contrib/bc/vs/bc.vcxproj +++ b/contrib/bc/vs/bc.vcxproj @@ -29,26 +29,26 @@ <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'" Label="Configuration"> <ConfigurationType>Application</ConfigurationType> <UseDebugLibraries>true</UseDebugLibraries> - <PlatformToolset>v142</PlatformToolset> + <PlatformToolset>v143</PlatformToolset> <CharacterSet>Unicode</CharacterSet> </PropertyGroup> <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|Win32'" Label="Configuration"> <ConfigurationType>Application</ConfigurationType> <UseDebugLibraries>false</UseDebugLibraries> - <PlatformToolset>v142</PlatformToolset> + <PlatformToolset>v143</PlatformToolset> <WholeProgramOptimization>true</WholeProgramOptimization> <CharacterSet>Unicode</CharacterSet> </PropertyGroup> <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|x64'" Label="Configuration"> <ConfigurationType>Application</ConfigurationType> <UseDebugLibraries>true</UseDebugLibraries> - <PlatformToolset>v142</PlatformToolset> + <PlatformToolset>v143</PlatformToolset> <CharacterSet>Unicode</CharacterSet> </PropertyGroup> <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|x64'" Label="Configuration"> <ConfigurationType>Application</ConfigurationType> <UseDebugLibraries>false</UseDebugLibraries> - <PlatformToolset>v142</PlatformToolset> + <PlatformToolset>v143</PlatformToolset> <WholeProgramOptimization>true</WholeProgramOptimization> <CharacterSet>Unicode</CharacterSet> </PropertyGroup> @@ -100,9 +100,10 @@ </PropertyGroup> <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'"> <ClCompile> + <AdditionalOptions>/std:c17 /MP $(AdditionalOptions)</AdditionalOptions> <WarningLevel>Level3</WarningLevel> <SDLCheck>true</SDLCheck> - <PreprocessorDefinitions>BC_ENABLED=1;DC_ENABLED=1;BC_ENABLE_EXTRA_MATH=1;BC_ENABLE_HISTORY=1;BC_ENABLE_NLS=0;BC_DEBUG_CODE=0;BC_ENABLE_LIBRARY=0;BC_ENABLE_EDITLINE=0;BC_ENABLE_READLINE=0;BUILD_TYPE=N;BC_DEFAULT_BANNER=1;BC_DEFAULT_SIGINT_RESET=0;DC_DEFAULT_SIGINT_RESET=0;BC_DEFAULT_TTY_MODE=1;DC_DEFAULT_TTY_MODE=1;BC_DEFAULT_PROMPT=1;DC_DEFAULT_PROMPT=1;BC_DEFAULT_EXPR_EXIT=1;DC_DEFAULT_EXPR_EXIT=1;WIN32;_DEBUG;_CONSOLE;%(PreprocessorDefinitions)</PreprocessorDefinitions> + <PreprocessorDefinitions>BC_ENABLED=1;DC_ENABLED=1;BC_ENABLE_EXTRA_MATH=1;BC_ENABLE_HISTORY=1;BC_ENABLE_NLS=0;BC_DEBUG_CODE=0;BC_ENABLE_LIBRARY=0;BC_ENABLE_EDITLINE=0;BC_ENABLE_READLINE=0;BC_ENABLE_OSSFUZZ=0;BUILD_TYPE=N;BC_DEFAULT_BANNER=1;BC_DEFAULT_SIGINT_RESET=0;DC_DEFAULT_SIGINT_RESET=0;BC_DEFAULT_TTY_MODE=1;DC_DEFAULT_TTY_MODE=1;BC_DEFAULT_PROMPT=1;DC_DEFAULT_PROMPT=1;BC_DEFAULT_EXPR_EXIT=1;DC_DEFAULT_EXPR_EXIT=1;BC_DEFAULT_DIGIT_CLAMP=1;DC_DEFAULT_DIGIT_CLAMP=1;WIN32;_DEBUG;_CONSOLE;%(PreprocessorDefinitions)</PreprocessorDefinitions> <AdditionalIncludeDirectories>..\include</AdditionalIncludeDirectories> <RuntimeLibrary>MultiThreadedDebug</RuntimeLibrary> <ConformanceMode>true</ConformanceMode> @@ -119,11 +120,12 @@ </ItemDefinitionGroup> <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Release|Win32'"> <ClCompile> + <AdditionalOptions>/std:c17 /MP $(AdditionalOptions)</AdditionalOptions> <WarningLevel>Level3</WarningLevel> <FunctionLevelLinking>true</FunctionLevelLinking> <IntrinsicFunctions>true</IntrinsicFunctions> <SDLCheck>true</SDLCheck> - <PreprocessorDefinitions>BC_ENABLED=1;DC_ENABLED=1;BC_ENABLE_EXTRA_MATH=1;BC_ENABLE_HISTORY=1;BC_ENABLE_NLS=0;BC_DEBUG_CODE=0;BC_ENABLE_LIBRARY=0;BC_ENABLE_EDITLINE=0;BC_ENABLE_READLINE=0;BUILD_TYPE=N;BC_DEFAULT_BANNER=1;BC_DEFAULT_SIGINT_RESET=0;DC_DEFAULT_SIGINT_RESET=0;BC_DEFAULT_TTY_MODE=1;DC_DEFAULT_TTY_MODE=1;BC_DEFAULT_PROMPT=1;DC_DEFAULT_PROMPT=1;BC_DEFAULT_EXPR_EXIT=1;DC_DEFAULT_EXPR_EXIT=1;WIN32;NDEBUG;_CONSOLE;%(PreprocessorDefinitions)</PreprocessorDefinitions> + <PreprocessorDefinitions>BC_ENABLED=1;DC_ENABLED=1;BC_ENABLE_EXTRA_MATH=1;BC_ENABLE_HISTORY=1;BC_ENABLE_NLS=0;BC_DEBUG_CODE=0;BC_ENABLE_LIBRARY=0;BC_ENABLE_EDITLINE=0;BC_ENABLE_READLINE=0;BC_ENABLE_OSSFUZZ=0;BUILD_TYPE=N;BC_DEFAULT_BANNER=1;BC_DEFAULT_SIGINT_RESET=0;DC_DEFAULT_SIGINT_RESET=0;BC_DEFAULT_TTY_MODE=1;DC_DEFAULT_TTY_MODE=1;BC_DEFAULT_PROMPT=1;DC_DEFAULT_PROMPT=1;BC_DEFAULT_EXPR_EXIT=1;DC_DEFAULT_EXPR_EXIT=1;BC_DEFAULT_DIGIT_CLAMP=1;DC_DEFAULT_DIGIT_CLAMP=1;WIN32;NDEBUG;_CONSOLE;%(PreprocessorDefinitions)</PreprocessorDefinitions> <AdditionalIncludeDirectories>..\include</AdditionalIncludeDirectories> <RuntimeLibrary>MultiThreaded</RuntimeLibrary> <ConformanceMode>true</ConformanceMode> @@ -142,9 +144,10 @@ </ItemDefinitionGroup> <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Debug|x64'"> <ClCompile> + <AdditionalOptions>/std:c17 /MP $(AdditionalOptions)</AdditionalOptions> <WarningLevel>Level3</WarningLevel> <SDLCheck>true</SDLCheck> - <PreprocessorDefinitions>BC_ENABLED=1;DC_ENABLED=1;BC_ENABLE_EXTRA_MATH=1;BC_ENABLE_HISTORY=1;BC_ENABLE_NLS=0;BC_DEBUG_CODE=0;BC_ENABLE_LIBRARY=0;BC_ENABLE_EDITLINE=0;BC_ENABLE_READLINE=0;BUILD_TYPE=N;BC_DEFAULT_BANNER=1;BC_DEFAULT_SIGINT_RESET=0;DC_DEFAULT_SIGINT_RESET=0;BC_DEFAULT_TTY_MODE=1;DC_DEFAULT_TTY_MODE=1;BC_DEFAULT_PROMPT=1;DC_DEFAULT_PROMPT=1;BC_DEFAULT_EXPR_EXIT=1;DC_DEFAULT_EXPR_EXIT=1;_DEBUG;_CONSOLE;%(PreprocessorDefinitions)</PreprocessorDefinitions> + <PreprocessorDefinitions>BC_ENABLED=1;DC_ENABLED=1;BC_ENABLE_EXTRA_MATH=1;BC_ENABLE_HISTORY=1;BC_ENABLE_NLS=0;BC_DEBUG_CODE=0;BC_ENABLE_LIBRARY=0;BC_ENABLE_EDITLINE=0;BC_ENABLE_READLINE=0;BC_ENABLE_OSSFUZZ=0;BUILD_TYPE=N;BC_DEFAULT_BANNER=1;BC_DEFAULT_SIGINT_RESET=0;DC_DEFAULT_SIGINT_RESET=0;BC_DEFAULT_TTY_MODE=1;DC_DEFAULT_TTY_MODE=1;BC_DEFAULT_PROMPT=1;DC_DEFAULT_PROMPT=1;BC_DEFAULT_EXPR_EXIT=1;DC_DEFAULT_EXPR_EXIT=1;BC_DEFAULT_DIGIT_CLAMP=1;DC_DEFAULT_DIGIT_CLAMP=1;_DEBUG;_CONSOLE;%(PreprocessorDefinitions)</PreprocessorDefinitions> <AdditionalIncludeDirectories>..\include</AdditionalIncludeDirectories> <RuntimeLibrary>MultiThreadedDebug</RuntimeLibrary> <ConformanceMode>true</ConformanceMode> @@ -161,10 +164,11 @@ </ItemDefinitionGroup> <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Release|x64'"> <ClCompile> + <AdditionalOptions>/std:c17 /MP $(AdditionalOptions)</AdditionalOptions> <WarningLevel>Level3</WarningLevel> <IntrinsicFunctions>true</IntrinsicFunctions> <SDLCheck>true</SDLCheck> - <PreprocessorDefinitions>BC_ENABLED=1;DC_ENABLED=1;BC_ENABLE_EXTRA_MATH=1;BC_ENABLE_HISTORY=1;BC_ENABLE_NLS=0;BC_DEBUG_CODE=0;BC_ENABLE_LIBRARY=0;BC_ENABLE_EDITLINE=0;BC_ENABLE_READLINE=0;BUILD_TYPE=N;BC_DEFAULT_BANNER=1;BC_DEFAULT_SIGINT_RESET=0;DC_DEFAULT_SIGINT_RESET=0;BC_DEFAULT_TTY_MODE=1;DC_DEFAULT_TTY_MODE=1;BC_DEFAULT_PROMPT=1;DC_DEFAULT_PROMPT=1;BC_DEFAULT_EXPR_EXIT=1;DC_DEFAULT_EXPR_EXIT=1;NDEBUG;_CONSOLE;%(PreprocessorDefinitions)</PreprocessorDefinitions> + <PreprocessorDefinitions>BC_ENABLED=1;DC_ENABLED=1;BC_ENABLE_EXTRA_MATH=1;BC_ENABLE_HISTORY=1;BC_ENABLE_NLS=0;BC_DEBUG_CODE=0;BC_ENABLE_LIBRARY=0;BC_ENABLE_EDITLINE=0;BC_ENABLE_READLINE=0;BC_ENABLE_OSSFUZZ=0;BUILD_TYPE=N;BC_DEFAULT_BANNER=1;BC_DEFAULT_SIGINT_RESET=0;DC_DEFAULT_SIGINT_RESET=0;BC_DEFAULT_TTY_MODE=1;DC_DEFAULT_TTY_MODE=1;BC_DEFAULT_PROMPT=1;DC_DEFAULT_PROMPT=1;BC_DEFAULT_EXPR_EXIT=1;DC_DEFAULT_EXPR_EXIT=1;BC_DEFAULT_DIGIT_CLAMP=1;DC_DEFAULT_DIGIT_CLAMP=1;NDEBUG;_CONSOLE;%(PreprocessorDefinitions)</PreprocessorDefinitions> <AdditionalIncludeDirectories>..\include</AdditionalIncludeDirectories> <RuntimeLibrary>MultiThreaded</RuntimeLibrary> <FunctionLevelLinking>true</FunctionLevelLinking> @@ -206,13 +210,13 @@ <ItemGroup> <CustomBuild Include="..\gen\strgen.c"> <FileType>CppCode</FileType> - <Command Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'">cl.exe /Fo:$(OutDir)strgen.obj /Fe:$(OutDir)strgen.exe %(Identity)</Command> + <Command Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'">cl.exe /I..\include /DBC_ENABLE_LIBRARY=0 /Fo:$(OutDir)strgen.obj /Fe:$(OutDir)strgen.exe %(Identity)</Command> <Outputs Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'">$(OutDir)strgen.exe</Outputs> - <Command Condition="'$(Configuration)|$(Platform)'=='Release|Win32'">cl.exe /Fo:$(OutDir)strgen.obj /Fe:$(OutDir)strgen.exe %(Identity)</Command> + <Command Condition="'$(Configuration)|$(Platform)'=='Release|Win32'">cl.exe /I..\include /DBC_ENABLE_LIBRARY=0 /Fo:$(OutDir)strgen.obj /Fe:$(OutDir)strgen.exe %(Identity)</Command> <Outputs Condition="'$(Configuration)|$(Platform)'=='Release|Win32'">$(OutDir)strgen.exe</Outputs> - <Command Condition="'$(Configuration)|$(Platform)'=='Debug|x64'">cl.exe /Fo:$(OutDir)strgen.obj /Fe:$(OutDir)strgen.exe %(Identity)</Command> + <Command Condition="'$(Configuration)|$(Platform)'=='Debug|x64'">cl.exe /I..\include /DBC_ENABLE_LIBRARY=0 /Fo:$(OutDir)strgen.obj /Fe:$(OutDir)strgen.exe %(Identity)</Command> <Outputs Condition="'$(Configuration)|$(Platform)'=='Debug|x64'">$(OutDir)strgen.exe</Outputs> - <Command Condition="'$(Configuration)|$(Platform)'=='Release|x64'">cl.exe /Fo:$(OutDir)strgen.obj /Fe:$(OutDir)strgen.exe %(Identity)</Command> + <Command Condition="'$(Configuration)|$(Platform)'=='Release|x64'">cl.exe /I..\include /DBC_ENABLE_LIBRARY=0 /Fo:$(OutDir)strgen.obj /Fe:$(OutDir)strgen.exe %(Identity)</Command> <Outputs Condition="'$(Configuration)|$(Platform)'=='Release|x64'">$(OutDir)strgen.exe</Outputs> </CustomBuild> <ClCompile Include="src2\bc_help.c" /> diff --git a/contrib/bc/vs/bcl.vcxproj b/contrib/bc/vs/bcl.vcxproj index a8de10e9f10b..f838cac7cbd1 100644 --- a/contrib/bc/vs/bcl.vcxproj +++ b/contrib/bc/vs/bcl.vcxproj @@ -130,6 +130,7 @@ </PropertyGroup> <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'"> <ClCompile> + <AdditionalOptions>/std:c17 /MP $(AdditionalOptions)</AdditionalOptions> <WarningLevel>Level3</WarningLevel> <SDLCheck>true</SDLCheck> <PreprocessorDefinitions>BC_ENABLED=1;DC_ENABLED=1;BC_ENABLE_EXTRA_MATH=1;BC_ENABLE_HISTORY=0;BC_ENABLE_NLS=0;BC_DEBUG_CODE=0;BC_ENABLE_LIBRARY=1;WIN32;_DEBUG;_CONSOLE;%(PreprocessorDefinitions)</PreprocessorDefinitions> @@ -143,6 +144,7 @@ </ItemDefinitionGroup> <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='ReleaseMD|Win32'"> <ClCompile> + <AdditionalOptions>/std:c17 /MP $(AdditionalOptions)</AdditionalOptions> <WarningLevel>Level3</WarningLevel> <FunctionLevelLinking>true</FunctionLevelLinking> <IntrinsicFunctions>true</IntrinsicFunctions> @@ -160,6 +162,7 @@ </ItemDefinitionGroup> <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='ReleaseMT|Win32'"> <ClCompile> + <AdditionalOptions>/std:c17 /MP $(AdditionalOptions)</AdditionalOptions> <WarningLevel>Level3</WarningLevel> <FunctionLevelLinking>true</FunctionLevelLinking> <IntrinsicFunctions>true</IntrinsicFunctions> @@ -178,6 +181,7 @@ </ItemDefinitionGroup> <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Debug|x64'"> <ClCompile> + <AdditionalOptions>/std:c17 /MP $(AdditionalOptions)</AdditionalOptions> <WarningLevel>Level3</WarningLevel> <SDLCheck>true</SDLCheck> <PreprocessorDefinitions>BC_ENABLED=1;DC_ENABLED=1;BC_ENABLE_EXTRA_MATH=1;BC_ENABLE_HISTORY=0;BC_ENABLE_NLS=0;BC_DEBUG_CODE=0;BC_ENABLE_LIBRARY=1;_DEBUG;_CONSOLE;%(PreprocessorDefinitions)</PreprocessorDefinitions> @@ -191,6 +195,7 @@ </ItemDefinitionGroup> <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='ReleaseMD|x64'"> <ClCompile> + <AdditionalOptions>/std:c17 /MP $(AdditionalOptions)</AdditionalOptions> <WarningLevel>Level3</WarningLevel> <FunctionLevelLinking>true</FunctionLevelLinking> <IntrinsicFunctions>true</IntrinsicFunctions> @@ -208,6 +213,7 @@ </ItemDefinitionGroup> <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='ReleaseMT|x64'"> <ClCompile> + <AdditionalOptions>/std:c17 /MP $(AdditionalOptions)</AdditionalOptions> <WarningLevel>Level3</WarningLevel> <FunctionLevelLinking>true</FunctionLevelLinking> <IntrinsicFunctions>true</IntrinsicFunctions> |