manuals/dc/H.1

0 .\"
2 .\" SPDX-License-Identifier: BSD-2-Clause
3 .\"
4 .\" Copyright (c) 2018-2023 Gavin D. Howard and contributors.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions are met:
8 .\"
9 .\" * Redistributions of source code must retain the above copyright notice,
10 .\"   this list of conditions and the following disclaimer.
11 .\"
12 .\" * Redistributions in binary form must reproduce the above copyright notice,
13 .\"   this list of conditions and the following disclaimer in the documentation
14 .\"   and/or other materials provided with the distribution.
15 .\"
16 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17 .\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
20 .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26 .\" POSSIBILITY OF SUCH DAMAGE.
27 .\"
28 .TH "DC" "1" "February 2023" "Gavin D. Howard" "General Commands Manual"
29 .nh
30 .ad l
31 .SH Name
33 .SH SYNOPSIS
34 \f[B]dc\f[R] [\f[B]-cChiPRvVx\f[R]] [\f[B]--version\f[R]]
35 [\f[B]--help\f[R]] [\f[B]--digit-clamp\f[R]]
36 [\f[B]--no-digit-clamp\f[R]] [\f[B]--interactive\f[R]]
37 [\f[B]--no-prompt\f[R]] [\f[B]--no-read-prompt\f[R]]
38 [\f[B]--extended-register\f[R]] [\f[B]-e\f[R] \f[I]expr\f[R]]
39 [\f[B]--expression\f[R]=\f[I]expr\f[R]\&...]
40 [\f[B]-f\f[R] \f[I]file\f[R]\&...]
41 [\f[B]--file\f[R]=\f[I]file\f[R]\&...]
42 [\f[I]file\f[R]\&...]
43 [\f[B]-I\f[R] \f[I]ibase\f[R]] [\f[B]--ibase\f[R]=\f[I]ibase\f[R]]
44 [\f[B]-O\f[R] \f[I]obase\f[R]] [\f[B]--obase\f[R]=\f[I]obase\f[R]]
45 [\f[B]-S\f[R] \f[I]scale\f[R]] [\f[B]--scale\f[R]=\f[I]scale\f[R]]
46 [\f[B]-E\f[R] \f[I]seed\f[R]] [\f[B]--seed\f[R]=\f[I]seed\f[R]]
47 .SH DESCRIPTION
48 dc(1) is an arbitrary-precision calculator.
50 of computations.
52 results.
53 .PP
55 \f[B]stdin\f[R] (see the \f[B]STDIN\f[R] section).
56 Otherwise, those files are processed, and dc(1) will then exit.
57 .PP
59 \f[B]DC_ENV_ARGS\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section).
60 For example, if a user wants the \f[B]scale\f[R] always set to
61 \f[B]10\f[R], they can set \f[B]DC_ENV_ARGS\f[R] to \f[B]-e 10k\f[R],
62 and this dc(1) will always start with a \f[B]scale\f[R] of \f[B]10\f[R].
63 .SH OPTIONS
64 The following are the options that dc(1) accepts.
65 .TP
66 \f[B]-C\f[R], \f[B]--no-digit-clamp\f[R]
68 \f[B]ibase\f[R] when parsing numbers.
69 .RS
70 .PP
74 significant digit.
75 .PP
76 If this and/or the \f[B]-c\f[R] or \f[B]--digit-clamp\f[R] options are
77 given multiple times, the last one given is used.
78 .PP
79 This option overrides the \f[B]DC_DIGIT_CLAMP\f[R] environment variable
80 (see the \f[B]ENVIRONMENT VARIABLES\f[R] section) and the default, which
81 can be queried with the \f[B]-h\f[R] or \f[B]--help\f[R] options.
82 .PP
83 This is a \f[B]non-portable extension\f[R].
84 .RE
85 .TP
86 \f[B]-c\f[R], \f[B]--digit-clamp\f[R]
88 \f[B]ibase\f[R] when parsing numbers.
89 .RS
90 .PP
95 digit.
96 .PP
97 If this and/or the \f[B]-C\f[R] or \f[B]--no-digit-clamp\f[R] options
98 are given multiple times, the last one given is used.
99 .PP
100 This option overrides the \f[B]DC_DIGIT_CLAMP\f[R] environment variable
101 (see the \f[B]ENVIRONMENT VARIABLES\f[R] section) and the default, which
102 can be queried with the \f[B]-h\f[R] or \f[B]--help\f[R] options.
103 .PP
104 This is a \f[B]non-portable extension\f[R].
105 .RE
106 .TP
107 \f[B]-E\f[R] \f[I]seed\f[R], \f[B]--seed\f[R]=\f[I]seed\f[R]
108 Sets the builtin variable \f[B]seed\f[R] to the value \f[I]seed\f[R]
109 assuming that \f[I]seed\f[R] is in base 10.
110 It is a fatal error if \f[I]seed\f[R] is not a valid number.
111 .RS
112 .PP
113 If multiple instances of this option are given, the last is used.
114 .PP
115 This is a \f[B]non-portable extension\f[R].
116 .RE
117 .TP
118 \f[B]-e\f[R] \f[I]expr\f[R], \f[B]--expression\f[R]=\f[I]expr\f[R]
119 Evaluates \f[I]expr\f[R].
120 If multiple expressions are given, they are evaluated in order.
122 evaluated in the order given.
124 read in and evaluated first.
125 .RS
126 .PP
127 If this option is given on the command-line (i.e., not in
128 \f[B]DC_ENV_ARGS\f[R], see the \f[B]ENVIRONMENT VARIABLES\f[R] section),
130 \f[B]-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to
131 \f[B]-f\f[R] or \f[B]--file\f[R], whether on the command-line or in
132 \f[B]DC_ENV_ARGS\f[R].
133 However, if any other \f[B]-e\f[R], \f[B]--expression\f[R],
134 \f[B]-f\f[R], or \f[B]--file\f[R] arguments are given after
135 \f[B]-f-\f[R] or equivalent is given, dc(1) will give a fatal error and
136 exit.
137 .PP
138 This is a \f[B]non-portable extension\f[R].
139 .RE
140 .TP
141 \f[B]-f\f[R] \f[I]file\f[R], \f[B]--file\f[R]=\f[I]file\f[R]
142 Reads in \f[I]file\f[R] and evaluates it, line by line, as though it
143 were read through \f[B]stdin\f[R].
145 in the order given.
146 .RS
147 .PP
148 If this option is given on the command-line (i.e., not in
149 \f[B]DC_ENV_ARGS\f[R], see the \f[B]ENVIRONMENT VARIABLES\f[R] section),
151 \f[B]-\f[R] (\f[B]stdin\f[R]) was given as an argument at least once to
152 \f[B]-f\f[R] or \f[B]--file\f[R].
153 However, if any other \f[B]-e\f[R], \f[B]--expression\f[R],
154 \f[B]-f\f[R], or \f[B]--file\f[R] arguments are given after
155 \f[B]-f-\f[R] or equivalent is given, dc(1) will give a fatal error and
156 exit.
157 .PP
158 This is a \f[B]non-portable extension\f[R].
159 .RE
160 .TP
161 \f[B]-h\f[R], \f[B]--help\f[R]
162 Prints a usage message and exits.
163 .TP
164 \f[B]-I\f[R] \f[I]ibase\f[R], \f[B]--ibase\f[R]=\f[I]ibase\f[R]
165 Sets the builtin variable \f[B]ibase\f[R] to the value \f[I]ibase\f[R]
166 assuming that \f[I]ibase\f[R] is in base 10.
167 It is a fatal error if \f[I]ibase\f[R] is not a valid number.
168 .RS
169 .PP
170 If multiple instances of this option are given, the last is used.
171 .PP
172 This is a \f[B]non-portable extension\f[R].
173 .RE
174 .TP
175 \f[B]-i\f[R], \f[B]--interactive\f[R]
176 Forces interactive mode.
177 (See the \f[B]INTERACTIVE MODE\f[R] section.)
178 .RS
179 .PP
180 This is a \f[B]non-portable extension\f[R].
181 .RE
182 .TP
183 \f[B]-L\f[R], \f[B]--no-line-length\f[R]
185 newlines.
186 In other words, this option sets \f[B]BC_LINE_LENGTH\f[R] to \f[B]0\f[R]
187 (see the \f[B]ENVIRONMENT VARIABLES\f[R] section).
188 .RS
189 .PP
190 This is a \f[B]non-portable extension\f[R].
191 .RE
192 .TP
193 \f[B]-O\f[R] \f[I]obase\f[R], \f[B]--obase\f[R]=\f[I]obase\f[R]
194 Sets the builtin variable \f[B]obase\f[R] to the value \f[I]obase\f[R]
195 assuming that \f[I]obase\f[R] is in base 10.
196 It is a fatal error if \f[I]obase\f[R] is not a valid number.
197 .RS
198 .PP
199 If multiple instances of this option are given, the last is used.
200 .PP
201 This is a \f[B]non-portable extension\f[R].
202 .RE
203 .TP
204 \f[B]-P\f[R], \f[B]--no-prompt\f[R]
205 Disables the prompt in TTY mode.
206 (The prompt is only enabled in TTY mode.
207 See the \f[B]TTY MODE\f[R] section.)
209 to having them in dc(1).
211 \f[B]DC_ENV_ARGS\f[R].
212 .RS
213 .PP
214 These options override the \f[B]DC_PROMPT\f[R] and \f[B]DC_TTY_MODE\f[R]
215 environment variables (see the \f[B]ENVIRONMENT VARIABLES\f[R] section).
216 .PP
217 This is a \f[B]non-portable extension\f[R].
218 .RE
219 .TP
220 \f[B]-R\f[R], \f[B]--no-read-prompt\f[R]
221 Disables the read prompt in TTY mode.
222 (The read prompt is only enabled in TTY mode.
223 See the \f[B]TTY MODE\f[R] section.)
225 used to having them in dc(1).
227 \f[B]BC_ENV_ARGS\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R] section).
229 prompt for user input.
230 .RS
231 .PP
233 is only used when the \f[B]?\f[R] command is used.
234 .PP
235 These options \f[I]do\f[R] override the \f[B]DC_PROMPT\f[R] and
236 \f[B]DC_TTY_MODE\f[R] environment variables (see the \f[B]ENVIRONMENT
237 VARIABLES\f[R] section), but only for the read prompt.
238 .PP
239 This is a \f[B]non-portable extension\f[R].
240 .RE
241 .TP
242 \f[B]-S\f[R] \f[I]scale\f[R], \f[B]--scale\f[R]=\f[I]scale\f[R]
243 Sets the builtin variable \f[B]scale\f[R] to the value \f[I]scale\f[R]
244 assuming that \f[I]scale\f[R] is in base 10.
245 It is a fatal error if \f[I]scale\f[R] is not a valid number.
246 .RS
247 .PP
248 If multiple instances of this option are given, the last is used.
249 .PP
250 This is a \f[B]non-portable extension\f[R].
251 .RE
252 .TP
253 \f[B]-v\f[R], \f[B]-V\f[R], \f[B]--version\f[R]
254 Print the version information (copyright header) and exits.
255 .TP
256 \f[B]-x\f[R] \f[B]--extended-register\f[R]
257 Enables extended register mode.
258 See the \f[I]Extended Register Mode\f[R] subsection of the
259 \f[B]REGISTERS\f[R] section for more information.
260 .RS
261 .PP
262 This is a \f[B]non-portable extension\f[R].
263 .RE
264 .TP
265 \f[B]-z\f[R], \f[B]--leading-zeroes\f[R]
266 Makes dc(1) print all numbers greater than \f[B]-1\f[R] and less than
267 \f[B]1\f[R], and not equal to \f[B]0\f[R], with a leading zero.
268 .RS
269 .PP
270 This is a \f[B]non-portable extension\f[R].
271 .RE
272 .PP
273 All long options are \f[B]non-portable extensions\f[R].
274 .SH STDIN
276 are given by the \f[B]-f\f[R], \f[B]--file\f[R], \f[B]-e\f[R], or
277 \f[B]--expression\f[R] options, then dc(1) reads from \f[B]stdin\f[R].
278 .PP
279 However, there is a caveat to this.
280 .PP
281 First, \f[B]stdin\f[R] is evaluated a line at a time.
283 ended.
285 balanced before dc(1) parses and executes.
286 .SH STDOUT
287 Any non-error output is written to \f[B]stdout\f[R].
288 In addition, if history (see the \f[B]HISTORY\f[R] section) and the
289 prompt (see the \f[B]TTY MODE\f[R] section) are enabled, both are output
290 to \f[B]stdout\f[R].
291 .PP
292 \f[B]Note\f[R]: Unlike other dc(1) implementations, this dc(1) will
293 issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot
294 write to \f[B]stdout\f[R], so if \f[B]stdout\f[R] is closed, as in
295 \f[B]dc  >&-\f[R], it will quit with an error.
296 This is done so that dc(1) can report problems when \f[B]stdout\f[R] is
297 redirected to a file.
298 .PP
301 redirect \f[B]stdout\f[R] to \f[B]/dev/null\f[R].
302 .SH STDERR
303 Any error output is written to \f[B]stderr\f[R].
304 .PP
305 \f[B]Note\f[R]: Unlike other dc(1) implementations, this dc(1) will
306 issue a fatal error (see the \f[B]EXIT STATUS\f[R] section) if it cannot
307 write to \f[B]stderr\f[R], so if \f[B]stderr\f[R] is closed, as in
308 \f[B]dc  2>&-\f[R], it will quit with an error.
310 \f[B]stderr\f[R] is redirected to a file.
311 .PP
314 redirect \f[B]stderr\f[R] to \f[B]/dev/null\f[R].
315 .SH SYNTAX
317 \f[B]NUMBERS\f[R] section) or a command (see the \f[B]COMMANDS\f[R]
318 section), is processed and executed, in order.
319 Input is processed immediately when entered.
320 .PP
321 \f[B]ibase\f[R] is a register (see the \f[B]REGISTERS\f[R] section) that
322 determines how to interpret constant numbers.
324 input numbers.
325 \f[B]ibase\f[R] is initially \f[B]10\f[R].
326 The max allowable value for \f[B]ibase\f[R] is \f[B]16\f[R].
327 The min allowable value for \f[B]ibase\f[R] is \f[B]2\f[R].
328 The max allowable value for \f[B]ibase\f[R] can be queried in dc(1)
329 programs with the \f[B]T\f[R] command.
330 .PP
331 \f[B]obase\f[R] is a register (see the \f[B]REGISTERS\f[R] section) that
332 determines how to output results.
334 numbers.
335 \f[B]obase\f[R] is initially \f[B]10\f[R].
336 The max allowable value for \f[B]obase\f[R] is \f[B]DC_BASE_MAX\f[R] and
337 can be queried with the \f[B]U\f[R] command.
338 The min allowable value for \f[B]obase\f[R] is \f[B]0\f[R].
339 If \f[B]obase\f[R] is \f[B]0\f[R], values are output in scientific
340 notation, and if \f[B]obase\f[R] is \f[B]1\f[R], values are output in
341 engineering notation.
342 Otherwise, values are output in the specified base.
343 .PP
345 extensions\f[R].
346 .PP
347 The \f[I]scale\f[R] of an expression is the number of digits in the
348 result of the expression right of the decimal point, and \f[B]scale\f[R]
349 is a register (see the \f[B]REGISTERS\f[R] section) that sets the
350 precision of any operations (with exceptions).
351 \f[B]scale\f[R] is initially \f[B]0\f[R].
352 \f[B]scale\f[R] cannot be negative.
353 The max allowable value for \f[B]scale\f[R] can be queried in dc(1)
354 programs with the \f[B]V\f[R] command.
355 .PP
356 \f[B]seed\f[R] is a register containing the current seed for the
357 pseudo-random number generator.
358 If the current value of \f[B]seed\f[R] is queried and stored, then if it
359 is assigned to \f[B]seed\f[R] later, the pseudo-random number generator
361 were generated after the value of \f[B]seed\f[R] was first queried.
362 .PP
363 Multiple values assigned to \f[B]seed\f[R] can produce the same sequence
364 of pseudo-random numbers.
365 Likewise, when a value is assigned to \f[B]seed\f[R], it is not
366 guaranteed that querying \f[B]seed\f[R] immediately after will return
367 the same value.
368 In addition, the value of \f[B]seed\f[R] will change after any call to
369 the \f[B]\[cq]\f[R] command or the \f[B]\[lq]\f[R] command that does not
370 get receive a value of \f[B]0\f[R] or \f[B]1\f[R].
371 The maximum integer returned by the \f[B]\[cq]\f[R] command can be
372 queried with the \f[B]W\f[R] command.
373 .PP
374 \f[B]Note\f[R]: The values returned by the pseudo-random number
375 generator with the \f[B]\[cq]\f[R] and \f[B]\[lq]\f[R] commands are
376 guaranteed to \f[B]NOT\f[R] be cryptographically secure.
377 This is a consequence of using a seeded pseudo-random number generator.
378 However, they \f[I]are\f[R] guaranteed to be reproducible with identical
379 \f[B]seed\f[R] values.
382 \f[I]ESSENTIAL\f[R].
383 In any other case, use a non-seeded pseudo-random number generator.
384 .PP
385 The pseudo-random number generator, \f[B]seed\f[R], and all associated
386 operations are \f[B]non-portable extensions\f[R].
387 .SS Comments
388 Comments go from \f[B]#\f[R] until, and not including, the next newline.
389 This is a \f[B]non-portable extension\f[R].
390 .SH NUMBERS
392 \f[B]F\f[R], and at most \f[B]1\f[R] period for a radix.
393 Numbers can have up to \f[B]DC_NUM_MAX\f[R] digits.
394 Uppercase letters are equal to \f[B]9\f[R] plus their position in the
395 alphabet (i.e., \f[B]A\f[R] equals \f[B]10\f[R], or \f[B]9+1\f[R]).
396 .PP
398 \f[B]ibase\f[R] (i.e., they are greater than or equal to the current
399 value of \f[B]ibase\f[R]), then the behavior depends on the existence of
400 the \f[B]-c\f[R]/\f[B]--digit-clamp\f[R] or
401 \f[B]-C\f[R]/\f[B]--no-digit-clamp\f[R] options (see the
402 \f[B]OPTIONS\f[R] section), the existence and setting of the
403 \f[B]DC_DIGIT_CLAMP\f[R] environment variable (see the \f[B]ENVIRONMENT
404 VARIABLES\f[R] section), or the default, which can be queried with the
405 \f[B]-h\f[R]/\f[B]--help\f[R] option.
406 .PP
408 equal to the current value of \f[B]ibase\f[R] are not changed.
410 \f[B]ibase\f[R] and added into the number.
411 This means that, with an \f[B]ibase\f[R] of \f[B]3\f[R], the number
412 \f[B]AB\f[R] is equal to \f[B]3\[ha]1*A+3\[ha]0*B\f[R], which is
413 \f[B]3\f[R] times \f[B]10\f[R] plus \f[B]11\f[R], or \f[B]41\f[R].
414 .PP
416 to the current value of \f[B]ibase\f[R] are set to the value of the
417 highest valid digit in \f[B]ibase\f[R] before being multiplied by the
418 appropriate power of \f[B]ibase\f[R] and added into the number.
419 This means that, with an \f[B]ibase\f[R] of \f[B]3\f[R], the number
420 \f[B]AB\f[R] is equal to \f[B]3\[ha]1*2+3\[ha]0*2\f[R], which is
421 \f[B]3\f[R] times \f[B]2\f[R] plus \f[B]2\f[R], or \f[B]8\f[R].
422 .PP
423 There is one exception to clamping: single-character numbers (i.e.,
424 \f[B]A\f[R] alone).
426 in the highest possible \f[B]ibase\f[R].
427 This means that \f[B]A\f[R] alone always equals decimal \f[B]10\f[R] and
428 \f[B]Z\f[R] alone always equals decimal \f[B]35\f[R].
431 \f[B]ibase\f[R] (with the \f[B]i\f[R] command) regardless of the current
432 value of \f[B]ibase\f[R].
433 .PP
435 leading zero, i.e., for \f[B]A\f[R], use \f[B]0A\f[R].
436 .PP
437 In addition, dc(1) accepts numbers in scientific notation.
438 These have the form \f[B]<number>e<integer>\f[R].
439 The exponent (the portion after the \f[B]e\f[R]) must be an integer.
440 An example is \f[B]1.89237e9\f[R], which is equal to
441 \f[B]1892370000\f[R].
442 Negative exponents are also allowed, so \f[B]4.2890e_3\f[R] is equal to
443 \f[B]0.0042890\f[R].
444 .PP
445 \f[B]WARNING\f[R]: Both the number and the exponent in scientific
446 notation are interpreted according to the current \f[B]ibase\f[R], but
447 the number is still multiplied by \f[B]10\[ha]exponent\f[R] regardless
448 of the current \f[B]ibase\f[R].
449 For example, if \f[B]ibase\f[R] is \f[B]16\f[R] and dc(1) is given the
450 number string \f[B]FFeA\f[R], the resulting decimal number will be
451 \f[B]2550000000000\f[R], and if dc(1) is given the number string
452 \f[B]10e_4\f[R], the resulting decimal number will be \f[B]0.0016\f[R].
453 .PP
455 extension\f[R].
456 .SH COMMANDS
457 The valid commands are listed below.
458 .SS Printing
459 These commands are used for printing.
460 .PP
462 available for printing numbers.
463 Scientific notation is activated by assigning \f[B]0\f[R] to
464 \f[B]obase\f[R] using \f[B]0o\f[R], and engineering notation is
465 activated by assigning \f[B]1\f[R] to \f[B]obase\f[R] using
466 \f[B]1o\f[R].
467 To deactivate them, just assign a different value to \f[B]obase\f[R].
468 .PP
470 \f[B]non-portable extension\f[R].
471 .TP
472 \f[B]p\f[R]
474 prints a newline after.
475 .RS
476 .PP
477 This does not alter the stack.
478 .RE
479 .TP
480 \f[B]n\f[R]
482 it off of the stack.
483 .TP
484 \f[B]P\f[R]
485 Pops a value off the stack.
486 .RS
487 .PP
489 result is printed as though \f[B]obase\f[R] is \f[B]256\f[R] and each
490 digit is interpreted as an 8-bit ASCII character, making it a byte
491 stream.
492 .PP
493 If the value is a string, it is printed without a trailing newline.
494 .PP
495 This is a \f[B]non-portable extension\f[R].
496 .RE
497 .TP
498 \f[B]f\f[R]
500 without altering anything.
501 .RS
502 .PP
503 Users should use this command when they get lost.
504 .RE
505 .SS Arithmetic
506 These are the commands used for arithmetic.
507 .TP
508 \f[B]+\f[R]
510 pushed onto the stack.
511 The \f[I]scale\f[R] of the result is equal to the max \f[I]scale\f[R] of
512 both operands.
513 .TP
514 \f[B]-\f[R]
516 is pushed onto the stack.
517 The \f[I]scale\f[R] of the result is equal to the max \f[I]scale\f[R] of
518 both operands.
519 .TP
520 \f[B]*\f[R]
522 is pushed onto the stack.
523 If \f[B]a\f[R] is the \f[I]scale\f[R] of the first expression and
524 \f[B]b\f[R] is the \f[I]scale\f[R] of the second expression, the
525 \f[I]scale\f[R] of the result is equal to
526 \f[B]min(a+b,max(scale,a,b))\f[R] where \f[B]min()\f[R] and
527 \f[B]max()\f[R] return the obvious values.
528 .TP
529 \f[B]/\f[R]
531 pushed onto the stack.
532 The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R].
533 .RS
534 .PP
535 The first value popped off of the stack must be non-zero.
536 .RE
537 .TP
538 \f[B]%\f[R]
540 is pushed onto the stack.
541 .RS
542 .PP
543 Remaindering is equivalent to 1) Computing \f[B]a/b\f[R] to current
544 \f[B]scale\f[R], and 2) Using the result of step 1 to calculate
545 \f[B]a-(a/b)*b\f[R] to \f[I]scale\f[R]
546 \f[B]max(scale+scale(b),scale(a))\f[R].
547 .PP
548 The first value popped off of the stack must be non-zero.
549 .RE
550 .TP
551 \f[B]\[ti]\f[R]
554 stack.
555 This is equivalent to \f[B]x y / x y %\f[R] except that \f[B]x\f[R] and
556 \f[B]y\f[R] are only evaluated once.
557 .RS
558 .PP
559 The first value popped off of the stack must be non-zero.
560 .PP
561 This is a \f[B]non-portable extension\f[R].
562 .RE
563 .TP
564 \f[B]\[ha]\f[R]
566 power of the first, and the result is pushed onto the stack.
567 The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R].
568 .RS
569 .PP
572 non-zero.
573 .RE
574 .TP
575 \f[B]v\f[R]
577 the result is pushed onto the stack.
578 The \f[I]scale\f[R] of the result is equal to \f[B]scale\f[R].
579 .RS
580 .PP
581 The value popped off of the stack must be non-negative.
582 .RE
583 .TP
584 \f[B]_\f[R]
585 If this command \f[I]immediately\f[R] precedes a number (i.e., no spaces
586 or other commands), then that number is input as a negative number.
587 .RS
588 .PP
590 is negated and pushed onto the stack.
591 This behavior without a number is a \f[B]non-portable extension\f[R].
592 .RE
593 .TP
594 \f[B]b\f[R]
596 back onto the stack.
597 Otherwise, its absolute value is pushed onto the stack.
598 .RS
599 .PP
600 This is a \f[B]non-portable extension\f[R].
601 .RE
602 .TP
603 \f[B]|\f[R]
605 is computed, and the result is pushed onto the stack.
606 .RS
607 .PP
609 integer and non-zero.
611 and non-negative.
612 The third value popped is the base and must be an integer.
613 .PP
614 This is a \f[B]non-portable extension\f[R].
615 .RE
616 .TP
617 \f[B]$\f[R]
619 truncated and pushed onto the stack.
620 .RS
621 .PP
622 This is a \f[B]non-portable extension\f[R].
623 .RE
624 .TP
625 \f[B]\[at]\f[R]
628 extension.
629 .RS
630 .PP
632 non-negative.
633 .PP
634 This is a \f[B]non-portable extension\f[R].
635 .RE
636 .TP
637 \f[B]H\f[R]
639 left (radix shifted right) to the value of the first.
640 .RS
641 .PP
643 non-negative.
644 .PP
645 This is a \f[B]non-portable extension\f[R].
646 .RE
647 .TP
648 \f[B]h\f[R]
650 right (radix shifted left) to the value of the first.
651 .RS
652 .PP
654 non-negative.
655 .PP
656 This is a \f[B]non-portable extension\f[R].
657 .RE
658 .TP
659 \f[B]G\f[R]
661 \f[B]1\f[R] is pushed if they are equal, or \f[B]0\f[R] otherwise.
662 .RS
663 .PP
664 This is a \f[B]non-portable extension\f[R].
665 .RE
666 .TP
667 \f[B]N\f[R]
668 The top value is popped off of the stack, and if it a \f[B]0\f[R], a
669 \f[B]1\f[R] is pushed; otherwise, a \f[B]0\f[R] is pushed.
670 .RS
671 .PP
672 This is a \f[B]non-portable extension\f[R].
673 .RE
674 .TP
675 \f[B](\f[R]
677 \f[B]1\f[R] is pushed if the first is less than the second, or
678 \f[B]0\f[R] otherwise.
679 .RS
680 .PP
681 This is a \f[B]non-portable extension\f[R].
682 .RE
683 .TP
684 \f[B]{\f[R]
686 \f[B]1\f[R] is pushed if the first is less than or equal to the second,
687 or \f[B]0\f[R] otherwise.
688 .RS
689 .PP
690 This is a \f[B]non-portable extension\f[R].
691 .RE
692 .TP
693 \f[B])\f[R]
695 \f[B]1\f[R] is pushed if the first is greater than the second, or
696 \f[B]0\f[R] otherwise.
697 .RS
698 .PP
699 This is a \f[B]non-portable extension\f[R].
700 .RE
701 .TP
702 \f[B]}\f[R]
704 \f[B]1\f[R] is pushed if the first is greater than or equal to the
705 second, or \f[B]0\f[R] otherwise.
706 .RS
707 .PP
708 This is a \f[B]non-portable extension\f[R].
709 .RE
710 .TP
711 \f[B]M\f[R]
712 The top two values are popped off of the stack.
713 If they are both non-zero, a \f[B]1\f[R] is pushed onto the stack.
714 If either of them is zero, or both of them are, then a \f[B]0\f[R] is
715 pushed onto the stack.
716 .RS
717 .PP
718 This is like the \f[B]&&\f[R] operator in bc(1), and it is \f[I]not\f[R]
719 a short-circuit operator.
720 .PP
721 This is a \f[B]non-portable extension\f[R].
722 .RE
723 .TP
724 \f[B]m\f[R]
725 The top two values are popped off of the stack.
726 If at least one of them is non-zero, a \f[B]1\f[R] is pushed onto the
727 stack.
728 If both of them are zero, then a \f[B]0\f[R] is pushed onto the stack.
729 .RS
730 .PP
731 This is like the \f[B]||\f[R] operator in bc(1), and it is \f[I]not\f[R]
732 a short-circuit operator.
733 .PP
734 This is a \f[B]non-portable extension\f[R].
735 .RE
736 .SS Pseudo-Random Number Generator
737 dc(1) has a built-in pseudo-random number generator.
738 These commands query the pseudo-random number generator.
739 (See Parameters for more information about the \f[B]seed\f[R] value that
740 controls the pseudo-random number generator.)
741 .PP
742 The pseudo-random number generator is guaranteed to \f[B]NOT\f[R] be
743 cryptographically secure.
744 .TP
745 \f[B]\[cq]\f[R]
746 Generates an integer between 0 and \f[B]DC_RAND_MAX\f[R], inclusive (see
747 the \f[B]LIMITS\f[R] section).
748 .RS
749 .PP
751 limitations of the pseudo-random number generator.
752 .PP
753 This is a \f[B]non-portable extension\f[R].
754 .RE
755 .TP
756 \f[B]\[lq]\f[R]
757 Pops a value off of the stack, which is used as an \f[B]exclusive\f[R]
758 upper bound on the integer that will be generated.
760 dc(1) resets (see the \f[B]RESET\f[R] section) while \f[B]seed\f[R]
761 remains unchanged.
762 If the bound is larger than \f[B]DC_RAND_MAX\f[R], the higher bound is
764 by appropriate powers of \f[B]DC_RAND_MAX+1\f[R], and adding them
765 together.
767 unbounded.
768 Using this command will change the value of \f[B]seed\f[R], unless the
769 operand is \f[B]0\f[R] or \f[B]1\f[R].
770 In that case, \f[B]0\f[R] is pushed onto the stack, and \f[B]seed\f[R]
771 is \f[I]not\f[R] changed.
772 .RS
773 .PP
775 limitations of the pseudo-random number generator.
776 .PP
777 This is a \f[B]non-portable extension\f[R].
778 .RE
779 .SS Stack Control
780 These commands control the stack.
781 .TP
782 \f[B]c\f[R]
783 Removes all items from (\[lq]clears\[rq]) the stack.
784 .TP
785 \f[B]d\f[R]
787 the copy onto the stack.
788 .TP
789 \f[B]r\f[R]
790 Swaps (\[lq]reverses\[rq]) the two top items on the stack.
791 .TP
792 \f[B]R\f[R]
793 Pops (\[lq]removes\[rq]) the top value from the stack.
794 .SS Register Control
795 These commands control registers (see the \f[B]REGISTERS\f[R] section).
796 .TP
797 \f[B]s\f[R]\f[I]r\f[R]
799 \f[I]r\f[R].
800 .TP
801 \f[B]l\f[R]\f[I]r\f[R]
802 Copies the value in register \f[I]r\f[R] and pushes it onto the stack.
803 This does not alter the contents of \f[I]r\f[R].
804 .TP
805 \f[B]S\f[R]\f[I]r\f[R]
807 stack of register \f[I]r\f[R].
808 The previous value of the register becomes inaccessible.
809 .TP
810 \f[B]L\f[R]\f[I]r\f[R]
811 Pops the value off the top of the stack for register \f[I]r\f[R] and
812 push it onto the main stack.
813 The previous value in the stack for register \f[I]r\f[R], if any, is now
814 accessible via the \f[B]l\f[R]\f[I]r\f[R] command.
815 .SS Parameters
816 These commands control the values of \f[B]ibase\f[R], \f[B]obase\f[R],
817 \f[B]scale\f[R], and \f[B]seed\f[R].
818 Also see the \f[B]SYNTAX\f[R] section.
819 .TP
820 \f[B]i\f[R]
822 \f[B]ibase\f[R], which must be between \f[B]2\f[R] and \f[B]16\f[R],
823 inclusive.
824 .RS
825 .PP
826 If the value on top of the stack has any \f[I]scale\f[R], the
827 \f[I]scale\f[R] is ignored.
828 .RE
829 .TP
830 \f[B]o\f[R]
832 \f[B]obase\f[R], which must be between \f[B]0\f[R] and
833 \f[B]DC_BASE_MAX\f[R], inclusive (see the \f[B]LIMITS\f[R] section and
834 the \f[B]NUMBERS\f[R] section).
835 .RS
836 .PP
837 If the value on top of the stack has any \f[I]scale\f[R], the
838 \f[I]scale\f[R] is ignored.
839 .RE
840 .TP
841 \f[B]k\f[R]
843 \f[B]scale\f[R], which must be non-negative.
844 .RS
845 .PP
846 If the value on top of the stack has any \f[I]scale\f[R], the
847 \f[I]scale\f[R] is ignored.
848 .RE
849 .TP
850 \f[B]j\f[R]
852 \f[B]seed\f[R].
853 The meaning of \f[B]seed\f[R] is dependent on the current pseudo-random
855 versions.
856 .RS
857 .PP
858 The \f[I]scale\f[R] and sign of the value may be significant.
859 .PP
860 If a previously used \f[B]seed\f[R] value is used again, the
862 sequence of pseudo-random numbers as it did when the \f[B]seed\f[R]
863 value was previously used.
864 .PP
865 The exact value assigned to \f[B]seed\f[R] is not guaranteed to be
866 returned if the \f[B]J\f[R] command is used.
867 However, if \f[B]seed\f[R] \f[I]does\f[R] return a different value, both
868 values, when assigned to \f[B]seed\f[R], are guaranteed to produce the
869 same sequence of pseudo-random numbers.
870 This means that certain values assigned to \f[B]seed\f[R] will not
871 produce unique sequences of pseudo-random numbers.
872 .PP
874 or \f[I]scale\f[R] of the value that can be assigned to \f[B]seed\f[R].
875 .PP
876 This is a \f[B]non-portable extension\f[R].
877 .RE
878 .TP
879 \f[B]I\f[R]
880 Pushes the current value of \f[B]ibase\f[R] onto the main stack.
881 .TP
882 \f[B]O\f[R]
883 Pushes the current value of \f[B]obase\f[R] onto the main stack.
884 .TP
885 \f[B]K\f[R]
886 Pushes the current value of \f[B]scale\f[R] onto the main stack.
887 .TP
888 \f[B]J\f[R]
889 Pushes the current value of \f[B]seed\f[R] onto the main stack.
890 .RS
891 .PP
892 This is a \f[B]non-portable extension\f[R].
893 .RE
894 .TP
895 \f[B]T\f[R]
896 Pushes the maximum allowable value of \f[B]ibase\f[R] onto the main
897 stack.
898 .RS
899 .PP
900 This is a \f[B]non-portable extension\f[R].
901 .RE
902 .TP
903 \f[B]U\f[R]
904 Pushes the maximum allowable value of \f[B]obase\f[R] onto the main
905 stack.
906 .RS
907 .PP
908 This is a \f[B]non-portable extension\f[R].
909 .RE
910 .TP
911 \f[B]V\f[R]
912 Pushes the maximum allowable value of \f[B]scale\f[R] onto the main
913 stack.
914 .RS
915 .PP
916 This is a \f[B]non-portable extension\f[R].
917 .RE
918 .TP
919 \f[B]W\f[R]
921 \f[B]\[cq]\f[R] pseudo-random number generator command.
922 .RS
923 .PP
924 This is a \f[B]non-portable extension\f[R].
925 .RE
926 .SS Strings
927 The following commands control strings.
928 .PP
930 \f[B]REGISTERS\f[R] section) can hold both strings and numbers.
932 number.
933 .PP
935 error if given a string, other commands accept strings.
936 .PP
937 Strings can also be executed as macros.
938 For example, if the string \f[B][1pR]\f[R] is executed as a macro, then
939 the code \f[B]1pR\f[R] is executed, meaning that the \f[B]1\f[R] will be
940 printed with a newline after and then popped from the stack.
941 .TP
942 \f[B][\f[R]\f[I]characters\f[R]\f[B]]\f[R]
943 Makes a string containing \f[I]characters\f[R] and pushes it onto the
944 stack.
945 .RS
946 .PP
947 If there are brackets (\f[B][\f[R] and \f[B]]\f[R]) in the string, then
948 they must be balanced.
949 Unbalanced brackets can be escaped using a backslash (\f[B]\[rs]\f[R])
950 character.
951 .PP
954 (first) backslash is not.
955 .RE
956 .TP
957 \f[B]a\f[R]
958 The value on top of the stack is popped.
959 .RS
960 .PP
961 If it is a number, it is truncated and its absolute value is taken.
962 The result mod \f[B]256\f[R] is calculated.
963 If that result is \f[B]0\f[R], push an empty string; otherwise, push a
965 interpreted as an ASCII character.
966 .PP
967 If it is a string, then a new string is made.
968 If the original string is empty, the new string is empty.
970 create the new string as a one-character string.
971 The new string is then pushed onto the stack.
972 .PP
973 This is a \f[B]non-portable extension\f[R].
974 .RE
975 .TP
976 \f[B]x\f[R]
977 Pops a value off of the top of the stack.
978 .RS
979 .PP
980 If it is a number, it is pushed back onto the stack.
981 .PP
982 If it is a string, it is executed as a macro.
983 .PP
985 command or by the conditional execution commands below.
986 .RE
987 .TP
988 \f[B]>\f[R]\f[I]r\f[R]
989 Pops two values off of the stack that must be numbers and compares them.
991 register \f[I]r\f[R] are executed.
992 .RS
993 .PP
994 For example, \f[B]0 1>a\f[R] will execute the contents of register
995 \f[B]a\f[R], and \f[B]1 0>a\f[R] will not.
996 .PP
998 error and reset (see the \f[B]RESET\f[R] section).
999 .RE
1000 .TP
1001 \f[B]>\f[R]\f[I]r\f[R]\f[B]e\f[R]\f[I]s\f[R]
1002 Like the above, but will execute register \f[I]s\f[R] if the comparison
1003 fails.
1004 .RS
1005 .PP
1007 error and reset (see the \f[B]RESET\f[R] section).
1008 .PP
1009 This is a \f[B]non-portable extension\f[R].
1010 .RE
1011 .TP
1012 \f[B]!>\f[R]\f[I]r\f[R]
1013 Pops two values off of the stack that must be numbers and compares them.
1015 to), then the contents of register \f[I]r\f[R] are executed.
1016 .RS
1017 .PP
1019 error and reset (see the \f[B]RESET\f[R] section).
1020 .RE
1021 .TP
1022 \f[B]!>\f[R]\f[I]r\f[R]\f[B]e\f[R]\f[I]s\f[R]
1023 Like the above, but will execute register \f[I]s\f[R] if the comparison
1024 fails.
1025 .RS
1026 .PP
1028 error and reset (see the \f[B]RESET\f[R] section).
1029 .PP
1030 This is a \f[B]non-portable extension\f[R].
1031 .RE
1032 .TP
1033 \f[B]<\f[R]\f[I]r\f[R]
1034 Pops two values off of the stack that must be numbers and compares them.
1036 register \f[I]r\f[R] are executed.
1037 .RS
1038 .PP
1040 error and reset (see the \f[B]RESET\f[R] section).
1041 .RE
1042 .TP
1043 \f[B]<\f[R]\f[I]r\f[R]\f[B]e\f[R]\f[I]s\f[R]
1044 Like the above, but will execute register \f[I]s\f[R] if the comparison
1045 fails.
1046 .RS
1047 .PP
1049 error and reset (see the \f[B]RESET\f[R] section).
1050 .PP
1051 This is a \f[B]non-portable extension\f[R].
1052 .RE
1053 .TP
1054 \f[B]!<\f[R]\f[I]r\f[R]
1055 Pops two values off of the stack that must be numbers and compares them.
1057 to), then the contents of register \f[I]r\f[R] are executed.
1058 .RS
1059 .PP
1061 error and reset (see the \f[B]RESET\f[R] section).
1062 .RE
1063 .TP
1064 \f[B]!<\f[R]\f[I]r\f[R]\f[B]e\f[R]\f[I]s\f[R]
1065 Like the above, but will execute register \f[I]s\f[R] if the comparison
1066 fails.
1067 .RS
1068 .PP
1070 error and reset (see the \f[B]RESET\f[R] section).
1071 .PP
1072 This is a \f[B]non-portable extension\f[R].
1073 .RE
1074 .TP
1075 \f[B]=\f[R]\f[I]r\f[R]
1076 Pops two values off of the stack that must be numbers and compares them.
1078 \f[I]r\f[R] are executed.
1079 .RS
1080 .PP
1082 error and reset (see the \f[B]RESET\f[R] section).
1083 .RE
1084 .TP
1085 \f[B]=\f[R]\f[I]r\f[R]\f[B]e\f[R]\f[I]s\f[R]
1086 Like the above, but will execute register \f[I]s\f[R] if the comparison
1087 fails.
1088 .RS
1089 .PP
1091 error and reset (see the \f[B]RESET\f[R] section).
1092 .PP
1093 This is a \f[B]non-portable extension\f[R].
1094 .RE
1095 .TP
1096 \f[B]!=\f[R]\f[I]r\f[R]
1097 Pops two values off of the stack that must be numbers and compares them.
1099 register \f[I]r\f[R] are executed.
1100 .RS
1101 .PP
1103 error and reset (see the \f[B]RESET\f[R] section).
1104 .RE
1105 .TP
1106 \f[B]!=\f[R]\f[I]r\f[R]\f[B]e\f[R]\f[I]s\f[R]
1107 Like the above, but will execute register \f[I]s\f[R] if the comparison
1108 fails.
1109 .RS
1110 .PP
1112 error and reset (see the \f[B]RESET\f[R] section).
1113 .PP
1114 This is a \f[B]non-portable extension\f[R].
1115 .RE
1116 .TP
1117 \f[B]?\f[R]
1118 Reads a line from the \f[B]stdin\f[R] and executes it.
1119 This is to allow macros to request input from users.
1120 .TP
1121 \f[B]q\f[R]
1123 the execution of the macro that executed it.
1124 If there are no macros, or only one macro executing, dc(1) exits.
1125 .TP
1126 \f[B]Q\f[R]
1128 number of macro executions to pop off of the execution stack.
1130 macros, dc(1) exits.
1131 .TP
1132 \f[B],\f[R]
1133 Pushes the depth of the execution stack onto the stack.
1134 The execution stack is the stack of string executions.
1136 to make dc(1) exit with the \f[B]Q\f[R] command, so the sequence
1137 \f[B],Q\f[R] will make dc(1) exit.
1138 .RS
1139 .PP
1140 This is a \f[B]non-portable extension\f[R].
1141 .RE
1142 .SS Status
1143 These commands query status of the stack or its top value.
1144 .TP
1145 \f[B]Z\f[R]
1146 Pops a value off of the stack.
1147 .RS
1148 .PP
1150 it has and pushes the result.
1151 It will push \f[B]1\f[R] if the argument is \f[B]0\f[R] with no decimal
1152 places.
1153 .PP
1154 If it is a string, pushes the number of characters the string has.
1155 .RE
1156 .TP
1157 \f[B]X\f[R]
1158 Pops a value off of the stack.
1159 .RS
1160 .PP
1161 If it is a number, pushes the \f[I]scale\f[R] of the value onto the
1162 stack.
1163 .PP
1164 If it is a string, pushes \f[B]0\f[R].
1165 .RE
1166 .TP
1167 \f[B]u\f[R]
1168 Pops one value off of the stack.
1169 If the value is a number, this pushes \f[B]1\f[R] onto the stack.
1170 Otherwise (if it is a string), it pushes \f[B]0\f[R].
1171 .RS
1172 .PP
1173 This is a \f[B]non-portable extension\f[R].
1174 .RE
1175 .TP
1176 \f[B]t\f[R]
1177 Pops one value off of the stack.
1178 If the value is a string, this pushes \f[B]1\f[R] onto the stack.
1179 Otherwise (if it is a number), it pushes \f[B]0\f[R].
1180 .RS
1181 .PP
1182 This is a \f[B]non-portable extension\f[R].
1183 .RE
1184 .TP
1185 \f[B]z\f[R]
1187 onto the stack.
1188 .TP
1189 \f[B]y\f[R]\f[I]r\f[R]
1190 Pushes the current stack depth of the register \f[I]r\f[R] onto the main
1191 stack.
1192 .RS
1193 .PP
1194 Because each register has a depth of \f[B]1\f[R] (with the value
1195 \f[B]0\f[R] in the top item) when dc(1) starts, dc(1) requires that each
1197 an error and reset otherwise (see the \f[B]RESET\f[R] section).
1198 This means that this command will never push \f[B]0\f[R].
1199 .PP
1200 This is a \f[B]non-portable extension\f[R].
1201 .RE
1202 .SS Arrays
1203 These commands manipulate arrays.
1204 .TP
1205 \f[B]:\f[R]\f[I]r\f[R]
1206 Pops the top two values off of the stack.
1207 The second value will be stored in the array \f[I]r\f[R] (see the
1208 \f[B]REGISTERS\f[R] section), indexed by the first value.
1209 .TP
1210 \f[B];\f[R]\f[I]r\f[R]
1212 array \f[I]r\f[R].
1213 The selected value is then pushed onto the stack.
1214 .TP
1215 \f[B]Y\f[R]\f[I]r\f[R]
1216 Pushes the length of the array \f[I]r\f[R] onto the stack.
1217 .RS
1218 .PP
1219 This is a \f[B]non-portable extension\f[R].
1220 .RE
1221 .SS Global Settings
1222 These commands retrieve global settings.
1224 and all of them begin with the letter \f[B]g\f[R].
1225 Only the characters below are allowed after the character \f[B]g\f[R];
1226 any other character produces a parse error (see the \f[B]ERRORS\f[R]
1227 section).
1228 .TP
1229 \f[B]gl\f[R]
1230 Pushes the line length set by \f[B]DC_LINE_LENGTH\f[R] (see the
1231 \f[B]ENVIRONMENT VARIABLES\f[R] section) onto the stack.
1232 .TP
1233 \f[B]gx\f[R]
1234 Pushes \f[B]1\f[R] onto the stack if extended register mode is on,
1235 \f[B]0\f[R] otherwise.
1236 See the \f[I]Extended Register Mode\f[R] subsection of the
1237 \f[B]REGISTERS\f[R] section for more information.
1238 .TP
1239 \f[B]gz\f[R]
1240 Pushes \f[B]0\f[R] onto the stack if the leading zero setting has not
1241 been enabled with the \f[B]-z\f[R] or \f[B]--leading-zeroes\f[R] options
1242 (see the \f[B]OPTIONS\f[R] section), non-zero otherwise.
1243 .SH REGISTERS
1244 Registers are names that can store strings, numbers, and arrays.
1245 (Number/string registers do not interfere with array registers.)
1246 .PP
1248 the top of the stack for the register.
1249 All registers, when first referenced, have one value (\f[B]0\f[R]) in
1251 of the register stack.
1252 .PP
1254 character that follows any command that needs a register name.
1255 The only exceptions are: a newline (\f[B]`\[rs]n'\f[R]) and a left
1256 bracket (\f[B]`['\f[R]); it is a parse error for a newline or a left
1257 bracket to be used as a register name.
1258 .SS Extended Register Mode
1260 unlimited amounts of registers, if extended register mode is enabled.
1261 .PP
1262 If extended register mode is enabled (\f[B]-x\f[R] or
1263 \f[B]--extended-register\f[R] command-line arguments are given), then
1264 normal single character registers are used \f[I]unless\f[R] the
1266 a space (according to \f[B]isspace()\f[R]) and not a newline
1267 (\f[B]`\[rs]n'\f[R]).
1268 .PP
1270 \f[B][a-z][a-z0-9_]*\f[R] (like bc(1) identifiers), and it is a parse
1271 error if the next non-space characters do not match that regex.
1272 .SH RESET
1274 handler for, it resets.
1275 This means that several things happen.
1276 .PP
1278 stack.
1279 The behavior is not unlike that of exceptions in programming languages.
1281 (after all macros returned) is skipped.
1282 .PP
1284 executed.
1286 (see the \f[B]EXIT STATUS\f[R] section), it asks for more input;
1287 otherwise, it exits with the appropriate return code.
1288 .SH PERFORMANCE
1289 Most dc(1) implementations use \f[B]char\f[R] types to calculate the
1290 value of \f[B]1\f[R] decimal digit at a time, but that can be slow.
1291 This dc(1) does something different.
1292 .PP
1293 It uses large integers to calculate more than \f[B]1\f[R] decimal digit
1294 at a time.
1295 If built in a environment where \f[B]DC_LONG_BIT\f[R] (see the
1296 \f[B]LIMITS\f[R] section) is \f[B]64\f[R], then each integer has
1297 \f[B]9\f[R] decimal digits.
1298 If built in an environment where \f[B]DC_LONG_BIT\f[R] is \f[B]32\f[R]
1299 then each integer has \f[B]4\f[R] decimal digits.
1301 \f[B]DC_BASE_DIGS\f[R].
1302 .PP
1304 checking.
1305 This integer type depends on the value of \f[B]DC_LONG_BIT\f[R], but is
1306 always at least twice as large as the integer type used to store digits.
1307 .SH LIMITS
1309 .TP
1310 \f[B]DC_LONG_BIT\f[R]
1311 The number of bits in the \f[B]long\f[R] type in the environment where
1312 dc(1) was built.
1314 integer (see the \f[B]PERFORMANCE\f[R] section).
1315 .TP
1316 \f[B]DC_BASE_DIGS\f[R]
1318 \f[B]PERFORMANCE\f[R] section).
1319 Depends on \f[B]DC_LONG_BIT\f[R].
1320 .TP
1321 \f[B]DC_BASE_POW\f[R]
1323 \f[B]DC_BASE_DIGS\f[R]) plus \f[B]1\f[R].
1324 Depends on \f[B]DC_BASE_DIGS\f[R].
1325 .TP
1326 \f[B]DC_OVERFLOW_MAX\f[R]
1327 The max number that the overflow type (see the \f[B]PERFORMANCE\f[R]
1328 section) can hold.
1329 Depends on \f[B]DC_LONG_BIT\f[R].
1330 .TP
1331 \f[B]DC_BASE_MAX\f[R]
1332 The maximum output base.
1333 Set at \f[B]DC_BASE_POW\f[R].
1334 .TP
1335 \f[B]DC_DIM_MAX\f[R]
1336 The maximum size of arrays.
1337 Set at \f[B]SIZE_MAX-1\f[R].
1338 .TP
1339 \f[B]DC_SCALE_MAX\f[R]
1340 The maximum \f[B]scale\f[R].
1341 Set at \f[B]DC_OVERFLOW_MAX-1\f[R].
1342 .TP
1343 \f[B]DC_STRING_MAX\f[R]
1344 The maximum length of strings.
1345 Set at \f[B]DC_OVERFLOW_MAX-1\f[R].
1346 .TP
1347 \f[B]DC_NAME_MAX\f[R]
1348 The maximum length of identifiers.
1349 Set at \f[B]DC_OVERFLOW_MAX-1\f[R].
1350 .TP
1351 \f[B]DC_NUM_MAX\f[R]
1353 digits after the decimal point.
1354 Set at \f[B]DC_OVERFLOW_MAX-1\f[R].
1355 .TP
1356 \f[B]DC_RAND_MAX\f[R]
1357 The maximum integer (inclusive) returned by the \f[B]\[cq]\f[R] command,
1358 if dc(1).
1359 Set at \f[B]2\[ha]DC_LONG_BIT-1\f[R].
1360 .TP
1362 The maximum allowable exponent (positive or negative).
1363 Set at \f[B]DC_OVERFLOW_MAX\f[R].
1364 .TP
1366 The maximum number of vars/arrays.
1367 Set at \f[B]SIZE_MAX-1\f[R].
1368 .PP
1371 at which they become a problem.
1372 In fact, memory should be exhausted before these limits should be hit.
1373 .SH ENVIRONMENT VARIABLES
1374 As \f[B]non-portable extensions\f[R], dc(1) recognizes the following
1376 .TP
1377 \f[B]DC_ENV_ARGS\f[R]
1378 This is another way to give command-line arguments to dc(1).
1379 They should be in the same format as all other command-line arguments.
1381 \f[B]DC_ENV_ARGS\f[R] will be processed before arguments and files given
1382 on the command-line.
1384 files to be used at every invocation.
1386 functions that the user might want every time dc(1) runs.
1387 Another use would be to use the \f[B]-e\f[R] option to set
1388 \f[B]scale\f[R] to a value other than \f[B]0\f[R].
1389 .RS
1390 .PP
1391 The code that parses \f[B]DC_ENV_ARGS\f[R] will correctly handle quoted
1392 arguments, but it does not understand escape sequences.
1393 For example, the string \f[B]\[lq]/home/gavin/some dc file.dc\[rq]\f[R]
1395 \[dq]dc\[dq] file.dc\[rq]\f[R] will include the backslashes.
1396 .PP
1397 The quote parsing will handle either kind of quotes, \f[B]\[cq]\f[R] or
1398 \f[B]\[lq]\f[R].
1401 `dc' file.dc\[rq]\f[R], and vice versa if you have a file with double
1402 quotes.
1404 \f[B]DC_ENV_ARGS\f[R] is not supported due to the complexity of the
1406 the parsing is done by the shell.
1407 .RE
1408 .TP
1409 \f[B]DC_LINE_LENGTH\f[R]
1411 greater than \f[B]1\f[R] and is less than \f[B]UINT16_MAX\f[R]
1412 (\f[B]2\[ha]16-1\f[R]), dc(1) will output lines to that length,
1413 including the backslash newline combo.
1414 The default line length is \f[B]70\f[R].
1415 .RS
1416 .PP
1417 The special value of \f[B]0\f[R] will disable line length checking and
1419 newlines.
1420 .RE
1421 .TP
1422 \f[B]DC_SIGINT_RESET\f[R]
1423 If dc(1) is not in interactive mode (see the \f[B]INTERACTIVE MODE\f[R]
1425 exits on \f[B]SIGINT\f[R] when not in interactive mode.
1426 .RS
1427 .PP
1430 reset on \f[B]SIGINT\f[R], rather than exit, and zero makes dc(1) exit.
1431 If this environment variable exists and is \f[I]not\f[R] an integer,
1432 then dc(1) will exit on \f[B]SIGINT\f[R].
1433 .PP
1435 with the \f[B]-h\f[R] or \f[B]--help\f[R] options.
1436 .RE
1437 .TP
1438 \f[B]DC_TTY_MODE\f[R]
1439 If TTY mode is \f[I]not\f[R] available (see the \f[B]TTY MODE\f[R]
1440 section), then this environment variable has no effect.
1441 .RS
1442 .PP
1445 TTY mode, and zero makes dc(1) not use TTY mode.
1446 .PP
1448 with the \f[B]-h\f[R] or \f[B]--help\f[R] options.
1449 .RE
1450 .TP
1451 \f[B]DC_PROMPT\f[R]
1452 If TTY mode is \f[I]not\f[R] available (see the \f[B]TTY MODE\f[R]
1453 section), then this environment variable has no effect.
1454 .RS
1455 .PP
1458 prompt, and zero or a non-integer makes dc(1) not use a prompt.
1459 If this environment variable does not exist and \f[B]DC_TTY_MODE\f[R]
1460 does, then the value of the \f[B]DC_TTY_MODE\f[R] environment variable
1461 is used.
1462 .PP
1463 This environment variable and the \f[B]DC_TTY_MODE\f[R] environment
1465 \f[B]-h\f[R] or \f[B]--help\f[R] options.
1466 .RE
1467 .TP
1468 \f[B]DC_EXPR_EXIT\f[R]
1470 with \f[B]-e\f[R], \f[B]--expression\f[R], \f[B]-f\f[R], or
1471 \f[B]--file\f[R], then if this environment variable exists and contains
1473 expressions and expression files, and a zero value makes dc(1) not exit.
1474 .RS
1475 .PP
1477 with the \f[B]-h\f[R] or \f[B]--help\f[R] options.
1478 .RE
1479 .TP
1480 \f[B]DC_DIGIT_CLAMP\f[R]
1483 greater than or equal to the current \f[B]ibase\f[R] so that all such
1484 digits are considered equal to the \f[B]ibase\f[R] minus 1, and a zero
1486 their value, which is multiplied by the power of the \f[B]ibase\f[R].
1487 .RS
1488 .PP
1490 (see the \f[B]STANDARDS\f[R] section).
1491 .PP
1493 with the \f[B]-h\f[R] or \f[B]--help\f[R] options.
1494 .RE
1495 .SH EXIT STATUS
1497 .TP
1498 \f[B]0\f[R]
1499 No error.
1500 .TP
1501 \f[B]1\f[R]
1502 A math error occurred.
1503 This follows standard practice of using \f[B]1\f[R] for expected errors,
1504 since math errors will happen in the process of normal execution.
1505 .RS
1506 .PP
1507 Math errors include divide by \f[B]0\f[R], taking the square root of a
1512 to use a non-integer where an integer is required.
1513 .PP
1515 power (\f[B]\[ha]\f[R]), places (\f[B]\[at]\f[R]), left shift
1516 (\f[B]H\f[R]), and right shift (\f[B]h\f[R]) operators.
1517 .RE
1518 .TP
1519 \f[B]2\f[R]
1520 A parse error occurred.
1521 .RS
1522 .PP
1523 Parse errors include unexpected \f[B]EOF\f[R], using an invalid
1525 token where it is invalid.
1526 .RE
1527 .TP
1528 \f[B]3\f[R]
1529 A runtime error occurred.
1530 .RS
1531 .PP
1533 (\f[B]ibase\f[R], \f[B]obase\f[R], or \f[B]scale\f[R]), giving a bad
1534 expression to a \f[B]read()\f[R] call, calling \f[B]read()\f[R] inside
1535 of a \f[B]read()\f[R] call, type errors (including attempting to execute
1537 elements.
1538 .RE
1539 .TP
1540 \f[B]4\f[R]
1541 A fatal error occurred.
1542 .RS
1543 .PP
1545 open files, attempting to use files that do not have only ASCII
1546 characters (dc(1) only accepts ASCII characters), attempting to open a
1547 directory as a file, and giving invalid command-line options.
1548 .RE
1549 .PP
1550 The exit status \f[B]4\f[R] is special; when a fatal error occurs, dc(1)
1551 always exits and returns \f[B]4\f[R], no matter what mode dc(1) is in.
1552 .PP
1554 interactive mode (see the \f[B]INTERACTIVE MODE\f[R] section), since
1555 dc(1) resets its state (see the \f[B]RESET\f[R] section) and accepts
1556 more input when one of those errors occurs in interactive mode.
1558 \f[B]-i\f[R] flag or \f[B]--interactive\f[R] option.
1559 .PP
1562 \f[B]-i\f[R] flag or \f[B]--interactive\f[R] option.
1563 .SH INTERACTIVE MODE
1564 Like bc(1), dc(1) has an interactive mode and a non-interactive mode.
1565 Interactive mode is turned on automatically when both \f[B]stdin\f[R]
1566 and \f[B]stdout\f[R] are hooked to a terminal, but the \f[B]-i\f[R] flag
1567 and \f[B]--interactive\f[R] option can turn it on in other situations.
1568 .PP
1570 \f[B]RESET\f[R] section), and in normal execution, flushes
1571 \f[B]stdout\f[R] as soon as execution is done for the current input.
1572 dc(1) may also reset on \f[B]SIGINT\f[R] instead of exit, depending on
1573 the contents of, or default for, the \f[B]DC_SIGINT_RESET\f[R]
1574 environment variable (see the \f[B]ENVIRONMENT VARIABLES\f[R] section).
1575 .SH TTY MODE
1576 If \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R] are all
1579 settings.
1580 .PP
1581 If there is the environment variable \f[B]DC_TTY_MODE\f[R] in the
1582 environment (see the \f[B]ENVIRONMENT VARIABLES\f[R] section), then if
1584 on TTY mode when \f[B]stdin\f[R], \f[B]stdout\f[R], and \f[B]stderr\f[R]
1585 are all connected to a TTY.
1586 If the \f[B]DC_TTY_MODE\f[R] environment variable exists but is
1587 \f[I]not\f[R] a non-zero integer, then dc(1) will not turn TTY mode on.
1588 .PP
1589 If the environment variable \f[B]DC_TTY_MODE\f[R] does \f[I]not\f[R]
1590 exist, the default setting is used.
1591 The default setting can be queried with the \f[B]-h\f[R] or
1592 \f[B]--help\f[R] options.
1593 .PP
1595 required in the bc(1) specification (see the \f[B]STANDARDS\f[R]
1596 section), and interactive mode requires only \f[B]stdin\f[R] and
1597 \f[B]stdout\f[R] to be connected to a terminal.
1598 .SS Prompt
1599 If TTY mode is available, then a prompt can be enabled.
1601 variable: \f[B]DC_PROMPT\f[R] (see the \f[B]ENVIRONMENT VARIABLES\f[R]
1602 section).
1603 .PP
1604 If the environment variable \f[B]DC_PROMPT\f[R] exists and is a non-zero
1605 integer, then the prompt is turned on when \f[B]stdin\f[R],
1606 \f[B]stdout\f[R], and \f[B]stderr\f[R] are connected to a TTY and the
1607 \f[B]-P\f[R] and \f[B]--no-prompt\f[R] options were not used.
1609 the \f[B]-R\f[R] and \f[B]--no-read-prompt\f[R] options must also not be
1610 used.
1611 .PP
1612 However, if \f[B]DC_PROMPT\f[R] does not exist, the prompt can be
1613 enabled or disabled with the \f[B]DC_TTY_MODE\f[R] environment variable,
1614 the \f[B]-P\f[R] and \f[B]--no-prompt\f[R] options, and the \f[B]-R\f[R]
1615 and \f[B]--no-read-prompt\f[R] options.
1616 See the \f[B]ENVIRONMENT VARIABLES\f[R] and \f[B]OPTIONS\f[R] sections
1617 for more details.
1618 .SH SIGNAL HANDLING
1619 Sending a \f[B]SIGINT\f[R] will cause dc(1) to do one of two things.
1620 .PP
1621 If dc(1) is not in interactive mode (see the \f[B]INTERACTIVE MODE\f[R]
1622 section), or the \f[B]DC_SIGINT_RESET\f[R] environment variable (see the
1623 \f[B]ENVIRONMENT VARIABLES\f[R] section), or its default, is either not
1624 an integer or it is zero, dc(1) will exit.
1625 .PP
1627 \f[B]DC_SIGINT_RESET\f[R] or its default is an integer and non-zero,
1629 \f[B]RESET\f[R] section) upon receiving a \f[B]SIGINT\f[R].
1630 .PP
1631 Note that \[lq]current input\[rq] can mean one of two things.
1632 If dc(1) is processing input from \f[B]stdin\f[R] in interactive mode,
1633 it will ask for more input.
1636 exists, or ask for input from \f[B]stdin\f[R] if no other file exists.
1637 .PP
1638 This means that if a \f[B]SIGINT\f[R] is sent to dc(1) as it is
1640 signal since it will immediately start executing the next file.
1642 dc(1) have function definitions, which are quick to parse.
1643 If a file takes a long time to execute, there may be a bug in that file.
1645 the user to continue.
1646 .PP
1647 \f[B]SIGTERM\f[R] and \f[B]SIGQUIT\f[R] cause dc(1) to clean up and
1648 exit, and it uses the default handler for all other signals.
1649 .SH LOCALES
1651 locales and thus, supports \f[B]LC_MESSAGES\f[R].
1652 .SH SEE ALSO
1654 .SH STANDARDS
1656 operators in the IEEE Std 1003.1-2017 (\[lq]POSIX.1-2017\[rq]) bc(1)
1658 https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html .
1659 .SH BUGS
1660 None are known.
1661 Report bugs at https://git.gavinhoward.com/gavin/bc .
1662 .SH AUTHOR
1663 Gavin D. Howard \c
1664 .MT gavin@gavinhoward.com
1665 .ME \c
1666 \ and contributors.