Commit | Line | Data |
---|---|---|

abcef8f0 | 1 | .\" $OpenBSD: dc.1,v 1.19 2004/10/18 07:49:00 otto Exp $ |

f2d37758 MD |
2 | .\" |

3 | .\" Copyright (C) Caldera International Inc. 2001-2002. | |

4 | .\" All rights reserved. | |

5 | .\" | |

6 | .\" Redistribution and use in source and binary forms, with or without | |

7 | .\" modification, are permitted provided that the following conditions | |

8 | .\" are met: | |

9 | .\" 1. Redistributions of source code and documentation must retain the above | |

10 | .\" copyright notice, this list of conditions and the following disclaimer. | |

11 | .\" 2. Redistributions in binary form must reproduce the above copyright | |

12 | .\" notice, this list of conditions and the following disclaimer in the | |

13 | .\" documentation and/or other materials provided with the distribution. | |

14 | .\" 3. All advertising materials mentioning features or use of this software | |

15 | .\" must display the following acknowledgement: | |

16 | .\" This product includes software developed or owned by Caldera | |

17 | .\" International, Inc. | |

18 | .\" 4. Neither the name of Caldera International, Inc. nor the names of other | |

19 | .\" contributors may be used to endorse or promote products derived from | |

20 | .\" this software without specific prior written permission. | |

21 | .\" | |

22 | .\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA | |

23 | .\" INTERNATIONAL, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR | |

24 | .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES | |

25 | .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. | |

26 | .\" IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE FOR ANY DIRECT, | |

27 | .\" INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES | |

28 | .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR | |

29 | .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |

30 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, | |

31 | .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING | |

32 | .\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE | |

33 | .\" POSSIBILITY OF SUCH DAMAGE. | |

34 | .\" | |

35 | .\" @(#)dc.1 8.1 (Berkeley) 6/6/93 | |

36 | .\" | |

abcef8f0 | 37 | .Dd October 10, 2004 |

f2d37758 | 38 | .Dt DC 1 |

fb5b3747 | 39 | .Os |

f2d37758 MD |
40 | .Sh NAME |

41 | .Nm dc | |

42 | .Nd desk calculator | |

43 | .Sh SYNOPSIS | |

44 | .Nm | |

45 | .Op Fl x | |

abcef8f0 | 46 | .Op Fl e Ar expression |

f2d37758 MD |
47 | .Op Ar file |

48 | .Sh DESCRIPTION | |

49 | .Nm | |

50 | is an arbitrary precision arithmetic package. | |

51 | The overall structure of | |

52 | .Nm | |

53 | is | |

54 | a stacking (reverse Polish) calculator i.e.\& | |

55 | numbers are stored on a stack. | |

56 | Adding a number pushes it onto the stack. | |

57 | Arithmetic operations pop arguments off the stack | |

58 | and push the results. | |

59 | See also the | |

60 | .Xr bc 1 | |

61 | utility, which is a preprocessor for | |

62 | .Nm | |

63 | providing infix notation and a C-like syntax | |

64 | which implements functions and reasonable control | |

65 | structures for programs. | |

66 | The options are as follows: | |

67 | .Bl -tag -width Ds | |

abcef8f0 SW |
68 | .It Fl e Ar expression |

69 | Evaluate | |

70 | .Ar expression . | |

71 | If multiple | |

72 | .Fl e | |

73 | options are specified, they will be processed in the order given. | |

74 | If no | |

75 | .Ar file | |

76 | argument is given, execution will stop after processing the expressions | |

77 | given on the command line, | |

78 | otherwise processing will continue with the contents of | |

79 | .Ar file . | |

f2d37758 MD |
80 | .It Fl x |

81 | Enable extended register mode. | |

82 | This mode is used by | |

83 | .Xr bc 1 | |

84 | to allow more than 256 registers. | |

85 | See | |

86 | .Sx Registers | |

87 | for a more detailed description. | |

88 | .El | |

89 | .Pp | |

90 | Ordinarily, | |

91 | .Nm | |

92 | operates on decimal integers, | |

93 | but one may specify an input base, output base, | |

94 | and a number of fractional digits (scale) to be maintained. | |

95 | If an argument is given, | |

96 | input is taken from that file until its end, | |

97 | then from the standard input. | |

98 | Whitespace is ignored, expect where it signals the end of a number, | |

99 | end of a line or when a register name is expected. | |

100 | The following constructions are recognized: | |

101 | .Bl -tag -width "number" | |

102 | .It Va number | |

103 | The value of the number is pushed on the stack. | |

104 | A number is an unbroken string of the digits 0\-9 and letters A\-F. | |

105 | It may be preceded by an underscore | |

106 | .Pq Sq _ | |

107 | to input a negative number. | |

108 | A number may contain a single decimal point. | |

109 | A number may also contain the characters A\-F, with the values 10\-15. | |

110 | .It Cm "+ - / * % ~ ^" | |

111 | The | |

112 | top two values on the stack are added | |

113 | (+), | |

114 | subtracted | |

115 | (\-), | |

116 | multiplied (*), | |

117 | divided (/), | |

118 | remaindered (%), | |

119 | divided and remaindered (~), | |

120 | or exponentiated (^). | |

121 | The two entries are popped off the stack; | |

122 | the result is pushed on the stack in their place. | |

123 | Any fractional part of an exponent is ignored. | |

124 | .Pp | |

125 | For addition and subtraction, the scale of the result is the maximum | |

126 | of scales of the operands. | |

127 | For division the scale of the result is defined | |

128 | by the scale set by the | |

129 | .Ic k | |

130 | operation. | |

131 | For multiplication, the scale is defined by the expression | |

132 | .Sy min(a+b,max(a,b,scale)) , | |

133 | where | |

134 | .Sy a | |

135 | and | |

136 | .Sy b | |

137 | are the scales of the operands, and | |

138 | .Sy scale | |

139 | is the scale defined by the | |

140 | .Ic k | |

141 | operation. | |

142 | For exponentiation with a non-negative exponent, the scale of the result is | |

143 | .Sy min(a*b,max(scale,a)) , | |

144 | where | |

145 | .Sy a | |

146 | is the scale of the base, and | |

147 | .Sy b | |

148 | is the | |

149 | .Em value | |

150 | of the exponent. | |

151 | If the exponent is negative, the scale of the result is the scale | |

152 | defined by the | |

153 | .Ic k | |

154 | operation. | |

155 | .Pp | |

156 | In the case of the division and modulus operator (~), | |

157 | the resultant quotient is pushed first followed by the remainder. | |

158 | This is a shorthand for the sequence: | |

159 | .Bd -literal -offset indent -compact | |

160 | x y / x y % | |

161 | .Ed | |

162 | The division and modulus operator is a non-portable extension. | |

163 | .It Ic a | |

164 | Pop the top value from the stack. | |

165 | If that value is a number, compute the integer part of the number modulo 256. | |

166 | If the result is zero, push an empty string. | |

167 | Otherwise push a one character string by interpreting the computed value | |

168 | as an | |

169 | .Tn ASCII | |

170 | character. | |

171 | .Pp | |

172 | If the top value is a string, push a string containing the first character | |

173 | of the original string. | |

174 | If the original string is empty, an empty string is pushed back. | |

175 | The | |

176 | .Ic a | |

177 | operator is a non-portable extension. | |

178 | .It Ic c | |

179 | All values on the stack are popped. | |

180 | .It Ic d | |

181 | The top value on the stack is duplicated. | |

182 | .It Ic f | |

183 | All values on the stack are printed, separated by newlines. | |

184 | .It Ic G | |

185 | The top two numbers are popped from the stack and compared. | |

186 | A one is pushed if the top of the stack is equal to the second number | |

187 | on the stack. | |

188 | A zero is pushed otherwise. | |

189 | This is a non-portable extension. | |

190 | .It Ic i | |

191 | The top value on the stack is popped and used as the | |

192 | base for further input. | |

193 | The initial input base is 10. | |

194 | .It Ic I | |

195 | Pushes the input base on the top of the stack. | |

196 | .It Ic J | |

197 | Pop the top value from the stack. | |

198 | The recursion level is popped by that value and, following that, | |

199 | the input is skipped until the first occurrence of the | |

200 | .Ic M | |

201 | operator. | |

202 | The | |

203 | .Ic J | |

204 | operator is a non-portable extension, used by the | |

205 | .Xr bc 1 | |

206 | command. | |

207 | .It Ic K | |

208 | The current scale factor is pushed onto the stack. | |

209 | .It Ic k | |

210 | The top of the stack is popped, and that value is used as | |

211 | a non-negative scale factor: | |

212 | the appropriate number of places | |

213 | are printed on output, | |

214 | and maintained during multiplication, division, and exponentiation. | |

215 | The interaction of scale factor, | |

216 | input base, and output base will be reasonable if all are changed | |

217 | together. | |

218 | .It Ic L Ns Ar x | |

219 | Register | |

220 | .Ar x | |

221 | is treated as a stack and its top value is popped onto the main stack. | |

222 | .It Ic l Ns Ar x | |

223 | The | |

224 | value in register | |

225 | .Ar x | |

226 | is pushed on the stack. | |

227 | The register | |

228 | .Ar x | |

229 | is not altered. | |

230 | Initially, all registers contain the value zero. | |

231 | .It Ic M | |

232 | Mark used by the | |

233 | .Ic J | |

234 | operator. | |

235 | The | |

236 | .Ic M | |

237 | operator is a non-portable extensions, used by the | |

238 | .Xr bc 1 | |

239 | command. | |

240 | .It Ic N | |

241 | The top of the stack is replaced by one if the top of the stack | |

242 | is equal to zero. | |

243 | If the top of the stack is unequal to zero, it is replaced by zero. | |

244 | This is a non-portable extension. | |

245 | .It Ic n | |

246 | The top value on the stack is popped and printed without a newline. | |

247 | This is a non-portable extension. | |

248 | .It Ic O | |

249 | Pushes the output base on the top of the stack. | |

250 | .It Ic o | |

251 | The top value on the stack is popped and used as the | |

252 | base for further output. | |

253 | The initial output base is 10. | |

254 | .It Ic P | |

255 | The top of the stack is popped. | |

256 | If the top of the stack is a string, it is printed without a trailing newline. | |

257 | If the top of the stack is a number, it is interpreted as a | |

258 | base 256 number, and each digit of this base 256 number is printed as | |

259 | an | |

260 | .Tn ASCII | |

261 | character, without a trailing newline. | |

262 | .It Ic p | |

263 | The top value on the stack is printed with a trailing newline. | |

264 | The top value remains unchanged. | |

265 | .It Ic Q | |

266 | The top value on the stack is popped and the string execution level is popped | |

267 | by that value. | |

268 | .It Ic q | |

269 | Exits the program. | |

270 | If executing a string, the recursion level is | |

271 | popped by two. | |

272 | .It Ic R | |

273 | The top of the stack is removed (popped). | |

274 | This is a non-portable extension. | |

275 | .It Ic r | |

276 | The top two values on the stack are reversed (swapped). | |

277 | This is a non-portable extension. | |

278 | .It Ic S Ns Ar x | |

279 | Register | |

280 | .Ar x | |

281 | is treated as a stack. | |

282 | The top value of the main stack is popped and pushed on it. | |

283 | .It Ic s Ns Ar x | |

284 | The | |

285 | top of the stack is popped and stored into | |

286 | a register named | |

287 | .Ar x . | |

288 | .It Ic v | |

289 | Replaces the top element on the stack by its square root. | |

290 | The scale of the result is the maximum of the scale of the argument | |

291 | and the current value of scale. | |

292 | .It Ic X | |

293 | Replaces the number on the top of the stack with its scale factor. | |

294 | If the top of the stack is a string, replace it with the integer 0. | |

295 | .It Ic x | |

296 | Treats the top element of the stack as a character string | |

297 | and executes it as a string of | |

298 | .Nm | |

299 | commands. | |

300 | .It Ic Z | |

301 | Replaces the number on the top of the stack with its length. | |

302 | The length of a string is its number of characters. | |

303 | The length of a number is its number of digits, not counting the minus sign | |

304 | and decimal point. | |

305 | .It Ic z | |

306 | The stack level is pushed onto the stack. | |

c51d6246 | 307 | .It Cm \&[ Ns ... Ns Cm \&] |

f2d37758 MD |
308 | Puts the bracketed |

309 | .Tn ASCII | |

310 | string onto the top of the stack. | |

311 | If the string includes brackets, these must be properly balanced. | |

312 | The backslash character | |

313 | .Pq Sq \e | |

314 | may be used as an escape character, making it | |

315 | possible to include unbalanced brackets in strings. | |

316 | To include a backslash in a string, use a double backslash. | |

317 | .It Xo | |

318 | .Cm < Ns Va x | |

319 | .Cm > Ns Va x | |

320 | .Cm = Ns Va x | |

321 | .Cm !< Ns Va x | |

322 | .Cm !> Ns Va x | |

323 | .Cm != Ns Va x | |

324 | .Xc | |

325 | The top two elements of the stack are popped and compared. | |

326 | Register | |

327 | .Ar x | |

328 | is executed if they obey the stated | |

329 | relation. | |

330 | .It Xo | |

331 | .Cm < Ns Va x Ns e Ns Va y | |

332 | .Cm > Ns Va x Ns e Ns Va y | |

333 | .Cm = Ns Va x Ns e Ns Va y | |

334 | .Cm !< Ns Va x Ns e Ns Va y | |

335 | .Cm !> Ns Va x Ns e Ns Va y | |

336 | .Cm != Ns Va x Ns e Ns Va y | |

337 | .Xc | |

338 | These operations are variants of the comparison operations above. | |

339 | The first register name is followed by the letter | |

340 | .Sq e | |

341 | and another register name. | |

342 | Register | |

343 | .Ar x | |

344 | will be executed if the relation is true, and register | |

345 | .Ar y | |

346 | will be executed if the relation is false. | |

347 | This is a non-portable extension. | |

348 | .It Ic \&( | |

349 | The top two numbers are popped from the stack and compared. | |

350 | A one is pushed if the top of the stack is less than the second number | |

351 | on the stack. | |

352 | A zero is pushed otherwise. | |

353 | This is a non-portable extension. | |

354 | .It Ic { | |

355 | The top two numbers are popped from the stack and compared. | |

356 | A one is pushed if the top of stack is less than or equal to the | |

357 | second number on the stack. | |

358 | A zero is pushed otherwise. | |

359 | This is a non-portable extension. | |

360 | .It Ic \&! | |

361 | Interprets the rest of the line as a | |

362 | .Ux | |

363 | command. | |

364 | .It Ic \&? | |

365 | A line of input is taken from the input source (usually the terminal) | |

366 | and executed. | |

c51d6246 | 367 | .It Ic \&: Ns Ar r |

f2d37758 MD |
368 | Pop two values from the stack. |

369 | The second value on the stack is stored into the array | |

370 | .Ar r | |

371 | indexed by the top of stack. | |

c51d6246 | 372 | .It Ic \&; Ns Ar r |

f2d37758 MD |
373 | Pop a value from the stack. |

374 | The value is used as an index into register | |

375 | .Ar r . | |

376 | The value in this register is pushed onto the stack. | |

377 | .Pp | |

378 | Array elements initially have the value zero. | |

379 | Each level of a stacked register has its own array associated with | |

380 | it. | |

381 | The command sequence | |

382 | .Bd -literal -offset indent | |

383 | [first] 0:a [dummy] Sa [second] 0:a 0;a p La 0;a p | |

384 | .Ed | |

385 | .Pp | |

386 | will print | |

387 | .Bd -literal -offset indent | |

388 | second | |

389 | first | |

390 | .Ed | |

391 | .Pp | |

392 | since the string | |

393 | .Ql second | |

394 | is written in an array that is later popped, to reveal the array that | |

395 | stored | |

396 | .Ql first . | |

397 | .It Ic # | |

398 | Skip the rest of the line. | |

399 | This is a non-portable extension. | |

400 | .El | |

401 | .Ss Registers | |

402 | Registers have a single character name | |

403 | .Ar x , | |

404 | where | |

405 | .Ar x | |

406 | may be any character, including space, tab or any other special character. | |

407 | If extended register mode is enabled using the | |

408 | .Fl x | |

409 | option and the register identifier | |

410 | .Ar x | |

411 | has the value 255, the next two characters are interpreted as a | |

412 | two-byte register index. | |

413 | The set of standard single character registers and the set of extended | |

414 | registers do not overlap. | |

415 | Extended register mode is a non-portable extension. | |

416 | .Sh EXAMPLES | |

417 | An example which prints the first ten values of | |

418 | .Ic n! : | |

419 | .Bd -literal -offset indent | |

420 | [la1+dsa*pla10>y]sy | |

421 | 0sa1 | |

422 | lyx | |

423 | .Ed | |

424 | .Pp | |

425 | Independent of the current input base, the command | |

426 | .Bd -literal -offset indent | |

427 | Ai | |

428 | .Ed | |

429 | .Pp | |

430 | will reset the input base to decimal 10. | |

431 | .Sh DIAGNOSTICS | |

432 | .Bl -diag | |

433 | .It %c (0%o) is unimplemented | |

434 | an undefined operation was called. | |

435 | .It stack empty | |

436 | for not enough elements on the stack to do what was asked. | |

437 | .It stack register '%c' (0%o) is empty | |

438 | for an | |

439 | .Ar L | |

440 | operation from a stack register that is empty. | |

441 | .It Runtime warning: non-zero scale in exponent | |

442 | for a fractional part of an exponent that is being ignored. | |

443 | .It divide by zero | |

444 | for trying to divide by zero. | |

445 | .It remainder by zero | |

446 | for trying to take a remainder by zero. | |

447 | .It square root of negative number | |

448 | for trying to take the square root of a negative number. | |

449 | .It index too big | |

450 | for an array index that is larger than 2048. | |

451 | .It negative index | |

452 | for a negative array index. | |

453 | .It "input base must be a number between 2 and 16" | |

454 | for trying to set an illegal input base. | |

455 | .It output base must be a number greater than 1 | |

456 | for trying to set an illegal output base. | |

457 | .It scale must be a nonnegative number | |

458 | for trying to set a negative or zero scale. | |

459 | .It scale too large | |

460 | for trying to set a scale that is too large. | |

461 | A scale must be representable as a 32-bit unsigned number. | |

462 | .It Q command argument exceeded string execution depth | |

463 | for trying to pop the recursion level more than the current | |

464 | recursion level. | |

465 | .It Q command requires a number >= 1 | |

466 | for trying to pop an illegal number of recursion levels. | |

467 | .It recursion too deep | |

468 | for too many levels of nested execution. | |

469 | .Pp | |

470 | The recursion level is increased by one if the | |

471 | .Ar x | |

472 | or | |

473 | .Ar ?\& | |

474 | operation or one of the compare operations resulting in the execution | |

475 | of register is executed. | |

476 | As an exception, the recursion level is not increased if the operation | |

477 | is executed as the last command of a string. | |

478 | For example, the commands | |

479 | .Bd -literal -offset indent | |

480 | [lax]sa | |

481 | 1 lax | |

482 | .Ed | |

483 | .Pp | |

484 | will execute an endless loop, while the commands | |

485 | .Bd -literal -offset indent | |

486 | [laxp]sa | |

487 | 1 lax | |

488 | .Ed | |

489 | .Pp | |

490 | will terminate because of a too deep recursion level. | |

491 | .It J command argument exceeded string execution depth | |

492 | for trying to pop the recursion level more than the current | |

493 | recursion level. | |

494 | .It mark not found | |

495 | for a failed scan for an occurrence of the | |

496 | .Ic M | |

497 | operator. | |

498 | .El | |

499 | .Sh SEE ALSO | |

500 | .Xr bc 1 | |

501 | .Rs | |

502 | .%B USD:05 | |

503 | .%A L. L. Cherry | |

504 | .%A R. Morris | |

505 | .%T "DC \- An Interactive Desk Calculator" | |

506 | .Re | |

507 | .Sh STANDARDS | |

508 | The arithmetic operations of the | |

509 | .Nm | |

510 | utility are expected to conform to the definition listed in the | |

511 | .Xr bc 1 | |

512 | section of the | |

513 | .St -p1003.2 | |

514 | specification. | |

515 | .Sh HISTORY | |

516 | The | |

517 | .Nm | |

518 | command first appeared in | |

519 | .At v6 . | |

520 | A complete rewrite of the | |

521 | .Nm | |

522 | command using the | |

523 | .Xr bn 3 | |

524 | big number routines first appeared in | |

525 | .Ox 3.5 . | |

526 | .Sh AUTHORS | |

f8a0f69a | 527 | .An -nosplit |

f2d37758 MD |
528 | The original version of the |

529 | .Nm | |

530 | command was written by | |

531 | .An Robert Morris | |

532 | and | |

533 | .An Lorinda Cherry . | |

534 | The current version of the | |

535 | .Nm | |

536 | utility was written by | |

537 | .An Otto Moerbeek . |